Dimension Config

pydantic model dsgrid.config.dimensions.DimensionModel

Defines a non-time dimension

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• file_hash (str | None)

• filename (str | None)

• records (list)

Validators:

• add_records » records

• check_file » filename

• compute_file_hash » file_hash

field file_hash: str | None = None

Hash of the contents of the file

Validated by:

• compute_file_hash

field filename: str | None = None (alias 'file')

Filename containing dimension records. Only assigned for user input and output purposes. The registry database stores records in the dimension JSON document.

Validated by:

• check_file

field 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’},

],

Validated by:

• add_records

validator add_records  »  records

Add records from the file.

validator check_file  »  filename

Validate that dimension file exists and has no errors

validator compute_file_hash  »  file_hash

serialize_cls(val: str, _) → None

DateTime Dimension Config

pydantic model dsgrid.config.dimensions.DateTimeDimensionModel

Defines a time dimension where timestamps translate to datetime objects.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• datetime_format (dsgrid.config.dimensions.AlignedTime | dsgrid.config.dimensions.LocalTimeAsStrings)

• frequency (datetime.timedelta)

• measurement_type (dsgrid.dimension.time.MeasurementType)

• ranges (list[dsgrid.config.dimensions.TimeRangeModel])

• str_format (str)

• time_interval_type (dsgrid.dimension.time.TimeIntervalType)

Validators:

• check_frequency » frequency

• check_times » ranges

• handle_legacy_fields » all fields

field datetime_format: AlignedTime | LocalTimeAsStrings [Required]

Format of the datetime used to define the data format, alignment between geography, and time zone information.

Validated by:

• handle_legacy_fields

field frequency: timedelta [Required]

Resolution of the timestamps

Validated by:

• check_frequency

• handle_legacy_fields

field measurement_type: MeasurementType = MeasurementType.TOTAL

The type of measurement represented by a value associated with a timestamp:

mean, min, max, measured, total

Validated by:

• handle_legacy_fields

field ranges: list[TimeRangeModel] [Required]

Defines the continuous ranges of time in the data, inclusive of start and end time.

Validated by:

• check_times

• handle_legacy_fields

field 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/.

Validated by:

• handle_legacy_fields

field time_interval_type: TimeIntervalType [Required]

The range of time that the value associated with a timestamp represents, e.g., period-beginning

Validated by:

• handle_legacy_fields

validator check_frequency  »  frequency

validator check_times  »  ranges

validator handle_legacy_fields  »  all fields

is_time_zone_required_in_geography() → bool

Returns True if the geography dimension records must contain a time_zone column.

Annual Time Dimension Config

pydantic model dsgrid.config.dimensions.AnnualTimeDimensionModel

Defines an annual time dimension where timestamps are years.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• include_leap_day (bool)

• measurement_type (dsgrid.dimension.time.MeasurementType)

• ranges (list[dsgrid.config.dimensions.TimeRangeModel])

• str_format (str)

• time_type (dsgrid.dimension.time.TimeDimensionType)

Validators:

• check_measurement_type » measurement_type

• check_times » ranges

field include_leap_day: bool = False

Whether annual time includes leap day.

field measurement_type: MeasurementType = MeasurementType.TOTAL

The type of measurement represented by a value associated with a timestamp:

e.g., mean, total

Validated by:

• check_measurement_type

field ranges: list[TimeRangeModel] = []

Defines the contiguous ranges of time in the data, inclusive of start and end time.

Validated by:

• check_times

field 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/.

field time_type: TimeDimensionType = TimeDimensionType.ANNUAL

validator check_measurement_type  »  measurement_type

validator check_times  »  ranges

is_time_zone_required_in_geography() → bool

Returns True if the geography dimension records must contain a time_zone column.

Representative Period Time Dimension Config

pydantic model dsgrid.config.dimensions.RepresentativePeriodTimeDimensionModel

Defines a representative time dimension.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• format (dsgrid.dimension.time.RepresentativePeriodFormat)

• measurement_type (dsgrid.dimension.time.MeasurementType)

• ranges (list[dsgrid.config.dimensions.MonthRangeModel])

• time_interval_type (dsgrid.dimension.time.TimeIntervalType)

• time_type (dsgrid.dimension.time.TimeDimensionType)

Validators:

field format: RepresentativePeriodFormat [Required]

Format of the timestamps in the load data

field measurement_type: MeasurementType = MeasurementType.TOTAL

The type of measurement represented by a value associated with a timestamp:

e.g., mean, total

field ranges: list[MonthRangeModel] [Required]

Defines the continuous ranges of time in the data, inclusive of start and end time.

field time_interval_type: TimeIntervalType [Required]

The range of time that the value associated with a timestamp represents

field time_type: TimeDimensionType = TimeDimensionType.REPRESENTATIVE_PERIOD

is_time_zone_required_in_geography() → bool

Returns True if the geography dimension records must contain a time_zone column.

No-op Time Dimension Config

pydantic model dsgrid.config.dimensions.NoOpTimeDimensionModel

Defines a NoOp time dimension.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• time_type (dsgrid.dimension.time.TimeDimensionType)

Validators:

field time_type: TimeDimensionType = TimeDimensionType.NOOP

is_time_zone_required_in_geography() → bool

Returns True if the geography dimension records must contain a time_zone column.

pydantic model dsgrid.config.dimensions.TimeRangeModel

Defines a continuous range of time.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• end (str)

• start (str)

field end: str [Required]

Last timestamp in the data (inclusive)

field start: str [Required]

First timestamp in the data

pydantic model dsgrid.config.dimensions.MonthRangeModel

Defines a continuous range of time.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• end (int)

• start (int)

field end: int [Required]

Last month in the data (inclusive)

field start: int [Required]

First month in the data (January is 1, December is 12)

Dimension Reference

pydantic model dsgrid.config.dimensions.DimensionReferenceModel

Reference to a dimension stored in the registry

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• dimension_id (str)

• dimension_type (dsgrid.dimension.base_models.DimensionType)

• version (str)

field 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.

field dimension_type: DimensionType [Required] (alias 'type')

Type of the dimension

field 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.

Dimensions Config

pydantic model dsgrid.config.dimensions_config.DimensionsConfigModel

Represents multiple dimension models.

Used when registering multiple dimensions in one command.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

• dimensions (list[dsgrid.config.dimensions.DimensionModel | dsgrid.config.dimensions.DateTimeDimensionModel | dsgrid.config.dimensions.AnnualTimeDimensionModel | dsgrid.config.dimensions.RepresentativePeriodTimeDimensionModel | dsgrid.config.dimensions.IndexTimeDimensionModel | dsgrid.config.dimensions.NoOpTimeDimensionModel])

Validators:

• check_files » dimensions

• check_names » dimensions

field dimensions: Annotated[list[DimensionModel | DateTimeDimensionModel | AnnualTimeDimensionModel | RepresentativePeriodTimeDimensionModel | IndexTimeDimensionModel | NoOpTimeDimensionModel], BeforeValidator(func=handle_dimension_union, json_schema_input_type=PydanticUndefined)] [Required]

Dimensions for submission to the dimension registry

Constraints:

• func = <function handle_dimension_union at 0x7f79613d8ae0>

• json_schema_input_type = PydanticUndefined

Validated by:

• check_files

• check_names

validator check_files  »  dimensions

Validate dimension files are unique across all dimensions

validator check_names  »  dimensions

Validate dimension names are unique across all dimensions.