iode.Scalars.setitem

Update/add a (subset of) scalar(s) referenced by key from/to the Scalars database.

The key can represent a single object name (e.g. “ACAF”) or a list of object names (“ACAF;ACAG;AOUC”) or a pattern (e.g. “A*”) or a list of sub-patterns (e.g. “A*;*_”).

If the key represents a list of object names or of sub-patterns, each name or sub-pattern is separated by a separator character which is either a whitespace ` , or a comma `,, or a semi-colon ;, or a tabulation t, or a newline n.

A (sub-)`pattern` is a list of characters representing a group of object names. It includes some special characters which have a special meaning:

* : any character sequence, even empty

? : any character (one and only one)

@ : any alphanumerical char [A-Za-z0-9]

& : any non alphanumerical char

| : any alphanumeric character or none at the beginning and end of a string

! : any non-alphanumeric character or none at the beginning and end of a string

`` : escape the next character

Note that the key can contain references to IODE lists which are prefixed with the symbol $.

Parameters:

key: str or list(str): (the list of) name(s) of the scalar(s) to update/add. The list of scalars to update/add can be specified by a pattern or by a list of sub-patterns (e.g. “A*;*_”).
value: float or tuple(float, float) or Scalar or dict(str, …) or pd.Series or pd.DataFrame or Scalars: If float, then it is interpreted as the value of the scalar. If tuple of two float, then it is interpreted as the value and relax of the scalar. The standard deviation is computed during the estimation process and cannot be modified manually. If Scalar, then it is used to update an existing scalar or to create a new scalar if it does not exist yet. If pandas Series, then it is interpreted as a list of couples (scalar name, scalar value). If pandas DataFrame, then only the columns names ‘value’ and ‘relax’ are allowed.

See also

iode.Scalar

Examples

>>> import pandas as pd
>>> from iode import SAMPLE_DATA_DIR
>>> from iode import scalars, Scalar
>>> scalars.load(f"{SAMPLE_DATA_DIR}/fun.scl")
Loading .../fun.scl
161 objects loaded 

>>> # a) -------- add one scalar -------- 
>>> # 1. default relax to 1.0
>>> scalars["a0"] = 0.1
>>> scalars["a0"]
Scalar(0.1, 1, na)
>>> # 2. value + relax
>>> scalars["a1"] = 0.1, 0.9
>>> scalars["a1"]
Scalar(0.1, 0.9, na)

>>> # b) -------- update one scalar --------
>>> scalars["acaf1"]
Scalar(0.0157684, 1, 0.00136871)
>>> # only update the value
>>> scalars["acaf1"] = 0.8
>>> scalars["acaf1"]
Scalar(0.8, 1, na)
>>> # update value and relax (tuple)
>>> scalars["acaf2"] = 0.8, 0.9
>>> scalars["acaf2"]
Scalar(0.8, 0.9, na)
>>> # update value and relax (list)
>>> scalars["acaf2"] = (0.7, 0.8)
>>> scalars["acaf2"]
Scalar(0.7, 0.8, na)
>>> # update value and relax (dictionary)
>>> scalars["acaf3"] = {"relax": 0.9, "value": 0.8}
>>> scalars["acaf3"]
Scalar(0.8, 0.9, na)
>>> # update value and/or relax (Scalar object)
>>> # NOTE: the standard deviation (std) cannot be changed manually
>>> scalars["acaf4"]
Scalar(-0.00850518, 1, 0.0020833)
>>> scl = scalars["acaf4"]
>>> scl.value = 0.8
>>> scl.relax = 0.9
>>> scalars["acaf4"]
Scalar(0.8, 0.9, na)

>>> # c) add/update multiple scalars at once
>>> # 1) using a dict of values
>>> values = {"acaf1": 0.016, "acaf2": (-8.e-04, 0.9), "acaf3": Scalar(2.5)}
>>> scalars["acaf1, acaf2, acaf3"] = values
>>> scalars["acaf1, acaf2, acaf3"]
Workspace: Scalars
nb scalars: 3
filename: ...fun.scl

 name    value  relax   std  
acaf1    0.0160 1.0000   na
acaf2   -0.0008 0.9000   na
acaf3    2.5000 1.0000   na

>>> # 2) using a pandas series (only scalar's values)
>>> data = [0.015, -9.e-04, 2.8]
>>> series = pd.Series(data, index=["acaf1", "acaf2", "acaf3"])
>>> scalars["acaf1, acaf2, acaf3"] = series
>>> scalars["acaf1, acaf2, acaf3"]
Workspace: Scalars
nb scalars: 3
filename: ...fun.scl

 name    value  relax   std  
acaf1    0.0150 1.0000   na
acaf2   -0.0009 0.9000   na
acaf3    2.8000 1.0000   na

>>> # 3) using a pandas DataFrame (value + relax)
>>> data = [(0.014, 0.98), (-7.e-04, 0.95), (2.3, 0.92)]
>>> df = pd.DataFrame(data, index=["acaf1", "acaf2", "acaf3"], columns=["value", "relax"])
>>> scalars["acaf1, acaf2, acaf3"] = df
>>> scalars["acaf1, acaf2, acaf3"]
Workspace: Scalars
nb scalars: 3
filename: ...fun.scl

 name    value  relax   std  
acaf1    0.0140 0.9800   na
acaf2   -0.0007 0.9500   na
acaf3    2.3000 0.9200   na

>>> # 4) using another Scalars database (subset)
>>> scalars_subset = scalars["acaf1, acaf2, acaf3"].copy()
>>> scalars_subset["acaf1"] = 0.02
>>> scalars_subset["acaf2"] = (-5.e-04, 0.94)
>>> scalars_subset["acaf3"] = Scalar(2.9)
>>> scalars["acaf1, acaf2, acaf3"] = scalars_subset
>>> scalars["acaf1, acaf2, acaf3"]
Workspace: Scalars
nb scalars: 3
filename: ...fun.scl

 name    value  relax   std  
acaf1    0.0200 0.9800   na
acaf2   -0.0005 0.9400   na
acaf3    2.9000 1.0000   na

>>> # d) working on a subset
>>> # 1) get subset
>>> scalars_subset = scalars["a*"]
>>> scalars_subset.names
['a0', 'a1', 'acaf1', 'acaf2', 'acaf3', 'acaf4']
>>> # 2) add a scalar to the subset 
>>> scalars_subset["acaf0"] = 1.0, 1.0
>>> scalars_subset["acaf0"]
Scalar(1, 1, na)
>>> # --> new scalar also appears in the global workspace
>>> "acaf0" in scalars
True
>>> scalars["acaf0"]
Scalar(1, 1, na)
>>> # 3) update a scalar in the subset
>>> scalars_subset["acaf0"] = 0.1
>>> scalars_subset["acaf0"]
Scalar(0.1, 1, na)
>>> # --> scalar is also updated in the global workspace
>>> scalars["acaf0"]
Scalar(0.1, 1, na)

iode.Scalars.__setitem__

iode.Scalars.setitem