Core¶

Parameters¶

Parameter handling.

openscm.core.parameters.HIERARCHY_SEPARATOR = '|'¶

String used to define different levels in our data hierarchies

By default we follow pyam and use “|”. In such a case, emissions of CO2 for energy from coal would be “Emissions|CO2|Energy|Coal”.

class openscm.core.parameters.ParameterInfo(parameter)¶

Bases: object

Information for a parameter.

__init__(parameter)¶

Initialize.

Parameters: parameter (_Parameter) – Parameter

_parameter = None¶: Parameter

property empty¶

Check if parameter is empty, i.e. has not yet been written to.

Return type: bool

ensure()¶

Ensure that parameter is not empty.

Raises: ParameterEmptyError – If parameter is empty
Return type: None

property name¶

Hierarchical name of the parameter

Return type: Tuple[str, …]

property parameter_type¶

Parameter type

Return type: Optional[ParameterType]

property region¶

Hierarchichal name of the region this parameter belongs to

Return type: Tuple[str, …]

property unit¶

Parameter unit

Return type: Optional[str]

property version¶

Version number of parameter (used internally)

Return type: int

class openscm.core.parameters.ParameterType¶

Bases: enum.Enum

Parameter type.

AVERAGE_TIMESERIES = 2¶

GENERIC = 4¶

POINT_TIMESERIES = 3¶

SCALAR = 1¶

from_timeseries_type(timeseries_type) = <bound method ParameterType.from_timeseries_type of <enum 'ParameterType'>>¶

timeseries_type_to_string(timeseries_type) = <bound method ParameterType.timeseries_type_to_string of <enum 'ParameterType'>>¶

class openscm.core.parameters._Parameter(name, region)¶

Bases: object

Represents a parameter in the parameter hierarchy.

__init__(name, region)¶

Initialize.

Parameters: name (str) – Name

attempt_read(parameter_type, unit=None, time_points=None)¶

Tell parameter that it will be read from. If the parameter has child parameters it will be read in in an aggregated way, i.e., aggregating over child parameters.

Parameters

parameter_type (ParameterType) – Parameter type to be read
unit (Optional[str]) – Unit to be read; only for scalar and timeseries parameters
time_points (Optional[ndarray]) – Timeseries time points; only for timeseries parameters

Raises

ParameterTypeError – If parameter has already been read from or written to in a different type
ParameterAggregationError – If parameter has child parameters which cannot be aggregated (for boolean and string parameters)

Return type

None

attempt_write(parameter_type, unit=None, time_points=None)¶

Tell parameter that its data will be written to.

Parameters

parameter_type (ParameterType) – Parameter type to be written
unit (Optional[str]) – Unit to be written; only for scalar and timeseries parameters
time_points (Optional[ndarray]) – Timeseries time points; only for timeseries parameters

Raises

ParameterReadonlyError – If parameter is read-only because it has child parameters

Return type

None

children = None¶: Child parameters

data = None¶: Data

property full_name¶

Full hierarchical name

Return type: Tuple[str, …]

get_or_create_child_parameter(name)¶

Get a (direct) child parameter of this parameter. Create and add it if not found.

Parameters

name (str) – Name

Returns

Parameter found or newly created

Return type

_Parameter

Raises

ParameterReadError – If the child parameter would need to be added, but this parameter has already been read from. In this case a child parameter cannot be added.
ParameterWrittenError – If the child parameter would need to be added, but this parameter has already been written to. In this case a child parameter cannot be added.

get_subparameter(name)¶

Get a sub parameter of this parameter or None if not found.

Parameters: name (Union[str, Sequence[str]]) – Hierarchical name of the subparameter below this parameter or () for this parameter
Returns: Parameter of None if not found
Return type: Optional[_Parameter]

has_been_read_from = None¶: If True, parameter has already been read from

has_been_written_to = None¶: If True, parameter data has already been changed

name = None¶: Name

parameter_type = None¶: Parameter type

parent = None¶: Parent parameter

region = None¶: Region this parameter belongs to

time_points = None¶: Timeseries time points; only for timeseries parameters

unit = None¶: Unit

version = None¶: Internal version (incremented by each write operation)

Parameter views¶

Parameter views provide ways to read and write parameter data with a defined unit and time information.

class openscm.core.views.GenericView(parameter)¶

Bases: openscm.core.parameters.ParameterInfo

View of a generic parameter.

__init__(parameter)¶

Initialize.

Parameters: parameter (_Parameter) – Parameter to handle

_writable = None¶: Is this view writable? Is set to True once this view is written to.

property empty¶

Check if parameter is empty, i.e. has not yet been written to.

Return type: bool

ensure()¶

Ensure that parameter is not empty.

Raises: ParameterEmptyError – If parameter is empty
Return type: None

property name¶

Hierarchical name of the parameter

Return type: Tuple[str, …]

property parameter_type¶

Parameter type

Return type: Optional[ParameterType]

property region¶

Hierarchichal name of the region this parameter belongs to

Return type: Tuple[str, …]

property unit¶

Parameter unit

Return type: Optional[str]

property value¶

Value of generic parameter

Raises

ParameterEmptyError – Parameter is empty, i.e. has not yet been written to
ParameterReadonlyError – Parameter is read-only (e.g. because its parent has been written to)

Return type

Any

property version¶

Version number of parameter (used internally)

Return type: int

class openscm.core.views.ScalarView(parameter, unit)¶

Bases: openscm.core.parameters.ParameterInfo

View of a scalar parameter.

__init__(parameter, unit)¶

Initialize.

Parameters

parameter (_Parameter) – Parameter to handle
unit (str) – Unit for the values in the view

_child_data_views = None¶: List of views to the child parameters for aggregated reads

_unit_converter = None¶: Unit converter

_writable = None¶: Is this view writable? Is set to True once this view is written to.

property empty¶

Check if parameter is empty, i.e. has not yet been written to.

Return type: bool

ensure()¶

Ensure that parameter is not empty.

Raises: ParameterEmptyError – If parameter is empty
Return type: None

property name¶

Hierarchical name of the parameter

Return type: Tuple[str, …]

property parameter_type¶

Parameter type

Return type: Optional[ParameterType]

property region¶

Hierarchichal name of the region this parameter belongs to

Return type: Tuple[str, …]

property unit¶

Parameter unit

Return type: Optional[str]

property value¶

Value of scalar parameter

If the parameter has child parameters, the returned value will be the sum of the values of all of the child parameters.

Raises

ParameterEmptyError – Parameter is empty, i.e. has not yet been written to
ParameterReadonlyError – Parameter is read-only (e.g. because its parent has been written to)

Return type

float

property version¶

Version number of parameter (used internally)

Return type: int

class openscm.core.views.TimeseriesView(parameter, unit, time_points, timeseries_type, interpolation_type, extrapolation_type)¶

Bases: openscm.core.parameters.ParameterInfo

View of a timeseries.

__init__(parameter, unit, time_points, timeseries_type, interpolation_type, extrapolation_type)¶

Initialize.

Parameters

parameter (_Parameter) – Parameter
unit (str) – Unit for the values in the view
time_points (ndarray) – Timeseries time points
timeseries_type (ParameterType) – Time series type
interpolation_type (InterpolationType) – Interpolation type
extrapolation_type (ExtrapolationType) – Extrapolation type

_check_write()¶

_child_data_views = None¶: List of views to the child parameters for aggregated reads

_data = None¶: Chache for underlying data

_get_values()¶

Return type: ndarray

_locked = None¶: Is this view locked (i.e., does it not update the underlying parameter on every write)?

_read()¶

_timeseries = None¶: Time series handler

_timeseries_converter = None¶: Timeseries converter

_unit_converter = None¶: Unit converter

_version = None¶: Version of cache

_writable = None¶: Is this view writable? Is set to True once this view is written to.

_write()¶

property empty¶

Check if parameter is empty, i.e. has not yet been written to.

Return type: bool

ensure()¶

Ensure that parameter is not empty.

Raises: ParameterEmptyError – If parameter is empty
Return type: None

property length¶

Length of timeseries

Return type: int

lock()¶

Lock this view (i.e., do not update the underlying parameter on every write).

Return type: None

property name¶

Hierarchical name of the parameter

Return type: Tuple[str, …]

property parameter_type¶

Parameter type

Return type: Optional[ParameterType]

property region¶

Hierarchichal name of the region this parameter belongs to

Return type: Tuple[str, …]

property unit¶

Parameter unit

Return type: Optional[str]

unlock()¶

Unlock this view (i.e., update the underlying parameter on every write).

Updates the underlying parameter.

Return type: None

property values¶

Values of the full timeseries

If the parameter has child parameters, the returned value will be the sum of the values of all of the child parameters.

Raises

ParameterEmptyError – Parameter is empty, i.e. has not yet been written to
ParameterReadonlyError – Parameter is read-only (e.g. because its parent has been written to)
TimeseriesPointsValuesMismatchError – Lengths of set value and the time points number mismatch

Return type

_Timeseries

property version¶

Version number of parameter (used internally)

Return type: int

class openscm.core.views._Timeseries(input_array, parameter_view)¶

Bases: pandas.core.arrays.base.ExtensionOpsMixin, numpy.lib.mixins.NDArrayOperatorsMixin

Internal class which wraps numpy to make sure data is buffered and up-to-date

_HANDLED_TYPES = (<class 'numpy.ndarray'>, <class 'numbers.Number'>)¶

__init__(input_array, parameter_view)¶

Initialize.

Parameters

input_array (ndarray) – Array to handle
parameter_view (TimeseriesView) – TimeseriesView this timeseries belongs to

classmethod _add_arithmetic_ops()¶

classmethod _add_comparison_ops()¶

classmethod _create_arithmetic_method(op)¶

classmethod _create_comparison_method(op)¶

property dtype¶

np.dtype of the timeseries

Return type: dtype

property nbytes¶: Bytes block of the unterlying timeseries

property ndim¶: Dimension of the timeseries (==1)

property shape¶

Shape of the 1-dimensional timeseries array

Return type: Tuple[int, …]

Regions¶

Handling of region information.

class openscm.core.regions._Region(name)¶

Bases: object

Represents a region in the region hierarchy.

__init__(name)¶

Initialize

Parameters: name (str) – Name

_children = None¶: Subregions

_has_been_aggregated = None¶: If True, a parameter of this region has already been read in an aggregated way, i.e., aggregating over subregions

_name = None¶: Name

_parameters = None¶: Parameters

_parent = None¶: Parent region (or None if root region)

attempt_aggregate()¶

Tell region that one of its parameters will be read from in an aggregated way, i.e., aggregating over subregions.

Return type: None

property full_name¶

Full hierarchical name

Return type: Tuple[str, …]

get_or_create_parameter(name)¶

Get a root parameter for this region. Create and add it if not found.

Parameters: name (str) – Name
Returns: Root parameter found or newly created
Return type: parameters._Parameter

get_or_create_subregion(name)¶

Get a (direct) subregion of this region. Create and add it if not found.

Parameters: name (str) – Name
Returns: Region found or newly created
Return type: _Region
Raises: RegionAggregatedError – If the subregion would need to be added and a parameter of this region has already been read in an aggregated way. In this case a subregion cannot be created.

get_parameter(name)¶

Get a (root or sub-) parameter for this region or None if not found.

Parameters: name (Union[str, Sequence[str]]) – Hierarchical name of the parameter
Returns: Parameter of None if not found
Return type: Optional[parameters._Parameter]
Raises: ValueError – Name not given

get_subregion(name)¶

Get a subregion of this region or None if not found.

Parameters: name (Union[str, Sequence[str]]) – Hierarchical name of the region below this region or () for this region
Returns: Subregion or None if not found
Return type: Optional[_Region]

property name¶

Name

Return type: str

property parent¶

Parent region (or None if root region)

Return type: Optional[_Region]

Time¶

Different climate models often use different time frames for their input and output data. This includes different ‘meanings’ of time steps (e.g. beginning vs middle of year) and different lengths of the time steps (e.g. years vs months). Accordingly, OpenSCM supports the conversion of timeseries data between such timeseries, which is handled in this module. A thorough explaination of the procedure used is given in a dedicated Jupyter Notebook.

class openscm.core.time.ExtrapolationType¶

Bases: enum.Enum

Extrapolation type.

CONSTANT = 0¶

LINEAR = 1¶

NONE = -1¶

from_extrapolation_type(extrapolation_type) = <bound method ExtrapolationType.from_extrapolation_type of <enum 'ExtrapolationType'>>¶

class openscm.core.time.InterpolationType¶

Bases: enum.Enum

Interpolation type.

LINEAR = 1¶

from_interpolation_type(interpolation_type) = <bound method InterpolationType.from_interpolation_type of <enum 'InterpolationType'>>¶

class openscm.core.time.TimePoints(values)¶

Bases: object

Handles time points by wrapping np.ndarray of np.datetime64..

__init__(values)¶

Initialize.

Parameters: values (Sequence[+T_co]) – Time points array to handle

_values = None¶: Actual time points array

days()¶

Get day of each time point.

Returns: Day of each time point
Return type: np.array of int

hours()¶

Get hour of each time point.

Returns: Hour of each time point
Return type: np.array of int

months()¶

Get month of each time point.

Returns: Month of each time point
Return type: np.array of int

to_index()¶

Get time points as pd.Index.

Returns: pd.Index of np.dtype object with name "time" made from the time points represented as datetime.datetime.
Return type: pd.Index

property values¶

Time points

Return type: ndarray

weekdays()¶

Get weekday of each time point.

Returns: Day of the week of each time point
Return type: np.array of int

years()¶

Get year of each time point.

Returns: Year of each time point
Return type: np.array of int

class openscm.core.time.TimeseriesConverter(source_time_points, target_time_points, timeseries_type, interpolation_type, extrapolation_type)¶

Bases: object

Converts timeseries and their points between two timeseriess (each defined by a time of the first point and a period length).

__init__(source_time_points, target_time_points, timeseries_type, interpolation_type, extrapolation_type)¶

Initialize.

Parameters

source_time_points (ndarray) – Source timeseries time points
target_time_points (ndarray) – Target timeseries time points
timeseries_type (ParameterType) – Time series type
interpolation_type (InterpolationType) – Interpolation type
extrapolation_type (ExtrapolationType) – Extrapolation type

Raises

InsufficientDataError – Timeseries too short to extrapolate

_calc_continuous_representation(time_points, values)¶

Calculate a “continuous” representation of a timeseries (see openscm.timeseries_converter._calc_integral_preserving_linear_interpolation()) with the time points time_points and values values.

Parameters

time_points (ndarray) – Time points of the timeseries
values (ndarray) – Values of the timeseries

Returns

Function that represents the interpolated timeseries. It takes a single argument, time (“x-value”), and returns a single float, the value of the interpolated timeseries at that point in time (“y-value”).

Return type

Callable[[float], float]

_convert(values, source_time_points, target_time_points)¶

Wrap _convert_unsafe() to provide proper error handling.

_convert_unsafe() converts time period average timeseries data values for timeseries time points source_time_points to the time points target_time_points.

Parameters

values (ndarray) – Array of data to convert
source_time_points (ndarray) – Source timeseries time points
target_time_points (ndarray) – Target timeseries time points

Raises

InsufficientDataError – Length of the time series is too short to convert
InsufficientDataError – Target time points are outside the source time points and _extrapolation_type is ExtrapolationType.NONE

Returns

Converted time period average data for timeseries values

Return type

np.ndarray

_convert_unsafe(values, source_time_points, target_time_points)¶

Convert time period average timeseries data values for timeseries time points source_time_points to the time points target_time_points.

Parameters

values (ndarray) – Array of data to convert
source_time_points (ndarray) – Source timeseries time points
target_time_points (ndarray) – Target timeseries time points

Raises

NotImplementedError – The timeseries type is not recognised

Returns

Converted time period average data for timeseries values

Return type

np.ndarray

_extrapolation_type = None¶: Extrapolation type

_get_scipy_extrapolation_args(values)¶

Return type: Dict[str, Any]

_get_scipy_interpolation_arg()¶

Return type: str

_interpolation_type = None¶: Interpolation type

_source = None¶: Source timeseries time points

_target = None¶: Target timeseries time points

_timeseries_type = None¶: Time series type

convert_from(values)¶

Convert value from source timeseries time points to target timeseries time points.

Parameters: values (ndarray) – Value
Returns: Converted array
Return type: np.ndarray

convert_to(values)¶

Convert value from target timeseries time points to source timeseries time points.

Parameters: values (ndarray) – Value
Returns: Converted array
Return type: np.ndarray

property source_length¶

Length of source timeseries

Return type: int

property target_length¶

Length of target timeseries

Return type: int

openscm.core.time._calc_integral_preserving_linear_interpolation(values)¶

Calculate the “linearization” values of the array values which is assumed to represent averages over time periods. Values at the edges of the periods are taken as the average of adjacent periods, values at the period middles are taken such that the integral over a period is the same as for the input data.

Parameters: values (ndarray) – Timeseries values of period averages
Returns: Values of linearization (of length 2 * len(values) + 1)
Return type: np.ndarray

openscm.core.time._calc_interval_averages(continuous_representation, target_intervals)¶

Calculate the interval averages of a continuous function.

Here interval average is calculated as the integral over the period divided by the period length.

Parameters

continuous_representation (Callable[[float], float]) – Continuous function from which to calculate the interval averages. Should be calculated using openscm.timeseries_converter.TimeseriesConverter._calc_continuous_representation().
target_intervals (ndarray) – Intervals to calculate the average of.

Returns

Array of the interval/period averages

Return type

np.ndarray

openscm.core.time._float_year_to_datetime(inp)¶

Return type: datetime64

openscm.core.time._format_datetime(dts)¶

Convert an array to an array of np.datetime64.

Parameters: dts (ndarray) – Input to attempt to convert
Returns: Converted array
Return type: np.ndarray of np.datetime64
Raises: ValueError – If one of the values in dts cannot be converted to np.datetime64

openscm.core.time._parse_datetime(inp)¶

Return type: ndarray

openscm.core.time.create_time_points(start_time, period_length, points_num, timeseries_type)¶

Create time points for an equi-distant time series.

Parameters

start_time (datetime64) – First time point of the timeseries
period_length (timedelta64) – Period length
points_num (int) – Length of timeseries
timeseries_type (Union[ParameterType, str]) – Timeseries type

Returns

Array of the timeseries time points

Return type

np.ndarray of np.datetime64