pymarthe.mparam

Contains the MartheModel class Designed for structured grid and layered parameterization

Attributes

ZPCFMT
FFMT
IFMT
PP_NAMES
PP_FMT
base_param

Classes

MartheField	Wrapper Marthe --> python
MartheListParam	Class for handling Marthe list-like properties.
MartheGridParam	Class for handling Marthe grid-like properties.

Functions

SFMT(item)

Module Contents

class pymarthe.mparam.MartheField(field, data, mm, use_imask=True)

Wrapper Marthe –> python

get_xyvertices(stack=False)

Function to fetch x and y vertices of the modelgrid.

Parameters:

stack (bool)stack output array

Formatnp.array([vx1, vy1],

[vx2, vy2],

… )

Default is False.

Returns:

if stack is False:

vx, vy (array) : xy-vertices.

if stack is True:

vxy (array) : stacked xy-vertices

Examples:

vx, vy = mf.get_xyvertices()

sample(x, y, layer, masked_values=None, as_mask=False, as_idx=False)

Sample field data by x, y, layer coordinates. It will perform simple a spatial intersection with field data.

Parameters:

x, y (float/iterable) : xy-coordinate(s) of the required point(s) layer (int/iterable) : layer id(s) to intersect data. masked_values (None/list, optional) : values to ignore during the sampling process

Default is None.

as_mask (bool, optional)return field boolean mask.

Does not allow duplicated value (array <= x,y). Default is False.

as_idx (bool, optional)return field indexes (=cell ids, =node numbers).

Allows duplicated values (array >= x,y)

Returns:

rec (np.recarray) : data intersected on point(s) mask (np.array [1D]) : field boolean mask (if as_mask = True) idx (np.array [1D]) : cell ids/node number/field indexes (if as_idx = True)

Examples:

rec = mf.sample(x=456.32, y=567.1, layer=0)

get_data(layer=None, inest=None, as_array=False, as_mask=False, masked_values=list())

Function to select/subset NON-masked values.

Parameters:

layer (int, optional)number(s) of layer required.

If None, all layers are considered. Default is None.

inest (int, optional)number(s) of nested grid required.

If None, all nested are considered. Default is None.

as_array (bool, optional)returning data as 3D-array.

Format : (layer*inest, row, col) Default is False.

as_mask (bool, optional)returning data as boolean index.

Default is False.

Returns:

if as_array is False:

rec (np.recarray) : selected data as recarray.

if as_array is True:

arr (3D-array) : selected data as array.

Note: if all arguments are set to None,

all data is returned.

Examples:

rec1 = mf.get_data(layer=[1,5,8], inest = 1) arr1 = mf.get_data(inest=3, as_array=True)

set_data(data, layer=None, inest=None)

Set field data for active cells (where imask is 1) and NON-masked values (see dmv)

Parameters:

data (object)field data to read/set.

Can be:

• Marthe property file (‘mymodel.permh’)

• Recarray with layer, inest,… informations

• 3D-array

layer (int, optional)number(s) of layer required.

If None, all layers are considered. Default is None.

inest (int, optional)number(s) of nested grid required.

If None, all nested are considered. Default is None.

Returns:

Set field data inplace.

Examples:

mf.set_data(permh_recarray) mf.set_data(permh3darray) # structured grids only mf.set_data(2.3e-3) # all layers/inest mf.set_data(2.3e-3, layer=2, inest=3) # one nest

get_masked(rec)

Return field data (rec.array) after masking with model active cells (.imask). Note : if the field is not related to the model (`use_imask`=False) then return

the input data.

Parameters:

rec (rec.array) : field data.

Returns:

mrec (rec.array) : masked field data

Examples:

mf.get_masked()

set_data_from_parfile(parfile, izone, btrans='none')

Set field data from parameter file inplace.

Parameters:

parfile (str)path to parameter file to read.

Can be either zpc or pp parameter.

izone (MartheField) : parameter zone(s) field.

btrans (str, optional)string function to back-transform

field values. Default is ‘none’.

Examples:

parfile = ‘par/hk_zpc.dat’ mf.set_data_from_parfile(parfile,

izone, btrans=’lambda x: 10**x’)

as_3darray()

Wrapper to .get_data(inest=0, as_array=True) with error handling for nested model.

Parameters:

self (MartheField) : MartheField instance.

Returns:

arr (3D-array)array 3D of main grid only.

Format : (layer, row, col)

Examples:

arr3d = mf.as_3darray()

static grids2rec(grids)

Read Marthe field property file. Wrapper of marthe_utils.read_grid_file().

Parameters:

filename (str) : path to Marthe field property file.

Returns:

rec (np.recarray)recarray with all usefull informations

for each model grid cell such as layer, inest, value, …

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

_3d2rec(arr3d)

Convert 3D-array Wrapper of marthe_utils.read_grid_file().

Parameters:

filename (str) : path to Marthe field property file.

Returns:

rec (np.recarray)recarray with all usefull informations

for each model grid cell such as layer, inest, value, …

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

_rec2grid(layer, inest)

Single MartheGrid instance construction from given layer and inest.

Parameters:

layer (int) : number of layer required. inest (int) : number of nested grid required.

Returns:

mg (MartheGrid) : Single Marthe grid instance.

Examples:

rec = mf._grid2rec(‘mymodel.emmca’)

to_grids(layer=None, inest=None)

Converting internal data (recarray) to a list of MartheGrid instance for given layers and inests.

Parameters:

layer (int, optional)number(s) of layer required.

If None, all layers are considered. Default is None.

inest (int, optional)number(s) of nested grid required.

If None, all nested are considered. Default is None.

Returns:

mgrids (list) : Required MartheGrid instances.

Examples:

mg = mf.to_grids(layer)

write_data(filename=None, keep_uniform_fmt=False)

Write field data in Marthe field property file.

Parameters:

filename (str) : path to write field data.

keep_uniform_fmt (bool, optional)whatever to conserve marthe light format

for uniform grid. If True, light format will be conserved. If False, all grids will be written explictly. Default is False. /!/ CAREFULL /!/ keeping uniform light format on permh field can modify the model geometry.

Returns:

Write in Marthe field property file on disk.

Examples:

mf.write_data(‘modified.permh’)

to_shapefile(filename=None, layer=0, inest=None, masked_values=dmv, log=False, epsg=None, prj=None)

Write field data as shapefile by layer.

Parameters:

filename (str, optional)shapefile path to write.

If None, filename = ‘field_layer.shp’. Default is None

layer (int, optional)layer numerical id to export.

Note : a unique layer id is allowed Default is 0.

inest (int, optional)nested grid numerical id to export.

If None, all nested grid are considered. Default is None.

masked_values (list, optional)field values to ignore.

Default is [-9999., 0., 9999].

log (bool, optional)logarithmic transformation of all values.

Default is False.

epsg (int, optional)Geodetic Parameter Dataset.

Default is None.

prj (str, optional)cartographic projection and coordinates

Default is None.

Returns:

Write shape in filename.

Examples:

filename = os.path.join(‘gis’, ‘permh_layer5.shp’) mf.to_shapefile(filename, layer=5)

plot(ax=None, layer=0, inest=None, vmin=None, vmax=None, log=False, extent=None, masked_values=dmv, basemap=False, **kwargs)

Plot data by layer

Parameters:

ax (matplotlib.axes, optional)matplotlib.axes custom ax.

If None basic ax will be create. Default is None.

layer (int, optional)layer numerical id to export.

Note : a unique layer id is allowed Default is 0.

inest (int, optional)nested grid numerical id to export.

If None, all nested grid are considered. Default is None.

vmin, vmax (float, optional) : min/max value(s) to plot.

log (bool, optional)logarithmic transformation of all values.

Default is False.

extent (tuple/list, optional): xy-limits of the plot window.

Format: (xmin, ymin, xmax, ymax). If None, window correspond to the entire model domain. Default is None.

masked_values (list, optional)field values to ignore.

Default is [-9999., 0., 9999].

basemap (dict/bool, optional)add base map to AxesSubplot.

/!/ Required python contextily module /!/ Can be:

• False : not adding any basemap

• Trueadd standard basemap.

  -> provider: Stamen Terrain web tiles. -> crs: Spherical Mercator projection (EPSG:3857)

• dict()contextily.add_basemap() arguments.

  Format:

  {‘source’:TileProvider object,

  zoom:’auto’, … , ‘crs’: ‘EPSG:2154’}

Default is False.

**kwargs (optional)matplotlib.PathCollection arguments.

(ex: cmap, lw, ls, edgecolor, …)

Returns:

ax (matplotlib.axes)standard ax with 2 collections:

• 1 for rectangles

• 1 for colorbar

Examples:

ax = mf.plot(layer=6, cmap=’jet’) ax.set_title(‘Field (layer = 6)’, fontsize=14)

zonal_stats(stats, polygons, layer=None, names=None, trans='none')

Perform statistics on zonal areas.

Parameters:

stats (str/list)statistics functions to perform.

Must be recognize by pandas.DataFrame.agg() method. Example: stats = [‘mean’, ‘min’,’max’,’median’,’count’].

polygons (it)iterable containing single part polygons.

Format: [ [(x0, y0),(x1,y1),(x2,y2)],.., [(x’N,y’N),..], ..]

<=> [ polygon_0 ,.., polygon_N ].

layer (int/it, optional)layer id(s) on wich perform zonal statistics.

If None, all layers are considered. Default is None.

names (str/it, optional)names of zones in the output.

If None, generic names are created with field and zone number (‘field_z0’, ‘field_z1’,…). Default is None.

trans (str/func, optional): function/function name to transform field values

before applying statistics. If None, field values are not transformed. Default is ‘none’.

Returns:

zstats_df (DataFrame) : DataFrame with rows MultiIndex (‘zone’, ‘layer’).

Examples:

stats = [‘mean’,’max’,’min’,’median’,’count’] polygons = shp_utils.read_shapefile(‘mypolygons.shp’)[‘coords’] zdf = mf.zonal_stats(stats, polygons, layer=[4,5,6])

to_vtk(filename=None, trans='none', masked_values=dmv, **kwargs)

Build vtk unstructured grid from model geometry and add current field to cell dataset.

**kwargs correspond to the arguments of the MartheModel.get_vtk() method.

Required python vtk package.

Parameters:

filename (str, optional)vtk file name to write without extension.

Extension will be inferred. If None, filename = field. Default is None.

trans (str, optional)transformation to apply to the values.

See pymarthe.utils.pest_utils.transform. Default is ‘none’.

masked_values (float/it, optional)values to mask of the current field data.

Default are [9999, 0, -9999].

vertical_exageration (float, kwargs)floating point value to scale vertical

exageration of the vtk points. Default is 0.05.

hws (str, kwargs)hanging wall state, flag to define whatever the superior

hanging walls of the model are defined as normal layers (explivitly) or not (implicitly). Can be:

• ‘implicit’

• ‘explicit’

Default is ‘implicit’.

smooth (bool, kwargs)boolean flag to enable interpolating vertex elevations

based on shared cell. Default is False.

binary (bool, kwargs)Enable binary writing, otherwise classic ASCII format

will be consider. Default is True. Note : binary is prefered as paraview can produced bug

representing NaN values from ASCII (non xml) files.

xml (bool, kwargs)Enable xml based VTK files writing.

Default is False.

shared_points (bool, kwargs)Enable sharing points in grid polyhedron construction.

Default is False. Note : False is prefered as paraview has a bug (8/4/2021)

where some polyhedron will not properly close when using shared points.

Returns:

vtk (pymarthe.utils.vtk_utils.Vtk) : Vtk class containg unstructured vtk grid

Example:

mf = mm.prop[‘permh’] myvtk = mf.to_vtk(filename = mf.field, trans=’log10’, vertical_exageration=0.02)

__str__()

Internal string method.

pymarthe.mparam.ZPCFMT

pymarthe.mparam.FFMT

pymarthe.mparam.IFMT

pymarthe.mparam.SFMT(item)

pymarthe.mparam.PP_NAMES = ['name', 'x', 'y', 'zone', 'value']

pymarthe.mparam.PP_FMT

pymarthe.mparam.base_param = ['parnme', 'trans', 'btrans', 'parchglim', 'defaultvalue', 'parlbnd', 'parubnd', 'pargp',...

class pymarthe.mparam.MartheListParam(parname, mobj, kmi, value_col='value', trans='none', btrans='none', defaultvalue=None, **kwargs)

Class for handling Marthe list-like properties.

gen_parnmes()

Internal method to generate parmaeters names from kmi.

Returns:

parnmes (list) –

Notename will be created as ‘item0__item1__…_itemN’

where items are kmi possible values.

Return type:

parameters names according to keys values of kmi.

Examples

parnmes = mlp.gen_parnmes()

get_param_df(transformed=False)

Return internal parameter DataFrame.

Parameters:

• (bool (transformed) – Default is False.

• optional) (whatever apply transformation on output DataFrame.) – Default is False.

Returns:

param_df (DataFrame) –

Format:

parnme trans btrans parchglim defaultvalue parlbnd parubnd pargp scale offset dercom

parname cap_soil_progr_01 cap_soil_progr_01 log10 lambda x: 10**x factor 40 1.000000e-10 1.000000e+10 csp 1 0 1 cap_soil_progr_02 cap_soil_progr_02 log10 lambda x: 10**x factor 40 1.000000e-10 1.000000e+10 csp 1 0 1 … … … … … … … … … … … …

Return type:

parameter data as DataFrame.

Examples

parnmes = mlp.get_param_df()

to_config()

Return the essential informations of current set of parameters to be written in the configuration file as a new parameter section.

Returns:

section (str)

Return type:

parameter section as string.

Examples

print(mlp.to_config())

write_parfile(parpath=None)

Write parameter file(s) in parameter folder. (wrapper to pymarthe.utils.pest_utils.write_mlp_parfile())

Parameters:

• (str (parpath) – If None, name taken from .parpath. Default is None.

• optional) (path to the folder where parameter files should be writen.) – If None, name taken from .parpath. Default is None.

Examples

mlp.write_parfile(parpath=’par’)

write_tplfile(tplpath=None)

Write template file(s) in template folder. (wrapper to pymarthe.utils.pest_utils.write_mlp_tplfile())

Parameters:

• (str (tplpath) – If None, name taken from .tplpath. Default is None.

• optional) (path to the folder where template files should be writen.) – If None, name taken from .tplpath. Default is None.

Examples

mglp.write_tplfile(tplpath=’tpl’)

__str__()

Internal string method.

class pymarthe.mparam.MartheGridParam(parname, mobj, izone=None, pp_data=None, trans='none', btrans='none', defaultvalue=None, **kwargs)

Class for handling Marthe grid-like properties.

set_izone(izone=None)

Manage izone (MartheField) input. It will detect zone ids:

• izone < 0 : zone of piecewise constancy

• izone > 0 : zone with pilot points

• izone = -9999, 0, 9999 : inactive zone

Parameters:

• (str/MartheField (izone) – If None, a generic field will be created from the input mobj with a unique zpc zone (in active cells) for each layer. Default is None.

• optional) (field with required zone ids as values.) – If None, a generic field will be created from the input mobj with a unique zpc zone (in active cells) for each layer. Default is None.

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) active = mm.query_grid(active=1, layer=0, target=’node’).values izone[‘value’][active] = -2 mgp.set_izone(izone)

get_dv_from_lz(layer, zone, agg=None)

Extract ‘default value’ as field mean for a given layer and zone id.

Parameters:

• (int) (zone) –

• (int) –

• (func/str (agg) –

• optional) (string/function to aggregate value.) –

Returns:

dv (float)

Return type:

default value(s).

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) mgp.get_dv_from_lz(layer=2, zone=1)

get_dv_from_xy(x, y, layer, agg=None)

Extract ‘default value’ as field mean for at given xy-coordinates

Parameters:

• (float/it) (y) –

• (float/it) –

• (int) (layer) –

• (func/str (agg) –

• optional) (string/function to aggregate value.) –

Returns:

dv (float)

Return type:

default value(s).

Examples

ppx,ppy = pest_utils.shp2points(‘myppoints.shp’) mgp.get_dv_from_xy(ppx, ppy)

init_zpc_df()

Initialise zone of piecewise constancy DataFrame

set_zpc_value(value, layer=None, zone=None)

Set value of required zone of piecewise constancy.

Parameters:

• (float/int) (value) –

• (int/it (zone) – If None, all layers will be considered. Default is None.

• optional) (zone id to set value.) – If None, all layers will be considered. Default is None.

• (int/it – If None, all zones (zpc) will be considered. Default is None.

• optional) – If None, all zones (zpc) will be considered. Default is None.

Return type:

Set values in .zpc_df

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’]) mgp.set_zpc_value(value= 1e-3, layer=[0,1], zone=-1)

init_pp_dic()

Initialize pilot points dictionary. Format : { layer_0 : pp_df_0,

layer_1 : pp_df_1, …, layer_N: pp_df_N}

zone_interp_coords(layer, zone)

Fetch centroid coordinates of required zone to perform pilot points interpolation.

Parameters:

• (int) (zone) –

• (int) –

Returns:

(xc,yc) (tuple [1D-array])

Return type:

x,y coordinates of cell centers.

Examples

mgp.zone_interp_coords(layer=0, zone=-1)

default_pp_coords(layer, zone)

Infer pilot point coordinates for a specific zone in a required layer. Pilot points will be regularly spaced on each x,y direction with adefault spacing of two times the average distance between all centroids of the current active cells.

Parameters:

• (int) (zone) –

• (int) –

Returns:

pp_coords (np.ndarray [(N,2)])

Return type:

coordinates of generated pilot points.

Examples

mgp = MartheGridParam(‘permh’, mm.prop[‘permh’], ipermh) pp_l2_z1 = mgp.pp_coords(layer=2, zone=1)

build_pp_df(coords, layer, zone)

Create pilot point Dataframe from xy-coordinates with generic names. Wrapper to PilotPoints.pp_df_from_coords().

Parameters:

• (list/array) (coords) – Format : [[ppx_0, ppy_0], …, [ppx_N, ppy_N]]

• (int) (zone) –

• (int) –

Returns:

pp_df (Dataframe) –

Format:

parname x y zone value

parname hk_l04_z01_00 hk_l04_z01_00 357.136364 209.0 1 1.780510e-05 hk_l04_z01_01 hk_l04_z01_01 373.681818 209.0 1 4.042830e-05 … … … … . … hk_l04_z01_N hk_l04_z01_N 357.136364 225.4 1 1.337280e-05

Return type:

pilot point standard DataFrame.

Examples

coords = shp_utils.shp2points(‘gis/pp_l04.shp’, stack=True) pp_df = mgp.build_pp_df(coords, layer=4, zone=1)

write_parfile(parpath=None, only_zpc=False, only_pp=False)

Write parameter file(s) in parameter folder. (wrapper to pymarthe.utils.pest_utils.write_mgp_parfile())

Parameters:

• (str (parpath) – If None, name taken from .parpath. Default is None.

• optional) (write pilot point parameter file(s) only.) – If None, name taken from .parpath. Default is None.

• (bool (only_pp) – Default is False.

• optional) – Default is False.

• (bool – Default is False.

• optional) – Default is False.

Examples

mgp.write_parfile(parpath=’par’, only_zpc=True)

write_tplfile(tplpath=None, only_zpc=False, only_pp=False)

Write template file(s) in template folder. (wrapper to pymarthe.utils.pest_utils.write_mgp_tplfile())

Parameters:

• (str (tplpath) – If None, name taken from .tplpath. Default is None.

• optional) (write pilot point template file(s) only.) – If None, name taken from .tplpath. Default is None.

• (bool (only_pp) – Default is False.

• optional) – Default is False.

• (bool – Default is False.

• optional) – Default is False.

Examples

mgp.write_tplfile(tplpath=’tpl’, only_zpc=True)

write_kfac(vgm_range, krig_transform='none', parpath=None, save_cov=False)

Compute and write kriging factor files (PEST-like) from exponential variogram ranges for each layer and zone of pilot points. Wrapper of some pyemu tools :

• pyemu.utils.geostats.ExpVario

• pyemu.utils.geostats.GeoStruct

• pyemu.utils.geostats.OrdinaryKrige

Note: the ranges must be in the same distance unit as the model fields.

Parameters:

• dict) (vgm_range (float/int/dict/nested) –

  Can be :

  • numeric

  • dictionary

    format: {layer_0range_0,

    …, layer_i : range_i }

  • nested dictionary

    format: {layer_0{zone_0: range_0_0, …, zone_i: range_0_i},

    …, layer_i : {zone_0: range_i_0, …, zone_i: range_i_i} }

• (str (parpath) –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• optional) (whatever write the covariance matrices as binary files.) –

  pyemu.utils.geostats.GeoStruct. Can be:

  • ’none’

  • ’log’

  Default is ‘none’.

• (str –

  If None, it will take the `.kfacpath’ argument. Default is None. Note: a kriging factor files will be written for each

  pilot point layer and zone. The file name will be generated as ‘{parname}_l{layer}_z{zone}.fac’.

• optional) –

  If None, it will take the `.kfacpath’ argument. Default is None. Note: a kriging factor files will be written for each

  pilot point layer and zone. The file name will be generated as ‘{parname}_l{layer}_z{zone}.fac’.

• (bool (save_cov) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

• optional) –

  Default is False. Note: the covariance matrices files will take the same

  names as kriging factor files with the ‘.jcb’ extension.

Returns:

• Write kriging factor file in parameter path (with ‘.fac’ extension).

• If save_cov is True, the covariance matrix will be written in

• parameter path too (with extension ‘.jcb’).

Examples

vgm_range= {2: {1:100}, 3: {1:200,2:150}} mgp.write_kfac(vgm_range, vgm_transform= ‘log’, save_cov=True)

get_param_df(transformed=False)

Join all parameter informations in a single DataFrame for the current field.

Parameters:

• (bool (transformed) – Default is False.

• optional) (whatever apply transformation on output DataFrame.) – Default is False.

Returns:

param_df (DataFrame)

Return type:

parameter information of current field.

Examples

mgp.get_param_df()

to_config()

Return the essential informations of current set of parameters to be written in the configuration file as a new parameter section.

Returns:

section (str)

Return type:

parameter section as string.

Examples

print(mgp.to_config())

__str__()

Internal string method.