Getting started

Interactive usage

Niche Vlaanderen can be used interactively in Python. For interactive use, we recommend using the Jupyter notebook. This allows one to save documentation, code and results in the same file.

This file itself is a notebook, and if you want to reproduce our result this is possible:

Download the niche sourcecode (use the zip file).
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.
Activate the niche environment: activate niche (not necessary if you used the alternative install).
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.
Navigate your web browser to the getting_started.ipynb file (in the Files tab, which should be opened by default).
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.

Steps to create a Niche model

To calculate a Niche model one has to take the following steps:

Initialize the model (create a Niche object)
Add the different input grids (or constant values) to the model (set_input method)
Run the model (run method)
Optionally inspect the results using plot() and table.
Save the results (write method).

These steps are mirrored in the design of the Niche class which is given below.

Optionally the user can also create difference maps showing how much MHW/MLW has to change to allow a certain vegetation type. This is done using the deviation parameter of the run method.

Creating a simple NICHE model

For our first example, we will be creating a simple model, using only MHW, MLW and soil for the predictions.

The first step is importing the niche_vlaanderen module. For convenience, we will be importing as nv.



In [ ]:

    
import niche_vlaanderen as nv

Creating a niche object

Next we create a Niche object. This object will hold all the data and results for an analysis.



In [ ]:

    
simple = nv.Niche()

Adding input files

After initialization, we can add input layers to this object, using the set_input method.



In [ ]:

    
simple.set_input("mhw","../testcase/zwarte_beek/input/mhw.asc")
simple.set_input("mlw","../testcase/zwarte_beek/input/mlw.asc")
simple.set_input("soil_code","../testcase/zwarte_beek/input/soil_code.asc")

Running the model

These three input files are the only required for running a simple NICHE model. This means we can already run our model.



In [ ]:

    
simple.run(full_model=False)

Inspecting the model

After a model is run, we can inspect the results using the table method. Note that the values are given in ha. In the example below we also use the head function to show only the first five rows.



In [ ]:

    
simple.table.head()

The returned object is a Pandas dataframe which makes it easy to manipulate (for example calculating a crosstabulation, filtering, ...) or save it to a file. Below we present two examples which can be useful when working with these data. The first is saving the data to a csv file.



In [ ]:

    
simple.table.to_csv("demo.csv")

By using the pandas pivot_table method, we can create a summarized table. Note that only the first 5 rows are shown because we use the head function



In [ ]:

    
result = simple.table.pivot_table(index="vegetation", 
                            values="area_ha", 
                            columns="presence",
                            fill_value=0).head()

result

It is also possible to show actual grids using the plot method.



In [ ]:

    
simple.plot(11)
import matplotlib.pyplot as plt
%matplotlib inline
plt.show()

It is possible to give your model a name - this will be shown when plotting and will be used when writing the files.



In [ ]:

    
simple.name="scen_1"
simple.plot(11)

plt.show()

Saving the model

The model results can be saved to disk using the write function. As an argument, this takes the directory to which you want to save, _output_scen1 in our example. When saving a model, the log file, containing the model configuration, a summary table and all 28 vegetation grids will be saved. Note we specify the overwrite_files option so subsequent calls of the example will not raise an error



In [ ]:

    
simple.write("_output_scen1", overwrite_files=True)

Below you can see the list of files that is generated by this operation: There are the 28 vegetation grids (*.tif files), the summary table (summary.csv) and a logfile (log.txt). All files are prepended with the model name we set earlier.



In [ ]:

    
import os
os.listdir("_output_scen1")

Showing the model configuration

While using niche, it is always possible to view the configuration by typing the object name.



In [ ]:

    
simple

Note that this overview contains the same information as the logfile which we wrote before. Later on, we will show that this can be used as input when running Niche with a configuration file (either from [within Python](advanced_usage.ipynb#Using-config-files) or from the [command line](cli.rst)).

Running a full Niche model

A full Niche model requires more inputs that only mhw, mlw and soil_code. The full list can be found in the documentation. It is also possible to look at the minimal_input set. When trying to run a model without sufficient inputs, a warning will be generated.



In [ ]:

    
nv.niche.minimal_input()

If we add all the required values, we can run the full model. Note that it is possible to set a constant value instead of a complete grid



In [ ]:

    
full = nv.Niche()
path = "../testcase/zwarte_beek/input/"
full.set_input("mhw", path + "mhw.asc")
full.set_input("mlw", path + "mlw.asc")
full.set_input("soil_code", path + "soil_code.asc")
full.set_input("nitrogen_animal", 0)
full.set_input("inundation_acidity", path + "inundation.asc")
full.set_input("inundation_nutrient", path + "inundation.asc")
full.set_input("nitrogen_fertilizer",0)
full.set_input("minerality", path + "minerality.asc")
full.set_input("management", path + "management.asc")
full.set_input("nitrogen_atmospheric", 0)
full.set_input("msw", path + "msw.asc")
full.set_input("rainwater", 0)
full.set_input("seepage", path + "seepage.asc")
full.run()

We can look at the full model using the same table and plot functions as we used for the simple model.



In [ ]:

    
full.table.head()

Comparing to the simple model, one can observe that the area where a vegetation type can be present is always smaller than in the simple model.



In [ ]:

    
simple.table.head()

In the next tutorial, we will focus on more advanced methods for using the package, starting with the comparison of these two models.