`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_)

Module Contents

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`(value[, type_])	Converts a parameter value from the DB into a Python object.
`to_database`(parsed_value)	Converts a Python object representing a parameter value into their DB representation.

spinedb_api.parameter_value.from_database(value, type_=None)[source]

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

Parameters:

value (bytes or None) – the value field from the parameter_value table.
type (str, optional) – the type field from the parameter_value table.

Returns:

a Python object representing the parameter value.

Return type:

ParameterValue, float, str, bool or None

spinedb_api.parameter_value.to_database(parsed_value)[source]

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

Parameters:: parsed_value (any) – the Python object.
Returns:: the value and type fields that would go in the parameter_value table.
Return type:: tuple(bytes,str)

class spinedb_api.parameter_value.ParameterValue[source]

Base for all classes representing parameter values.

abstract static type_()[source]

Returns the type of the parameter value represented by this object.

Returns:: str

to_database()[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.
Return type:: tuple(bytes,str)

class spinedb_api.parameter_value.DateTime(value=None)[source]

Bases: ParameterValue

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

Parameters:: value (DateTime or str or datetime) – the date_time value.

property value[source]

The value.

Returns:: datetime

class spinedb_api.parameter_value.Duration(value=None)[source]

Bases: ParameterValue

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

Parameters:: value (str or Duration or relativedelta) – the duration value.

property value[source]

The value.

Returns: relativedelta

class spinedb_api.parameter_value.IndexedValue(values, value_type=None, index_name='')[source]

Bases: ParameterValue

Base for all classes representing indexed parameter values.

property indexes[source]

The indexes.

Returns:: ndarray

property values[source]

The values.

Returns:: ndarray

property value_type[source]

The type of the values.

Return type:: type

get_nearest(index)[source]

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

Parameters:: index (any) – The index.
Returns:: The value.
Return type:: any

get_value(index)[source]

Returns the value at the given index.

Parameters:: index (any) – The index.
Returns:: The value.
Return type:: any

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, value_type=None, index_name='')[source]

Bases: IndexedValue

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

Parameters:

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

class spinedb_api.parameter_value.TimePattern(indexes, values, index_name='')[source]

Bases: IndexedValue

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

Parameters:

indexes (list) – the time pattern strings.
values (Sequence) – the values associated to different patterns.
index_name (str) – index name

class spinedb_api.parameter_value.TimeSeries(values, ignore_year, repeat, index_name='')[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, resolution, values, ignore_year, repeat, index_name='')[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 (str or datetime or datetime64) – the first time stamp
resolution (str, relativedelta, list) – duration(s) between the time stamps.
values (Sequence) – the values in the time-series.
ignore_year (bool) – True if the year should be ignored.
repeat (bool) – True if the series is repeating.
index_name (str) – index name.

property indexes[source]

The indexes.

Returns:: ndarray

property start[source]

Returns the start index.

Return type:: datetime64

property resolution[source]

Returns the resolution as list of durations.

Return type:: list(Duration)

class spinedb_api.parameter_value.TimeSeriesVariableResolution(indexes, values, ignore_year, repeat, index_name='')[source]

Bases: TimeSeries

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

Parameters:

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

class spinedb_api.parameter_value.Map(indexes, values, index_type=None, index_name='')[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 (Sequence) – the indexes in the map.
values (Sequence) – the value for each index.
index_type (type or NoneType) – index type or None to deduce from indexes.
index_name (str) – index name.

is_nested()[source]

Whether any of the values is also a map.

Return type:: bool

value_to_database_data()[source]: Returns map’s database representation’s ‘data’ dictionary.

spinedb_api.parameter_value

Module Contents

Classes

Functions

`spinedb_api.parameter_value`