{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# [FR] Exemple d'utilisation de gridmarthe\n", "\n", "Le package gridmarthe est conçu pour faciliter la lecture/l'écriture de grille au format Marthe.\n", "Ce notebook permet d'explorer quelques fonctionnalités de base du package et de montrer un exemple\n", "de traitement des grilles." ] }, { "cell_type": "code", "execution_count": 29, "metadata": {}, "outputs": [], "source": [ "# import du package\n", "import gridmarthe as gm" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "La librairie gridmarthe s'appuie sur `xarray`, qui permet de faciliter le traitement de grilles spatio-temporelles. La documentation complète de cette librairie est accessible : \n", "https://docs.xarray.dev/en/stable/index.html" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Fonctionnalités de base\n", "\n", "Les grilles contiennent certaines métadonnées, dont l'index du pas de temps\n", "mais pas les dates en elles-même. Aussi, il est utile de fournir à la fonction de lecture\n", "soit une série de date (à construire manuellement) soit un fichier pastp pour que les dates soient\n", "lues automatiquement.\n", "\n", "En complément, plusieurs arguments peuvent être utiles à la lecture (retrait des valeurs nulles, transformation des xy, ajout de l'indicateur de maillage ou des numéros de colonnes/lignes, etc.).\n", "\n", "Pour évaluer les options possibles, on peut afficher l'aide de la fonction." ] }, { "cell_type": "code", "execution_count": 30, "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": 31, "metadata": {}, "outputs": [], "source": [ "# lecture d'une grille marthe et stockage dans un Dataset (librairie xarray)\n", "ds = gm.load_marthe_grid(\n", " './data/chasim_hallue.out', 'CHARGE',\n", " fpastp='./data/hallue.pastp',\n", " drop_nan=True # si la valeur des nans n'est pas 9999 (ex. permh, NaNs = 0), on peut spécifier la valeur\n", ")" ] }, { "cell_type": "code", "execution_count": 32, "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:34:59Z 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:34:59Z 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:34:59Z 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:34:59Z UTC\n",
" comment: Hydrogeological model created with MARTHE code (Thi...\n",
" domain: FR-France\n",
" institution: BRGM, French Geological Survey, Orléans, France