gridmarthe.load_marthe_grid

gridmarthe.load_marthe_grid(filename, varname=None, fpastp=None, times=None, drop_nan=False, nan_value=None, xyfactor=1.0, shallow_only=False, add_col_row=False, add_id_grid=False, title=None, var_attrs={}, epsg=27572, full_3d=False, drop_time=False, model_attrs={'domain': 'FR-France', 'institution': 'BRGM, French Geological Survey, Orléans, France'}, engine='xarray', verbose=False, **kwargs)[source]

Read Marthe Grid File as xarray.Dataset

The gridfile is read as a sequence: the variable for all layer for main grid, then all layer for nested grids, is stored in a 1D vector for every timestep. A single spatial identifier zone is used to map spatial coordinates.

Before plot operations, user can assign coordinates (set x,y as dimension coordinates and drop zone) to get 2-D arrays (or 3D arrays if multilayer) for every timesteps.

Parameters:
filenamestr

A path to marthegrid file (.permh, .out, etc.)

varnamestr, optional

Variable to access in martgrid file. See marthegrid (filename) file content.

  • If None is passed (default), function will scan all varnames in filename

and keep first only.

  • If a varname is passed, e.g CHARGE for groundwater head, the returned

dataset will contains only this variable.

  • If ‘all’ is passed, function will scan all varnames in filename and keep all.

All datavars are added to dataset, using recursive call to func

  • If wrong variable name is passed, empty data will be returned.

fpastpstr, optional

A pastp file to read for times

timessequence, optional

Can be a pd.date_range, pd.Series, pd.DatetimeIndex, np.array or list of datetime/np.datetime objects. If no times (or no fpastp) is provided, a fake sequence of int will be used.

drop_nanbool, optional

Drop nan values (corresponding to nan_value) in xarray object to return. Default is False (keep nan values).

nan_valuefloat or list of float, optional

A code value for nan values. The default value is inferred from field name. E.g. of default nan values:

  • hydraulic conductivity: 0 or -9999. (Warning: a value of +9999. is not a NaN value for hydraulic conductivity. See Marthe User Guide for explanation about this code, refering here to impervious layer);

  • hydraulic head: 9999.;

  • groundwater flow: 0. (9999. is used as special value for this field);

  • any other: 9999.

xyfactorint or float, optional

factor to transform X and Y values. e.g.: 1000 to convert km XY to meters. Default is 1.

shallow_onlybool, optional

Boolean to read only the first layer. Default is False. Warning: only valid for NON nested grids for now.

add_col_rowbool, optional

Add columns (col) and rows (row, formerly lig (v<=0.1.3)) index (from 1 to n). Default is False.

add_id_gridbool, optional

Add grid id (from 0 to n), useful for nested grids. 0 is main grid, Default is False

titlestr , optional

Title for grid attributes. Default is None (not used)

var_attrsdict, optional

Dictionnary of attributes to add to variable DataArray.

epsgint, optional

EPSG code for projection. Default is 27572 for legacy reasons (Lambert 2 Etendu, for France). Used to write CRS information in attributes. Useful for GUI (eg visualisation in QGIS).

full_3dbool, optional

Is z dimension an aquifer layer or real Z axis (in meters for exemple) Default is False (z is aquifer layer number)

drop_timebool, optional

Drop time dimension even if only one timestep is present. Default is False. If True and only one timestep, time dimension is removed. Useful for parameters grids.

model_attrsdict, optional

Dictionnary of attributes to add to Dataset. by default, gis attrs are added and can be modified

>>> {
...    'domain': 'FR-France',
...    'institution': 'BRGM, French Geological Survey, Orléans, France'
... }

For example, if your data is associated with a reference (report, paper, etc.):

>>> {
...    'references': 'https://doi.org/...'
... }
enginestr, optional

Engine to use for returned object. Default is ‘xarray’, which return xarray.Dataset object. Another option is ‘numpy’, which return a list of numpy arrays : [zvar, zdates, isteps, zxcol, zylig, zdxlu, zdylu, ztitle, dims]

verbosebool, optional

Print some information about execution in stdout. Default is False.

Returns:
dsxarray.Dataset

A xarray.Dataset object containing values and attributes read from Marthe grid file.

Notes

A former known issue with some version of Marthe is that field name is not written in metadata, as number of nested grids or number of layers., which This can cause some bug when reading grids with gridmarthe. As of gridmarthe version 0.4, if no varname is scanned in file and/or number of layer/grids are missing, these informations are guessed when parsing data, which are stored in a variable named ‘variable’ and a warning is raised to alert user to rename the variable later. This is only valid for parameters grids (with only one timestep). In case of remaining errors, the command line tool cleanmgrid (provided with gridmarthe) can still be used to clean the file and add missing metadata.