tessl/pypi-xclim
Climate indices computation package based on Xarray with extensive climate analysis capabilities
utilities.mddocs/
Utilities and Configuration
Core utilities for units handling, calendar operations, missing data management, and global configuration. These utilities provide the foundation for XClim's robust climate data processing capabilities.
Capabilities
Units Operations
Unit handling and conversion utilities for climate data processing with automatic CF-compliant unit management.
def convert_units_to(da, target, context="none"):
"""
Convert data array to target units.
Parameters:
- da: xr.DataArray, input data with units attribute
- target: str, target unit specification (e.g., "degC", "mm/day")
- context: str, unit conversion context (default "none")
Returns:
xr.DataArray: Data converted to target units
"""
def check_units(da, expected):
"""
Check if data array has expected units.
Parameters:
- da: xr.DataArray, input data to check
- expected: str or list, expected unit(s)
Raises:
ValidationError: If units don't match expected
"""
def ensure_cf_units(da):
"""
Ensure data array has CF-compliant units.
Parameters:
- da: xr.DataArray, input data
Returns:
xr.DataArray: Data with CF-compliant units
"""
def infer_sampling_units(freq):
"""
Infer temporal sampling units from frequency string.
Parameters:
- freq: str, frequency string (e.g., "D", "MS", "YS")
Returns:
str: Inferred temporal units
"""
def str2pint(unit_str):
"""
Parse unit string to pint Quantity.
Parameters:
- unit_str: str, unit specification
Returns:
pint.Quantity: Parsed unit quantity
"""
def units2pint(units):
"""
Convert various unit specifications to pint units.
Parameters:
- units: str, pint.Unit, or pint.Quantity, unit specification
Returns:
pint.Unit: Standardized pint unit
"""Calendar Operations
Calendar handling and conversion utilities for different calendar systems used in climate models.
def convert_calendar(da, target_calendar, align_on="date", **kwargs):
"""
Convert data array to different calendar system.
Parameters:
- da: xr.DataArray, input data with time coordinate
- target_calendar: str, target calendar ("standard", "noleap", "360_day", etc.)
- align_on: str, alignment method ("date", "year", "random")
- **kwargs: additional conversion parameters
Returns:
xr.DataArray: Data converted to target calendar
"""
def get_calendar(da):
"""
Get calendar type from data array time coordinate.
Parameters:
- da: xr.DataArray, input data with time coordinate
Returns:
str: Calendar type ("standard", "noleap", "360_day", etc.)
"""
def common_calendar(calendars):
"""
Find common calendar from list of calendar types.
Parameters:
- calendars: list, calendar type strings
Returns:
str: Common calendar type
"""
def datetime_to_decimal_year(dt):
"""
Convert datetime to decimal year representation.
Parameters:
- dt: datetime-like, input datetime
Returns:
float: Decimal year value
"""
def days_in_year(year, calendar="standard"):
"""
Get number of days in year for specified calendar.
Parameters:
- year: int, year value
- calendar: str, calendar type (default "standard")
Returns:
int: Number of days in year
"""
def max_doy(calendar="standard"):
"""
Maximum day of year for calendar type.
Parameters:
- calendar: str, calendar type (default "standard")
Returns:
int: Maximum day of year (365, 366, or 360)
"""
def percentile_doy(percentiles, calendar="standard"):
"""
Day of year percentiles for calendar type.
Parameters:
- percentiles: list, percentile values (0-100)
- calendar: str, calendar type
Returns:
list: Day of year values for percentiles
"""
def resample_doy(da, doy, **kwargs):
"""
Resample data by day of year.
Parameters:
- da: xr.DataArray, input data with time coordinate
- doy: int or list, day(s) of year to select
- **kwargs: additional resampling parameters
Returns:
xr.DataArray: Resampled data for specified days of year
"""
def within_bnds_doy(doy, bnds, calendar="standard"):
"""
Check if day of year is within bounds.
Parameters:
- doy: int, day of year to check
- bnds: tuple, (start, end) day of year bounds
- calendar: str, calendar type
Returns:
bool: True if day of year is within bounds
"""Missing Data Management
Missing data validation and handling for robust climate analysis.
class MissingBase:
"""
Base class for missing data validators.
Provides interface for custom missing data validation logic.
"""
def is_missing(self, data, freq):
"""
Determine if data has missing values based on criteria.
Parameters:
- data: xr.DataArray, input data to validate
- freq: str, resampling frequency
Returns:
xr.DataArray: Boolean array indicating missing periods
"""
class AtLeastNValid(MissingBase):
"""
Validator requiring at least N valid values.
Parameters:
- n: int, minimum number of valid values required
"""
def __init__(self, n):
self.n = n
class AnyMissing(MissingBase):
"""
Validator that flags any missing data as invalid.
Strictest validation - requires complete data.
"""
class AllMissing(MissingBase):
"""
Validator that only flags periods with all missing data.
Most permissive validation.
"""
class FromContext(MissingBase):
"""
Validator that uses context-dependent missing data rules.
Parameters:
- context: str, validation context name
"""
def __init__(self, context):
self.context = context
class Percentage(MissingBase):
"""
Validator requiring minimum percentage of valid data.
Parameters:
- pct: float, minimum percentage of valid data (0-100)
"""
def __init__(self, pct):
self.pct = pct
class SkipMissing(MissingBase):
"""
Validator that skips missing data validation entirely.
Allows computation to proceed regardless of missing data.
"""Global Configuration
Global options and settings management for XClim behavior customization.
def set_options(**kwargs):
"""
Set global XClim options.
Available options:
- metadata_locales: list, locales for metadata translation
- cf_compliance: str, CF compliance level ("strict", "warn", "log")
- data_validation: str, data validation level ("strict", "warn", "log")
- missing_options: dict, missing data handling options
- check_missing: str, missing data checking ("any", "wmo", "percent", "skip")
Parameters:
- **kwargs: option names and values to set
Examples:
set_options(cf_compliance="warn", check_missing="wmo")
set_options(metadata_locales=["en", "fr"])
"""
def get_options():
"""
Get current global XClim options.
Returns:
dict: Current option values
"""
def reset_options():
"""
Reset all options to default values.
"""
def register_option(name, default_value, validator=None, doc=None):
"""
Register a new global option.
Parameters:
- name: str, option name
- default_value: any, default value for option
- validator: callable, validation function (optional)
- doc: str, documentation string (optional)
"""
def unregister_option(name):
"""
Remove a registered option.
Parameters:
- name: str, option name to remove
"""Data Validation and Quality Flags
Data quality assessment and flag generation for climate data QC.
def data_flags(data, checks=None, **kwargs):
"""
Generate data quality flags based on various checks.
Parameters:
- data: xr.DataArray or xr.Dataset, input climate data
- checks: list, quality check names to apply
- **kwargs: additional parameters for specific checks
Returns:
xr.DataArray: Data quality flag array
"""
def temperature_warnings(tasmin, tasmax, **kwargs):
"""
Generate warnings for temperature data quality issues.
Parameters:
- tasmin: xr.DataArray, minimum temperature data
- tasmax: xr.DataArray, maximum temperature data
- **kwargs: threshold parameters for warnings
Returns:
xr.DataArray: Temperature warning flags
"""
def precipitation_warnings(pr, **kwargs):
"""
Generate warnings for precipitation data quality issues.
Parameters:
- pr: xr.DataArray, precipitation data
- **kwargs: threshold parameters for warnings
Returns:
xr.DataArray: Precipitation warning flags
"""
def wind_warnings(sfcwind, **kwargs):
"""
Generate warnings for wind data quality issues.
Parameters:
- sfcwind: xr.DataArray, surface wind speed data
- **kwargs: threshold parameters for warnings
Returns:
xr.DataArray: Wind warning flags
"""
def ecad_compliant(data, **kwargs):
"""
Check ECAD (European Climate Assessment & Dataset) compliance.
Parameters:
- data: xr.DataArray, input climate data
- **kwargs: compliance checking parameters
Returns:
bool: True if data meets ECAD standards
"""Usage Examples
Unit Conversion
import xarray as xr
from xclim.core import units
# Load temperature data in Kelvin
ds = xr.tutorial.open_dataset("air_temperature")
tas_k = ds.air.rename("tas")
tas_k.attrs["units"] = "K"
# Convert to Celsius
tas_c = units.convert_units_to(tas_k, "degC")
# Check units
units.check_units(tas_c, "degC") # No error if correct
# Convert precipitation units
pr = ds.precip.rename("pr") if "precip" in ds else None
if pr is not None:
pr.attrs["units"] = "kg m-2 s-1"
pr_mm = units.convert_units_to(pr, "mm/day")Calendar Operations
from xclim.core import calendar
# Check calendar type
cal_type = calendar.get_calendar(tas_k)
print(f"Calendar: {cal_type}")
# Convert to no-leap calendar
tas_noleap = calendar.convert_calendar(tas_k, "noleap", align_on="date")
# Work with day of year
max_day = calendar.max_doy("360_day") # Returns 360
percentiles = calendar.percentile_doy([25, 50, 75], "noleap")Missing Data Validation
from xclim.core.missing import AtLeastNValid, Percentage
# Create validators
validator_5days = AtLeastNValid(5) # Need at least 5 valid days
validator_80pct = Percentage(80) # Need 80% valid data
# Use with indicators (example)
import xclim.atmos as xca
# Apply strict validation
xca.tg_mean.missing = validator_5days
result = xca.tg_mean(tas_c, freq="MS") # Monthly with validationGlobal Configuration
import xclim
# Set global options
xclim.set_options(
cf_compliance="warn", # Warn about CF compliance issues
check_missing="wmo", # Use WMO missing data standards
metadata_locales=["en", "fr"] # English and French metadata
)
# Check current options
options = xclim.get_options()
print(options)
# Reset to defaults
xclim.reset_options()Data Quality Checking
from xclim.core import dataflags
# Generate quality flags
flags = dataflags.data_flags(
{"tasmin": tasmin, "tasmax": tasmax},
checks=["temperature_coherence", "valid_range"]
)
# Temperature-specific warnings
temp_warnings = dataflags.temperature_warnings(tasmin, tasmax)
# Check for common issues
if temp_warnings.any():
print("Temperature data quality issues detected")