argopy Python Library

argopy provides a suite of tools designed to complement existing Argo quality control (QC) procedures. Instead of a single monolithic QC function, it offers elementary blocks to help you build a custom Python-based QC pipeline. These tools include:

• Argo file stores: Separates I/O operations from data analysis.
• OWC salinity calibration: Tools for data preprocessing related to Ocean Working Group (OWC) salinity calibration.
• Reference dataset access: Facilitated access to reference datasets for comparison.
• Topographic data: Access to topographic data specifically for trajectory analysis.
• CLS altimetry QC: Easy access to CLS altimetry QC test results.

Beyond basic fetching, argopy supports several advanced operations:

• Data Transformation: Convert data between collections of individual measurements and collections of vertical profiles.
• Interpolation: Interpolate irregularly sampled measurements onto standard pressure levels.
• Caching: Cache fetched data locally to speed up subsequent requests and save bandwidth.
• Local Fetching: Fetch data from a local copy of the Argo database instead of online servers.
• Metadata/Index Lookup: Fetch only metadata (organized in index lookup tables) to determine regional Argo sampling without downloading full measurement datasets.

Argopy provides several advanced capabilities for working with Argo data:

• Filtering: Apply filters at fetch time (standard vs expert modes, QC flags, etc.).
• Data Sources: Select between different sources like erddap, ftp, local, or argovis.
• Data Manipulation: Perform operations like interpolation, binning, and working with profiles or points.
• Visualisation: Generate trajectories, topography, and histograms.
• Quality Control: Access tools like OWC and specialized figures.
• Metadata: Access reference tables, deployment plans, topography, and DOIs.
• Performance: Utilize caching and parallel data fetching to improve speed.

The gdacfs class provides a generic file system interface for accessing Argo Global Data Assembly Centre (GDAC) files. It abstracts the underlying host protocol (local filesystem, HTTP, FTP, or S3), allowing you to write GDAC-agnostic code.

When you create a gdacfs instance, it returns a specific store (like httpstore or s3store) with a prefixed directory. This means you can access files using paths relative to the GDAC root without including the root URL or path in every call.

from argopy import gdacfs

# Create a GDAC-agnostic file system instance
fs = gdacfs("https://data-argo.ifremer.fr")

# Access files using paths relative to the GDAC root
fs.glob("dac/aoml/13857/*_meta.nc")

You can extend the Dataset.argo accessor by using the @register_argo_accessor decorator. This allows you to add custom methods and properties to Argo datasets, making them accessible via the .argo namespace.

from argopy.extensions import register_argo_accessor, ArgoAccessorExtension
import argopy
import numpy as np

@register_argo_accessor('floats')
class WorkWithWMO(ArgoAccessorExtension):
    """Example of a new Argo dataset feature"""

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self._uid = argopy.utils.to_list(np.unique(self._obj["PLATFORM_NUMBER"].values))

    @property
    def wmo(self):
        return self._uid

    @property
    def N(self):
         return len(self.wmo)

# Usage after registration:
# ds.argo.floats.N
# ds.argo.floats.wmo

The ArgoFloat class is a specialized store designed to facilitate loading and reading all Argo files associated with a specific WMO (World Meteorological Organization) float number. It handles transfer protocols and GDAC (Global Data Assembly Centre) path construction automatically, whether the data is hosted locally or remotely.

from argopy import ArgoFloat
WMO = 3902492
# Fetch profile data directly
ds = ArgoFloat(WMO).open_dataset('prof')

argopy can fetch data from three primary sources, each with different characteristics:

1. erddap (Default): Uses the Ifremer ERDDAP server. It is highly efficient because it only downloads the specific data requested. It is based on mono-profile files from the GDAC.
2. gdac: Accesses official Argo GDAC online servers (Ifremer or US HTTPS/FTP) or a local GDAC-compliant folder. This is useful for offline work or using a local mirror.
3. argovis: Uses the Argovis server, which provides curated Argo data (QC=1 only) and is updated daily.

To start using argopy, perform a standard import and reset options to ensure a clean state:

import argopy
from argopy import DataFetcher as ArgoDataFetcher
argopy.reset_options()

By default, argopy provides data as an xarray.Dataset or a pandas.DataFrame. You can explicitly switch between these formats using the to_dataframe() or to_xarray() methods on a DataFetcher instance. This allows you to choose the data structure that best fits your specific analysis workflow.

Internally, argopy also utilizes pyarrow.Table for data handling.

from argopy import DataFetcher

# Fetch a profile and convert it to a pandas DataFrame
DataFetcher().profile(6902746, 34).to_dataframe()

Argopy includes local copies of NVS data so it can function offline. When offline, the data reflects the state at the time of the Argopy release. When online, it queries the NVS server directly.

To configure online access, you can use the argopy.stores.NVS class with the following options:

• nvs: The URL of the server.
• cache: Boolean to enable/disable caching.
• cachedir: Directory for cached files.
• api_timeout: HTTP request timeout in seconds.

Note: The NVS class is a singleton. Options must be defined during the first instantiation in a session to take effect.

from argopy.stores import NVS

# Initialize the NVS store (singleton)
nvs = NVS(cache=True, cachedir='./cache')

# Load vocabularies
nvs.load_vocabulary('R27')

# Load specific concepts
nvs.load_concept('AANDERAA_OPTODE_3835')

# Load mappings
nvs.load_mapping('R24', 'R23')