Time Utilities

Calendars

Water-year and calendar-year reindexing for cftime-aware datasets.

elm_diagnostics.time.calendars.water_year(time_val, start_month=10)[source]

Compute the water year for a given time value.

A water year starting in October means that Oct 2014 - Sep 2015 is water year 2015.

Return type:

int

Parameters:

start_month (int)

elm_diagnostics.time.calendars.add_water_year_coord(ds, start_month=10, dim='time')[source]

Add a water_year coordinate to a dataset.

Parameters:

  • ds (Dataset) – Dataset with a time dimension.

  • start_month (int) – First month of the water year (default 10 = October).

  • dim (str) – Name of the time dimension.

Returns:

Dataset with an added water_year coordinate on the time dimension.

Return type:

Dataset

elm_diagnostics.time.calendars.select_year(ds, year, frame='calendar', start_month=10, dim='time')[source]

Select a single year from a dataset.

Parameters:

  • ds (Dataset)

  • year (int) – The year to select.

  • frame (str) – Whether to select by calendar year or water year.

  • start_month (int) – Only used when frame=’water_year’.

  • dim (str) – Name of the time dimension.

Return type:

Dataset

elm_diagnostics.time.calendars.get_available_years(ds, frame='calendar', start_month=10, dim='time')[source]

Return sorted list of complete years available in the dataset.

Return type:

list[int]

Parameters:
elm_diagnostics.time.calendars.subset_climo_years(da, climo_start_year, climo_end_year, dim='time')[source]

Subset a DataArray to a climatology year window.

Uses -1 as a sentinel for earliest/latest available year.

Return type:

DataArray

Parameters:
elm_diagnostics.time.calendars.day_of_year(time_val, start_month=1)[source]

Compute day-of-year, optionally offset by start_month.

For water-year-relative DOY, pass start_month=10.

Return type:

int

Parameters:

start_month (int)

Integration

Time-bounds-aware cumulative integration for flux variables.

elm_diagnostics.time.integration.get_time_deltas(ds, dim='time')[source]

Compute time step widths (in seconds) from time_bounds.

This is non-negotiable: we never assume uniform dt. The actual time_bounds widths are used for flux integration.

Parameters:

  • ds (Dataset) – Must contain time_bounds or time_bnds.

  • dim (str) – Name of the time dimension.

Returns:

Time deltas in seconds, with the same time coordinate.

Return type:

DataArray

elm_diagnostics.time.integration.cumulative_integral(da, ds, dim='time')[source]

Integrate a flux variable cumulatively over time using time_bounds.

Parameters:

  • da (DataArray) – Flux variable (units with /s, e.g. mm/s, gC/m2/s, W/m2).

  • ds (Dataset) – Parent dataset (needed for time_bounds).

  • dim (str) – Time dimension name.

Returns:

Cumulative integral. For mm/s input, result is in mm. For W/m2 input, result is in J/m2.

Return type:

DataArray

elm_diagnostics.time.integration.storage_change(da, dim='time')[source]

Compute dS/dt as a cumulative change from the first time step.

For state variables: dS(t) = S(t) - S(t=0).

Parameters:

  • da (DataArray) – State variable (e.g. SOILLIQ in kg/m2).

  • dim (str) – Time dimension name.

Returns:

S(t) - S(0), same units as input.

Return type:

DataArray