Merge branch 'v1' into update_examples_cli

Deltares · Sep 25, 2024 · 7bc2a07 · 7bc2a07
2 parents 1177b7e + 956350e
commit 7bc2a07
Show file tree

Hide file tree

Showing 20 changed files with 53 additions and 466 deletions.
diff --git a/docs/assets/example_catalog.yml b/docs/assets/example_catalog.yml
@@ -2,6 +2,7 @@
     roots:
       - /linux/path/to/data_root/
       - C:\Windows\path\to\data_root
+      - .
     version: version
     name: data_catalog_name
 

diff --git a/docs/guides/advanced_user/data_prepare_cat.rst b/docs/guides/advanced_user/data_prepare_cat.rst
@@ -146,7 +146,7 @@ To request a specific variant, the variant arguments can be used as keyword argu
 the `DataCatalog.get_rasterdataset` method, see code below. By default the newest
 version from the last provider is returned when requesting a data source with specific
 version or provider. Requesting a specific version from a HydroMT configuration file is
-also possible, see :ref:`model_config`.
+also possible.
 
 
 .. code-block:: python

diff --git a/docs/guides/core_dev/contributing.rst b/docs/guides/core_dev/contributing.rst
@@ -236,7 +236,7 @@ should be created with model-specific data readers, writers and setup methods as
   (i.e. with default values), but no required arguments. The results component does not have write method.
 - All public model methods may only contain arguments which require one of the following basic python types:
   string, numeric integer and float, boolean, None, list and dict types. This is requirement makes it possible to
-  expose these methods and their arguments via a :ref:`model config .yml file <model_config>`.
+  expose these methods and their arguments via a :ref:`model workflow .yml file <model_workflow>`.
 - Data is exposed to each model method through the ``Model.data_catalog`` attribute which is an instance of the
   :py:class:`hydromt.DataCatalog`. Data of :ref:`supported data types <data_types>` is provided to model methods
   by arguments which end with ``_fn`` (short for filename) which refer to a source in the data catalog

diff --git a/docs/guides/intro.rst b/docs/guides/intro.rst
@@ -32,79 +32,3 @@ help you get started with HydroMT. Our user guide is separated into four (main)
   advanced_user/index
   plugin_dev/index
   core_dev/index
-
-
-..   The user guide is organized as follows:
-.. - :ref:``
-.. - :ref:`Introduction to HydroMT <detailed_intro>`: A brief introduction to HydroMT and its main functionalities.
-.. - :ref:`Quick overview <quick_overview>`: A quick overview on how to use HydroMT.
-.. - :ref:`HydroMT command line interface <hydromt_cli>`: A detailed description of the command line interface.
-.. - :ref:`HydroMT Python API <hydromt_python>`: A detailed description of the Python API (advanced users).
-.. - :ref:`Working with data in HydroMT <get_data>`: A detailed section to go through how HydroMT interacts
-..   with raw input data through its DataCatalog.
-.. - :ref:`Working with models in HydroMT <model_main>`: A detailed section to go through how to prepare and interact with
-..   models using HydroMT.
-.. - :ref:`Methods and workflows <methods_workflows>`: A detailed section to go through the different methods and workflows
-..   available in HydroMT (advanced or python users).
-
-.. One final remark: because each model is unique at least in its input file format (e.g.
-.. netCDF, text, binary, etc.), HydroMT is usually used in combination with a **plugin**.
-.. These plugins are here to define model specific file formats and readers/writers. You can
-.. find the list of available plugins in the :ref:`plugins section <plugins>`.
-
-.. .. toctree::
-..    :maxdepth: 2
-..    :hidden:
-..    :caption: Working with HydroMT
-
-..    hydromt_intro.rst
-..    ../getting_started/quick_overview.rst
-..    hydromt_cli.rst
-..    hydromt_python.rst
-..    terminology.rst
-
-.. .. toctree::
-..    :maxdepth: 2
-..    :hidden:
-..    :caption: Working with data in HydroMT
-
-..    data_overview.rst
-..    data_prepare_cat.rst
-..    data_types.rst
-..    data_existing_cat.rst
-..    data_conventions.rst
-..    ../_examples/prep_data_catalog.ipynb
-..    ../_examples/export_data.ipynb
-..    ../_examples/reading_raster_data.ipynb
-..    ../_examples/reading_vector_data.ipynb
-..    ../_examples/reading_point_data.ipynb
-..    ../_examples/reading_tabular_data.ipynb
-..    ../_examples/working_with_tiled_raster_data.ipynb
-
-.. .. toctree::
-..    :maxdepth: 2
-..    :hidden:
-..    :caption: Working with models in HydroMT
-
-..    model_overview.rst
-..    model_build.rst
-..    model_update.rst
-..    model_clip.rst
-..    model_config.rst
-..    model_region.rst
-..    ../_examples/working_with_models_basics.ipynb
-..    ../_examples/working_with_models.ipynb
-..    ../_examples/working_with_meshmodel.ipynb
-..    ../_examples/delineate_basin.ipynb
-
-.. .. toctree::
-..    :maxdepth: 2
-..    :hidden:
-..    :caption: Methods and workflows
-
-..    methods_main.rst
-..    methods_stats.rst
-..    ../_examples/working_with_raster.ipynb
-..    ../_examples/working_with_geodatasets.ipynb
-..    ../_examples/working_with_flow_directions.ipynb
-..    ../_examples/doing_extreme_value_analysis.ipynb
diff --git a/docs/guides/user_guide/_cli.rst b/docs/guides/user_guide/_cli.rst
diff --git a/docs/guides/user_guide/about.rst b/docs/guides/user_guide/about.rst
diff --git a/docs/guides/user_guide/building_blocks.rst b/docs/guides/user_guide/building_blocks.rst
diff --git a/docs/guides/user_guide/data_conventions.rst b/docs/guides/user_guide/data_conventions.rst
@@ -8,9 +8,6 @@ It is possible to use the ``rename`` option in the :ref:`data catalog yaml file
 This section lists the different variable naming and unit conventions of HydroMT by types.
 A list of recognized :ref:`dimension names <dimensions>` is found here.
 
-.. NOTE::
-
-    This list is still in development.
 
 
 Topography

diff --git a/docs/guides/user_guide/data_existing_cat.rst b/docs/guides/user_guide/data_existing_cat.rst
@@ -35,14 +35,14 @@ Alternatively, deltares_data can also be accessed with the ``--dd`` option:
     hydromt build MODEL --dd ...
 
 
-You can specify a version of the catalog by adding the version number after the catalog name, e.g. ``deltares_data=2024.2``.
+You can specify a version of the catalog by adding the version number after the catalog name, e.g. ``deltares_data=v1.0.0``.
 
 .. code-block:: bash
 
-    hydromt build MODEL -d deltares_data=2024.2 ...
+    hydromt build MODEL -d deltares_data=v1.0.0 ...
 
 Once you have set the data catalog you can specify the data source(s) for each method in the HydroMT
-:ref:`model configuration file <model_config>` as shown in the example below with the `setup_precip_forcing` method.
+:ref:`model workflow file <model_workflow>` as shown in the example below with the `setup_precip_forcing` method.
 
 .. code-block:: yaml
 
@@ -56,7 +56,6 @@ Once you have set the data catalog you can specify the data source(s) for each m
         version: 'v22.0e'
 
 
-
 From Python
 ~~~~~~~~~~~
 
@@ -74,32 +73,5 @@ catalog name. You can then get data from the catalog using the
     data_catalog = DataCatalog(data_libs=["deltares_data=v2024.2"])
     # get data from the catalog
     ds = data_catalog.get_rasterdataset("eobs") # get the most recently added
-    ds = data_catalog.get_rasterdataset("eobs", version="22.0e") # get a specific version
-
-
-Similar when building a model using the :py:class:`Model` class you can specify the
-data catalog and version. Subsequently you can use specific data sources for each
-model :ref: `setup method`
-
-.. code-block:: python
-
-    from hydromt import Model
-    # initialize a model with a specific data catalog version
-    mod = Model(data_libs=["deltares_data=v2024.2"])
-    # setup a region and create a map based on eobs orography
-    mod.setup_region(region = {'bbox': [4.5, 51.5, 6.5, 53.5]})
-    # create a map using the latest version
-    mod.setup_maps_from_rasterdataset(
-        raster_fn='eobs_orography',
-        name="orography_latest",
-    )
-    # create a map using a specific version
-    mod.setup_maps_from_rasterdataset(
-        raster_fn={'source': 'eobs_orography',  "version": "22.0e"},
-        name="orography_v22.0e",
-    )
-
-Available pre-defined data catalogs
------------------------------------
-
-.. .. include:: ../_generated/predefined_catalogs.rst
+    ds = data_catalog.get_rasterdataset("eobs", version="22.0e") # get a specific
+    version
diff --git a/docs/guides/user_guide/data_overview.rst b/docs/guides/user_guide/data_overview.rst
@@ -20,7 +20,7 @@ You can :ref:`explore and make use of pre-defined data catalogs <existing_catalo
 
 .. TIP::
 
-    Tiles of tiled rasterdatasets which are described by a .vrt file can be cached locally (starting from v0.7.0).
+    Tiles of tiled rasterdatasets which are described by a .vrt file can be cached locally.
     The requested data tiles will by default be stored to ~/.hydromt_data.
     To use this option from command line add `--cache` to the `hydromt build` or `hydromt update` commands
     In Python the cache is a property of the DataCatalog and can be set at Initialization.
@@ -32,56 +32,12 @@ From CLI
 
 When using the HydroMT command line interface (CLI), one can provide a data catalog by specifying the
 path to the yaml file with the ``-d (--data)`` option.
-Multiple yaml files can be added by reusing the ``-d`` option. If the yaml files have data sources with
-the same name, the source from the last catalog in the list is used.
-
-For example when using the :ref:`build <cli_build>` CLI method:
-
-.. code-block:: console
-
-    hydromt build MODEL -r REGION -d /path/to/data_catalog1.yml -d /path/to/data_catalog2.yml
-
 Alternatively, you can also use names and versions of the :ref:`predefined data catalogs <existing_catalog>`.
 If no version is specified, the latest version available is used.
 
 .. code-block:: console
 
-    hydromt build MODEL -r REGION -d deltares_data=v2022.5 -d artifact_data
-
-A special exception is made for the Deltares data catalog which can be accessed with the
-``--dd (--deltares-data)`` flag (requires access to the Deltares P-drive).
-
-.. code-block:: console
-
-    hydromt build MODEL -r REGION --dd
-
-.. NOTE::
-
-    When using several data catalogs, the order in which they are listed is important! If several catalogs contain
-    data sources with the same names, the sources from the last catalog in the list are used.
-    If the ``--dd (--deltares-data)`` flag is used the deltares_data catalog is read first.
-
-The CLI also provides two other utility subcommands: `export` and `check`. The export function can be used
-to export a subset of the data available in your data catalogs for e.g. collaboration. This sub command supports
-providing a region (bounding box or path to geom only), data catalogs, data source names, and time ranges
-for example:
-
-.. code-block:: console
-
-    hydromt export -r "{'bbox': [4.6891,52.9750,4.9576,53.1994]}" -s era5_hourly -d ../hydromt/data/catalogs/artifact_data.yml -t '["2010-01-01", "2022-12-31"]' path/to/output_dir
-
-
-Finally the CLI also provides a lightweight command to check your files for compliance without having to build the model.
-Note that this does not yet validate the data specified, but only the syntax of the files themselves.
-However, we do plan to expand its functionality over time. It can be use for example like so:
-
-.. code-block:: console
-
-    hydromt check grid -d /path/to/data_catalog.yml -i /path/to/model_config.yml -r '{'bbox': [-1,-1,1,1]}'
-
-currently only `bbox` and `geom` variants of regions are supported in validation. Also note that the geom variant will only check whether the file exists not its contents. We also plan to expand this functionality in the future.
-
-.. _get_data_python:
+    hydromt build MODEL -d artifact_data
 
 From Python
 -----------