tessl/pypi-erddapy

Python interface for ERDDAP data servers that simplifies accessing scientific datasets

—

Pending

Overview

Eval results

Files

ERDDAP Client

Name: tessl/pypi-erddapy
Author: tessl

Core functionality for connecting to ERDDAP servers, searching datasets, and downloading data with flexible constraint-based filtering. The ERDDAP class serves as the main interface for all data operations.

Capabilities

ERDDAP Class Constructor

Creates an ERDDAP instance for a specific server endpoint, supporting both direct URLs and server shortcuts.

class ERDDAP:
    def __init__(
        self,
        server: str,
        protocol: str | None = None,
        response: str = "html"
    ):
        """
        Create ERDDAP instance for server endpoint.
        
        Parameters:
        - server: ERDDAP server URL or shortcut name from servers dictionary
        - protocol: 'tabledap' or 'griddap' data protocol
        - response: default response format ('html', 'csv', 'json', etc.)
        """

Usage Examples:

# Using full server URL
e = ERDDAP(server="https://gliders.ioos.us/erddap")

# Using server shortcut
e = ERDDAP(server="SECOORA", protocol="tabledap")

# Setting default response format
e = ERDDAP(server="NGDAC", protocol="tabledap", response="csv")

Dataset and Configuration Properties

Configure the ERDDAP instance with dataset ID, variables, constraints, and other settings.

class ERDDAP:
    @property
    def dataset_id(self) -> str: ...
    
    @dataset_id.setter  
    def dataset_id(self, value: str) -> None: ...
    
    # Configuration attributes
    server: str  # ERDDAP server URL
    protocol: str  # 'tabledap' or 'griddap'
    response: str  # Default response format
    constraints: dict  # Download constraints
    variables: list  # Variables to download
    dim_names: list  # Dimension names (griddap only)
    requests_kwargs: dict  # HTTP request options
    auth: tuple  # Authentication credentials

Usage Examples:

e = ERDDAP(server="SECOORA", protocol="tabledap")

# Set dataset
e.dataset_id = "edu_fau_himb_5a99_50c5_adb4"

# Configure constraints
e.constraints = {
    'time>=': '2020-01-01T00:00:00Z',
    'time<=': '2020-01-31T23:59:59Z',
    'latitude>=': 25.0,
    'latitude<=': 30.0,
}

# Set variables to download  
e.variables = ['temperature', 'salinity', 'time', 'latitude', 'longitude']

# Configure authentication if needed
e.auth = ('username', 'password')

URL Building Methods

Generate ERDDAP URLs for different types of data requests including search, metadata, categorization, and data download.

class ERDDAP:
    def get_search_url(
        self,
        response: str = None,
        search_for: str = None,
        protocol: str = None,
        items_per_page: int = 1000000, 
        page: int = 1,
        **kwargs
    ) -> str:
        """
        Build search URL for datasets.
        
        Parameters:
        - search_for: Search terms (supports Google-like syntax)
        - response: Response format ('html', 'csv', 'json')
        - protocol: 'tabledap' or 'griddap' 
        - items_per_page: Results per page
        - page: Page number
        - **kwargs: Additional search constraints (minLon, maxLon, etc.)
        
        Returns:
        - Search URL string
        """
    
    def get_info_url(
        self,
        dataset_id: str = None,
        response: str = None
    ) -> str:
        """
        Build info URL for dataset metadata.
        
        Parameters:
        - dataset_id: Dataset ID (uses instance dataset_id if None)
        - response: Response format ('html', 'csv', 'json')
        
        Returns:
        - Info URL string
        """
        
    def get_categorize_url(
        self,
        categorize_by: str,
        value: str = None,
        response: str = None
    ) -> str:
        """
        Build categorize URL for browsing by attributes.
        
        Parameters: 
        - categorize_by: Attribute to categorize by ('ioos_category', 'standard_name', etc.)
        - value: Specific attribute value
        - response: Response format
        
        Returns:
        - Categorize URL string
        """
        
    def get_download_url(
        self,
        dataset_id: str = None,
        protocol: str = None, 
        variables: list = None,
        dim_names: list = None,
        response: str = None,
        constraints: dict = None,
        distinct: bool = False
    ) -> str:
        """
        Build download URL with constraints.
        
        Parameters:
        - dataset_id: Dataset ID 
        - protocol: 'tabledap' or 'griddap'
        - variables: List of variables to download
        - dim_names: Dimension names (griddap only)
        - response: Response format
        - constraints: Constraint dictionary
        - distinct: Return only unique values
        
        Returns:
        - Download URL string
        """

Usage Examples:

# Search for glider datasets
search_url = e.get_search_url(
    search_for="glider temperature",
    response="csv",
    minLat=38.0,
    maxLat=42.0
)

# Get dataset metadata
info_url = e.get_info_url(dataset_id="whoi_406-20160902T1700", response="csv")

# Browse by category
cat_url = e.get_categorize_url("ioos_category", "Temperature")

# Build download URL with constraints
download_url = e.get_download_url(
    response="csv",
    constraints={'time>=': '2020-01-01T00:00:00Z'},
    distinct=True
)

GridDAP Initialization

Initialize constraints and variables for gridded datasets using GridDAP protocol.

class ERDDAP:
    def griddap_initialize(
        self,
        dataset_id: str = None,
        step: int = 1
    ) -> None:
        """
        Fetch dataset metadata and initialize griddap constraints.
        
        Parameters:
        - dataset_id: Dataset ID (uses instance dataset_id if None)
        - step: Step size for subsetting dataset
        """

Usage Example:

e = ERDDAP(server="SECOORA", protocol="griddap") 
e.dataset_id = "HYCOM_Region_7_Aggregation_best"
e.griddap_initialize()  # Automatically sets constraints and variables

# Check what was initialized
print("Available constraints:", e.constraints)
print("Available variables:", e.variables)
print("Dimension names:", e.dim_names)

Data Conversion Methods

Convert ERDDAP data directly to various Python data analysis formats.

class ERDDAP:
    def to_pandas(
        self,
        requests_kwargs: dict = None,
        **kwargs
    ):
        """
        Download data as pandas DataFrame.
        
        Parameters:
        - requests_kwargs: HTTP request options
        - **kwargs: Additional pandas.read_csv arguments
        
        Returns:
        - pandas.DataFrame with downloaded data
        """
        
    def to_xarray(
        self,
        requests_kwargs: dict = None,
        **kwargs
    ):
        """
        Download data as xarray Dataset.
        
        Parameters:
        - requests_kwargs: HTTP request options  
        - **kwargs: Additional xarray.open_dataset arguments
        
        Returns:
        - xarray.Dataset with downloaded data
        """
        
    def to_ncCF(
        self,
        protocol: str = None,
        **kwargs
    ):
        """
        Download data as netCDF4 Dataset.
        
        Parameters:
        - protocol: Override protocol ('tabledap' or 'griddap')
        - **kwargs: Additional netCDF4 arguments
        
        Returns:
        - netCDF4.Dataset with downloaded data
        """
        
    def to_iris(
        self,
        **kwargs
    ):
        """
        Download data as iris CubeList.
        
        Parameters:
        - **kwargs: Additional iris.load_raw arguments
        
        Returns:
        - iris.cube.CubeList with downloaded data
        """

Variable Discovery Methods

Discover and filter dataset variables by their attributes.

class ERDDAP:
    def get_var_by_attr(
        self,
        dataset_id: str = None,
        **kwargs
    ) -> list[str]:
        """
        Get variables matching specified attributes.
        
        Parameters:
        - dataset_id: Dataset ID (uses instance dataset_id if None)
        - **kwargs: Attribute name-value pairs to match
        
        Returns:
        - List of variable names matching criteria
        """

Usage Examples:

# Find variables by standard_name
temp_vars = e.get_var_by_attr(
    dataset_id="whoi_406-20160902T1700",
    standard_name="sea_water_temperature"
)

# Find coordinate variables
axis_vars = e.get_var_by_attr(
    dataset_id="whoi_406-20160902T1700", 
    axis=lambda v: v in ["X", "Y", "Z", "T"]
)

print("Temperature variables:", temp_vars)
print("Axis variables:", axis_vars)

File Download

Download datasets directly to files in various formats.

class ERDDAP:
    def download_file(
        self,
        file_type: str
    ) -> str:
        """
        Download dataset to file.
        
        Parameters:
        - file_type: File format extension (csv, netcdf, etc.)
        
        Returns:
        - Path to downloaded file
        """

Usage Example:

e.dataset_id = "whoi_406-20160902T1700"
e.constraints = {'time>=': '2020-01-01T00:00:00Z'}

# Download as CSV file
csv_file = e.download_file("csv")
print(f"Downloaded: {csv_file}")

# Download as NetCDF file  
nc_file = e.download_file("nc")
print(f"Downloaded: {nc_file}")

Constraint Format Examples

ERDDAP constraints use a dictionary format with comparison operators:

# Time constraints
constraints = {
    'time>=': '2020-01-01T00:00:00Z',
    'time<=': '2020-12-31T23:59:59Z',
}

# Spatial constraints  
constraints = {
    'latitude>=': 25.0,
    'latitude<=': 30.0,
    'longitude>=': -90.0,
    'longitude<=': -80.0,
}

# Relative constraints
constraints = {
    'time>': 'now-7days',
    'latitude<': 'min(longitude)+180',
    'depth>': 'max(depth)-23',
}

# Value constraints
constraints = {
    'station_id=': 'KBDI1',
    'sensor_depth<=': 100.0,
}

Install with Tessl CLI