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 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
`time_column`	`str`	`"timestamp"`	Name of time column in the dataframe. It should be updated during the query process to reflect any changes to the dataframe time column.
`localize_to_time_zone`	`bool`	`True`	Whether to localize timestamps to time zone(s). If True, timestamps in the dataframe must be tz-naive.

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

AlignedTimeSingleTimeZone¶

dsgrid.config.dimensions.AlignedTimeSingleTimeZone

For each geography, data has the same set of timestamps in absolute time. Timestamps in the data must be tz-aware.

E.g., data in CA and NY both start in 2018-01-01 00:00 EST.

Fields¶

Name	Type	Default	Description
`format_type`	`Literal`	`"TimeZoneFormat.ALIGNED_IN_ABSOLUTE_TIME"`
`time_zone`	`str`	(required)	IANA time zone of data

Validators¶

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

LocalTimeMultipleTimeZones¶

dsgrid.config.dimensions.LocalTimeMultipleTimeZones

For each geography, data has the same set of timestamps when interpreted as local clock time by adjusting for the time zone of each geography. Timestamps in the data must be tz-aware.

E.g., data in CA may start in 2018-01-01 00:00 PST while data in NY may start in 2018-01-01 00:00 EST. They are aligned in clock time but not in absolute time.

Fields¶

Name	Type	Default	Description
`format_type`	`Literal`	`"TimeZoneFormat.ALIGNED_IN_CLOCK_TIME"`
`time_zones`	list[`str`]	(required)	List of unique IANA time zones in the dataset

TimeFormatDateTimeNTZModel¶

dsgrid.config.dimensions.TimeFormatDateTimeNTZModel

Format of timestamps in a dataset is timezone-naive datetime, requiring localization to time zones.

Fields¶

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

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.

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.
`time_zone`	`str` \| None	`None`	IANA time zone of the timestamps. Use None for time zone-naive timestamps.

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)

DatetimeExternalTimeZoneDimensionModel¶

dsgrid.config.dimensions.DatetimeExternalTimeZoneDimensionModel

Defines a time dimension where timestamps are tz-naive and require localizing to a time zone using a time zone column.

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_EXTERNAL_TZ`
`time_zone_format`	AlignedTimeSingleTimeZone \| LocalTimeMultipleTimeZones	(required)	Specifies whether timestamps are aligned in absolute time or in local time when adjusted for time zone.
`measurement_type`	MeasurementType	`MeasurementType.TOTAL`	The type of measurement represented by a value associated with a timestamp: e.g., mean, total
`ranges`	list[TimeRangeModel]	(required)	Defines the continuous ranges of time in the data, inclusive of start and end time. If the timestamps are tz-naive, they will be localized to the time zones provided in the geography dimension records.
`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

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.