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), preferring adjusted values where available.

psal property

Return salinity (PSU), preferring adjusted values where available.

temp property

Return temperature (°C), preferring adjusted values where available.

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

The SatelliteData class handles files from both supported satellite data sources. The format is detected automatically — the collocation workflow is identical regardless of the source.

ocstrack.Observation.satellite.SatelliteData

Unified satellite altimetry data handler.

Loads a NetCDF file produced by either the CoastWatch (NOAA STAR) or the ESA CCI Sea State (IFREMER) pipeline and exposes a consistent interface for use with the :class:~ocstrack.Collocation.collocate.Collocate engine.

The data source format is detected automatically. The following coordinates are always available: time, lat, lon.

Wave height variables (accessed as properties) depend on what is present in the file and are never None only if the variable actually exists:

• swh — always required.
• swh_adjusted — CCI only (when present).
• swh_with_8m_offset_correction — CCI only (when present).
• sla — CoastWatch only (when present).
• source — CoastWatch only (when present).

Parameters

filepath : str Path to the satellite NetCDF file.

Raises

ValueError If required coordinates (time, lat, lon) or the primary swh variable are missing from the dataset.

Examples

CoastWatch data::

sat = SatelliteData('/path/to/multisat_cropped_2019-07-30_2019-08-03.nc')
print(sat.source)   # array of satellite names

CCI data::

sat = SatelliteData('/path/to/concat_cci_cropped_jason-3_2023-01-16_2023-01-31.nc')
print(sat.swh_with_8m_offset_correction)  # not capped at 8 m
print(sat.swh_quality_level)              # quality flags

bathymetry property

Return bathymetry values as a NumPy array, or None if not present.

Available in CCI files only.

data_source property

Return the detected data source format: 'coastwatch' or 'cci'.

distance_to_coast property

Return distance-to-coast values as a NumPy array, or None if not present.

Available in CCI files only.

lat property writable

Return latitude values as a NumPy array.

lon property writable

Return longitude values as a NumPy array.

sla property

Return sea level anomaly (SLA) as a NumPy array, or None if not present.

Available in CoastWatch files only.

source property

Return the satellite source identifier as a NumPy array, or None if not present.

Available in CoastWatch files only.

swh property

Return significant wave height (SWH) as a NumPy array.

swh_adjusted property

Return denoised/adjusted SWH as a NumPy array, or None if not present.

Available in CCI files only.

swh_quality_level property

Return SWH quality level flags as a NumPy array, or None if not present.

Available in CCI files only. Higher values generally indicate better quality.

swh_uncertainty property

Return SWH uncertainty as a NumPy array, or None if not present.

Available in CCI files only.

swh_with_8m_offset_correction property

Return SWH with 8 m offset correction as a NumPy array, or None if not present.

This variable is not capped at 8 m and is recommended for extreme wave event analysis. Available in CCI files only.

time property

Return time values as a NumPy array.

filter_by_time(start_date, end_date)

Filter the dataset to a specific time range (in-place).

Parameters

start_date : str ISO 8601 start date string (e.g. '2023-01-16'). end_date : str ISO 8601 end date string (e.g. '2023-01-31').

---

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, shape=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.

Spatial cropping can be specified either as a bounding box (lat_min/lat_max/lon_min/lon_max) or as a polygon / shapefile (shape). If both are provided a ValueError is raised.

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 bounding-box cropping bounds. Mutually exclusive with shape. shape : str, dict, or shapely geometry, optional Alternative polygon/shapefile for spatial cropping. Accepts a shapefile path (.shp), a GeoJSON-like dict, or any shapely Polygon / MultiPolygon. Mutually exclusive with the bounding box arguments. Requires shapely (and geopandas for shapefile paths). Install with pip install "ocstrack[geo]". 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.

Raises

ValueError If both bounding-box arguments and shape are provided.

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 — CoastWatch (NOAA STAR)

Daily merged NetCDF files from the NOAA STAR CoastWatch program. No credentials required. Note that CoastWatch SWH is capped at 8 m and old data may be removed without notice.

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

ocstrack.Observation.get_sat_coastwatch.get_per_sat_coastwatch(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. Punctuation/case-insensitive
    (e.g. 'jason3', 'jason-3', 'Jason_3' all resolve to the same
    satellite).
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_coastwatch.get_multi_sat_coastwatch(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_coastwatch.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_coastwatch.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_coastwatch.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_coastwatch.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_coastwatch.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

Satellite Data Acquisition — ESA CCI Sea State v5 (IFREMER)

Along-track per-pass files from the ESA Climate Change Initiative Sea State project, served from the IFREMER FTP server. No SWH cap; stable long-term archive. Credentials required — register at https://eftp.ifremer.fr.

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

!!! warning FTP credentials are required. Never hard-code them in scripts. Use environment variables instead: bash export CCI_FTP_USER="your_username" export CCI_FTP_PASS="your_password"

ocstrack.Observation.get_sat_cci.get_per_sat_cci(start_date, end_date, sat, output_dir, ftp_user, ftp_pass, lat_min=None, lat_max=None, lon_min=None, lon_max=None, shape=None, keep_vars=None, sensor_type='altimeter', max_parallel=4, concat=True, clean_raw=False, clean_cropped=False, version=CCI_FTP_VERSION)

Download, crop, and optionally merge ESA CCI Sea State data for one satellite.

This mirrors the get_per_sat_coastwatch workflow for CoastWatch data.

Parameters

start_date : str Start date in 'YYYY-MM-DD' format. end_date : str End date in 'YYYY-MM-DD' format. sat : str Satellite key. For altimeters use keys from CCI_ALTIMETERS (e.g. 'jason-3', 'sentinel-3a'). For SAR use keys from CCI_SARS (e.g. 'sentinel-1a'). output_dir : str or path-like Root directory for all output files. ftp_user : str IFREMER FTP username. Register at https://eftp.ifremer.fr. ftp_pass : str IFREMER FTP password. lat_min, lat_max, lon_min, lon_max : float, optional Bounding box for spatial cropping. If all four are provided, a box crop is performed. Mutually exclusive with shape. shape : str, dict, or shapely geometry, optional Alternative polygon/shapefile for spatial cropping. Mutually exclusive with the bounding box arguments. Requires shapely (and geopandas for shapefile paths). keep_vars : list of str, optional Variables to retain in merged output. Defaults to CCI_KEEP_VARS. sensor_type : str, optional 'altimeter' (default) or 'sar'. max_parallel : int, optional Maximum simultaneous FTP downloads (keep <= 5). concat : bool, optional If True (default), save a single merged NetCDF file. clean_raw : bool, optional Delete raw per-pass files after processing (default False). clean_cropped : bool, optional Delete cropped files after merging (default False). version : str, optional CCI product version (default '5').

Returns

xr.Dataset or None Merged dataset if concat=True, otherwise None.

Raises

ValueError If FTP credentials are missing or the satellite key is not recognised.

ocstrack.Observation.get_sat_cci.get_multi_sat_cci(start_date, end_date, sat_list, output_dir, ftp_user, ftp_pass, lat_min=None, lat_max=None, lon_min=None, lon_max=None, shape=None, keep_vars=None, sensor_type='altimeter', max_parallel=4, concat=True, clean_raw=True, clean_cropped=True, version=CCI_FTP_VERSION)

Download, crop, and merge ESA CCI Sea State data for multiple satellites.

This mirrors the get_multi_sat_coastwatch workflow for CoastWatch data.

Parameters

start_date : str Start date in 'YYYY-MM-DD' format. end_date : str End date in 'YYYY-MM-DD' format. sat_list : list of str List of satellite keys (see get_per_sat_cci for valid values). output_dir : str or path-like Root directory for all output files. ftp_user : str IFREMER FTP username. Register at https://eftp.ifremer.fr. ftp_pass : str IFREMER FTP password. lat_min, lat_max, lon_min, lon_max : float, optional Bounding box for spatial cropping. shape : str, dict, or shapely geometry, optional Alternative polygon/shapefile for spatial cropping. keep_vars : list of str, optional Variables to retain. Defaults to CCI_KEEP_VARS. sensor_type : str, optional 'altimeter' (default) or 'sar'. max_parallel : int, optional Maximum simultaneous FTP downloads (keep <= 5). concat : bool, optional If True (default), save a merged multi-satellite NetCDF file. clean_raw : bool, optional Delete raw per-pass files after processing (default True). clean_cropped : bool, optional Delete per-satellite cropped files after merging (default True). version : str, optional CCI product version (default '5').

Returns

xr.Dataset or None Merged multi-satellite dataset, or None if no data was processed.

Raises

ValueError If FTP credentials are missing.

ocstrack.Observation.get_sat_cci.download_cci_data(start_date, end_date, sat_ftp_name, raw_dir, ftp_user, ftp_pass, sensor_type='altimeter', max_parallel=4, version=CCI_FTP_VERSION)

Download ESA CCI Sea State per-pass NetCDF files from the IFREMER FTP server.

Parameters

start_date : str Start date in 'YYYY-MM-DD' format. end_date : str End date in 'YYYY-MM-DD' format. sat_ftp_name : str The FTP directory name for the satellite (e.g. 'jason-3'). Use values from CCI_ALTIMETERS or CCI_SARS in urls.py. raw_dir : str Local directory where raw files will be saved. ftp_user : str IFREMER FTP username. Register at https://eftp.ifremer.fr. ftp_pass : str IFREMER FTP password. sensor_type : str, optional 'altimeter' (default) or 'sar'. max_parallel : int, optional Maximum simultaneous downloads (keep <= 5 to avoid server limits). version : str, optional CCI product version (default '5').

Returns

list of str Paths to all successfully downloaded (or already existing) local files.

Raises

ValueError If FTP credentials are not provided.

ocstrack.Observation.get_sat_cci.crop_cci_data(file_paths, cropped_dir, lat_min, lat_max, lon_min, lon_max, keep_vars=None)

Crop a list of CCI per-pass NetCDF files to a bounding box and retain only the variables needed for collocation.

Parameters

file_paths : list of str Paths to raw CCI NetCDF files. cropped_dir : str Directory to save cropped files. lat_min, lat_max, lon_min, lon_max : float Bounding box for spatial cropping. keep_vars : list of str, optional Variables to retain. Defaults to CCI_KEEP_VARS.

Returns

list of xr.Dataset Non-empty cropped datasets.

ocstrack.Observation.get_sat_cci.crop_cci_data_by_shape(file_paths, cropped_dir, shape, keep_vars=None)

Crop a list of CCI per-pass NetCDF files to a polygon / shapefile.

Parameters

file_paths : list of str Paths to raw CCI NetCDF files. cropped_dir : str Directory to save cropped files. shape : str, dict, or shapely geometry Bounding shape. See :func:ocstrack.Observation.get_sat_coastwatch.crop_by_shape for accepted formats. keep_vars : list of str, optional Variables to retain. Defaults to CCI_KEEP_VARS.

Returns

list of xr.Dataset Non-empty cropped datasets.

ocstrack.Observation.get_sat_cci.concat_cci_data(datasets, output_path, sat)

Concatenate a list of CCI datasets along the time dimension.

Parameters

datasets : list of xr.Dataset Cropped (or raw) CCI datasets for a single satellite. output_path : str Path where the merged NetCDF file will be saved. sat : str Satellite name used to set the source coordinate.

Returns

xr.Dataset or None The merged dataset, or None if concatenation fails.

---

Data URLs

This module contains the base URLs and FTP configuration for all data sources.

ocstrack.Observation.urls

Satellite data URLS

resolve_sat_key(key, lookup)

Resolve a user-supplied satellite key against a lookup dictionary, tolerating punctuation and case differences.

An exact match is tried first; failing that, both the input and the dictionary keys are canonicalized (see :func:_canonical_sat_key) and compared. This means CoastWatch-style keys (e.g. 'jason3') and CCI-style keys (e.g. 'jason-3') are interchangeable for the caller.

Parameters

key : str The user-supplied satellite key. lookup : dict The mapping of valid satellite keys (e.g. URL_TEMPLATES for CoastWatch or CCI_ALTIMETERS for CCI).

Returns

str The matching key as it appears in lookup.

Raises

ValueError If no exact or canonical match is found.