Dimensions¶

DimensionModel¶

dsgrid.config.dimensions.DimensionModel

Defines a non-time dimension

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`filename`	`str` \| None	`None`	Filename containing dimension records. Only assigned for user input and output purposes. The registry database stores records in the dimension JSON document.
`file_hash`	`str` \| None	`None`	Hash of the contents of the file
`records`	`list`	`[]`	Dimension records that can either be loaded from filename at runtime or provided directly. Example of records provided directly: records: [ {id: ‘scenario_1’, name: ‘Scenario 1’}, {id: ‘scenario_2’, name: ‘Scenario 2’}, ],

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description
`check_file`	`check_file`	Validate that dimension file exists and has no errors
`compute_file_hash`	`compute_file_hash`	No description
`add_records`	`add_records`	Add records from the file.

DateTimeDimensionModel¶

dsgrid.config.dimensions.DateTimeDimensionModel

Defines a time dimension where timestamps translate to datetime objects.

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`time_type`	TimeDimensionType	`TimeDimensionType.DATETIME`	Type of time dimension
`column_format`	TimeFormatDateTimeTZModel \| TimeFormatDateTimeNTZModel \| TimeFormatInPartsModel	`dtype='timestamp_tz' time_column='timestamp'`	Specifies the format of the timestamps in the dataset.
`time_zone_format`	AlignedTimeSingleTimeZone \| LocalTimeMultipleTimeZones	(required)	Specifies whether timestamps are aligned in absolute time or in local standard time when adjusted for time zone.
`measurement_type`	MeasurementType	`MeasurementType.TOTAL`	The type of measurement represented by a value associated with a timestamp: mean, min, max, measured, total
`ranges`	list[TimeRangeModel]	(required)	Defines the continuous ranges of datetime in the data, inclusive of start and end time.
`time_interval_type`	TimeIntervalType	(required)	The range of time that the value associated with a timestamp represents, e.g., period-beginning

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description
`check_times`	`check_times`	No description
`handle_legacy_fields`	`(model)`	No description
`check_standard_time_zones_for_localization`	`(model)`	Validate that only fixed-offset time zones are used when localizing tz-naive timestamps.

AlignedTimeSingleTimeZone¶

dsgrid.config.dimensions.AlignedTimeSingleTimeZone

All geographies have data with the same set of timestamps in absolute time.

E.g., data in CA and NY both start in 2018-01-01 00:00 Etc/GMT+5 (EST).

For time zone, only an IANA time zone name or None is accepted. The types of time zones supported (fixed offset or DST-observing) depend on column_format, which in part defines whether the timestamps are tz-naive after parsing:

When the input timestamps are tz-aware, both fixed offset or DST-observing time zones (“America/New_York”) are accepted.
When the input timestamps are tz-naive (i.e., ‘timestamp_ntz’ or TimeFormatInParts without offset column), only IANA time zones with constant UTC offsets (e.g., “Etc/GMT+5”) are allowed because dsgrid will localize the tz-naive timestamps to the time zone specified here. By definition, the timestamps in the data table must also be in standard time without skips and duplicates for daylight saving time (DST). This restriction is necessary to avoid ambiguous or missing timestamps at DST transitions when localizing tz-naive timestamps.

Note: IANA time zone names (e.g., “America/New_York”, “Etc/GMT+5”) are distinct from UTC offsets (e.g., UTC-5). Fixed-offset zones like “Etc/GMT+5” observe a single UTC offset (UTC-5) year-round, while DST-observing zones like “America/New_York” have multiple offsets depending on the calendar date (UTC-5 during standard time, UTC-4 during daylight saving time).

Fields¶

Name	Type	Default	Description
`format_type`	`Literal`	`"TimeZoneFormat.ALIGNED_IN_ABSOLUTE_TIME"`
`time_zone`	`str` \| None	(required)	IANA time zone of data. Accepts `None` for no time zone. The types of time zones supported (fixed offset or DST-observing) depend on `column_format.dtype`. When timestamps are tz-aware, both fixed offset and DST-observing zones are accepted. When timestamps are tz-naive (`timestamp_ntz` or `time_format_in_parts` without `offset_column`), only fixed UTC offset zones are allowed.

Validators¶

Name	Applies To	Description
`handle_legacy_fields`	`(model)`	No description

LocalTimeMultipleTimeZones¶

dsgrid.config.dimensions.LocalTimeMultipleTimeZones

Timestamps cover the same interval of local clock time across geographies.

All data represents the same interval of standard clock time as experienced locally in each geography’s time zone, but the intervals represent different absolute UTC instants.

Example: California data starts at 2018-01-01 00:00-08:00, while New York data starts at 2018-01-01 00:00-05:00. Both rows have the same local clock time but represent different absolute UTC instants.

The data table must contain a time_zone column with IANA time zone names (one per row) that match the entries in the time_zones list below. The types of of time zones supported (fixed offset or DST-observing) depend on column_format, which in part defines whether the timestamps are tz-naive after parsing:

When the input timestamps are tz-aware, both fixed offset or DST-observing time zones (“America/New_York”) are accepted.
When the input timestamps are tz-naive (i.e., ‘timestamp_ntz’ or TimeFormatInParts without offset column), only IANA time zones with constant UTC offsets (e.g., “Etc/GMT+5”) are allowed because dsgrid will localize the tz-naive timestamps to the time zone specified here. By definition, the timestamps in the data table must also be in standard time without skips and duplicates for daylight saving time (DST). This restriction is necessary to avoid ambiguous or missing timestamps at DST transitions when localizing tz-naive timestamps.

Fields¶

Name	Type	Default	Description
`format_type`	`Literal`	`"TimeZoneFormat.ALIGNED_IN_STD_CLOCK_TIME"`
`time_zones`	list[`str`]	(required)	List of unique IANA time zones in the dataset. Does not allow `None` as a time zone. The types of time zones supported (fixed offset or DST-observing) depend on `column_format.dtype`. When timestamps are tz-aware, both fixed offset and DST-observing zones are accepted. When timestamps are tz-naive (`timestamp_ntz` or `time_format_in_parts` without `offset_column`), only fixed UTC offset zones are allowed.

TimeFormatDateTimeNTZModel¶

dsgrid.config.dimensions.TimeFormatDateTimeNTZModel

Format of timestamps in a dataset is timezone-naive datetime

Fields¶

Name	Type	Default	Description
`dtype`	`Literal`	`"timestamp_ntz"`
`time_column`	`str`	`"timestamp"`	Name of the timestamp column in the dataset.

Validators¶

Name	Applies To	Description
`handle_legacy_fields`	`(model)`	No description

TimeFormatDateTimeTZModel¶

dsgrid.config.dimensions.TimeFormatDateTimeTZModel

Format of timestamps in a dataset is timezone-aware datetime.

Fields¶

Name	Type	Default	Description
`dtype`	`Literal`	`"timestamp_tz"`
`time_column`	`str`	`"timestamp"`	Name of the timestamp column in the dataset.

Validators¶

Name	Applies To	Description
`handle_legacy_fields`	`(model)`	No description

TimeFormatInPartsModel¶

dsgrid.config.dimensions.TimeFormatInPartsModel

Format of timestamps in a dataset is in parts, e.g., month-day-hour format, requiring conversion to datetime.

Fields¶

Name	Type	Default	Description
`dtype`	`Literal`	`"time_format_in_parts"`
`year_column`	`str`	(required)	Name of the year column in the dataset.
`month_column`	`str`	(required)	Name of the month column in the dataset. Value is the month in a year (1 - 12)
`day_column`	`str`	(required)	Name of the day column in the dataset. Value is the day in a month (1 - 31).
`hour_column`	`str` \| None	`None`	Name of the hour column in the dataset. Value is the hour in a day (0 - 23). If None, the hour will be set to 0 for all rows.
`offset_column`	`str` \| None	`None`	Name of the offset column in the dataset. Value is the UTC offset, either as a numeric offset in hours (e.g., -8) or as a string in ±HH:MM format (e.g., -08:00). If None, no offset is applied and the resulting timestamp will be timezone-naive. Example: ‘2024-01-01 00:00:00-05:00’ is the start of 2024 in New York; the offset column records ‘-05:00’ for that row. For America/New_York, the offset is -05:00 during standard time and -04:00 during daylight saving time.

TimeRangeModel¶

dsgrid.config.dimensions.TimeRangeModel

Defines a continuous range of time.

Fields¶

Name	Type	Default	Description
`start`	`str`	(required)	First timestamp in the data
`end`	`str`	(required)	Last timestamp in the data (inclusive)
`str_format`	`str`	`"%Y-%m-%d %H:%M:%S"`	Timestamp string format (for parsing the time ranges). The string format is used to parse the timestamps provided in the time ranges.Cheatsheet reference: `<https://strftime.org/>`_.
`frequency`	`timedelta`	`1:00:00`	Resolution of the timestamps

AnnualTimeDimensionModel¶

dsgrid.config.dimensions.AnnualTimeDimensionModel

Defines an annual time dimension where timestamps are years. Each value associated with a year represents the MEASUREMENT_TYPE over the entire year. i.e., MEASUREMENT_TYPE = total means the value is the total over the year, not over the range frequency.

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`time_type`	TimeDimensionType	`TimeDimensionType.ANNUAL`
`measurement_type`	MeasurementType	`MeasurementType.TOTAL`	The type of measurement represented by a value associated with an annual time: e.g., total
`ranges`	list[AnnualRangeModel]	`[]`	Defines the contiguous ranges of annual time in the data, inclusive of start and end time.
`include_leap_day`	`bool`	`False`	Whether annual time includes leap day.

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description
`check_times`	`check_times`	No description
`check_measurement_type`	`check_measurement_type`	No description
`handle_legacy_fields`	`(model)`	No description

AnnualRangeModel¶

dsgrid.config.dimensions.AnnualRangeModel

Defines a continuous range of annual time.

Fields¶

Name	Type	Default	Description
`start`	`str`	(required)	First year in the data
`end`	`str`	(required)	Last year in the data (inclusive)
`str_format`	`str`	`"%Y"`	Timestamp string format. The string format is used to parse the timestamps provided in the time ranges. Cheatsheet reference: `<https://strftime.org/>`_.
`frequency`	`int`	`1`	Resolution of the annual time in number of years

RepresentativePeriodTimeDimensionModel¶

dsgrid.config.dimensions.RepresentativePeriodTimeDimensionModel

Defines a representative time dimension.

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`time_type`	TimeDimensionType	`TimeDimensionType.REPRESENTATIVE_PERIOD`
`measurement_type`	MeasurementType	`MeasurementType.TOTAL`	The type of measurement represented by a value associated with a timestamp: e.g., mean, total
`format`	RepresentativePeriodFormat	(required)	Format of the timestamps in the load data
`ranges`	list[MonthRangeModel]	(required)	Defines the continuous ranges of datetime in the data, inclusive of start and end time.
`time_interval_type`	TimeIntervalType	(required)	The range of time that the value associated with a timestamp represents

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description

MonthRangeModel¶

dsgrid.config.dimensions.MonthRangeModel

Defines a continuous range of time.

Fields¶

Name	Type	Default	Description
`start`	`int`	(required)	First month in the data (January is 1, December is 12)
`end`	`int`	(required)	Last month in the data (inclusive)

IndexTimeDimensionModel¶

dsgrid.config.dimensions.IndexTimeDimensionModel

Defines a time dimension where timestamps are indices and requires converting to datetime.

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`time_type`	TimeDimensionType	`TimeDimensionType.INDEX`
`measurement_type`	MeasurementType	`MeasurementType.TOTAL`	The type of measurement represented by a value associated with a timestamp: e.g., mean, total
`ranges`	list[IndexRangeModel]	(required)	Defines the continuous ranges of indices of the data, inclusive of start and end index.
`time_interval_type`	TimeIntervalType	(required)	The range of time that the value associated with a timestamp represents, e.g., period-beginning

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description
`check_indices`	`check_indices`	No description
`handle_legacy_fields`	`(model)`	No description

IndexRangeModel¶

dsgrid.config.dimensions.IndexRangeModel

Defines a continuous range of indices.

Fields¶

Name	Type	Default	Description
`start`	`int`	(required)	First of indices
`end`	`int`	(required)	Last of indices (inclusive)
`starting_timestamp`	`str`	(required)	Timestamp the start index corresponds to.
`str_format`	`str`	`"%Y-%m-%d %H:%M:%S"`	Timestamp string format. The string format is used to parse the starting timestamp provided. Cheatsheet reference: `<https://strftime.org/>`_.
`frequency`	`timedelta`	`1:00:00`	Resolution of the timestamps for which the index range represents.

NoOpTimeDimensionModel¶

dsgrid.config.dimensions.NoOpTimeDimensionModel

Defines a NoOp time dimension.

Fields¶

Name	Type	Default	Description
`id`	`int` \| None	`None`	Registry database ID
`version`	`str` \| None	`None`	Version, generated by dsgrid
`name`	`str`	(required)	Dimension name
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str` \| None	`None`	Unique identifier, generated by dsgrid
`module`	`str`	`"dsgrid.dimension.standard"`	Python module with the dimension class
`class_name`	`str`	(required)	Dimension record model class name. The dimension class defines the expected and allowable fields (and their data types) for the dimension records file.All dimension records must have a ‘id’ and ‘name’ field.Some dimension classes support additional fields that can be used for mapping, querying, display, etc.dsgrid in online-mode only supports dimension classes defined in the :mod:`dsgrid.dimension.standard` module. If dsgrid does not currently support a dimension class that you require, please contact the dsgrid-coordination team to request a new class feature
`cls`	`Any`	`None`	Dimension record model class
`description`	`str` \| None	`None`	A description of the dimension records that is helpful, memorable, and identifiable
`time_type`	TimeDimensionType	`TimeDimensionType.NOOP`

Validators¶

Name	Applies To	Description
`check_name`	`check_name`	No description
`check_module`	`check_module`	No description
`get_dimension_class_name`	`get_dimension_class_name`	Set class_name based on inputs.
`get_dimension_class`	`get_dimension_class`	No description

DimensionReferenceModel¶

dsgrid.config.dimensions.DimensionReferenceModel

Reference to a dimension stored in the registry

Fields¶

Name	Type	Default	Description
`dimension_type`	DimensionType	(required)	Type of the dimension
`dimension_id`	`str`	(required)	Unique ID of the dimension in the registry. The dimension ID is generated by dsgrid when a dimension is registered. Only alphanumerics and dashes are supported.
`version`	`str`	(required)	Version of the dimension. The version string must be in semver format (e.g., ‘1.0.0’) and it must be a valid/existing version in the registry.