The mHM basin extractor. Extract basins for given gauging stations.
If you have GDAL already installed, basinex can be installed via pip:
pip install basinex
Getting GDAL installed with pip is allways a bit cumbersome. Therefore we compiled instructions for the main target systems.
To get a recent version of GDAL, you can use the ppa of ubuntugis:
sudo add-apt-repository ppa:ubuntugis/ppa
sudo apt-get update
sudo apt install gdal-bin libgdal-dev
pip install wheel numpy
pip install GDAL==$(gdal-config --version)
GDAL can be installed with homebrew:
brew install gdal
pip install wheel numpy
pip install GDAL==$(gdal-config --version)
You can use the unoffical wheels of Christoph Gohlke to install GDAL. The easiest way to do so, is using pipwin:
pip install pipwin
pipwin install gdal
It is best to use basinex with conda to have gdal and NetCDF installed properly. To use the development version of basinex, download this repository and do the following in your conda environment:
conda install -y gdal netcdf4 pyyaml cxx-compiler
pip install .
Then you can execute basinex in that conda environment.
Here is a short introduction about how to use the basin extractor. Have a look at the example directory or try it out directly with:
basinex -c examples
A command line script basinex will be installed with this package.
You can execute it in your terminal and it will search for an input.yml file in your current directory.
To get more information about how to use the command line interface, you can have a look at the help message:
$ basinex -h
usage: basinex [-h] [-n LINE] [-i INPUT] [-v] [-c CWD] [--version]
mHM basin extractor
optional arguments:
-h, --help show this help message and exit
-n LINE, --line LINE the gauge to extract, given as its (0-based) line number in the look up table
-i INPUT, --input INPUT
the input yaml file to read (default: 'input.yml')
-v, --verbose give some status output
-c CWD, --cwd CWD the working directory
--version show program's version number and exit
The main input file input.yml is documented and should (hopefully) give an overview
The default input file looks like this:
outpath: /path/to/output/
flowacc: /path/to/facc.asc
flowdir: /path/to/fdir.asc
gauges: /path/to/lut.txt
matching:
scaling_factor: 0.001
max_distance: 800
max_error: 0.8
mask:
fname: basin.asc
outpath: morph
gauge:
fname: idgauges.asc
outpath: morph
gridfiles:
- fname: /path/to/input/facc.asc
outpath: morph
- fname: /path/to/input/input1.asc
outpath: morph
- fname: /path/to/input/input2.asc
outpath: luse
ncfiles:
- fname: /path/to/input/input1.nc
outpath: meteo
ydim: northing
xdim: easting
y_shift: 0.5
x_shift: 0.5
- fname: /path/to/input/input2.nc
outpath: meteo
ydim: 'y'
xdim: 'x'
outpath: outpath/gauge_id/ - Required: Output location, all data will be writen to outpath/gauge_id/flowacc: /path/to/facc.asc - Required: flowaccumulationflowdir: /path/to/fdir.asc - Required: flowdirectiongauges: /path/to/lut.txt - Required: gauging data lookup table
Structure of the table:
id: an unique gauging station identifiersize: size of the catchmenty: y coordinate of the gauging stationx: x coordinate of the gauging stationid: an unique basin identifierpath: path to the mask filevarname: name of the mask variable (optional, only needed if the mask is stored in a netcdf file)latitude-size-correction: False - Optional:
perform a latitude correction for the given basin size (default: False)
AREA = N_cells * res_x * ( cos(LAT) * res_y ) * scaling factor^2matching: - Required: gauge matching parameters
scaling_factor: .001 - scaling factor to account for the (possible) unit differences between the flowaccumulation and the gauging data. In order to make the data comparable the effective flowaccumulation will be caclulated as:
flowaccumulation_value * (cellsize * scaling_factor)^2max_distance: 800 - maximum distance [in map units] around a given gauging station location to search for a matching cellmax_error: 0.8 - maximum error, as a fraction of the given basin sizemask: - Optional: Write the delineated basin
fname: basin.asc - Optional: file name of the mask grid (default: mask.asc)outpath: morph - output subdirectorygauge: - Optional: Write the gauge basin
fname: idgauges.asc - Optional: file name of the gauge grid (default: idgauges.asc)outpath: morph - output subdirectorygridfiles: - Optional: Any number of grid files to extract.
fname: /path/to/input/facc.asc - flow accumulation and flow direction won't be written unless listed hereoutpath: morph - Optional: output subdirectory under outpath/gauge_idncfiles: - Optional: Any number of netcdf files to extract.
time, y, x
your file should also contain the two one-dimensional (!) variables
y (depending solely on the dimension y) and x (depending solely
on the dimension x).
Tools like cdo tend to silently remove variables, so double check, that this information is avaialablefname: /path/to/input/input1.ncoutpath: meteo - Optional: output subdirectory under outpath/gauge_idydim: northing - Required: name of the (1D-) variable holding the y coordinatesxdim: easting - Required: name of the (1D-) variable holding the x coordinatesy_shift: .5 and x_shift: .5 - Optional:
Coordinates of spatial data are definied on a certain location
of the cell they belong to (e.g. upper or lower left corner).
All the supported file formats handle coordinates transparently,
with excpetion of netcdf.
To account for the flexibility the format offers, it is possible
to specify the fraction of a cell the origin is shifted from
the upper left corner in x and y direction.
The bounding box of the dataset (an imaginary box, that contains
exactly the entire spatial domain) is then caclulated as:
ymin = min(y_values) - (cellsize * (1 - y_shift))ymax = max(y_values) + (cellsize * y_shift)xmin = min(x_values) - (cellsize * (1 - x_shift))xmax = max(x_values) + (cellsize * x_shift)y_shift: 0x_shift: 0y_shift: 0.5x_shift: 0.5y_shift: 1x_shift: 0y_shift: 1x_shift: 0This package was orginally developed by David Schäfer who also provides a standalone version of the geoarray subpackage.
The netcdf4 and geoarray subpackages have been taken from the jams-python package, that was formerly developed at the CHS department at the UFZ and is now released under the MIT license.
LGPLv3
FAQs
A basin extractor.
We found that basinex demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.