xarray_save

PlasmaCalcs.tools.xarray_tools.xarray_io.xarray_save(array, filename=None, *, exist_ok=False, add_code_snapshot_info=True, notes=None, reset_multi_index=True, expand_dict_attrs=True, stringify_bool_attrs=True, engine=None, compress=None, encoding=None, **kw_to_netcdf)

saves the array or dataset as filename.nc with a companion text file filename.txt.

Both will be saved into a new directory named filename.pcxarr

(“pcxarr” stands for “PlasmaCalcs xarray.DataArray or xarray.Dataset object”)

array: xarray.DataArray or xarray.Dataset

the array or dataset to save

filename: None or str

where to save the array. Extension “.pcxarr” will be added if not present.

None –> infer filename=array.name, or “unnamed_array” if array.name is None.

(actually: array.name.replace(‘/’, ‘÷’). To avoid interpreting division as directories.)

if filename implies directories, those directories will be created, as per os.makedirs.

exist_ok: bool, default False

whether it’s okay if directory with the target name to already exist.

False –> crash with FileExistsError if directory exists.

True –> might overwrite files in that directory!

add_code_snapshot_info: bool or dict

whether to array.assign_attrs(details about current version of PlasmaCalcs code)

Those details include ‘pc__version__’, ‘pc__commit_hash’, and ‘datetime’.

If dict, pass kwargs to code_snapshot_info(). E.g. dict(default=’_undefined_’)

notes: None or object to convert to str

if provided, also save a notes.txt file containing str(notes).

Feel free to use this to write anything, e.g. describe what array means, in words.

reset_multi_index: bool

whether to array.reset_index(idx) for all MultiIndex idx, before saving.

if True, also add info to array.attrs[‘reset_multi_index:{d}’ for reset d].

if False, may crash with NotImplementedError if any MultiIndex present.

expand_dict_attrs: bool

whether to expand dict-valued attributes into separate attributes,

with names like “__dictattr_{origattrname}__{dictkey}__”.

(netcdf doesn’t allow saving dict-valued attributes.)

(will be applied before stringify_bool_attrs.)

stringify_bool_attrs: bool

whether to replace bool-valued attributes’ values with “__bool=True__” or “__bool=False__”.

(netcdf doesn’t like saving bool-valued attributes.)

(xarray_load will automatically convert these back into bools.)

additional kwargs relate to internal strategy for to_netcdf:

engine: None or str (‘netcdf4’, ‘h5netcdf’, ‘scipy’)

which engine to use for saving.

None –> use _xarray_best_save_engine()

(picks first available, from netcdf4 > h5netcdf > scipy)

compress: None, bool, or dict

whether to compress data when writing.

None –> True if engine can do compression, else False.

(‘scipy’ engine is not compatible with compression.)

bool –> get dict from _xarray_engine_compression_defaults(engine)

(crash with InputConflictError if engine can’t do compression.)

(default {‘zlib’: True} for ‘netcdf4’ and ‘h5netcdf’)

dict –> apply this strategy to each data variable.

equivalent: encoding={var1: compress, var2: compress, …}

encoding: None or dict

dict of {var: {encoding options for var}} across data vars.

determined automatically if provided compress.

returns abspath to filename.pcxarr directory where the array was saved.