mt_metadata.common.mttime

Created on Wed May 13 19:10:46 2020

For dealing with obsy.core.UTCDatetime and an soft requirement imports have a look at https://github.com/pydantic/pydantic/discussions/3673.

@author: jpeacock

Attributes

`from_obspy`
`leap_second_dict`
`TMIN`
`TMAX`

Classes

`MTime`	Date and time container based on pandas.Timestamp with UTC enforcement.
`MDate`	Date and time container based on pandas.Timestamp with UTC enforcement.

Functions

`calculate_leap_seconds`(year, month, day)	Get the leap seconds for the given year to convert GPS time to UTC time.
`parse`([dt_str, gps_time])	Parse a datetime input into a pandas Timestamp with UTC timezone.
`get_now_utc`()	Get the current UTC time as an MTime object.

Module Contents

mt_metadata.common.mttime.from_obspy = True

mt_metadata.common.mttime.leap_second_dict

mt_metadata.common.mttime.calculate_leap_seconds(year, month, day)

Get the leap seconds for the given year to convert GPS time to UTC time.

GPS time started in 1980. GPS time is leap seconds ahead of UTC time, therefore you should subtract leap seconds from GPS time to get UTC time.

Parameters:

year (int) – Year of the date.
month (int) – Month of the date (1-12).
day (int) – Day of the date (1-31).

Returns:

Number of leap seconds for the given date.

Return type:

int

Raises:

ValueError – If the date is outside the defined leap second range (1981-07-01 to 2026-07-01).

Notes

Leap seconds are defined for the following date ranges:

Date Range	Leap Seconds
1981-07-01 - 1982-07-01	1
1982-07-01 - 1983-07-01	2
1983-07-01 - 1985-07-01	3
1985-07-01 - 1988-01-01	4
1988-01-01 - 1990-01-01	5
1990-01-01 - 1991-01-01	6
1991-01-01 - 1992-07-01	7
1992-07-01 - 1993-07-01	8
1993-07-01 - 1994-07-01	9
1994-07-01 - 1996-01-01	10
1996-01-01 - 1997-07-01	11
1997-07-01 - 1999-01-01	12
1999-01-01 - 2006-01-01	13
2006-01-01 - 2009-01-01	14
2009-01-01 - 2012-07-01	15
2012-07-01 - 2015-07-01	16
2015-07-01 - 2017-01-01	17
2017-01-01 - ????-??-??	18

mt_metadata.common.mttime.TMIN

mt_metadata.common.mttime.TMAX

mt_metadata.common.mttime.parse(dt_str=None, gps_time=False)

Parse a datetime input into a pandas Timestamp with UTC timezone.

Accepts various input types and converts them to a standardized pandas Timestamp object. Handles special cases like GPS time conversion, nanosecond timestamps, and out-of-bounds dates.

Parameters:

dt_str (float, int, np.number, np.datetime64, pd.Timestamp, str, dict, or None, optional) – Input to be parsed. Can be: - None, empty string, or “none” variants: returns default 1980-01-01 - float/int: interpreted as epoch seconds (or nanoseconds if large) - numpy numeric types: converted to standard Python types first - pd.Timestamp: validated and timezone-corrected - str: parsed using dateutil.parser with flexible formatting - dict: extracted time_stamp and gps_time fields Default is None.
gps_time (bool, optional) – If True, converts GPS time to UTC by subtracting leap seconds. Default is False.

Returns:

UTC-localized timestamp object.

Return type:

pd.Timestamp

Raises:

ValueError – If input is before GPS start time when gps_time=True. If string parsing fails with invalid format.

Notes

Large numeric inputs (ratio > 1000 vs 3e8) are assumed to be nanoseconds
Timestamps outside pandas bounds are clamped to min/max values
GPS time conversion uses calculated leap seconds for the date
All outputs are forced to UTC timezone regardless of input timezone

class mt_metadata.common.mttime.MTime(/, **data)

Bases: pydantic.BaseModel

Date and time container based on pandas.Timestamp with UTC enforcement.

A flexible datetime container that accepts various input formats and converts them to a UTC-localized pandas.Timestamp object. Provides convenient access to date/time components and handles nanosecond precision.

Parameters:

time_stamp (float, int, np.number, np.datetime64, pd.Timestamp, str, or None, optional) – Input timestamp in various formats: - float/int: epoch seconds - np.number: numpy numeric types (converted to Python types) - np.datetime64: numpy datetime - pd.Timestamp: pandas timestamp (will be UTC-localized) - str: ISO format or parseable date string - None: defaults to 1980-01-01T00:00:00+00:00 Default is None.
gps_time (bool, optional) – If True, interprets time_stamp as GPS time and converts to UTC. Default is False.

time_stamp

The stored timestamp, always UTC-localized.

Type:: pd.Timestamp

gps_time

Whether GPS time conversion was applied.

Type:: bool

Notes

The pandas.Timestamp backend allows nanosecond precision timing.

Input values outside pandas timestamp bounds are automatically clamped: - Values > 2200: set to pandas.Timestamp.max (2262-04-11 23:47:16.854775807) - Values < 1900: set to pandas.Timestamp.min (1677-09-21 00:12:43.145224193)

All timestamps are forced to UTC timezone regardless of input timezone.

Examples

Create from various input types:

>>> t = MTime()  # Default time
>>> t.isoformat()
'1980-01-01T00:00:00+00:00'

>>> t = MTime(time_stamp="2020-01-15T12:30:45")
>>> t.year
2020

>>> t = MTime(time_stamp=1579095045.0)  # Epoch seconds
>>> t.isoformat()
'2020-01-15T12:30:45+00:00'

Access and modify components:

>>> t.year = 2025
>>> t.month = 12
>>> t.day = 31
>>> t.epoch_seconds
1767225045.0

model_config: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

gps_time: Annotated[bool, Field(description='Defines if the time give in GPS time [True] or UTC [False]', default=False, json_schema_extra={'units': None, 'required': False, 'examples': [True, False]})] = False

time_stamp: Annotated[float | int | numpy.number | numpy.datetime64 | pandas.Timestamp | str | None, Field(default_factory=lambda: pd.Timestamp(MTime._default_time.default), description='Time in UTC format', examples=['1980-01-01T00:00:00+00:00'])]

classmethod validate_time_stamp(field_value, validation_info)

Validate and convert input timestamp to pandas Timestamp.

Pydantic field validator that processes various timestamp input formats and converts them to a standardized UTC pandas Timestamp object.

Parameters:

field_value (float, int, np.datetime64, pd.Timestamp, str, or UTCDateTime) – Input timestamp value in any supported format.
validation_info (ValidationInfo) – Pydantic validation context containing model data including gps_time setting.

Returns:

UTC-localized timestamp object, clamped to pandas bounds if necessary.

Return type:

pd.Timestamp

Notes

This method is automatically called during model instantiation. GPS time conversion is applied if gps_time=True in the model data. Out-of-bounds timestamps are automatically clamped to valid ranges.

is_default()

Test if the time_stamp value is the default value

to_dict(nested=False, single=False, required=True)

Convert the time stamp to a dictionary with the ISO format string.

Returns:: The ISO format string.
Return type:: str

from_dict(value, skip_none=False)

This will have to accept just a single value, not a dict. This is to keep original functionality.

Parameters:: value (str | int | float | np.datetime64 | pd.Timestamp) – time stamp value

property iso_str: str

returns: ISO formatted string of the time stamp. :rtype: str

property iso_no_tz: str

ISO formatted string of the time stamp without the timezone. This is useful for storing the time stamp in a database or other format where the timezone is not needed.

Returns:: ISO formatted string of the time stamp without the timezone.
Return type:: str

property epoch_seconds: float

Epoch seconds of the time stamp. This is the number of seconds since the epoch (1970-01-01 00:00:00 UTC).

Returns:: epoch seconds of the time stamp.
Return type:: float

property date: str

Date in ISO format. This is the date part of the time stamp without the time part. This is useful for storing the date in a database or other format where the time is not needed. The date is in the format YYYY-MM-DD.

Returns:: ISO formatted date string of the time stamp.
Return type:: str

property year: int

Year of the time stamp

Returns:: year of the time stamp
Return type:: int

property month: int

Month of the time stamp. This is the month part of the time stamp without the time part. This is useful for storing the month in a database or other format where the time is not needed.

Returns:: month of time stamp
Return type:: int

property day: int

Day of the time stamp. This is the day part of the time stamp without the time part.

Returns:: Day of the time stamp
Return type:: int

property hour: int

Hour of the time stamp.

Returns:: hour of the time stamp
Return type:: int

property minutes: int

property seconds: int

property microseconds: int

property nanoseconds: int

now()

The current time in UTC format.

Returns:: The current time as an MTime object.
Return type:: MTime

copy()

make a copy of the time

isoformat()

ISO formatted string of the time stamp. This is the ISO format string of the time stamp.

formatted as: YYYY-MM-DDThh:mm:ss.ssssss+00:00

Returns:: ISO formatted date time string
Return type:: str

isodate()

ISO formatted date string of the time stamp. This is the ISO format string of the date part of the time stamp.

formatted as: YYYY-MM-DD

Returns:: _description_
Return type:: str

isocalendar()

ISO formatted calendar string of the time stamp. This is the ISO format string of the calendar part of the time stamp.

Formatted as: YYYY-WW-D where YYYY is the year, WW is the week number, and D is the day of the week.

Returns:: ISO formatted calendar string of the time stamp.
Return type:: str

mt_metadata.common.mttime.get_now_utc()

Get the current UTC time as an MTime object.

Creates an MTime instance set to the current UTC time.

Returns:: ISO format string of the current UTC time.
Return type:: str

Notes

Despite the return type annotation suggesting MTime, this function actually returns an ISO format string from the MTime object.

class mt_metadata.common.mttime.MDate(/, **data)

Bases: MTime

Date and time container based on pandas.Timestamp with UTC enforcement.

A flexible datetime container that accepts various input formats and converts them to a UTC-localized pandas.Timestamp object. Provides convenient access to date/time components and handles nanosecond precision.

Parameters:

time_stamp (float, int, np.number, np.datetime64, pd.Timestamp, str, or None, optional) – Input timestamp in various formats: - float/int: epoch seconds - np.number: numpy numeric types (converted to Python types) - np.datetime64: numpy datetime - pd.Timestamp: pandas timestamp (will be UTC-localized) - str: ISO format or parseable date string - None: defaults to 1980-01-01T00:00:00+00:00 Default is None.
gps_time (bool, optional) – If True, interprets time_stamp as GPS time and converts to UTC. Default is False.

time_stamp

The stored timestamp, always UTC-localized.

Type:: pd.Timestamp

gps_time

Whether GPS time conversion was applied.

Type:: bool

Notes

The pandas.Timestamp backend allows nanosecond precision timing.

Input values outside pandas timestamp bounds are automatically clamped: - Values > 2200: set to pandas.Timestamp.max (2262-04-11 23:47:16.854775807) - Values < 1900: set to pandas.Timestamp.min (1677-09-21 00:12:43.145224193)

All timestamps are forced to UTC timezone regardless of input timezone.

Examples

Create from various input types:

>>> t = MTime()  # Default time
>>> t.isoformat()
'1980-01-01T00:00:00+00:00'

>>> t = MTime(time_stamp="2020-01-15T12:30:45")
>>> t.year
2020

>>> t = MTime(time_stamp=1579095045.0)  # Epoch seconds
>>> t.isoformat()
'2020-01-15T12:30:45+00:00'

Access and modify components:

>>> t.year = 2025
>>> t.month = 12
>>> t.day = 31
>>> t.epoch_seconds
1767225045.0

is_default(): Test if time_stamp is the default value

isoformat()

ISO formatted string of the time stamp. This is the ISO format string of the time stamp.

formatted as: YYYY-MM-DDThh:mm:ss.ssssss+00:00

Returns:: ISO formatted date time string
Return type:: str

to_dict(nested=False, single=False, required=True)

Convert the time stamp to a dictionary with the ISO format string.

Returns:: The ISO format string.
Return type:: str

from_dict(value, skip_none=False)

This will have to accept just a single value, not a dict. This is to keep original functionality.

Parameters:: value (str | int | float | np.datetime64 | pd.Timestamp) – time stamp value