time_series

Module time_series contains ...

get_item(ens_fc_ts, i, convert_to_xr=True)

Gets an item in an indexable uchronia object

Gets an item in an indexable uchronia object of one of the the C++ uchronia types identifed by TIME_SERIES_PTR, ENSEMBLE_PTR_TIME_SERIES_PTR, or ENSEMBLE_FORECAST_TIME_SERIES_PTR.

Parameters:

Name	Type	Description	Default
ens_fc_ts	NdTimeSeries	a uni- or multidimensional time series	required
i	int	One-based index in the indexable object.	required
convert_to_xr	bool	if True, (try to) convert to an xarray object	True

Returns:

Type	Description
Union[ItemSliceNdTimeSeries, xr.DataArray]	Union["ItemSliceNdTimeSeries", xr.DataArray]: one item extracted from the series, so it has lost one dimension compared to the input.

Example

TODO

Source code in uchronia/time_series.py

def get_item(ens_fc_ts: "NdTimeSeries", i, convert_to_xr=True) -> Union["ItemSliceNdTimeSeries", xr.DataArray]:
    """
    Gets an item in an indexable uchronia object

    Gets an item in an indexable uchronia object of one of the the C++ uchronia types identifed by TIME_SERIES_PTR,
    ENSEMBLE_PTR_TIME_SERIES_PTR, or ENSEMBLE_FORECAST_TIME_SERIES_PTR.

    Args:
        ens_fc_ts (NdTimeSeries): a uni- or multidimensional time series
        i (int): One-based index in the indexable object.
        convert_to_xr (bool): if True, (try to) convert to an xarray object

    Returns:
        Union["ItemSliceNdTimeSeries", xr.DataArray]: one item extracted from the series, so it has lost one dimension compared to the input.

    Example:
        TODO

    """
    #    \dontrun{
    #    ensFcTs <- createEnsembleForecastTimeSeries(lubridate::origin, 3, 'daily')
    #    fcastsOffset <- lubridate::hours(1)
    #    nLead <- 5
    #    nEns <- 4
    #    set.seed(465)
    #    x <- matrix(rnorm(n=nEns*nLead), ncol=nEns)
    #    multiTimeSeriesIn <- mkHourlySeries(lubridate::origin + fcastsOffset, x, is.na)
    #    uchronia::setItem(ensFcTs, 1, multiTimeSeriesIn)
    #    print(x)
    #    print(uchronia::getItem(ensFcTs, 1))
    #    }
    if not isinstance(i, int):
        raise ValueError("Only numeric indices are supported for now")
    zero_index = i - 1
    if is_singular_time_series(ens_fc_ts):
        return uwg.GetValueFromUnivariateTimeSeries_py(ens_fc_ts, zero_index)
    elif is_ensemble_time_series(ens_fc_ts):
        univ_ts = uwg.TimeSeriesFromEnsembleOfTimeSeries_py(ens_fc_ts, zero_index)
        if convert_to_xr:
            univ_ts = as_xarray(univ_ts)
        return univ_ts
    elif is_time_series_of_ensemble_time_series(ens_fc_ts):
        mts = uwg.GetItemEnsembleForecastTimeSeries_py(ens_fc_ts, zero_index)
        if convert_to_xr:
            mts = as_xarray(mts)
        return mts
    else:
        raise ValueError(
            'get_item: does not know how to get from an object of external type "'
            + ens_fc_ts.type_id,
            '"',
        )

mk_date(year, month, day, hour=0, min=0, sec=0, tz='UTC')

Creates a pandas Timestamp date/time object

Creates a pandas Timestamp date/time object, with a default UTC time zone and zeroes as default time arguments (i.e. midnight)

Parameters:

Name	Type	Description	Default
year	int	integer	required
month	int	integer	required
day	int	integer	required
hour	int	integer	0
min	int	integer	0
sec	int	numeric	0
tz	str	character, A time zone specification to be used for the conversion. Defaults to UTC.	'UTC'

Returns:

Type	Description
	a pandas Timestamp date/time object

Source code in uchronia/time_series.py

def mk_date(year, month, day, hour=0, min=0, sec=0, tz="UTC"):
    """
    Creates a pandas Timestamp date/time object

    Creates a pandas Timestamp date/time object, with a default UTC time zone and zeroes as default time arguments (i.e. midnight)

    Args:
        year (int): integer
        month (int): integer
        day (int): integer
        hour (int): integer
        min (int): integer
        sec (int): numeric
        tz (str): character, A time zone specification to be used for the conversion. Defaults to UTC.

    Returns:
        a pandas Timestamp date/time object

    """
    return pd.Timestamp(
        year=year, month=month, day=day, hour=hour, minute=min, second=sec, tz=tz
    )

sub_identifiers(data_library, identifier)

Gets the next level data identifier of a top level ID

Gets the next level data identifier of a top level ID. A collection of time series such as one identified by "streamflows" may have sub-identifiers such as gauge numbers. A single time series in a data library may thus be retrieved by a hierarchical string ID "streamflows.401221" 401221 is a gauge ID.

Parameters:

Name	Type	Description	Default
data_library	TimeSeriesLibrary	external pointer type ENSEMBLE_DATA_SET_PTR, or a Python class wrapper around it	required
identifier	str	character, the top level identifier to test again for next level ids	required

Returns:

Type	Description
List[str]	List[str] sub-identifiers for a root identifier

Source code in uchronia/time_series.py

def sub_identifiers(data_library: "TimeSeriesLibrary", identifier:str) -> List[str]:
    """
    Gets the next level data identifier of a top level ID

    Gets the next level data identifier of a top level ID.
    A collection of time series such as one identified by "streamflows" may have
    sub-identifiers such as gauge numbers. A single time series in a data library
    may thus be retrieved by a hierarchical string ID  "streamflows.401221" 401221 is a gauge ID.

    Args:
        data_library (TimeSeriesLibrary): external pointer type ENSEMBLE_DATA_SET_PTR, or a Python class wrapper around it 
        identifier (str): character, the top level identifier to test again for next level ids

    Returns:
        List[str] sub-identifiers for a root identifier

    """
    return uwg.GetEnsembleDatasetDataSubIdentifiers_py(data_library, identifier)