Merge pull request #99 from rcaneill/issue95

more details in examples

docs/examples/compute_metrics.ipynb

@@ -1,5 +1,14 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "f95face2-9fbc-4ec5-8546-ce17fe290147",
+   "metadata": {},
+   "source": [
+    "This example showcases how `xnemogcm` can compute certain missing metrics (metrics are called scale factors in the NEMO community, and called metrics in the xgcm community).\n",
+    "It is thus possible to e.g. compute `e3u` from `e3t`. We let the reader refer to the NEMO documentation for the explanation of the scale factors."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

docs/examples/open_process_files.ipynb

@@ -1,5 +1,18 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "111a159d-c529-49db-a71b-e01f817b02cf",
+   "metadata": {},
+   "source": [
+    "This example demonstrates how to open NEMO files and make them compliant with xgcm.\n",
+    "NEMO files consist of two different types of files: 1) the domain files containing information on the grid (domain_cfg and mesh_mask files),\n",
+    "and 2) the nemo files containing the outputted variables (usually, the filenames are similar to `XXX_01234_01234_grid_X.nc`).\n",
+    "To create the `xgcm.Grid`, most of the information is located in the domain files. It is thus necessary to open both the domain and the nemo files.\n",
+    "\n",
+    "These files can either be opened in two different Datasets, or combined into a single one. Both options are demonstrated in this example.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d4baf777-28bc-42a2-95d9-714e62b9fa84",
@@ -37,7 +50,7 @@
    "id": "cf68f882-90a2-420a-b5b5-ceded0c96420",
    "metadata": {},
    "source": [
-    "## First open the domain_cfg and nemo files into 2 datasets\n",
+    "## First open the domain and nemo files into 2 datasets\n",
     "### domain"
    ]
   },
@@ -59,11 +72,11 @@
     "---\n",
     "\n",
     "You can provide the file names / folder using 3 similar methods:\n",
-    "1. Give the path to the files and xnemogcm opens the domain_cfg_out and mesh_mesk files\n",
+    "1. Give the path to the files and xnemogcm opens the domain_cfg_out and/or mesh_mesk files\n",
     "2. Give the path to the data folder + the name of the files\n",
     "3. Give the name of the files that already contain the tree (e.g. ['/path/to/file1', '/path/to/file2']\n",
     "\n",
-    "These 3 methods are equivalent, however if your domain files don't have the strandard names you need to provide them by hand.\n",
+    "These 3 methods are equivalent, however if your domain files don't have the standard names you need to provide them by hand.\n",
     "\n",
     "We use one of the test folder:"
    ]
@@ -133,7 +146,7 @@
    "metadata": {},
    "source": [
     "---\n",
-    "We can provide the files folder / name following the same convention as for the `open_domain_cfg` function. We also need to provide the `domcfg` dataset so xnemogcm knows how to set the variables on the proper grid position. We can also provide extra kwargs to the underlying call to `xarray.open_mfdataset` function."
+    "We can provide the files folder / name following the same convention as for the `open_domain_cfg` function. We also **need** to provide the `domcfg` dataset so xnemogcm knows how to set the variables on the proper grid position. We can also provide extra kwargs to the underlying call to `xarray.open_mfdataset` function."
    ]
   },
   {

docs/examples/recombing_mesh_mask_domain_cfg.ipynb

@@ -1,5 +1,20 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "96f57a3d-4035-4c7b-acb5-5ae843eb87fd",
+   "metadata": {},
+   "source": [
+    "Two types of files related to the domain grid can be of use with NEMO: the `domain_cfg` files and the `mesh_mask` files. They are very similar, and any of them can be used by xnemogcm. If you are using a realistic (regional or global) configuration, they are provided as input files to NEMO so you should have these file. If you are using idealised configuration with analytical bathymetry, these files can be outputted by NEMO.\n",
+    "\n",
+    "By default, NEMO outputs a mesh_mask / domain_cfg file per computing processor, if the namelist parameter is set on .true.:\n",
+    "\n",
+    "* `ln_write_cfg = .true.` to output the domain_cfg if created analytically in the usrdef_zgr.F90 and usrdef_hgr.F90 files\n",
+    "* `ln_meshmask = .true.` to output the mesh_mask files (that also contain the masks)\n",
+    "\n",
+    "While it is possible to recombine the files using the nemo fortran toolbox, xnemogcm can also recombine them easily."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "41aec3c0-ece5-4ba1-b47f-d7a6d67b0860",
@@ -34,17 +49,10 @@
   },
   {
    "cell_type": "markdown",
-   "id": "96f57a3d-4035-4c7b-acb5-5ae843eb87fd",
+   "id": "f71a5a14-d662-42f0-a695-ab0d421b6b24",
    "metadata": {},
    "source": [
-    "By default nemo outputs a mesh_mask / domain_cfg file per computing processor, if the namelist parameter is set on .true.:\n",
-    "\n",
-    "* `ln_write_cfg = .true.` to output the domain_cfg if created analytically in the usrdef_zgr.F90 and usrdef_hgr.F90 files\n",
-    "* `ln_meshmask = .true.` to output the mesh_mask files (that also contain the masks)\n",
-    "\n",
-    "While it is possible to recombine the files using the nemo fortran toolbox, xnemogcm can also recombine them easily.\n",
-    "\n",
-    "To illustrate this, we use a data folder from the test data:"
+    "We use a data folder from the test data:"
    ]
   },
   {