Utilities#

The utilities module provides helper functions for data conversion and manipulation, primarily focused on pandas integration.

Overview#

The utilities module currently provides pandas integration helpers that enable conversion of API responses to pandas DataFrames. This is an optional feature requiring pandas installation.

pandas Integration#

The pandas_helpers module provides decorators and utilities for converting Pydantic models to pandas DataFrames.

Installation:

To use pandas features, install with the recommended extras:

pip install "sgu-client[recommended]"

Usage Example:

from sgu_client import SGUClient

client = SGUClient()

# Get data
measurements = client.levels.observed.get_measurements(limit=1000)

# Convert to DataFrame
df = measurements.to_dataframe()

# Now you can use pandas for analysis
print(df.describe())
print(df.groupby('station_id')['water_level'].mean())

Features:

  • Automatic flattening of nested GeoJSON structures

  • Geometry coordinates expanded to separate columns (longitude, latitude)

  • Properties flattened to top-level DataFrame columns

  • Datetime parsing for temporal analysis

  • Optional dependency - graceful error if pandas not installed

API Documentation#

Pandas utilities with optional dependency handling.

exception sgu_client.utils.pandas_helpers.PandasImportError(feature='this feature')[source]#

Bases: ImportError

Raised when pandas functionality is used but pandas is not installed.

Parameters:

feature (str)

__init__(feature='this feature')[source]#
Parameters:

feature (str)

sgu_client.utils.pandas_helpers.check_pandas_available(feature='this feature')[source]#

Check if pandas is available and raise helpful error if not.

Parameters:

feature (str) – Description of the feature that requires pandas

Raises:

PandasImportError – If pandas is not available

Return type:

None

sgu_client.utils.pandas_helpers.get_pandas()[source]#

Get pandas module with proper error handling.

Return type:

Any

Returns:

The pandas module

Raises:

PandasImportError – If pandas is not available

sgu_client.utils.pandas_helpers.optional_pandas_method(feature_name)[source]#

Decorator to mark methods that require pandas.

Parameters:

feature_name (str)

DataFrame Conversion Details#

When converting API responses to DataFrames:

  1. GeoJSON Features: Each feature becomes a DataFrame row

  2. Geometry: Coordinates extracted to longitude, latitude columns (and altitude if 3D)

  3. Properties: All properties flattened to top-level columns

  4. Metadata: Collection-level metadata (links, timestamps) excluded

Example Structure:

# Original GeoJSON structure
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {"type": "Point", "coordinates": [15.5, 58.3]},
            "properties": {"station_id": "95_2", "water_level": 45.3}
        }
    ]
}

# Converted DataFrame
#    longitude  latitude  station_id  water_level
# 0       15.5      58.3        95_2         45.3

See Also#