UserSpace.new_pandas¶

UserSpace.new_pandas(name, path, data, filetype)¶

Assigns a pandas object to a Reference associating a new PandasData object

pandas DataFrame and Series objects can be assigned to References by the normal assignment operation, such as space.x = df, but the pandas DataFrame/Series assigned this way are saved in a binary file together with other Reference objects. This method allows a DataFrame/Series object passed as data to be saved in a separate file.

This method creates a PandasData object that wraps a DataFrame or Series passed as data, and assigns data or the PandasData object to a Reference named name in this Space/Model.

When the model is saved, the DataFrame or Series is written to a file whose path is given by the path parameter, and whose format is specified by the filetype parameter. If path is relative, it is interpreted relative to the model folder. The filetype can take either “excel” or “csv”.

If “excel” is given, the pandas object is written to an Excel file. The file name in path must have either “.xlsx”, “.xlsm” or “.xls” extention. This method internally uses pandas.read_excel function and to_excel method for reading from and writing to Excel files, so appropriate Excel engines for reading and writing Excel files must be installed, depending on the types of Excel files. See pandas’ document for the required packeges for Excel engines.

By default, data is assigned to name, and the associated PandasData object is assigned to data._mx_dataclient. If False is passed to expose_data, the PandasData object is assigned to name. To get data, call the PandasData or get its value attribute.

Example

The script below creates a sample DataFrame df:

>>> index = pd.date_range("20210101", periods=3)

>>> df = pd.DataFrame(np.random.randn(3, 3), index=index, columns=list("XYZ"))

>>> df
                   X         Y         Z
2021-01-01  0.184497  0.140037 -1.599499
2021-01-02 -1.029170  0.588080  0.081129
2021-01-03  0.028450 -0.490102  0.025208

The code below assigns the DataFrame created above to a Reference named x in space, and at the same time creates a PandasData object and assigns it to the _mx_dataclient attribute of the DataFrame:

>>> space.new_pandas("x", "Space1/df.xlsx", data=df, filetype="excel")

>>> space.x
                   X         Y         Z
2021-01-01  0.184497  0.140037 -1.599499
2021-01-02 -1.029170  0.588080  0.081129
2021-01-03  0.028450 -0.490102  0.025208

>>> space.x._mx_dataclient
<modelx.io.pandasio.PandasData at 0x15ebc562356>

When the model is saved, the DataFrame is written to an Excel file named df.xlsx placed under the Space1 folder in model.

>>> model.write("model")    # `model` is the parent of `space`

When the model is read back by modelx.read_model() function, the DataFrame is read from the file:

>>> model2 = mx.read_model("model", name="Model2")

>>> model2.Space1.x
                   X         Y         Z
2021-01-01  0.184497  0.140037 -1.599499
2021-01-02 -1.029170  0.588080  0.081129
2021-01-03  0.028450 -0.490102  0.025208

If False is passed to expose_data, the PandasData object instead of data itself is assigned to x To get the DataFrame, call the PandasData object or access its value property:

>>> space.x
<modelx.io.pandasio.PandasData at 0x15efa565548>

>>> space.x()     # or space.value
                   X         Y         Z
2021-01-01  0.184497  0.140037 -1.599499
2021-01-02 -1.029170  0.588080  0.081129
2021-01-03  0.028450 -0.490102  0.025208

Parameters

name (str) – Name of the Reference
path – A path to a file to save the Pandas object. If a relative path is given, it is relative to the model folder.
data – pandas DataFrame or Series
filetype – String to indicate file format. (“excel” or “csv”)
expose_data (bool, optional) – If True, assigns data to name, otherwise assigns the PandasData object associted with data to name. True by default.

Changed in version 0.13.0: Add the expose_data parameter. By default, data is assigned instead of its PandasData object

New in version 0.12.0.