# Fundamentos de Python

```{note}
**Duración:** 2 horas. **Objetivo central:** Dominar tipos de datos,
estructuras y funciones en Python a través de ejemplos oceanográficos
reales.
```

## Tipos de datos primarios y variables

En oceanografía, trabajamos constantemente con números enteros (conteo
de muestras), flotantes (temperatura, salinidad, profundidad), cadenas
de texto (identificadores de estaciones) y booleanos (control de
calidad):

``` python
station_id = "CTD-B01"      # Cadena (str)
latitude = 24.1425           # Flotante (float)
longitude = -110.3128        # Flotante (float)
depth_m = 450.5              # Profundidad en metros (float)
qc_passed = True             # Bandera de calidad (bool)
sample_count = 12            # Conteo de botellas Niskin (int)
```

## Estructuras de datos: Listas y diccionarios

Las **listas** almacenan secuencias ordenadas de valores (ej.
profundidades de muestreo), mientras que los **diccionarios** vinculan
claves y atributos (ej. metadatos de una estación):

``` python
# Lista de profundidades estandar (metros)
sampling_depths = [0, 10, 25, 50, 75, 100, 200, 500]

# Diccionario con metadatos de estación oceanográfica
station_metadata = {
    "cruise": "GOLFO-2026-I",
    "station": "E04",
    "lat_dms": (25, 30, 15.2),  # Grados, Minutos, Segundos
    "lon_dms": (-111, 12, 45.8),
    "bottom_depth_m": 820.0,
}
```
# Tipos de datos en Python, pandas y GeoPandas

En Python, un tipo de dato describe la clase de un valor, como un número o
una cadena de texto. En una tabla de pandas o GeoPandas, cada columna tiene
un tipo de datos, o *dtype*, que indica cómo se almacenan sus valores.

## 1. Tipos básicos de Python

| Tipo | Ejemplo | Descripción |
|---|---|---|
| `int` | `12` | Número entero. |
| `float` | `4.5` | Número decimal. |
| `bool` | `True`, `False` | Valor lógico. |
| `str` | `"La Paz"` | Cadena de texto. |
| `NoneType` | `None` | Ausencia de valor. |
| `complex` | `2 + 3j` | Número complejo. |

Se puede consultar el tipo de un valor con `type()`:

```python
magnitud = 4.5
print(type(magnitud))  # <class 'float'>
```

### Colecciones

Python también dispone de tipos que reúnen varios valores. Los siguientes
ejemplos usan datos hipotéticos de sismos.

| Tipo | Características | Ejemplo |
|---|---|---|
| `list` | Secuencia ordenada y modificable; admite valores repetidos. | `[3.2, 4.5, 3.2]` |
| `tuple` | Secuencia ordenada que no se puede modificar después de crearla. | `(-110.3, 24.1)` |
| `dict` | Asocia claves únicas con valores; es modificable. | `{"mag": 4.5, "depth": 10.0}` |
| `set` | Conjunto de valores únicos, sin orden garantizado. | `{"ml", "mw"}` |

Una **lista** puede almacenar las magnitudes de varios eventos:

```python
magnitudes = [3.2, 4.5, 3.2]
magnitudes.append(5.1)
print(magnitudes[0])  # 3.2
```

Una **tupla** puede representar la ubicación de un sismo como
`(longitud, latitud)`:

```python
ubicacion = (-110.3, 24.1)
longitud, latitud = ubicacion
print(longitud, latitud)  # -110.3 24.1
```

Un **diccionario** puede reunir los atributos de un evento:

```python
evento = {
    "place": "La Paz",
    "mag": 4.5,
    "depth": 10.0,
    "ubicacion": (-110.3, 24.1),
}
print(evento["mag"])  # 4.5
```

Un **conjunto** permite identificar tipos de magnitud distintos sin
repeticiones:

```python
tipos_magnitud = {"ml", "mw", "ml"}
print(tipos_magnitud)  # Contiene solo "ml" y "mw"; el orden puede variar.
```

## 2. Tipos de columnas en pandas

Un `DataFrame` puede contener columnas de distintos tipos. Cada columna
tiene su propio `dtype`.

| `dtype` habitual | Contenido | Ejemplo |
|---|---|---|
| `int64` | Números enteros. | `12` |
| `float64` | Números decimales. | `4.5` |
| `bool` | Valores lógicos. | `True` |
| `object` | Objetos de Python, frecuentemente cadenas o valores mezclados. | `"La Paz"` |
| `string` | Texto, con soporte de valores faltantes. | `"La Paz"` |
| `datetime64[...]` | Fechas y horas, con o sin zona horaria. | `2024-01-15` |
| `timedelta64[...]` | Intervalos de tiempo. | `2 días` |
| `category` | Valores categóricos, útiles cuando se repiten categorías. | `"reviewed"` |
| `Int64`, `Float64`, `boolean` | Tipos que admiten valores faltantes con `pd.NA`. | `12`, `pd.NA` |

Los nombres concretos pueden variar según los datos y la versión de pandas.
La diferencia entre mayúsculas y minúsculas importa: por ejemplo, `Int64`
es un tipo de pandas que admite valores faltantes, mientras que `int64`
es un tipo entero de NumPy.

Para consultar los tipos de la tabla de la libreta:

```python
sismos.dtypes
```

En la salida de ejemplo, `latitude`, `longitude`, `depth` y `mag` son
`float64`, mientras que `place`, `magType` y `time` aparecen como `object`.
La última línea, `dtype: object`, describe el tipo de la serie que devuelve
`sismos.dtypes`, no el tipo de todas las columnas originales.

### ¿Qué significa `object`?

Una columna `object` almacena referencias a objetos Python. A menudo contiene
cadenas de texto, pero `object` **no garantiza** que todos sus valores sean
texto ni que tengan el mismo tipo. Puede incluir, por ejemplo, cadenas,
números, listas y valores faltantes.

```python
import pandas as pd

valores = pd.Series([4.5, "4.6", None], dtype="object")
print(valores.dtype)            # object
print(valores.map(type))        # float, str y NoneType
```

Aunque `4.5` y `"4.6"` se parecen, el primero es un número y el segundo
es texto. Esta mezcla puede dificultar cálculos, comparaciones y
ordenamientos. Para inspeccionar los tipos de los valores de una columna:

```python
sismos["mag"].map(type).value_counts()
```

Si una columna debería contener números, `pd.to_numeric` puede convertirla:

```python
numeros = pd.to_numeric(valores, errors="coerce")
```

Con `errors="coerce"`, los valores que no se puedan convertir pasan a ser
faltantes. Conviene revisarlos antes de reemplazar los datos originales:

```python
no_convertidos = valores.notna() & numeros.isna()
print(valores[no_convertidos])
```

De forma similar, una columna `object` con fechas en texto puede convertirse
a fechas. En la libreta, `time` aparece como `object`, por lo que todavía
no tiene un dtype de fecha:

```python
sismos["time"] = pd.to_datetime(sismos["time"], utc=True, errors="coerce")
```

Aquí `utc=True` normaliza las fechas a UTC; `errors="coerce"` convierte las
fechas que no se puedan interpretar en `NaT`, el valor faltante para fechas.

## 3. Tipos en GeoPandas

Un `GeoDataFrame` admite las mismas columnas que un `DataFrame` de pandas y
añade columnas de tipo `geometry`. Una columna de geometría puede contener:

| Geometría | Representación | Ejemplo |
|---|---|---|
| `Point` | Punto. | Localización de un sismo. |
| `LineString` | Línea. | Trazo de una falla. |
| `Polygon` | Polígono. | Límite de una región. |
| `MultiPoint`, `MultiLineString`, `MultiPolygon` | Colecciones de geometrías del mismo tipo. | Un estado formado por varios polígonos. |
| `GeometryCollection` | Colección de geometrías que pueden ser de distintos tipos. | Un punto y una línea agrupados. |

Si `longitude` y `latitude` son coordenadas WGS84, se pueden convertir a
puntos así:

```python
import geopandas as gpd

sismos_geo = gpd.GeoDataFrame(
    sismos,
    geometry=gpd.points_from_xy(sismos["longitude"], sismos["latitude"]),
    crs="EPSG:4326",
)

print(sismos_geo.dtypes)
```

La columna `geometry` tendrá el dtype `geometry` y cada valor representará
un punto. El sistema de referencia de coordenadas, o **CRS**, indica cómo
interpretar las coordenadas; no es un dtype. `EPSG:4326` solo debe asignarse
si las coordenadas originales están en WGS84.

Para inspeccionar la tabla y sus geometrías:

```python
type(sismos_geo)                       # Tipo del objeto completo
sismos_geo.dtypes                      # Tipo de cada columna
sismos_geo.geometry.geom_type          # Tipo de cada geometría
sismos_geo.geometry.geom_type.value_counts()  # Conteo por tipo
sismos_geo.crs                         # Sistema de referencia
```


Control de flujo: Condicionales y bucles
---------------------------------------

Iterar sobre perfiles oceanográficos y filtrar según criterios físicos:

``` python
temperatures = [24.5, 22.1, 18.3, 14.2, 11.0, 8.5]

for temp in temperatures:
    if temp > 20.0:
        layer = "Capa superficial cálida"
    elif temp >= 12.0:
        layer = "Termoclina"
    else:
        layer = "Agua profunda"
    print(f"Temperatura: {temp:4.1f} C -> {layer}")
```

## Funciones reutilizables: Conversión de coordenadas

En bitácoras y cartas náuticas es habitual registrar coordenadas en
formato sexagesimal (Grados, Minutos y Segundos). La librería espacial
requiere **Grados Decimales (DD)**:

$$\text{DD} = \text{Grados} + \frac{\text{Minutos}}{60} + \frac{\text{Segundos}}{3600}$$

``` python
def dms_to_dd(degrees: float, minutes: float, seconds: float, hemisphere: str = "N") -> float:
    """
    Convierte coordenadas de Grados, Minutos y Segundos (DMS) a Grados Decimales (DD).

    Parametros:
        degrees (float): Grados absolutos.
        minutes (float): Minutos sexagesimales.
        seconds (float): Segundos sexagesimales.
        hemisphere (str): Orientacion cardinal ('N', 'S', 'E', 'W').

    Retorna:
        float: Coordenada en grados decimales con signo apropiado.
    """
    dd = degrees + (minutes / 60.0) + (seconds / 3600.0)
    if hemisphere.upper() in ["S", "W"]:
        dd = -dd
    return round(dd, 6)

# Ejemplo de aplicacion practica
lat_estacion = dms_to_dd(24, 15, 30.5, "N")
lon_estacion = dms_to_dd(110, 20, 15.0, "W")
print(f"Coordenadas en Grados Decimales: ({lat_estacion}, {lon_estacion})")
```

## Ejercicios de la sesión

1.  Escriba una función que reciba una lista de temperaturas registradas
    por un CTD y devuelva el gradiente térmico vertical entre la
    superficie y la máxima profundidad.
2.  Cree una lista de diccionarios representando tres estaciones
    oceanográficas con coordenadas en DMS y conviértalas a grados
    decimales mediante un bucle `for`.
