{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# [EN] Basic example of use - gridmarthe 101\n", "\n", "The gridmarthe package is designed to facilitate reading/writing grids in the Marthe format.\n", "This notebook allows you to explore some basic features of the package and shows an example\n", "of grid processing." ] }, { "cell_type": "code", "execution_count": 30, "metadata": {}, "outputs": [], "source": [ "# import package\n", "import gridmarthe as gm" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "gridmarthe library is based on `xarray`, which enhances working with multidimensional grids. \n", "Full documentation is available at:\n", "https://docs.xarray.dev/en/stable/index.html" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic features\n", "\n", "\n", "Marthe Grids contain metadata, including the time step index,\n", "but not the actual dates. Therefore, it is useful to provide the reading function\n", "either with a series of dates (to be constructed manually) or a timestep file so that the dates are\n", "read automatically.\n", "\n", "Additionally, several arguments can be useful for reading (removal of null values, \n", "transformation of xy, addition of mesh indicator or column/row numbers, etc.).\n", "\n", "To check for possible options, you can display the function's help.\n" ] }, { "cell_type": "code", "execution_count": 31, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Help on function load_marthe_grid in module gridmarthe.grid.io.gridmarthe:\n", "\n", "load_marthe_grid(filename: str, varname: Optional[str] = None, fpastp: Optional[str] = None, dates=None, drop_nan: bool = False, nan_value: Union[int, float, list, NoneType] = None, xyfactor: Union[int, float] = 1.0, shallow_only=False, add_col_row: bool = False, add_id_grid: bool = False, title: Optional[str] = None, var_attrs: dict = {}, epsg: int = 27572, full_3d: bool = False, drop_time: bool = False, model_attrs: dict = {'domain': 'FR-France', 'institution': 'BRGM, French Geological Survey, Orléans, France'}, engine: str = 'xarray', verbose: bool = False, **kwargs)\n", " Read Marthe Grid File as xarray.Dataset\n", " \n", " The gridfile is read as a sequence: the variable for all layer\n", " for main grid, then all layer for nested grids, is stored in\n", " a 1D vector for every timestep. A single spatial identifier\n", " ``zone`` is used to map spatial coordinates.\n", " \n", " Before plot operations, user can assign coordinates (set x,y\n", " as dimension coordinates and drop zone) to get 2-D arrays (or\n", " 3D arrays if multilayer) for every timesteps.\n", " \n", " Note\n", " ----\n", " \n", " A former known issue with some version of Marthe is that field name is\n", " not written in metadata, as number of nested grids or number of layers., which\n", " This can cause some bug when reading grids with gridmarthe.\n", " As of `gridmarthe` version 0.4, if no varname is scanned in file and/or number of layer/grids\n", " are missing, these informations are guessed when parsing data, which are stored in\n", " a variable named 'variable' and a warning is raised to alert user to rename the\n", " variable later. This is only valid for parameters grids (with only one timestep).\n", " In case of remaining errors, the command line tool `cleanmgrid`\n", " (provided with gridmarthe) can still be used to clean the file and add missing metadata.\n", " \n", " Parameters\n", " ----------\n", " filename: str\n", " A path to marthegrid file (.permh, .out, etc.)\n", " \n", " varname : str, optional\n", " Variable to access in martgrid file. See marthegrid (`filename`) file content.\n", " \n", " - If None is passed (default), function will scan all varnames in filename\n", " and keep first only.\n", " \n", " - If a varname is passed, e.g ``CHARGE`` for groundwater head, the returned\n", " dataset will contains only this variable.\n", " \n", " - If 'all' is passed, function will scan all varnames in filename and keep all.\n", " All datavars are added to dataset, using recursive call to func\n", " \n", " - If wrong variable name is passed, empty data will be returned.\n", " \n", " fpastp: str, optional\n", " A pastp file to read for dates\n", " \n", " dates: sequence, optional\n", " Can be a pd.date_range, pd.Series, pd.DatetimeIndex, np.array or list of\n", " datetime/np.datetime objects.\n", " If no dates (or no fpastp) is provided, a fake sequence of dates from\n", " 1850 to 1900 will be used for xarray object\n", " \n", " drop_nan: bool, optional\n", " Drop nan values (corresponding to nan_value) in xarray object to return.\n", " Default is False (keep nan values).\n", " \n", " nan_value: float or list of float, optional\n", " A code value for nan values. The default value is inferred from field name.\n", " E.g. of default nan values:\n", " \n", " - hydraulic conductivity: 0 or -9999. (Warning: a value of +9999. is not\n", " a NaN value for hydraulic conductivity. See Marthe User Guide for explanation\n", " about this code, refering here to impervious layer);\n", " \n", " - hydraulic head: 9999.;\n", " \n", " - groundwater flow: 0. (9999. is used as special value for this field);\n", " \n", " - any other: 9999.\n", " \n", " xyfactor: int or float, optional\n", " factor to transform X and Y values. e.g.: 1000 to convert km XY to meters.\n", " Default is 1.\n", " \n", " shallow_only: bool, optional\n", " Boolean to read only the first layer. Default is False.\n", " Warning: only valid for NON nested grids for now.\n", " \n", " add_col_row: bool, optional\n", " Add columns (col) and rows (row, formerly lig (v<=0.1.3)) index (from 1 to n).\n", " Default is False.\n", " \n", " add_id_grid: bool, optional\n", " Add grid id (from 0 to n), useful for nested grids.\n", " 0 is main grid, Default is False\n", " \n", " title: str , optional\n", " Title for grid attributes. Default is None (not used)\n", " \n", " var_attrs: dict, optional\n", " Dictionnary of attributes to add to variable DataArray.\n", " \n", " epsg: int, optional\n", " EPSG code for projection. Default is 27572 for legacy reasons (Lambert 2 Etendu,\n", " for France). Used to write CRS information in attributes. Useful for GUI\n", " (eg visualisation in QGIS).\n", " \n", " full_3d: bool, optional\n", " Is z dimension an aquifer layer or real Z axis (in meters for exemple)\n", " Default is False (z is aquifer layer number)\n", " \n", " drop_time: bool, optional\n", " Drop time dimension even if only one timestep is present.\n", " Default is False. If True and only one timestep, time dimension is removed.\n", " Useful for parameters grids.\n", " \n", " model_attrs: dict, optional\n", " Dictionnary of attributes to add to Dataset.\n", " by default, gis attrs are added and can be modified\n", " \n", " >>> {\n", " ... 'domain': 'FR-France',\n", " ... 'institution': 'BRGM, French Geological Survey, Orléans, France'\n", " ... }\n", " \n", " For example, if your data is associated with a reference (report, paper, etc.):\n", " \n", " >>> {\n", " ... 'references': 'https://doi.org/...'\n", " ... }\n", " \n", " engine: str, optional\n", " Engine to use for returned object. Default is 'xarray', which return\n", " xarray.Dataset object.\n", " Another option is 'numpy', which return a list of numpy arrays :\n", " [zvar, zdates, isteps, zxcol, zylig, zdxlu, zdylu, ztitle, dims]\n", " \n", " verbose: bool, optional\n", " Print some information about execution in stdout.\n", " Default is False.\n", " \n", " Returns\n", " -------\n", " ds: xr.Dataset\n", " A xarray.Dataset object containing values and attributes read from Marthe\n", " grid file.\n", "\n" ] } ], "source": [ "help(gm.load_marthe_grid)" ] }, { "cell_type": "code", "execution_count": 32, "metadata": {}, "outputs": [], "source": [ "# reading data and storing into Dataset object (with xarray)\n", "ds = gm.load_marthe_grid(\n", " './data/chasim_hallue.out', 'CHARGE',\n", " fpastp='./data/hallue.pastp',\n", " drop_nan=True\n", ")" ] }, { "cell_type": "code", "execution_count": 33, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
<xarray.Dataset> Size: 2MB\n",
"Dimensions: (time: 205, zone: 927)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 2kB 1995-07-31 1995-08-01 ... 2012-07-01\n",
" * zone (zone) int32 4kB 255 256 257 258 259 ... 2722 2723 2724 2725 2726\n",
"Data variables:\n",
" charge (time, zone) float64 2MB 100.0 100.6 101.1 ... 27.0 26.0 26.35\n",
" x (zone) float32 4kB 617.8 618.2 618.8 619.2 ... 606.8 607.2 607.8\n",
" y (zone) float32 4kB 2.567e+03 2.567e+03 ... 2.543e+03 2.543e+03\n",
" dx (zone) float32 4kB 0.5 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5 0.5\n",
" dy (zone) float32 4kB 0.5 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5 0.5\n",
" izone (zone) int32 4kB 1 2 3 4 5 6 7 8 ... 921 922 923 924 925 926 927\n",
"Attributes: (12/17)\n",
" conventions: CF-1.10\n",
" title: Modélisation du bassin de la SOMME Nappe_Libre\n",
" marthe_grid_version: 9.0\n",
" original_dimensions: x,y,z [grids]: 53 54 1\n",
" crs: {'crs_wkt': 'PROJCRS["NTF (Paris) / Lambert zone II...\n",
" lon_resolution: 0.5\n",
" ... ...\n",
" period: 1995-2012\n",
" frequency: 30 day(s)\n",
" creation_date: Created on 2026-04-30T11:35:03Z UTC\n",
" comment: Hydrogeological model created with MARTHE code (Thi...\n",
" domain: FR-France\n",
" institution: BRGM, French Geological Survey, Orléans, France<xarray.Dataset> Size: 3MB\n",
"Dimensions: (y: 48, x: 44, time: 205)\n",
"Coordinates:\n",
" * y (y) float32 192B 2.567e+03 2.566e+03 ... 2.544e+03 2.543e+03\n",
" * x (x) float32 176B 599.2 599.8 600.2 600.8 ... 619.8 620.2 620.8\n",
" * time (time) datetime64[ns] 2kB 1995-07-31 1995-08-01 ... 2012-07-01\n",
"Data variables:\n",
" charge (time, y, x) float64 3MB nan nan nan nan nan ... nan nan nan nan\n",
" dx (y, x) float32 8kB nan nan nan nan nan nan ... nan nan nan nan nan\n",
" dy (y, x) float32 8kB nan nan nan nan nan nan ... nan nan nan nan nan\n",
" izone (y, x) float64 17kB nan nan nan nan nan nan ... nan nan nan nan nan\n",
"Attributes: (12/17)\n",
" conventions: CF-1.10\n",
" title: Modélisation du bassin de la SOMME Nappe_Libre\n",
" marthe_grid_version: 9.0\n",
" original_dimensions: x,y,z [grids]: 53 54 1\n",
" crs: {'crs_wkt': 'PROJCRS["NTF (Paris) / Lambert zone II...\n",
" lon_resolution: 0.5\n",
" ... ...\n",
" period: 1995-2012\n",
" frequency: 30 day(s)\n",
" creation_date: Created on 2026-04-30T11:35:03Z UTC\n",
" comment: Hydrogeological model created with MARTHE code (Thi...\n",
" domain: FR-France\n",
" institution: BRGM, French Geological Survey, Orléans, France<xarray.DataArray 'charge' (zone: 927)> Size: 7kB\n",
"array([ 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00,\n",
" 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00,\n",
" -3.25440e-01, -4.60980e-01, -5.27480e-01, -5.59100e-01,\n",
" -5.74500e-01, 0.00000e+00, -3.74970e-01, -6.81720e-01,\n",
" -8.68420e-01, -9.77570e-01, -1.04721e+00, -1.09548e+00,\n",
" 0.00000e+00, -6.41230e-01, -1.00733e+00, -1.22240e+00,\n",
" -1.35717e+00, -1.45930e+00, -1.57370e+00, -1.80513e+00,\n",
" 0.00000e+00, 0.00000e+00, 0.00000e+00, 0.00000e+00,\n",
" -5.66100e-01, -1.02068e+00, -1.33316e+00, -1.53087e+00,\n",
" -1.65762e+00, -1.74995e+00, -1.82523e+00, -1.90350e+00,\n",
" 0.00000e+00, 0.00000e+00, -1.43024e+00, -1.00962e+00,\n",
" -1.14766e+00, -8.35060e-01, -7.87260e-01, -8.78120e-01,\n",
" -1.16742e+00, -1.45697e+00, -1.68467e+00, -1.83483e+00,\n",
" -1.92341e+00, -1.97372e+00, -1.99069e+00, -1.98500e+00,\n",
" 0.00000e+00, 0.00000e+00, -3.44370e-01, -3.57610e-01,\n",
" 0.00000e+00, 0.00000e+00, 0.00000e+00, -2.09688e+00,\n",
" -1.83277e+00, -1.61107e+00, -1.55613e+00, -1.44464e+00,\n",
" -1.43203e+00, -1.52037e+00, -1.68965e+00, -1.87151e+00,\n",
" -2.02142e+00, -2.11349e+00, -2.14897e+00, -2.14145e+00,\n",
" -2.09989e+00, -1.43919e+00, -1.36450e+00, -9.45770e-01,\n",
"...\n",
" -6.78740e-01, -1.82235e+00, -1.73151e+00, -1.55717e+00,\n",
" -1.30703e+00, -9.77720e-01, -5.57570e-01, -4.35400e-02,\n",
" -1.44860e-01, -2.52990e-01, -3.26250e-01, -3.69900e-01,\n",
" -4.01230e-01, -5.87460e-01, -6.72990e-01, -1.76108e+00,\n",
" -1.67109e+00, -1.50200e+00, -1.26479e+00, -9.60430e-01,\n",
" -5.85770e-01, -1.32270e-01, -3.03400e-02, -1.52940e-01,\n",
" -1.90000e-01, -1.65750e-01, 0.00000e+00, -1.76839e+00,\n",
" -1.72637e+00, -1.62543e+00, -1.45758e+00, -1.23024e+00,\n",
" -9.55270e-01, -6.37120e-01, -3.04530e-01, -2.48100e-02,\n",
" -7.04900e-02, 0.00000e+00, 0.00000e+00, -1.75184e+00,\n",
" -1.68804e+00, -1.58243e+00, -1.41312e+00, -1.18093e+00,\n",
" -9.31090e-01, -6.64310e-01, -3.79320e-01, -4.50800e-02,\n",
" -1.84200e-02, -1.20000e-02, -1.64234e+00, -1.54945e+00,\n",
" -1.37045e+00, -1.08295e+00, -8.56250e-01, -6.43070e-01,\n",
" -4.37550e-01, -2.51870e-01, -1.76770e-01, -1.46430e-01,\n",
" -8.46730e-01, -6.94620e-01, -5.40770e-01, -4.04770e-01,\n",
" -2.89830e-01, -2.15860e-01, -1.52910e-01, -6.92440e-01,\n",
" -4.57850e-01, -3.42300e-01, -2.65000e-01, -2.01410e-01,\n",
" -1.59930e-01, 3.00000e-05, 0.00000e+00, 0.00000e+00,\n",
" -2.06900e-02, 0.00000e+00, -1.24820e-01])\n",
"Coordinates:\n",
" * zone (zone) int32 4kB 255 256 257 258 259 ... 2722 2723 2724 2725 2726\n",
"Attributes:\n",
" varname: CHARGE\n",
" units: m\n",
" missing_value: 9999.0\n",
" standard_name: water_table_level\n",
" long_name: groundwater head<xarray.Dataset> Size: 2MB\n",
"Dimensions: (time: 205, zone: 927)\n",
"Coordinates:\n",
" * time (time) datetime64[ns] 2kB 1995-07-31 1995-08-01 ... 2012-07-01\n",
" * zone (zone) int32 4kB 255 256 257 258 259 ... 2722 2723 2724 2725 2726\n",
" quantile float64 8B 0.05\n",
"Data variables:\n",
" charge (time, zone) float64 2MB 100.0 100.6 101.1 ... 27.0 26.0 26.35\n",
" x (zone) float32 4kB 617.8 618.2 618.8 619.2 ... 606.8 607.2 607.8\n",
" y (zone) float32 4kB 2.567e+03 2.567e+03 ... 2.543e+03 2.543e+03\n",
" dx (zone) float32 4kB 0.5 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5 0.5\n",
" dy (zone) float32 4kB 0.5 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5 0.5\n",
" izone (zone) int32 4kB 1 2 3 4 5 6 7 8 ... 921 922 923 924 925 926 927\n",
" q5 (zone) float64 7kB 100.0 100.6 101.1 101.6 ... 26.98 26.0 26.31\n",
" tresh (time, zone) bool 190kB False False False ... False False False\n",
"Attributes: (12/17)\n",
" conventions: CF-1.10\n",
" title: Modélisation du bassin de la SOMME Nappe_Libre\n",
" marthe_grid_version: 9.0\n",
" original_dimensions: x,y,z [grids]: 53 54 1\n",
" crs: {'crs_wkt': 'PROJCRS["NTF (Paris) / Lambert zone II...\n",
" lon_resolution: 0.5\n",
" ... ...\n",
" period: 1995-2012\n",
" frequency: 30 day(s)\n",
" creation_date: Created on 2026-04-30T11:35:03Z UTC\n",
" comment: Hydrogeological model created with MARTHE code (Thi...\n",
" domain: FR-France\n",
" institution: BRGM, French Geological Survey, Orléans, France<xarray.Dataset> Size: 152kB\n",
"Dimensions: (season: 4, zone: 927)\n",
"Coordinates:\n",
" * season (season) object 32B 'DJF' 'JJA' 'MAM' 'SON'\n",
" * zone (zone) int32 4kB 255 256 257 258 259 ... 2722 2723 2724 2725 2726\n",
"Data variables:\n",
" charge (season, zone) float64 30kB 100.0 100.6 101.1 ... 26.99 26.0 26.33\n",
" x (season, zone) float32 15kB 617.8 618.2 618.8 ... 606.8 607.2 607.8\n",
" y (season, zone) float32 15kB 2.567e+03 2.567e+03 ... 2.543e+03\n",
" dx (season, zone) float32 15kB 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5\n",
" dy (season, zone) float32 15kB 0.5 0.5 0.5 0.5 0.5 ... 0.5 0.5 0.5 0.5\n",
" izone (season, zone) float64 30kB 1.0 2.0 3.0 4.0 ... 925.0 926.0 927.0\n",
" anom (season, zone) float64 30kB 0.0 0.0 0.0 ... -0.002924 0.0 0.001059\n",
"Attributes: (12/17)\n",
" conventions: CF-1.10\n",
" title: Modélisation du bassin de la SOMME Nappe_Libre\n",
" marthe_grid_version: 9.0\n",
" original_dimensions: x,y,z [grids]: 53 54 1\n",
" crs: {'crs_wkt': 'PROJCRS["NTF (Paris) / Lambert zone II...\n",
" lon_resolution: 0.5\n",
" ... ...\n",
" period: 1995-2012\n",
" frequency: 30 day(s)\n",
" creation_date: Created on 2026-04-30T11:35:03Z UTC\n",
" comment: Hydrogeological model created with MARTHE code (Thi...\n",
" domain: FR-France\n",
" institution: BRGM, French Geological Survey, Orléans, France