iode.Variables.setitem

Variables.__setitem__(key, value)[source]

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

The key represents a selection on the Variables names and optionally on the periods.

The selection on names can be:

a single Variable name (e.g. “ACAF”)

a list of Variable names (e.g. “ACAF;ACAG;AOUC”)

a pattern (e.g. “A*;*_”).

If the selection on names represents a list of names or of sub-patterns, each name or sub-pattern must be 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 selection on names can contain references to IODE lists which are prefixed with the symbol $.

The selection on periods can be:

the whole sample (e.g. None)

a single period (e.g. “1990Y1”)

a range of periods (e.g. “1990Y1:2000Y1”)

a list of periods (e.g. [“1990Y1”, “1995Y1”, “2000Y1”])

Parameters:

key: str or list(str) or tuple(str, str) or tuple(str, list(str)) or tuple(str, str:str): The key is split into two parts: the selection on names and the selection on periods. The selection on names can be a single name, a list of names, or a pattern. The selection on periods (optional) can be a single period, a list of periods, or a range of periods.
value: str or int or float or dict(str, …) or numpy array or pandas Series or pandas DataFrame or Variables: If str, the value is interpreted as a LEC expression and is evaluated for each period. If int, the value is first converted to a float and then used for all periods. If float, the value is used for all periods. If dict, the keys represents the names of the variables to be modified. If numpy array or pandas Series/DataFrame, there must be a value for each variable and period to be set. If Variables, names and periods must match.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> import larray as la
>>> from iode import SAMPLE_DATA_DIR
>>> from iode import variables, NA, Sample
>>> variables.load(f"{SAMPLE_DATA_DIR}/fun.var")
Loading .../fun.var
394 objects loaded

>>> # a) -------- add one variable --------
>>> # 1) same value for all periods
>>> variables["A0"] = np.nan
>>> variables["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0              na      na  ...      na       na

>>> # or equivalently
>>> variables["A0"] = NA
>>> variables["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0              na      na  ...      na       na

>>> # 2) LEC expression
>>> variables["A1"] = "t + 10"
>>> variables["A1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A1           10.00   11.00  ...   64.00    65.00

>>> # 3) list of values for each period
>>> values = list(range(variables.nb_periods))
>>> values[0] = NA
>>> values[-1] = np.nan
>>> variables["A2"] = values
>>> variables["A2"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
A2              na    1.00    2.00  ...   53.00   54.00      na

>>> # 4) numpy ndarray
>>> values = np.asarray(values)
>>> variables["A3"] = values
>>> variables["A3"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
A3              na    1.00    2.00  ...   53.00   54.00      na

>>> # 5) pandas Series
>>> values = pd.Series(values, index=variables.periods_as_str)
>>> variables["A4"] = values
>>> variables["A4"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
A4              na    1.00    2.00  ...   53.00   54.00      na

>>> # 6) Variables object
>>> variables["A5"] = variables["ACAF"]
>>> variables["A5"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2013Y1  2014Y1  2015Y1
A5              na      na  ...  -68.89  -83.34  -96.41
 

>>> # b) -------- update one variable --------
>>> # 1) set one value of a variable for a specific period
>>> variables["ACAG", "1990Y1"]
-28.1721855713507
>>> variables["ACAG", "1990Y1"] = -28.2
>>> variables["ACAG", "1990Y1"]
-28.2

>>> # 2) update all values of a variable
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
ACAF            na      na  ...  -83.34   -96.41

>>> # 2.1) same value for all periods
>>> variables["ACAF"] = np.nan
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
ACAF            na      na  ...      na       na

>>> # or equivalently
>>> variables["ACAF"] = NA
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
ACAF            na      na  ...      na       na

>>> # 2.2) LEC expression
>>> variables["ACAF"] = "t + 10"
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
ACAF         10.00   11.00  ...   64.00    65.00

>>> # 2.3) list of values for each period
>>> values = list(range(variables.nb_periods))
>>> values[0] = NA
>>> values[-1] = np.nan
>>> variables["ACAF"] = values
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
ACAF            na    1.00    2.00  ...   53.00   54.00      na

>>> # 2.4) numpy array
>>> values = np.asarray(values)
>>> variables["ACAG"] = values
>>> variables["ACAG"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
ACAG            na    1.00    2.00  ...   53.00   54.00      na

>>> # 2.5) pandas Series
>>> values = pd.Series(values, index=variables.periods_as_str)
>>> variables["AOUC"] = values
>>> variables["AOUC"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
AOUC            na    1.00    2.00  ...   53.00   54.00      na

>>> # 2.6) Variables object
>>> variables["AQC"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
AQC           0.22    0.22    0.22  ...    1.56    1.61    1.67

>>> variables["ACAF"] = variables["AQC"]
>>> variables["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  1962Y1  ...  2013Y1  2014Y1  2015Y1
ACAF          0.22    0.22    0.22  ...    1.56    1.61    1.67

>>> # 3) set the values for range of (contiguous) periods 
>>> # 3.1) variable[t:t+x] = same value for all periods
>>> variables["ACAF", "1991Y1:1995Y1"] = 0.0
>>> variables["ACAF", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF          0.00    0.00    0.00    0.00    0.00

>>> # 3.2) variable[t:t+x] = LEC expression
>>> variables["ACAF", "1991Y1:1995Y1"] = "t + 10"
>>> variables["ACAF", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF         41.00   42.00   43.00   44.00   45.00

>>> # 3.3) variable[t:t+x] = list of values for each period
>>> values = [1.0, NA, 3.0, np.nan, 5.0]
>>> variables["ACAF", "1991Y1:1995Y1"] = values
>>> variables["ACAF", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF          1.00      na    3.00      na    5.00

>>> # 3.4) variable[t:t+x] = numpy array
>>> values = np.asarray(values)
>>> variables["ACAG", "1991Y1:1995Y1"] = values
>>> variables["ACAG", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAG          1.00      na    3.00      na    5.00

>>> # 3.5) variable[t:t+x] = pandas Series
>>> periods = Sample("1991Y1:1995Y1").periods
>>> variables["AOUC", "1991Y1:1995Y1"] = pd.Series(values, index=periods)
>>> variables["AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
AOUC          1.00      na    3.00      na    5.00

>>> # 3.6) variable[t:t+x] = Variables object
>>> variables["AQC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
AQC           1.06    1.11    1.15    1.16    1.16

>>> variables["ACAF", "1991Y1:1995Y1"] = variables["AQC", "1991Y1:1995Y1"]
>>> variables["ACAF", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF          1.06    1.11    1.15    1.16    1.16

>>> # 4) set the values for a list of non-contiguous periods
>>> values = [1.0, 3.0, 5.0]
>>> variables["ACAF", ["1991Y1", "1993Y1", "1995Y1"]] = values
>>> variables["ACAF", ["1991Y1", "1993Y1", "1995Y1"]]
time
1991Y1    1.0
1993Y1    3.0
1995Y1    5.0
Name: ACAF, dtype: float64

>>> # c) -------- update several variables at once --------
>>> # 1) using a string
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = "t + 1"
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name    1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF     32.00   33.00   34.00   35.00   36.00
ACAG     32.00   33.00   34.00   35.00   36.00
AOUC     32.00   33.00   34.00   35.00   36.00

>>> # 2) using a dict of values
>>> periods = ["1991Y1", "1992Y1", "1993Y1", "1994Y1", "1995Y1"]
>>> values = {"ACAF": "ACAF * 1.05", 
...           "ACAG": [np.nan, -39.96, -42.88, -16.33, -41.16], 
...           "AOUC": pd.Series([1.023, np.nan, 1.046, np.nan, 1.064], index=periods)}
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = values
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name    1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF     33.60   34.65   35.70   36.75   37.80
ACAG        na  -39.96  -42.88  -16.33  -41.16
AOUC      1.02      na    1.05      na    1.06

>>> # 3) using a numpy array
>>> data = [[28.89, 31.90, 36.66, 42.13, 9.92],
...         [np.nan, -39.96, -42.88, -16.33, -41.16], 
...         [1.023, np.nan, 1.046, np.nan, 1.064]]
>>> data = np.asarray(data)
>>> data
array([[ 28.89 ,  31.9  ,  36.66 ,  42.13 ,   9.92 ],
       [    nan, -39.96 , -42.88 , -16.33 , -41.16 ],
       [  1.023,     nan,   1.046,     nan,   1.064]])
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = data
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name    1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF     28.89   31.90   36.66   42.13    9.92
ACAG        na  -39.96  -42.88  -16.33  -41.16
AOUC      1.02      na    1.05      na    1.06

>>> # 4) using a pandas DataFrame
>>> data += 2.0
>>> df = pd.DataFrame(data, index=["ACAF", "ACAG", "AOUC"], columns=periods)
>>> df
1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF    30.890  33.90   38.660  44.13   11.920
ACAG    NaN     -37.96  -40.880 -14.33  -39.160
AOUC    3.023   NaN     3.046   NaN     3.064
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = df
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name    1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF     30.89   33.90   38.66   44.13   11.92
ACAG        na  -37.96  -40.88  -14.33  -39.16
AOUC      3.02      na    3.05      na    3.06

>>> # 5) using an Array object (from the larray library)
>>> data += 2.0
>>> names_axis = la.Axis(name="names", labels=["ACAF", "ACAG", "AOUC"])
>>> time_axis = la.Axis(name="time", labels=periods)
>>> array = la.Array(data, axes=[names_axis, time_axis])
>>> array
names\time  1991Y1  1992Y1  1993Y1               1994Y1  1995Y1
      ACAF   32.89    35.9   40.66                46.13   13.92
      ACAG     nan  -35.96  -38.88  -12.329999999999998  -37.16
      AOUC   5.023     nan   5.046                  nan   5.064
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = array
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name    1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF     32.89   35.90   40.66   46.13   13.92
ACAG        na  -35.96  -38.88  -12.33  -37.16
AOUC      5.02      na    5.05      na    5.06

>>> # 6) using another variables database (subset)
>>> variables_subset = variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"].copy()
>>> variables_subset["ACAF"] = [1991, 1992, 1993, 1994, 1995]
>>> variables_subset["ACAG"] = [1996, 1997, 1998, 1999, 2000]
>>> variables_subset["AOUC"] = [2001, 2002, 2003, 2004, 2005]
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"] = variables_subset
>>> variables["ACAF, ACAG, AOUC", "1991Y1:1995Y1"]
Workspace: Variables
nb variables: 3
filename: ...fun.var
description: Modèle fun - Simulation 1                         
sample: 1991Y1:1995Y1
mode: LEVEL

name     1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF    1991.00 1992.00 1993.00 1994.00 1995.00
ACAG    1996.00 1997.00 1998.00 1999.00 2000.00
AOUC    2001.00 2002.00 2003.00 2004.00 2005.00

>>> # d) -------- working on a subset (whole sample) --------
>>> # reset variables database to initial state
>>> variables.load(f"{SAMPLE_DATA_DIR}/fun.var")
Loading .../fun.var
394 objects loaded
>>> # 1) get subset
>>> vars_subset = variables["A*"]
>>> vars_subset.names
['ACAF', 'ACAG', 'AOUC', 'AOUC_', 'AQC']
>>> # 2) add a variable to the subset
>>> vars_subset["A0"] = np.nan
>>> vars_subset["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0              na      na  ...      na       na

>>> # --> new variable also appears in the global workspace
>>> "A0" in variables
True
>>> variables["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0              na      na  ...      na       na

>>> # 3) update a variable in the subset
>>> vars_subset["A0"] = 0.0
>>> vars_subset["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0            0.00    0.00  ...    0.00     0.00

>>> # --> variable is also updated in the global workspace
>>> variables["A0"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1960Y1:2015Y1
mode: LEVEL

name        1960Y1  1961Y1  ...  2014Y1   2015Y1
A0            0.00    0.00  ...    0.00     0.00

>>> # 4) delete a variable in the subset
>>> del vars_subset["A0"]
>>> "A0" in vars_subset
False
>>> # --> variable is also deleted in the global workspace
>>> "A0" in variables
False

>>> # e) -------- working on a subset (names + periods) --------
>>> # 1) get subset
>>> vars_subset = variables["A*", "1991Y1:1995Y1"]
>>> vars_subset.names
['ACAF', 'ACAG', 'AOUC', 'AOUC_', 'AQC']
>>> vars_subset
Workspace: Variables
nb variables: 5
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

 name       1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF         26.24   30.16   34.66    8.16  -13.13
ACAG        -30.93  -40.29  -43.16  -16.03  -41.85
AOUC          1.02    1.03    1.03    1.05    1.05
AOUC_         0.96    0.97    0.98    0.99    1.00
AQC           1.06    1.11    1.15    1.16    1.16

>>> # 2) add a new variable in the subset -> Forbidden !
>>> vars_subset["A0"] = 0.0
Traceback (most recent call last):
   ...
RuntimeError: Cannot add the IODE variable 'A0' when the subset does not cover the whole sample of the IODE Variables workspace.
>>> # 3) update a variable in the subset
>>> vars_subset["ACAF"] = 1.0
>>> vars_subset["ACAF"]
Workspace: Variables
nb variables: 1
filename: ...fun.var
description: Modèle fun - Simulation 1
sample: 1991Y1:1995Y1
mode: LEVEL

name        1991Y1  1992Y1  1993Y1  1994Y1  1995Y1
ACAF          1.00    1.00    1.00    1.00    1.00

>>> # --> variable is also updated in the global workspace
>>> variables["ACAF", "1991Y1"]
1.0
>>> variables["ACAF", "1995Y1"]
1.0
>>> # 4) delete a variable in the subset -> Forbidden !
>>> del vars_subset["ACAF"]
Traceback (most recent call last):
  ...
RuntimeError: Cannot delete variable(s) 'ACAF' when the subset does not cover the whole sample of the IODE Variables workspace

iode.Variables.__setitem__

iode.Variables.setitem