Observation Data

This section covers tools for downloading, processing, and handling observational data from satellite altimetry and Argo floats.

Data Handlers

These classes are used to interact with processed observational data within the collocation workflow.

Argo Floats

ocstrack.Observation.argofloat.ArgoData

Argo Float profile data handler.

Loads, preprocesses, and concatenates multiple Argo NetCDF profile files from a specified directory. Handles varying vertical levels (N_LEVELS) by padding smaller datasets with NaNs. Ensures key coordinates exist.

Attributes

ds : xarray.Dataset The concatenated Argo dataset, indexed by 'JULD', ready for collocation.

Properties

time : numpy.ndarray Array of JULD times. lon : numpy.ndarray Array of longitudes. lat : numpy.ndarray Array of latitudes. pres : numpy.ndarray Array of pressures (dbar). temp : numpy.ndarray Array of temperatures (°C). psal : numpy.ndarray Array of salinities (PSU). depth : numpy.ndarray Depths (meters), approximate from pressure.

Methods

filter_by_time(start_date, end_date) Restrict dataset to a specific time range.

depth property

Return depth (meters) from pressure. Simple approximation: depth ≈ -1.0197 * pres.

lat property writable

Return latitudes as a numpy array.

lon property writable

Return longitudes as a numpy array.

pres property

Return pressure (dbar) as a numpy array.

psal property

Return salinity (PSU) as a numpy array.

temp property

Return temperature (°C) as a numpy array.

time property

Return time (JULD) as a numpy array.

__init__(directory_path)

Initialize the ArgoData object by loading all NetCDF datasets in a directory.

Parameters

directory_path : str Path to the directory containing processed Argo .nc files.

filter_by_time(start_date, end_date)

Filter the dataset by a time range.

Parameters

start_date : str Start date (ISO 8601 string, e.g., "2020-01-01"). end_date : str End date (ISO 8601 string, e.g., "2020-02-01").

Notes

Modifies the internal dataset in-place.

Satellite Altimetry

ocstrack.Observation.satellite.SatelliteData

Satellite altimetry data handler.

Loads a NetCDF file containing satellite-derived variables such as significant wave height (SWH), sea level anomaly (SLA), and metadata.

Provides accessor properties and time filtering functionality.

Methods

filter_by_time(start_date, end_date) Restrict the dataset to a specific time range

lat property writable

return lat

lon property writable

return lon

sla property

return sla

source property

return source

swh property

return swh

time property

return time

__init__(filepath)

Initialize the SatelliteData object by loading a NetCDF dataset.

Parameters

filepath : str Path to the satellite NetCDF file

Raises

ValueError If required variables are missing from the dataset

filter_by_time(start_date, end_date)

Filter the dataset by time range.

Parameters

start_date : str ISO 8601 string representing the start date end_date : str ISO 8601 string representing the end date

Notes

The method converts time variables to datetime64 and ensures the time dimension is sorted before filtering.

---

Data Acquisition

These functions are high-level entry points for downloading and pre-processing raw data from public repositories.

Argo Data Acquisition

Use these functions to download and prepare Argo float data.

!!! tip The main function to use here is get_argo. It orchestrates the entire download and processing pipeline.

ocstrack.Observation.get_argo.get_argo(start_date, end_date, region, output_dir, lat_min=None, lat_max=None, lon_min=None, lon_max=None, clean_raw=False)

Download, clean, and optionally crop Argo data for a given region within a specific date range.

This is the main entry-point function. It will download all raw data and create a 'processed' directory containing cleaned, time-filtered, and (optionally) spatially-cropped individual .nc files.

Parameters

start_date : str Start date in 'YYYY-MM-DD'. Data from this date will be INCLUDED. end_date : str End date in 'YYYY-MM-DD'. Data from this date will be INCLUDED. region : str Argo geo region (e.g., 'pacific_ocean', 'atlantic_ocean') output_dir : Union[str, os.PathLike] Base directory to save files. A 'raw' and 'processed' folder will be created inside a sub-directory named after the region. lat_min, lat_max, lon_min, lon_max : Optional[float] Optional cropping bounds clean_raw : bool Delete raw files after processing is complete

Returns

Optional[str] The path to the 'processed' directory containing the final .nc files, or None if the process failed.

ocstrack.Observation.get_argo.download_argo_data(year, month, region, base_url, raw_dir, start_date, end_date)

Downloads Argo data for a given year/month using requests + re. This function recursively finds and downloads all .nc files from the Ifremer FTP-like HTML directory.

Parameters

year : str Year string (e.g., "2019") month : str Month string (e.g., "08") region : str Geo region (e.g., "pacific_ocean") base_url : str Base URL for Argo (from urls.py) raw_dir : str Path to where the raw data will be saved start_date : str ISO 8601 string for start date. end_date : str ISO 8601 string for end date.

Returns

List[str] List of paths to the downloaded .nc files.

ocstrack.Observation.get_argo.crop_argo_data(file_paths, cropped_dir, lat_min, lat_max, lon_min, lon_max, start_date, end_date)

Handles the Argo data loading, time filtering, and spatial cropping.

This function uses a robust loading strategy to avoid decoding errors with metadata variables.

Parameters

file_paths : List[str] List of raw .nc files to process. cropped_dir : str Directory to save the new cropped .nc files. lat_min : float Mininum latitude. lat_max : float Maximum latitude. lon_min : float Mininum longitude. lon_max : float Maximum longitude. start_date : str ISO 8601 string for start date. end_date : str ISO 8601 string for end date.

ocstrack.Observation.get_argo.clean_argo_data(file_paths, clean_dir, start_date, end_date)

Loads, time-filters, and re-saves Argo data to the clean_dir. This is used when cropping is disabled.

Parameters

file_paths : List[str] List of raw .nc files to process. clean_dir : str Directory to save the new cleaned .nc files. start_date : str ISO 8601 string for start date. end_date : str ISO 8601 string for end date.

ocstrack.Observation.get_argo.generate_monthly_dates(start_date_str, end_date_str)

Generates a list of (year, month) tuples between start and end dates.

Parameters:

Name	Type	Description	Default
start_date_str	str	String with dates as 'YYYY-MM-DD'	required
end_date_str	str	String with dates as 'YYYY-MM-DD'	required

Returns:

Type	Description
List[Tuple[str, str]]	List of tuples, e.g., [('2019', '08'), ('2019', '09')]

ocstrack.Observation.get_argo.crop_by_box_argo(dataset, lat_min, lat_max, lon_min, lon_max)

Crops xarray data based on lats and lons (Argo variable names).

Parameters

dataset : xr.Dataset The Argo dataset to crop. lat_min : float Mininum latitude. lat_max : float Maximum latitude. lon_min : float Mininum longitude. lon_max : float Maximum longitude.

Returns

xr.Dataset xarray object of the cropped data.

Notes

Argo data uses the -180 to 180 longitude standard. If you want to cross the meridian, then pass a lon_min > lon_max.

Satellite Data Acquisition

Use these functions to download and prepare satellite altimetry data.

!!! tip The main functions to use here are get_per_sat for a single satellite and get_multi_sat for multiple satellites.

ocstrack.Observation.get_sat.get_per_sat(start_date, end_date, sat, output_dir, lat_min=None, lat_max=None, lon_min=None, lon_max=None, concat=True, clean_raw=False, clean_cropped=False)

Download, crop, and optionally concatenate satellite data.

Parameters

start_date: Start date in 'YYYY-MM-DD'
end_date: End date in 'YYYY-MM-DD'
sat: Satellite key for URL_TEMPLATES
output_dir: Directory to save files
lat_min, lat_max, lon_min, lon_max: Optional cropping bounds
concat: Save a single concatenated output
clean_raw: Delete raw files after processing
clean_cropped: Delete cropped files after processing

Returns

xarray.Dataset if concatenated, otherwise None

ocstrack.Observation.get_sat.get_multi_sat(start_date, end_date, sat_list, output_dir, lat_min=None, lat_max=None, lon_min=None, lon_max=None, concat=True, clean_raw=True, clean_cropped=True)

Run download and processing for multiple satellites.

Parameters

start_date: Start date in 'YYYY-MM-DD'
end_date: End date in 'YYYY-MM-DD'
sat: Satellite key for URL_TEMPLATES
output_dir: Directory to save files
lat_min, lat_max, lon_min, lon_max: Optional cropping bounds
concat: Save a single concatenated output
clean_raw: Delete raw files after processing

Returns

xarray.Dataset if concatenated, otherwise None

ocstrack.Observation.get_sat.download_sat_data(dates_str, url_template, raw_dir, sat, retries=1, delay=5)

This function downloads the satellite data

Parameters

dates_str: List with all the dates data will be downloaded for
url_template: from urls.py
raw_dir: path to where the raw sat data will be saved
retries: how many times will it try to download the data
delay: how long will it wait to try the download again

Returns

List of paths to the downlaoded satellite files.

ocstrack.Observation.get_sat.crop_sat_data(file_paths, cropped_dir, lat_min, lat_max, lon_min, lon_max)

Handles the satellite data cropping Crops and saves all the satellite data

Parameters

lat_min: float/int of mininum latitude
lat_max: float/int of maximum latitude
lon_min: float/int of mininum longitude
lon_max: float/int of maximum latitude

Returns

xarray object of the cropped data

Notes

Satellite data uses the -180 to 180 standard
If you want to change the longitudes, use util.convert_longitude(sat_data.lon,mode=?)

ocstrack.Observation.get_sat.concat_sat_data(datasets, output_path, sat)

Handles the satellite data concatenation Concat and saves all the satellite data on the datasets list

Parameters

datasets: List xr satellite data to be concatenated
output_path: path to where the concatenated data will be saved
sat: name of the satellite

Returns

xarray object of the concatenated data

ocstrack.Observation.get_sat.generate_daily_dates(start_date_str, end_date_str)

This function generates a list of formated dates between the start and end dates.

Parameters:

Name	Type	Description	Default
start_date_str	str	String with dates as 'YYYY-MM-DD'	required
end_date_str	str	String with dates as 'YYYY-MM-DD'	required

Returns:

Type	Description
List[str]	List of formated dates (daily).

ocstrack.Observation.get_sat.crop_by_box(dataset, lat_min, lat_max, lon_min, lon_max)

Crops xarray data based on lats and lons

Parameters

lat_min: float/int of mininum latitude
lat_max: float/int of maximum latitude
lon_min: float/int of mininum longitude
lon_max: float/int of maximum latitude

Returns

xarray object of the cropped data

Notes

Satellite data uses the -180 to 180 standard
If you want to cross the meridian, then pass a lon_min > lon_max

---

Data URLs

This module contains the base URLs for the data sources.

ocstrack.Observation.urls

Satellite data URLS