Installation v3.1.0

Overview

BasinMaker is a python package work on several existing GIS platforms. So, the installation of BasinMaker includes two steps: 1) setup the python environment for the dependent GIS platforms; and 2) install BasinMaker itself.

Two installation modes (light installation and full installation) are available. The light installation will allow user to use BasinMaker to post process an existing routing product, such as the Basinmaker derived North American lake-river routing product. But it cannot be used to delineate a lake-river routing structure from DEM. The combination of BasinMaker light installation and the North American lake-river routing product could generate lake-river routing structures satisfying many user modeling demands. While the full installation of BasinMaker enables users to delineate a new lake-river routing structure from a user specified DEM.

For light installation (recommended unless users know for sure they need to delineate their watershed from scratch from a DEM), only geopandas or ArcGIS pro is needed. The python environment for both geopandas can be easily compiled within the anaconda environment under windows OS environment. The instruction about light installation procedure can be found in Light installation. Note that users can install both the light version and the full version on the same OS system.

Users, who want to use BasinMaker post processing functions without a Windows OS system, could try BasinMaker on Google Colab in BasinMaker on Google Colab

For full installation, BasinMaker can work under two python enviroments: the ArcGIS Pro and GRASS/QGIS GIS python enviroments. The instruction to install BasinMaker for each python enviroments are provided at Full installation. It is quite a challenge to setup a python environment for QGIS and GRASS together. Here, two procedures are provided for Windows OS systems, respectively. The procedure has been tested on several machines. But we can’t guarantee install procedures work on every machine. If you run into a problem create an issue on the GitHub and, time permitting, we will try to help. If you managed to do the full installation on a different operating system, we would be grateful if you could document and share the detailed installation procedure that was successful (email: m43han@uwaterloo.ca).

Updating BasinMaker to v3.1

For existing users of a BasinMaker version before 3.1 who want to update to version v3.1, users should simply reinstall BasinMaker 3.1 to a new working environment (e.g., called ‘Basinmaker3_1’)

BasinMaker on Google Colab

A post-processing example via google colab (no installation on your local machine necessary!) can be found at here here. The google colab is an online python notebook dose not require installation. This example will show you how to discretize, simplify, and revise the provided routing product for your purposes.

Light installation

Geopandas with anaconda

  1. Install anaconda

    The installer of anaconda can be installed from here. Note for windows system, please activate the ‘Register Anaconda3 as my default python 3.9’

  2. Create an empty python environment and then active it

    For windows system, search and open “Anacoda Prompt” (Windows) to active a conda command line. Users must make sure:

    • They have the proper privileges to create environment variables (e.g., run Anacoda Prompt as administrator will work)

    • DO NOT USE Anaconda Powershell Prompt

    Then

    conda create --name <any_name_for_env> python==3.11.3
conda activate <any_name_for_env>

  3. Install packages (may take some time)

    conda config --append channels conda-forge

    conda install gdal

    python -m pip install  pytest  simpledbf netCDF4 joblib jupyter requests wget gdown pandas rasterstats geopandas rasterio scipy

  4. Install BasinMaker

    python -m pip install https://github.com/dustming/basinmaker/archive/master.zip

  5. Test validation

    Please download the test data and scripts from here. and unzip it to a folder, the path of this folder will refer as path_test_data in following section. Then

    Please ignore following output messages

    • PyTables is not installed. No support for HDF output.

    • SQLalchemy is not installed. No support for SQL output.

    • Warnings

    cd path_test_data/test
python test_light_installation_qgis.py
(... some messages)
####################################
BasinMaker is successfully installed
####################################

  6. Users must active this conda environment when they wish to use functionalities from BasinMaker.

Full installation

The BasinMaker watershed delineation mode can be used under both ArcGIS Pro and GRASS GIS environments. We recommend using BasinMaker under the ArcGIS Pro environment. However, installation instructions for both Python environments are provided in the following two sections.

ArcGIS Pro in Windows

  1. Install ArcGIS Pro

    BasinMaker has been tested with ArcGIS Pro version 3.0.3. To use the software, please ensure that you have installed this version of ArcGIS Pro. If you need assistance with installing ArcGIS Pro, please contact your IT department for detailed instructions.

  2. Setup the python environment for BasinMaker in ArcGIS Pro

    Below are the key steps to create an ArcGIS Python environment. For detailed instructions, please refer to this link .

    • Open ArcGIS Pro and click on the “Settings/Project” icon in the upper left corner of the ArcGIS Pro window.

    • Click the “Package Manager” tab. And then click the “Manage Environments” button in the upper right corner of the window.

    • Clone the “ArcGIS Pro” environment and name it <any_name_for_env>. The clone process will take a few minutes.

    • Select and active the newly created environment and restart ArcGIS Pro for the changes to take effect

  3. Install BasinMaker in ArcGIS Pro

    • Open the ArcGIS Pro Python command prompt. To open the ArcGIS Pro Python command prompt, navigate to the Windows program directory: Programs > ArcGIS > Python Command Prompt.

    • Install BasinMaker and related pacakges using the following command:

    > python -m pip install https://github.com/dustming/basinmaker/archive/master.zip

  4. Install dependent packages

    > python -m pip install pytest simpledbf netCDF4 joblib jupyter requests wget gdown geopandas rasterstats

  5. Validate the installation with the package of test files.

    • Please download the test data and script and unzip it to a folder, the path of this folder will refer as path_test_data in following section. Then

    • Open the ArcGIS Pro Python command prompt and run the following command:

    cd path_test_data
python test_full_delineation_arcgis.py
(... some messages)
####################################
BasinMaker is successfully installed
####################################

    • Please ignore following output messages

      PyTables is not installed. No support for HDF output.

      SQLalchemy is not installed. No support for SQL output.

      Warnings

  6. Users must Open the ArcGIS Pro Python command prompt every time they wish to use functionalities from BasinMaker.

QGIS and GRASS in Windows

  1. Installation of QGIS and GRASS using OSGEO4W:

    For the Windows system, we can install both GRASS and QGIS within OSGEO4W environment.

    The OSGeo4W is a binary distribution of a broad set of open source geospatial software for Windows environments, including both GRASS GIS and QGIS.

    The OSGeo4W installer can be downloaded from here.

    Please use the advanced install option and keep the default selection in all pop up pages, except in the ‘select package page’.

    In the select package:

    • In the Desktop group, please select 1) grass: GRASS GIS 7.8; 2) qgis: QGIS DESKTOP; 3)qt5_tools:Qt5 tools (development); 4)saga:SAGA(…)

    • In the Libs group, please select 1)python3-geopandas; 2)python3-rtree; 3)python3-rasterstats

    We would suggest to

    • Install QGIS and GRASS outside the C/:Program Files. Better to install them into a folder path without space in the folder name.

    • Run the downloaded installation file

  2. Setup GRASS and QGIS python environment

    The python environment for QGIS and GRASS GIS in Windows can be set up by modifying the following basinmaker.bat.txt.

    • Please rename ‘basinmaker.bat.txt’ to ‘basinmaker.bat’.

    • Please change OSGEO4W_ROOT to your OSGEO4W installation folder at line 2.

    • Please change the grass78.* in line 8 and 10 to your GRASS GIS version number.

    • Please double check the paths defined in the basinmaker.bat file exist in your machine

    • Save the modified basinmaker.bat to a handy directory. Run basinmaker.bat every time before using basinmaker.

  3. Install BasinMaker (do not activate anaconda)

    >basinmaker.bat
Microsoft Windows [Version 10.0.19041.867]
(c) 2020 Microsoft Corporation. All rights reserved
>
>python -m pip install https://github.com/dustming/basinmaker/archive/master.zip

  4. Validate the GRASS and QGIS python environment

    • Please check if the python executable comes from the OSGeo4W installation folder by typing following commands after run basinmaker.bat. If the output is not similar to the output showed in following output block. Please go back to step 2 and check the basinmaker.bat file

    >where python
C:\OSGeo4W\apps\Python37\python.exe

    • Check if all dependent QGIS and GRASS libraries can be imported in current python environment by type following commands.

    >python
>>>from qgis.core import *
>>>import qgis
>>>from qgis.analysis import QgsNativeAlgorithms
>>>from qgis.PyQt.QtCore import *
>>>from qgis import processing
Application path not initialized
>>>from processing.core.Processing import Processing
>>>from processing.tools import dataobjects
>>>import grass.script as grass
>>>from grass.script import array as garray
>>>from grass.script import core as gcore
>>>import grass.script.setup as gsetup
>>>from grass.pygrass.modules.shortcuts import general as g
>>>from grass.pygrass.modules.shortcuts import raster as r
>>>from grass.pygrass.modules import Module
>>>quit()

  5. Install dependent packages

    python -m pip install simpledbf grass_session scipy joblib wget gdown
python -m pip install --upgrade pip
python -m pip install geopandas -U
python -m pip install rasterstats -U
  6. Install GRASS GIS addons

    Install following GRASS GIS addons:

    • r.accumulate

    • r.clip

    • r.stream.basins

    • r.stream.snap

    For new GRASS users, see how to install GRASS GIS addon here.

    If you want to learn how to use GRASS for more than BasinMaker, this site. may help you.

  7. Test validation

    • Please download the test data and scripts from here. and unzip it to a folder, the path of this folder will refer as path_test_data in following section. Then

    • run basinmaker.bat

    • Please ignore following output messages

      PyTables is not installed. No support for HDF output.

      SQLalchemy is not installed. No support for SQL output.

      Warnings

    cd path_test_data/test
python test_full_installation.py
(... some messages)
####################################
BasinMaker is successfully installed
####################################

  8. Users must run basinmaker.bat every time they wish to use functionalities from BasinMaker.