diff --git a/docs/getting_started.ipynb b/docs/getting_started.ipynb index 92bff144..99b0dac2 100644 --- a/docs/getting_started.ipynb +++ b/docs/getting_started.ipynb @@ -14,7 +14,7 @@ "\n", " * Download the [niche sourcecode](https://github.com/inbo/niche_vlaanderen/releases) (use the zip file).\n", " * Extract the file and navigate to the `docs` folder from the anaconda prompt. Make sure you also extract the testcases directory, as this contains the data we will be using.\n", - " * Activate the niche environment: `activate niche` (not necessary if you used the alternative install).\n", + " * Activate the niche environment: `conda activate niche` (not necessary if you used the alternative install).\n", " * Run Jupyter notebook: `jupyter notebook`. This should open a web page (similar or equal to http://localhost:8888 ) - check your anaconda prompt for a link if this is not the case.\n", " * Navigate your web browser to the `getting_started.ipynb` file (in the Files tab, which should be opened by default).\n", " * Any cell with code can be run by by pressing Ctrl+Enter. If you are unfamiliar with notebooks, you can take some time familiarizing yourself by taking the User interface tour from the `Help` menu.\n", diff --git a/docs/installation.rst b/docs/installation.rst index c2b76aa9..ddd1bd9c 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -5,7 +5,7 @@ Installation Windows ======= -The recommended way of installing niche on windows uses miniconda_ for installation. +The recommended way of installing niche_vlaanderen on windows uses miniconda_ for installation. The recommended version is `64 bit with Python 3.9`__. __ https://repo.anaconda.com/miniconda/Miniconda3-py39_4.12.0-Windows-x86_64.exe @@ -16,40 +16,50 @@ we will proceed installing niche_vlaanderen in its own environment. Start the `Anaconda prompt` from the start menu -Create an environment that will contain niche and its dependencies. +You will probably see something as: .. code-block:: shell - (C:\Users\johan\Miniconda3) C:\Users\johan> conda create --name niche + (C:\Users\myusername\Miniconda3) C:\Users\myusername> + OR + (base) C:\Users\myusername> -Activate the niche environment +Create an environment (called niche in this example) that will contain niche_vlaanderen and its dependencies: .. code-block:: shell - (C:\Users\johan\Miniconda3) C:\Users\johan> activate niche + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda create --name niche -And install niche and it's dependencies +Activate the niche environment: .. code-block:: shell - conda install pandas=1.5.3 pyyaml rasterio fiona - pip install niche_vlaanderen + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche + +You will see that `(C:\\Users\\myusername\\Miniconda3)`/`(base)` will change into `(niche)`. + +Now install the niche_vlaanderen package and its dependencies within the niche environment: + +.. code-block:: shell + + (niche) C:\Users\myusername> conda install pandas=1.5.3 pyyaml rasterio fiona + (niche) C:\Users\myusername> pip install niche_vlaanderen It is strongly recommended to install also `matplotlib` (otherwise plotting will not work) and `jupyter` notebook, which allows interactive usage from a web browser. .. code-block:: shell - conda install matplotlib jupyter + (niche) C:\Users\myusername> conda install matplotlib jupyter -You can verify the installation was successful by running the cli interface. +You can verify the installation was successful by running the command line interface. Note you must activate niche once more, because some changes were made during installation. .. code-block:: shell - (C:\Users\johan\Miniconda3) C:\Users\johan> activate niche - (niche) C:\Users\johan> niche --help + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche + (niche) C:\Users\myusername> niche --help Usage: niche [OPTIONS] CONFIG Command line interface to the NICHE vegetation model @@ -62,26 +72,29 @@ installation. Upgrading ========= -Existing installations of Niche can be updated using pip (run -from the Anaconda prompt. +Existing installations of niche_vlaanderen can be updated using pip (run +from the Anaconda prompt). .. code-block:: shell - pip install niche_vlaanderen --upgrade + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche + (niche) C:\Users\myusername> pip install niche_vlaanderen --upgrade + +Note you might need to update other packages. Installing a specific version ============================= -If you want to install a specific niche version, you can install using pip: +If you want to install a specific niche_vlaanderen version, you can install using pip: .. code-block:: shell - (C:\Users\johan\Miniconda3) C:\Users\johan> activate niche - (niche) C:\Users\johan> pip install niche_vlaanderen==1.0 + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche + (niche) C:\Users\myusername> pip install niche_vlaanderen==1.0 Alternative installation ======================== -It is possible to install niche without using an environment. This is currently not +It is possible to install niche_vlaanderen without using an environment. This is currently not the recommended installation as it requires setting an environment variable for opening some grid files. (See :ref:`missing_gcs` for instructions). @@ -100,27 +113,26 @@ will not work) and `jupyter` notebook, which allows interactive usage from a web Running niche ============= -Whenever you want to use niche (either from the command line or Python) you need +Whenever you want to use niche_vlaanderen (either from the command line or Python) you need to start from the `Anaconda prompt` (in the start menu) and activate the environment: .. code-block:: shell - (C:\Users\johan\Miniconda3) C:\Users\johan> activate niche + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche Optionally - Jupyter Notebook ============================= If you want to run niche_vlaanderen interactively, we recommend using a [jupyter notebook](http://jupyter.org/). -To run this, from the anaconda prompt do: +To run this, from the `Anaconda prompt` do: .. code-block:: default - (C:\Users\johan\Miniconda3) C:\Users\johan> activate niche - (niche) C:\Users\johan> jupyter notebook + (C:\Users\myusername\Miniconda3) C:\Users\myusername> conda activate niche + (niche) C:\Users\myusername> jupyter notebook -This should open a webbrowser pointing towards http://localhost:8888 . If you browser does not open, try looking for the -correct URL at the anaconda prompt. +This should open a webbrowser pointing towards http://localhost:8888 . If your browser does not open, try looking for the correct URL at the `Anaconda prompt`. The :doc:`tutorials` will use these jupyter notebooks, and are the best place to continue from here. diff --git a/docs/invoer.rst b/docs/invoer.rst index 612244a3..c46fcaac 100644 --- a/docs/invoer.rst +++ b/docs/invoer.rst @@ -67,7 +67,7 @@ De NICHE bodemkaart speelt een rol: Brongegevens ------------ Voor het aanmaken van deze ecologische NICHE bodemkaart kan er gebruik gemaakt worden van de Bodemkaart van België, van een gecorrigeerde bodemkaart (op basis van veldgegevens) of er kan gebruik gemaakt worden van een zelf aangemaakte bodemkaart. Er is een Vlaanderen dekkende NICHE bodemkaart voorhanden, waarin voor Vlaanderen de oorspronkelijke bodemcodes van de Belgische Bodemkaart werden omgezet naar de NICHE-codes via een bodemvertaalsleutel ( -`Callebaut et al. 2007 `_). Aan elke polygoon hangt dus de juiste NICHE bodemcode (zowel letter- als cijfercode). Deze NICHE bodemkaart is beschikbaar onder de vorm van `deze shapefile `_. Uit deze shapefile kan met gepaste GIS-bewerkingen het gewenste studiegebied geknipt worden en vervolgens verrasterd met de gewenste extent en resolutie. +`Callebaut et al. 2007 `_). Aan elke polygoon hangt dus de juiste NICHE bodemcode (zowel letter- als cijfercode). Deze NICHE bodemkaart is beschikbaar onder de vorm van `deze shapefile `_. Uit deze shapefile kan met gepaste GIS-bewerkingen het gewenste studiegebied geknipt worden en vervolgens verrasterd met de gewenste extent en resolutie. De procedure om eigen bodemgegevens of een eigen bodemkaart te gebruiken wordt beschreven in het NICHE rapport ( `Callebaut et al. 2007 `_, hoofdstukken 3.3 *Vertaalsleutel bodemkaart* en 3.4 *Vertaalsleutel bodemprofielen*, met een gedetailleerde beschrijving van de verschillende NICHE bodemtypen, en de procedure om codes van de Bodemkaart van België of profielbeschrijvingen om te zetten naar de NICHE-codes). diff --git a/docs/validation.ipynb b/docs/validation.ipynb index e4b6b1e5..3f2e17de 100644 --- a/docs/validation.ipynb +++ b/docs/validation.ipynb @@ -471,11 +471,11 @@ "\n", "- area_effective: total area in ha with a given vegetation type, taking into account the proportion of the vegetation within each shape (pHAB)\n", "- nonpot: total area with actual presence according to the vegetation map, but without potential presence according to niche\n", - "- nonpot_phab: total area with actual presence according to the vegetation map, but without potential presence according to niche (taking pHAB into account)\n", + "- nonpot_phab: total area with actual presence according to the vegetation map, but without potential presence according to niche (taking pHAB into account). We recommend using nonpot_phab instead of nonpot.\n", "- pot: total area with actual presence according to the vegetation map and with potential presence according to niche\n", "- polygon count: number of shapes with the actual vegetation type according to the vegetation map. If there are few polygons, the final score should be taken with caution.\n", "- score: proportion of the total area with potential presence according to niche, compared to the total area of polygons with presence of a vegetation according to the vegetation map\n", - "- score_phab: proportion of the total area with potential presence according to niche, compared to the actual area of a vegetation type according to the vegetation map (i.e. taking pHAB into account)\n", + "- score_phab: proportion of the total area with potential presence according to niche, compared to the actual area of a vegetation type according to the vegetation map (i.e. taking pHAB into account). We recommend using score_phab instead of score.\n", "\n", "\n", "**Intermediate tables** giving values for each shape can be retrieved by their names:\n", @@ -485,11 +485,13 @@ "* area_nonpot: area with actual presence according to the vegetation map, but without potential presence according to niche\n", "* area_nonpot_phab: area with actual presence according to the vegetation map, but without potential presence according to niche (taking pHAB into account)\n", " * calculated as: If([area_effective]>[area_pot];[area_effective]-[area_pot];0)\n", + " * Note we recommend using area_nonpot_phab instead of area_nonpot.\n", "* area_pot: area with actual presence according to the vegetation map and with potential presence predicted by niche\n", "* area_pot_perc: proportion (%) of the area with correct predicted area (not taking into account pHAB)\n", " * calculated as: 100*[area_pot]/ ([area_pot]+[area_nonpot])\n", "* area_pot_perc_phab: proportion (%) of the area with correct predicted area (taking into account pHAB)\n", - " * calculated as: If([area_pot]<[area_effective];100*[ area_pot]/([area_effective]);100)" + " * calculated as: If([area_pot]<[area_effective];100*[ area_pot]/([area_effective]);100)\n", + " * Note we recommend using area_pot_perc_phab instead of area_pot_perc." ] }, {