On the internet many scripts are available for hydrological analysis and modelling. But, where to start or which script is useful? This hydrological toolbox contains scripts that have proven to be useful in Deltares projects all over the world. This toolbox is initiated by the Department of Hydrology of Deltares. For now most of these tools are written in the Python programming language, since this is the most applied language within the Department of Hydrology. However additional tools in other languages are also welcome, these can be placed directly in OpenEarth under the correct programming language folder. The documentation of these tools can be placed on the wiki.

OpenEarthTools contains a dedicated toolbox for model input and output. You can access this toolbox from the OSS Deltares SVN server, after downloading a copy with SVN (using Tortoise SVN for instance) with your OpenEarth account. This toolbox allows you to automate actions that are common practice in hydrological modelling. For example, tools are available for:

  • Data analyses tools (e.g. computation of GHG)
  • Data validation (e.g. double mass analysis)
  • Data conversion (e.g. PCRaster to GeoTIFF)
  • Coupling tools to software packages

Toolbox structure

  • Hydrotools - location of classes / functions
    • hydrotools.conversion -  conversion tools for different data formats (NetCDF, GeoTIFF, CSV)
    • hydrotools.coupling - coupling tools to software packages (SOBEK, wflow, 3Di)

    • hydrotools.gis - GIS functions, this could be useful for pre- and postprocessing steps

    • hydrotools.models - integrated functions

    • hydrotools.process - single functions for hydro-meteorological processes e.g. evaporation

    • hydrotools.statistics - pre- and postprocessing tools for computation of statistical parameters (frequency analysis, design discharge calculations)

    • hydrotools.validation - data validation tools (double mass curve, ...)

  • Sandbox - placeholders for unfinished scripts using the same structure as above (e.g. examples of how to use functions or unfinished tools)
  • Notebooks - placeholders for IPython notebooks, same as Sandbox

How can I use the Hydro Toolbox?

  • Make a checkout (like any subversion project with Tortoise SVN). If you are new to Tortoise SVN consider reading Tortoise SVN Quick Start first
  • Install it by running on command line: python setup.py develop
  • Import the package within Python like any other package: import hydrotools / from hydrotools import *
  • Try out a function e.g.: 
>>> help(hydrotools.gis.gdal_readmap)
Help on function gdal_readmap in module hydrotools.gis.gdal_readmap:
gdal_readmap(file_name, file_format)
    Read geographical file into memory
    Dependencies are osgeo.gdal and numpy
    Input:
        file_name: -- string: reference path to GDAL-compatible file
        file_format: -- string: file format according to GDAL acronym
        (see http://www.gdal.org/formats_list.html)
    Output:
        x: -- 1D np-array: x-axis
        y: -- 1D np-array: y-axis
        data:           -- 2D np-array: raster data
        fill_val         -- float:       fill value

How can I contribute to the Hydro Toolbox?

You are welcome to contribute to this initiative by improving the current scripts or adding new ones. Scripts that are added to the main "Hydrotools" folder should be setup in a generic way and comply with basic quality requirements. However, you can add your unfinished scripts to the "Sandbox" folder so that others can benefit from your work and further improve it. 

  • update a script or copy your new script in the correct folder in the toolbox structure
  • right click on the folder and choose "SVN Commit"
  • tell us in the comments of the new revision what you changed or added

Basic quality requirements

Python scripts in the main "hydrotools" folder should comply with the following requirements:

A new script should have:

  • a generic setup;
  • a header (docstring) at the start of the script with 1) the date of creation 2) the name(s) of the author(s) 3) a general explanation of the functionality of the script and 4) keywords;
  • a help for each python function, i.e.: a docstring at the top of the script explaining the functionality, followed by the input and output parameters of the script.

A revision of a script should have:

  • a change log including date of revision, revision number, author should be added to the header of the script.

For a good example see the dem_fill_dig script in the "gis" folder of the Hydro Toolbox.

For more tips on how to write a proper python script check:

 

  • No labels

Disclaimer