spinedb_api.parameter_value

Parameter values in a Spine DB can be of different types (see Parameter value format). For each of these types, this module provides a Python class to represent values of that type.

Parameter value type and Python class
type	Python class
`date_time`	`DateTime`
`duration`	`Duration`
`array`	`Array`
`time_pattern`	`TimePattern`
`time_series`	`TimeSeriesFixedResolution` and `TimeSeriesVariableResolution`
`map`	`Map`

The module also provides the functions to_database() and from_database() to translate between instances of the above classes and their DB representation (namely, the value and type fields that would go in the parameter_value table).

For example, to write a Python object into a parameter value in the DB:

# Create the Python object
parsed_value = TimeSeriesFixedResolution(
    "2023-01-01T00:00",             # start
    "1D",                           # resolution
    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0], # values
    ignore_year=False,
    repeat=False,
)
# Translate it to value and type
value, type_ = to_database(parsed_value)
# Add a parameter_value to the DB with that value and type
with DatabaseMapping(url) as db_map:
    db_map.add_parameter_value_item(
        entity_class_name="cat",
        entity_byname=("Tom",),
        parameter_definition_name="number_of_lives",
        alternative_name="Base",
        value=value,
        type=type_,
    )
    db_map.commit_session("Tom is living one day at a time")

The value can be accessed as a Python object using the parsed_value field:

# Get the parameter_value from the DB
with DatabaseMapping(url) as db_map:
    pval_item = db_map.get_parameter_value_item(
        entity_class_name="cat",
        entity_byname=("Tom",),
        parameter_definition_name="number_of_lives",
        alternative_name="Base",
    )
value = pval_item["parsed_value"]

In the rare case where a manual conversion from a DB value to Python object is needed, use from_database():

# Obtain value and type
value, type_ = pval_item["value"], pval_item["type"]
# Translate value and type to a Python object manually
parsed_value = from_database(value, type_)

Classes

`ParameterValue`	Base for all classes representing parameter values.
`DateTime`	A parameter value of type 'date_time'. A point in time.
`Duration`	A parameter value of type 'duration'. An extension of time.
`IndexedValue`	Base for all classes representing indexed parameter values.
`Array`	A parameter value of type 'array'. A one dimensional array with zero based indexing.
`TimePattern`	A parameter value of type 'time_pattern'.
`TimeSeries`	Base for all classes representing 'time_series' parameter values.
`TimeSeriesFixedResolution`	A parameter value of type 'time_series'.
`TimeSeriesVariableResolution`	A parameter value of type 'time_series'.
`Map`	A parameter value of type 'map'. A mapping from key to value, where the values can be other instances

Functions

`from_database`(→ Optional[Value])	Converts a parameter value from the DB into a Python object.
`to_database`(→ tuple[bytes, Optional[str]])	Converts a Python object representing a parameter value into its DB representation.
`convert_map_to_dict`(→ dict)	Converts a `Map` to a nested dictionary.
`type_for_value`(→ tuple[str, int])	Declares value's database type and rank.
`type_for_scalar`(→ Optional[str])	Declares scalar value's database type.

Module Contents

spinedb_api.parameter_value.from_database(value: bytes, type_: str | None) → Value | None[source]

Converts a parameter value from the DB into a Python object.

Parameters:

value – The binary blob containing the value data from database.
type – Value’s type.

Returns:

A Python object representing the value.

spinedb_api.parameter_value.to_database(parsed_value: Value | None) → tuple[bytes, str | None][source]

Converts a Python object representing a parameter value into its DB representation.

Parameters:: parsed_value – A Python object representing the value.
Returns:: The value as a binary blob and its type string.

class spinedb_api.parameter_value.ParameterValue[source]

Base for all classes representing parameter values.

classmethod type_() → str[source]: Returns the type of the parameter value represented by this object.

to_database() → tuple[bytes, str][source]

Returns the DB representation of this object. Equivalent to calling to_database() with it.

Returns:: The value and type fields that would go in the parameter_value table.

class spinedb_api.parameter_value.DateTime(value: str | DateTime | datetime.datetime | None = None)[source]

Bases: ParameterValue

A parameter value of type ‘date_time’. A point in time.

Parameters:: value. (The date_time)

class spinedb_api.parameter_value.Duration(value: str | dateutil.relativedelta.relativedelta | Duration | None = None)[source]

Bases: ParameterValue

A parameter value of type ‘duration’. An extension of time.

Parameters:: value – the duration value.

class spinedb_api.parameter_value.IndexedValue(values: collections.abc.Sequence[Any], value_type: Type | None = None, index_name: str = '')[source]

Bases: ParameterValue

Base for all classes representing indexed parameter values.

property values: collections.abc.Sequence[Any][source]: The values.

property indexes: numpy.typing.NDArray[source]: The indexes.

property value_type: Type[source]: The type of the values.

get_nearest(index: Any) → Any[source]

Returns the value at the nearest index to the given one.

Parameters:: index – The index.
Returns:: The value.

get_value(index: Any) → Any[source]

Returns the value at the given index.

Parameters:: index – The index.
Returns:: The value.

set_value(index, value)[source]

Sets the value at the given index.

Parameters:

index (any) – The index.
value (any) – The value.

class spinedb_api.parameter_value.Array(values: collections.abc.Sequence[ScalarValue], value_type: Type | None = None, index_name: str = '')[source]

Bases: IndexedValue

A parameter value of type ‘array’. A one dimensional array with zero based indexing.

Parameters:

values – the array values.
value_type – the type of the values; if not given, it will be deduced from values. Defaults to float if values is empty.
index_name – the name you would give to the array index in your application.

indexes[source]: The indexes.

class spinedb_api.parameter_value.TimePattern(indexes: list[str], values: collections.abc.Sequence[float], index_name: str = '')[source]

Bases: IndexedValue

A parameter value of type ‘time_pattern’. A mapping from time patterns strings to numerical values.

Parameters:

indexes – the time pattern strings.
values – the values associated to different patterns.
index_name – index name

indexes[source]: The indexes.

class spinedb_api.parameter_value.TimeSeries(values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '')[source]

Bases: IndexedValue

Base for all classes representing ‘time_series’ parameter values.

property ignore_year[source]

Whether the year should be ignored.

Return type:: bool

property repeat[source]

Whether the series is repeating.

Return type:: bool

class spinedb_api.parameter_value.TimeSeriesFixedResolution(start: str | datetime.datetime | numpy.datetime64, resolution: str | dateutil.relativedelta.relativedelta | list[str | dateutil.relativedelta.relativedelta], values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '')[source]

Bases: TimeSeries

A parameter value of type ‘time_series’. A mapping from time stamps to numerical values, with fixed durations between the time stamps.

When getting the indexes the durations are applied cyclically.

Currently, there is no support for the ignore_year and repeat options other than having getters for their values.

Parameters:

start – the first time stamp
resolution – duration(s) between the time stamps.
values – the values in the time-series.
ignore_year – True if the year should be ignored.
repeat – True if the series is repeating.
index_name – index name.

property start: numpy.datetime64[source]: Returns the start index.

property resolution: list[dateutil.relativedelta.relativedelta][source]: Returns the resolution as list of durations.

property indexes[source]: The indexes.

get_value(index: numpy.datetime64) → numpy.float64 | None[source]: Returns the value at the given time stamp.

set_value(index: numpy.datetime64, value: float) → None[source]: Sets the value at the given index.

class spinedb_api.parameter_value.TimeSeriesVariableResolution(indexes: collections.abc.Sequence[str | datetime.datetime | numpy.datetime64 | DateTime], values: collections.abc.Sequence[float], ignore_year: bool, repeat: bool, index_name: str = '')[source]

Bases: TimeSeries

A parameter value of type ‘time_series’. A mapping from time stamps to numerical values with arbitrary time steps.

Parameters:

indexes – the time stamps.
values – the value for each time stamp.
ignore_year – True if the year should be ignored.
repeat – True if the series is repeating.
index_name – index name.

indexes[source]: The indexes.

class spinedb_api.parameter_value.Map(indexes: collections.abc.Sequence[MapIndex], values: collections.abc.Sequence[Value], index_type: Type | None = None, index_name: str = '')[source]

Bases: IndexedValue

A parameter value of type ‘map’. A mapping from key to value, where the values can be other instances of ParameterValue.

Parameters:

indexes – the indexes in the map.
values – the value for each index.
index_type – index type or None to deduce from indexes.
index_name – index name.

indexes[source]: The indexes.

is_nested() → bool[source]: Whether any of the values is also a map.

value_to_database_data() → tuple[list[list[float | str]], int][source]: Returns map’s database representation’s ‘data’ dictionary.

spinedb_api.parameter_value.convert_map_to_dict(map_: Map) → dict[source]: Converts a Map to a nested dictionary.

spinedb_api.parameter_value.type_for_value(value: Value) → tuple[str, int][source]

Declares value’s database type and rank.

Parameters:: value – value to inspect
Returns:: type and rank

spinedb_api.parameter_value.type_for_scalar(parsed_value: JSONValue) → str | None[source]

Declares scalar value’s database type.

Parameters:: parsed_value – parsed scalar
Returns:: value’s type