earthkit.data.field.component.time¶

Classes¶

`AnalysisTime`	Field time component for analyses.
`EmptyTime`	A TimeBase object representing an empty time component.
`ForecastTime`	Field time component for forecasts.
`MonthlyForecastTime`	Field time component for monthly forecasts.
`TimeBase`	Base class for time component of a field.

Functions¶

create_time(d)

Create a TimeBase object from a dictionary.

Module Contents¶

class earthkit.data.field.component.time.AnalysisTime(valid_datetime=None)¶

Bases: TimeBase

Field time component for analyses.

Parameters:: valid_datetime (datetime.datetime, optional) – The valid datetime of the analysis. Default is None.

aliases()¶: Return the aliases in the component.

abstractmethod base_date()¶

Return the date part of the base_datetime().

Returns:: The date part of the base datetime.
Return type:: datetime.date

base_datetime()¶

Return the base datetime of the time object.

This is the same as the valid datetime for analysis time.

Returns:: The base datetime of the time object.
Return type:: datetime.datetime

abstractmethod base_time()¶

Return the time part of the base_datetime().

Returns:: The time part of the base datetime.
Return type:: datetime.time

forecast_month()¶

Return the forecast month.

For analysis time, the forecast month is not defined, so return None.

forecast_period()¶

forecast_reference_time()¶

classmethod from_dict(d)¶

Create a FieldComponent instance from a dictionary.

Parameters:: d (dict) – Dictionary containing specification data.
Returns:: The created FieldComponent instance.
Return type:: FieldComponent

classmethod from_valid_datetime(*, valid_datetime=None)¶

Create an AnalysisTime object from a valid datetime.

Parameters:: valid_datetime (datetime.datetime)
Returns:: The created AnalysisTime instance.
Return type:: AnalysisTime

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

indexing_datetime()¶

Return the indexing datetime.

For analysis time, the indexing datetime is not defined, so return None.

keys()¶: Return the available keys in the component.

set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

*args – Positional arguments.
**kwargs – Keyword arguments.

Returns:

The created FieldComponent instance.

Return type:

FieldComponent

Raises:

KeyError – If any of the keys to be set are not supported.

step()¶

Return the forecast period of the time object.

For analysis time, the step is not defined, so return None.

to_dict()¶: Return a dictionary representation of the time object.

valid_datetime()¶: Return the valid datetime of the time object.

class earthkit.data.field.component.time.EmptyTime¶

Bases: TimeBase

A TimeBase object representing an empty time component.

aliases()¶: Return the aliases in the component.

base_date()¶

Return the date part of the base_datetime().

Returns:: The date part of the base datetime.
Return type:: datetime.date

base_datetime()¶

Return the base datetime.

The base datetime is the datetime from which a forecast is made. For analysis data, the base datetime is the same as the valid datetime.

Returns:: The base datetime of the time object.
Return type:: datetime.datetime

base_time()¶

Return the time part of the base_datetime().

Returns:: The time part of the base datetime.
Return type:: datetime.time

forecast_month()¶

Return the forecast month.

Returns:: The forecast month. For non-monthly forecast time types, this method returns None.
Return type:: int

forecast_period()¶

forecast_reference_time()¶

classmethod from_dict(d)¶

Create a FieldComponent instance from a dictionary.

Parameters:: d (dict) – Dictionary containing specification data.
Returns:: The created FieldComponent instance.
Return type:: FieldComponent

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

indexing_datetime()¶

Return the indexing datetime.

Returns:: The indexing datetime. For non-indexed time types, this method returns None.
Return type:: datetime.datetime

keys()¶: Return the available keys in the component.

set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

*args – Positional arguments.
**kwargs – Keyword arguments.

Returns:

The created FieldComponent instance.

Return type:

FieldComponent

Raises:

KeyError – If any of the keys to be set are not supported.

step()¶

Return the forecast period.

Returns:: The forecast period.
Return type:: datetime.timedelta

to_dict()¶

Convert the object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict

valid_datetime()¶

Return the valid datetime.

Returns:: The valid datetime.
Return type:: datetime.datetime

class earthkit.data.field.component.time.ForecastTime(base_datetime=None, step=None)¶

Bases: TimeBase

Field time component for forecasts.

Parameters:

base_datetime (datetime.datetime, optional) – The base datetime of the forecast. Default is None.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None. Integer values are treated a hours, and string values are parsed using the to_timedelta function.

aliases()¶: Return the aliases in the component.

base_date()¶

Return the date part of the base_datetime().

Returns:: The date part of the base datetime.
Return type:: datetime.date

base_datetime()¶

Return the base datetime.

The base datetime is the datetime from which a forecast is made. For analysis data, the base datetime is the same as the valid datetime.

Returns:: The base datetime of the time object.
Return type:: datetime.datetime

base_time()¶

Return the time part of the base_datetime().

Returns:: The time part of the base datetime.
Return type:: datetime.time

forecast_month()¶

Return the forecast month.

Forecast month is not defined for this time type, so return None.

forecast_period()¶

forecast_reference_time()¶

classmethod from_base_date_and_time(*, base_date=None, base_time=None, step=None)¶

Create a ForecastTime object from a base date, base time, and step.

Parameters:

base_date (datetime.date, string, int, optional) – The base date of the forecast. String or integer values are parsed using the to_datetime function.
base_time (datetime.time, string, int, optional) – The base time of the forecast. Default is None, which is treated as 00:00:00. String or integer values are parsed using the to_time function.
step (datetime.timedelta, string, or number) – The forecast period. Default is None, which is treated as zero timedelta. Integer values are treated as hours, and string values are parsed using the to_timedelta function.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

classmethod from_base_datetime(*, base_datetime=None, step=None)¶

Create a ForecastTime object from a base datetime and step.

Parameters:

base_datetime (datetime.datetime, string, int) – The base datetime of the forecast. String or integer values are parsed using the to_datetime function.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None, which is treated as zero timedelta. Integer values are treated as hours, and string values are parsed using the to_timedelta function.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

classmethod from_base_datetime_and_valid_datetime(*, base_datetime=None, valid_datetime=None)¶

Create a ForecastTime object from a base datetime and valid datetime.

The step is calculated as the difference between the valid datetime and the base datetime.

Parameters:

base_datetime (datetime.datetime, string, int) – The base datetime of the forecast. String or integer values are parsed using the to_datetime function.
valid_datetime (datetime.datetime, string, int) – The valid datetime of the forecast. String or integer values are parsed using the to_datetime function.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

classmethod from_dict(d)¶

Create a ForecastTime object from a dictionary.

Parameters:

d (dict) –

Dictionary containing time data. The allowed keys are:

”valid_datetime”
”base_datetime”
”step”
”base_date”
”base_time”

All aliases of these keys are also allowed. The method used to create the ForecastTime object is determined by the combination of keys provided in the dictionary.

The datetime values can be provided as datetime objects, strings, or integers. String and integer values are parsed using the to_datetime function.

The date values can be provided as datetime.date objects, strings, or integers. String and integer values are parsed using the to_datetime function.

The time values can be provided as datetime.time objects, strings, or integers. String and integer values are parsed using the to_time function.

The “step” value can be a datetime.timedelta, string, or number. Integer values are treated as hours, and string values are parsed using the to_timedelta function.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

classmethod from_valid_datetime(*, valid_datetime=None, step=None)¶

Create a ForecastTime object from a valid datetime and step.

The base datetime is calculated as the difference between the valid datetime and the step.

Parameters:

valid_datetime (datetime.datetime, string, int) – The valid datetime of the forecast. String or integer values are parsed using the to_datetime function.
step (datetime.timedelta, string, or number) – The forecast period. Default is None, which is treated as zero timedelta. Integer values are treated as hours, and string values are parsed using the to_timedelta function.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

indexing_datetime()¶

Return the indexing datetime.

Indexing datetime is not defined for this time type, so return None.

keys()¶: Return the available keys in the component.

set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

args (tuple) – Positional arguments containing time data. Only dictionaries are allowed.
kwargs (dict) – Keyword arguments containing time data.

Returns:

The created ForecastTime instance.

Return type:

ForecastTime

Notes

The allowed keys in the dictionaries and keyword arguments are:

“valid_datetime”
“base_datetime”
“step”
“base_date”
“base_time”

All aliases of these keys are also allowed. The method used to create the new ForecastTime object is determined by the combination of keys provided in the arguments.

The “step” value can be a datetime.timedelta, string, or number. Integer values are treated as hours, and string values are parsed using the to_timedelta function.

The following special rules apply for ambiguous cases:

If only “base_datetime” are provided, the “step” from the current object is kept and the “valid_datetime” is updated accordingly.
If only “step” is provided, the “base_datetime” from the current object is kept and the “valid_datetime” is updated accordingly.

step()¶

Return the forecast period.

Returns:: The forecast period.
Return type:: datetime.timedelta

to_dict()¶: Return a dictionary representation of the time object.

valid_datetime()¶

Return the valid datetime of the time object.

It is calculated as the sum of the base datetime and the step.

class earthkit.data.field.component.time.MonthlyForecastTime(base_datetime=None, step=None, forecast_month=None, indexing_datetime=None)¶

Bases: TimeBase

Field time component for monthly forecasts.

Parameters:

base_datetime (datetime.datetime, optional) – The base datetime of the forecast. Default is None.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None. Integer values are treated as hours, and string values are parsed using the to_timedelta function.
forecast_month (int, optional) – The forecast month. Default is None.
indexing_datetime (datetime.datetime, optional) – The indexing datetime. Default is None.

aliases()¶: Return the aliases in the component.

base_date()¶

Return the date part of the base_datetime().

Returns:: The date part of the base datetime.
Return type:: datetime.date

base_datetime()¶

Return the base datetime.

The base datetime is the datetime from which a forecast is made. For analysis data, the base datetime is the same as the valid datetime.

Returns:: The base datetime of the time object.
Return type:: datetime.datetime

base_time()¶

Return the time part of the base_datetime().

Returns:: The time part of the base datetime.
Return type:: datetime.time

forecast_month()¶: Return the forecast month.

forecast_period()¶

forecast_reference_time()¶

classmethod from_base_date_and_time(*, base_date=None, base_time=None, step=None, forecast_month=None)¶

Create a MonthlyForecastTime object from a base date and time.

Parameters:

base_date (datetime.date, optional) – The base date of the forecast. Default is None.
base_time (datetime.time, optional) – The base time of the forecast. Default is None.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None. Integer values are treated as hours, and string values are parsed using the to_timedelta function.
forecast_month (int, optional) – The forecast month. Default is None.

Returns:

A new MonthlyForecastTime object.

Return type:

MonthlyForecastTime

classmethod from_base_datetime(*, base_datetime=None, step=None, forecast_month=None, indexing_datetime=None)¶

Create a MonthlyForecastTime object from a base datetime and step.

Parameters:

base_datetime (datetime.datetime, optional) – The base datetime of the forecast. Default is None.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None. Integer values are treated as hours, and string values are parsed using the to_timedelta function.
forecast_month (int, optional) – The forecast month. Default is None.
indexing_datetime (datetime.datetime, optional) – The indexing datetime. Default is None.

Returns:

A new MonthlyForecastTime object.

Return type:

MonthlyForecastTime

classmethod from_base_datetime_and_valid_datetime(*, base_datetime=None, valid_datetime=None, forecast_month=None, indexing_datetime=None)¶

Create a MonthlyForecastTime object from a base datetime and valid datetime.

The step is calculated as the difference between the valid datetime and the base datetime.

Parameters:

base_datetime (datetime.datetime, optional) – The base datetime of the forecast. Default is None.
valid_datetime (datetime.datetime, optional) – The valid datetime of the forecast. Default is None.
forecast_month (int, optional) – The forecast month. Default is None.
indexing_datetime (datetime.datetime, optional) – The indexing datetime. Default is None.

Returns:

A new MonthlyForecastTime object.

Return type:

MonthlyForecastTime

classmethod from_dict(d)¶

Create a MonthlyForecastTime object from a dictionary.

Parameters:

d (dict) –
A dictionary containing the keys and values to create the MonthlyForecastTime object. The allowed keys are:
- ”valid_datetime”
- ”base_datetime”
- ”step”
- ”base_date”
- ”base_time”
- ”forecast_month”
- ”indexing_datetime”
datetime.timedelta (The "step" value can be a)
string
treated (or number. Integer values are)
hours (as)
function. (and string values are parsed using the to_timedelta)

Returns:

A new MonthlyForecastTime object.

Return type:

MonthlyForecastTime

classmethod from_valid_datetime(*, valid_datetime=None, step=None, forecast_month=None, indexing_datetime=None)¶

Create a MonthlyForecastTime object from a valid datetime.

The base datetime is calculated as the difference between the valid datetime and the step.

Parameters:

valid_datetime (datetime.datetime, optional) – The valid datetime of the forecast. Default is None.
step (datetime.timedelta, string, or number, optional) – The forecast period. Default is None. Integer values are treated as hours, and string values are parsed using the to_timedelta function.
forecast_month (int, optional) – The forecast month. Default is None.
indexing_datetime (datetime.datetime, optional) – The indexing datetime. Default is None.

Returns:

A new MonthlyForecastTime object.

Return type:

MonthlyForecastTime

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

indexing_datetime()¶: Return the indexing datetime.

keys()¶: Return the available keys in the component.

abstractmethod set(*args, **kwargs)¶

Create a new instance with updated data.

This method is not implemented yet, as the logic for determining the method to use based on the provided keys is more complex than for the ForecastTime class, due to the additional keys “forecast_month” and “indexing_datetime”.

step()¶

Return the forecast period.

Returns:: The forecast period.
Return type:: datetime.timedelta

to_dict()¶: Return a dictionary representation of the time object.

valid_datetime()¶

Return the valid datetime of the time object.

It is calculated as the sum of the base datetime and the step

class earthkit.data.field.component.time.TimeBase¶

Bases: earthkit.data.field.component.component.SimpleFieldComponent

Base class for time component of a field.

This class defines the interface for time components, which can represent different types of time information. Some of the methods may not be applicable to all time types (e.g. forecast_month()), and may return None.

The temporal information can be accessed by methods like base_datetime(), valid_datetime(), and step(). Each of these methods has an associated key that can be used in the get() method to retrieve the corresponding information. The list of supported keys are as follows:

“base_datetime”
“base_date”
“base_time”
“valid_datetime”
“step”
“forecast_month”
“indexing_datetime”
“forecast_reference_time” (alias of “base_datetime”)
“forecast_period” (alias of “step”)

Depending on the type of time information available, some of these keys may not be supported and will return None in the subclasses. For example, the “forecast_month” key is only supported for monthly forecast time, and will return None for other time types.

Typically, this object is used as a component of a field, and can be accessed via the time attribute of a field. The keys above can also be accessed via the get() method of the field, using the “time.” prefix.

The following example demonstrates how to access the time information from a field using various methods and keys:

>>> import earthkit.data as ekd
>>> field = ekd.from_source("sample", "test.grib").to_fieldlist()[0]
>>> field.time.base_datetime()
datetime.datetime(2020, 1, 1, 0, 0)
>>> field.time.get("base_datetime")
datetime.datetime(2020, 1, 1, 0, 0)
>>> field.get("time.base_datetime")
datetime.datetime(2020, 1, 1, 0, 0)

The time component is immutable. The set() method to create a new instance with updated values. For example, the following code creates a new time component with an updated step:

>>> new_time = field.time.set(step=3)
>>> new_time.step()
datetime.timedelta(hours=3)

We can also call the Field’s set() method to create a new field with an updated time component:

>>> new_field = field.set({"time.step": 3})
>>> new_field.time.step()
datetime.timedelta(hours=3)

aliases()¶: Return the aliases in the component.

abstractmethod base_date()¶

Return the date part of the base_datetime().

Returns:: The date part of the base datetime.
Return type:: datetime.date

abstractmethod base_datetime()¶

Return the base datetime.

The base datetime is the datetime from which a forecast is made. For analysis data, the base datetime is the same as the valid datetime.

Returns:: The base datetime of the time object.
Return type:: datetime.datetime

abstractmethod base_time()¶

Return the time part of the base_datetime().

Returns:: The time part of the base datetime.
Return type:: datetime.time

abstractmethod forecast_month()¶

Return the forecast month.

Returns:: The forecast month. For non-monthly forecast time types, this method returns None.
Return type:: int

forecast_period()¶

forecast_reference_time()¶

classmethod from_dict(d)¶

Abstractmethod:

Create a FieldComponent instance from a dictionary.

Parameters:: d (dict) – Dictionary containing specification data.
Returns:: The created FieldComponent instance.
Return type:: FieldComponent

get(key, default=None, *, astype=None, raise_on_missing=False)¶

Return the value for the specified key.

Parameters:

key (str) – The key to retrieve.
default (Any, optional) – The default value to return if the key is not found. Default is None.
astype (type, optional) – The type to which the value should be cast. Default is None.
raise_on_missing (bool, optional) – If True, raise a KeyError if the key is not found. Default is False.

Returns:

The value for the specified key.

Return type:

Any

Raises:

KeyError – If raise_on_missing is True and the key is not found.

abstractmethod indexing_datetime()¶

Return the indexing datetime.

Returns:: The indexing datetime. For non-indexed time types, this method returns None.
Return type:: datetime.datetime

keys()¶: Return the available keys in the component.

abstractmethod set(*args, **kwargs)¶

Create a new instance with updated data.

Parameters:

*args – Positional arguments.
**kwargs – Keyword arguments.

Returns:

The created FieldComponent instance.

Return type:

FieldComponent

Raises:

KeyError – If any of the keys to be set are not supported.

abstractmethod step()¶

Return the forecast period.

Returns:: The forecast period.
Return type:: datetime.timedelta

abstractmethod to_dict()¶

Convert the object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict

abstractmethod valid_datetime()¶

Return the valid datetime.

Returns:: The valid datetime.
Return type:: datetime.datetime

earthkit.data.field.component.time.create_time(d)¶

Create a TimeBase object from a dictionary.

Parameters:: d (dict) – Dictionary containing time data.
Returns:: The created TimeBase instance.
Return type:: TimeBase