Example Dataset for running STEMMUS-SCOPE

STEMMUS-SCOPE Example Dataset
authors: Yijian Zeng (y.zeng@utwente.nl), Bob Su(z.su@utwente.nl)

1. Example Input Dataset
Data required by the STEMMUS-SCOPE model can be sotred under your work directory with a folder named "input", wherein the example station dataset, named 'ExampleRun_Input_PyStemmusScope.zip' can be unzip. You will then get the example data for the example station named 'AR-SLu_2024-01-25-0911'. This folder includes:

- '*.dat' files: the forcing/driving data provided by PLUMBER2. Users are referred to (Ukkola, A. M., Abramowitz, G., and De Kauwe, M. G.: A flux tower dataset tailored for land model evaluation, Earth Syst. Sci. Data, 14, 449–461, https://doi.org/10.5194/essd-14-449-2022, 2022.).
 

- SoilProperty: the soil texture data and soil hydraulic parameters. Users are referred to (Montzka, C., Herbst, M., Weihermüller, L., Verhoef, A., and Vereecken, H.: A global data set of soil hydraulic properties and sub-grid variability of soil water retention and hydraulic conductivity curves, Earth Syst. Sci. Data, 9, 529–543, https://doi.org/10.5194/essd-9-529-2017, 2017.)

Below the directory explanations are from SCOPE documentation (https://scope-model.readthedocs.io/en/master/):

- directional: the observer’s zenith and azimuth angles.(only used for multi-angle simulations (if the option ‘directional’ is switched on in parameters).
- fluspect_parameters: absorption spectra of different leaf components are provided, according to PROSPECT 3.1, as well as - leafangles: example leaf inclination distribution data are provided.
- radiationdata: RTMo.m calculates spectra based on MODTRAN5 outputs (T-18 system).Note that in the input data (files as well as the spreadsheet), the broadband input radiation may be provided. SCOPE linearly scales the input spectra of the optical and the thermal domain in such a way that the spectrally integrated input shortwave and long-wave radiation matches with the measured values.
- soil_spectrum: the soil spectrum is provided. Note that it is also possible to simulate a soil reflectance spectrum with the BSM model. In that case, the values for the BSM model parameters are taken from the input data, and the archived spectra in this folder are not used.
- input_data.xlsx: the input to SCOPE model is provided. It provides parameter inputs for PROSPECT, leaf_biochemical, fluorescence, soil, canopy, aerodynamic, angles, photosynthetic temperature dependence functional parameters, etc.

Config file (AR-SLu_2024-01-25-0911_config.txt): it is a text file that sets the paths required by the model. For example, see config_file_crib.txt in this repository. This file includes:

- SoilPropertyPath: a path to soil texture data and soil hydraulic parameters.
- InputPath: this is the working/running directory of the model and should include the data of directional, fluspect_parameters, leafangles, radiationdata, soil_spectra, and input_data.xlsx.
- OutputPath: this is the base path to store outputs of the model. When the model runs, it creates sitename_timestamped directories under this path.
- ForcingPath: a path to the forcing/driving data. I.e. the Plumber2 dataset.
- Location: Location where the model should be run. Currently, the model runs at the site scale. For example, if we put AR-SLu here, the model runs at the AR-SLu site.
- StartTime: The start time of the model, in the ISO 8601 format. For example: 2001-01-01T00:00. Note that the time can only be defined in half hour increments. If you want the start time to be the first available data point of the forcing data, you can set StartTime to NA.
- EndTime: The end time of the model. Formatted the same way as the StartTime. For example: 2001-12-31T23:30. If you want the end time to be the last available data point of the forcing data, you can set EndTime to NA.

To edit the config file, open the file with a text editor and change the paths. The variable names e.g. SoilPropertyPath should not be changed. Also, note a / is required at the end of each line.

As explained above, the "InputPath" directory of the model is considered as the working/running directory and should include some data required by the model. As seen in the config file, the "InputPath" is now set as same as the "input" folder. This means that the "input" folder is treated as the model's working/running directory. However, it is possible to create a different working/running directory and set the "InputPath" to it. Then, you should copy the required data i.e. directional, fluspect_parameters, leafangles, radiationdata, soil_spectra, and input_data.xlsx to the working/running directory.

2. Example Output Dataset
After successfuly running the STEMMUS-SCOPE model, the output variables will be stored in '*.csv' format. After running a script, all these output will be then saved as a NetCDF file. In this case 'AR-SLu_2024-01-25-0911_STEMMUS_SCOPE.nc'.

- In the folder 'Parameters': it makes a copy of 'input_data.xlsx' as a '*.csv' file (for example, in this case 'input_data.xlsx_AR-SLu.csv'); and the version of SCOPE is stored in 'SCOPEversion.txt';

- output.mat: it stores all STEMMUS-SCOPE output variables in a '*.mat' format

- wlS.txt: it defines the spectral regions for SCOPE. see (https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/e91bea322f970f9e1763c34b435ac8982322764c/src/%2Bio/define_bands.m#L13)

- wlF.txt: spectral range for the chlorophyll fluorescnce (https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/e91bea322f970f9e1763c34b435ac8982322764c/src/%2Bio/define_bands.m#L19)