Join the newly launched Discord
community for real-time discussions, peer support, and direct interaction with the Meridian team!
meridian.data.time_coordinates.TimeCoordinates
Stay organized with collections
Save and categorize content based on your preferences.
A wrapper around time coordinates in Meridian's input data.
meridian
.
data
.
time_coordinates
.
TimeCoordinates
(
datetime_index
:
pd
.
DatetimeIndex
)
Meridian models store time coordinates as untyped strings. It treats them as
labels, and they have no intrinsic meaning to the model other than the
assumption that they represent some linearly increasing time coordinates.
This wrapper object performs some additional validation and methods for
extracting values out of these time coordinates which are treated as numeric
"date" values.
The given time coordinates, parsed as indexable DatetimeIndex
.
The given time coordinates, as a list of Pythonic datetime.date
objects.
The given time coordinates, as a list of Meridian-formatted
date strings. This can be used for the model internals, which treat time
coordinates as simple labels.
Returns the mean
interval between two neighboring dates in all_dates
.
Methods
expand_selected_time_dims
View source
expand_selected_time_dims
(
start_date
:
meridian
.
data
.
time_coordinates
.
Date
=
None
,
end_date
:
meridian
.
data
.
time_coordinates
.
Date
=
None
)
->
(
list
[
datetime
.
date
]
|
None
)
Validates and returns time dimension values based on the selected times.
If both start_date
and end_date
are None, returns None. If specified,
both start_date
and end_date
are inclusive, and must be present in the
time coordinates of the input data.
start_date
Start date of the selected time period. If None
, implies the
earliest time dimension value in the input data.
end_date
End date of the selected time period. If None
, implies the
latest time dimension value in the input data.
A list of time dimension values (as datetime.date
objects) in the input
data within the selected time period, or do nothing and pass through None
if both arguments are None
, or if start_date
and end_date
correspond to the entire time range in the input data.
ValueError
if start_date
or end_date
is not in the input data's time
dimension coordinates.
from_dates
View source
@classmethod
from_dates
(
dates
:
_TimeCoordinateValues
)
->
'TimeCoordinates'
Creates a TimeCoordinates
from a polymorphic series of dates.
dates
A polymorphic series of dates; it can either be a Pandas DatetimeIndex
or an Xarray DataArray
with "YYYY-mm-dd" string
labels.
A normalized TimeCoordinates
dataclass.
get_selected_dates
View source
get_selected_dates
(
selected_interval
:
(
meridian
.
data
.
time_coordinates
.
DateInterval
|
None
)
=
None
)
->
list
[
datetime
.
date
]
Creates a sequence of dates containing all points in selected interval.
selected_interval
Tuple of the start and end times, or a DateInterval
proto. If None
, then all_dates
is returned.
A sequence of dates representing the subset of all_dates
between the
given start and end dates, as Python's builtin datetime.date
objects.
ValueError
If selected_interval
is not a subset of all_dates
.
__eq__
__eq__
(
other
)
Return self==value.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License
, and code samples are licensed under the Apache 2.0 License
. For details, see the Google Developers Site Policies
. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-09-05 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-05 UTC."],[[["\u003cp\u003e\u003ccode\u003eTimeCoordinates\u003c/code\u003e is a wrapper for time coordinates in Meridian's input data, treating them as linearly increasing numeric "date" values, while the model internally views them as untyped string labels.\u003c/p\u003e\n"],["\u003cp\u003eThe wrapper provides attributes like \u003ccode\u003edatetime_index\u003c/code\u003e, \u003ccode\u003eall_dates\u003c/code\u003e, \u003ccode\u003eall_dates_str\u003c/code\u003e, and \u003ccode\u003einterval_days\u003c/code\u003e to access and manipulate the time coordinate data.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eexpand_selected_time_dims\u003c/code\u003e method allows validation and retrieval of time dimension values based on specified \u003ccode\u003estart_date\u003c/code\u003e and \u003ccode\u003eend_date\u003c/code\u003e, which must be present in the input data's time coordinates.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003efrom_dates\u003c/code\u003e class method creates a \u003ccode\u003eTimeCoordinates\u003c/code\u003e object from various date formats, including Pandas \u003ccode\u003eDatetimeIndex\u003c/code\u003e or Xarray \u003ccode\u003eDataArray\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eget_selected_dates\u003c/code\u003e method returns a sequence of \u003ccode\u003edatetime.date\u003c/code\u003e objects representing a subset of \u003ccode\u003eall_dates\u003c/code\u003e within a specified interval.\u003c/p\u003e\n"]]],[],null,["\u003cbr /\u003e\n\n|---------------------------------------------------------------------------------------------------------------------|\n| [View source on GitHub](https://github.com/google/meridian/blob/v1.2.0/meridian/data/time_coordinates.py#L105-L294) |\n\nA wrapper around time coordinates in Meridian's input data. \n\n meridian.data.time_coordinates.TimeCoordinates(\n datetime_index: pd.DatetimeIndex\n )\n\nMeridian models store time coordinates as untyped strings. It treats them as\nlabels, and they have no intrinsic meaning to the model other than the\nassumption that they represent some linearly increasing time coordinates.\n\nThis wrapper object performs some additional validation and methods for\nextracting values out of these time coordinates which are treated as numeric\n\"date\" values.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Attributes ||\n|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `datetime_index` | The given time coordinates, parsed as indexable `DatetimeIndex`. |\n| `all_dates` | The given time coordinates, as a list of Pythonic `datetime.date` objects. |\n| `all_dates_str` | The given time coordinates, as a list of Meridian-formatted date strings. This can be used for the model internals, which treat time coordinates as simple labels. |\n| `interval_days` | Returns the *mean* interval between two neighboring dates in `all_dates`. |\n\n\u003cbr /\u003e\n\nMethods\n\n`expand_selected_time_dims`\n\n[View source](https://github.com/google/meridian/blob/v1.2.0/meridian/data/time_coordinates.py#L237-L294) \n\n expand_selected_time_dims(\n start_date: ../../../meridian/data/time_coordinates.md#Date = None,\n end_date: ../../../meridian/data/time_coordinates.md#Date = None\n ) -\u003e (list[datetime.date] | None)\n\nValidates and returns time dimension values based on the selected times.\n\nIf both `start_date` and `end_date` are None, returns None. If specified,\nboth `start_date` and `end_date` are inclusive, and must be present in the\ntime coordinates of the input data.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Args ||\n|--------------|-----------------------------------------------------------------------------------------------------------------|\n| `start_date` | Start date of the selected time period. If `None`, implies the earliest time dimension value in the input data. |\n| `end_date` | End date of the selected time period. If `None`, implies the latest time dimension value in the input data. |\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Returns ||\n|---|---|\n| A list of time dimension values (as `datetime.date` objects) in the input data within the selected time period, or do nothing and pass through `None` if both arguments are `None`, or if `start_date` and `end_date` correspond to the entire time range in the input data. ||\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Raises ||\n|---|---|\n| `ValueError` if `start_date` or `end_date` is not in the input data's time dimension coordinates. ||\n\n\u003cbr /\u003e\n\n`from_dates`\n\n[View source](https://github.com/google/meridian/blob/v1.2.0/meridian/data/time_coordinates.py#L129-L144) \n\n @classmethod\n from_dates(\n dates: _TimeCoordinateValues\n ) -\u003e 'TimeCoordinates'\n\nCreates a `TimeCoordinates` from a polymorphic series of dates.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Args ||\n|---------|------------------------------------------------------------------------------------------------------------------------------------|\n| `dates` | A polymorphic series of dates; it can either be a Pandas `DatetimeIndex` or an Xarray `DataArray` with \"YYYY-mm-dd\" string labels. |\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Returns ||\n|---|---|\n| A normalized `TimeCoordinates` dataclass. ||\n\n\u003cbr /\u003e\n\n`get_selected_dates`\n\n[View source](https://github.com/google/meridian/blob/v1.2.0/meridian/data/time_coordinates.py#L209-L235) \n\n get_selected_dates(\n selected_interval: (../../../meridian/data/time_coordinates/DateInterval.md | None) = None\n ) -\u003e list[datetime.date]\n\nCreates a sequence of dates containing all points in selected interval.\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Args ||\n|---------------------|-------------------------------------------------------------------------------------------------------|\n| `selected_interval` | Tuple of the start and end times, or a `DateInterval` proto. If `None`, then `all_dates` is returned. |\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Returns ||\n|---|---|\n| A sequence of dates representing the subset of `all_dates` between the given start and end dates, as Python's builtin `datetime.date` objects. ||\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n\u003cbr /\u003e\n\n| Raises ||\n|--------------|--------------------------------------------------------|\n| `ValueError` | If `selected_interval` is not a subset of `all_dates`. |\n\n\u003cbr /\u003e\n\n`__eq__` \n\n __eq__(\n other\n )\n\nReturn self==value."]]
