Tutorial 1: Setting up a Xanthos run

Set up configuration file

An example configuration file set to the default Penman-Monteith/ABCD/MRTM configuration is included here: examples/pm_abcd_mrtm.ini. The configuration parameters associated with each PET, runoff, and routing model option can be reviewed here: Available modules. To get started with the default configuration, set the following configuration variables to your local preferences:

In [PROJECT]...
RootDir = <the directory holding your input and output directories>

In [Runoff][abcd]...
TempMinFile = <the directory holding your example directory>/example/input/climate/tasmin_watch_monthly_degc_1991_2001.npy
PrecipitationFile = <the directory holding your example directory>/example/input/climate/pr_gpcc_watch_monthly_mmpermth_1991_2001.npy

In [Calibrate]...
observed =  <the directory holding your example directory>/example/input/calibration/vic_watch_basin_km3_1971_2001_monthly.csv
calib_out_dir = <a local directory of your choosing>

Required Project Level Configuration settings

Config tag:

[Project]

Variable	Description	Required
ProjectName	Name of the project that defines the name of the output directory; no spaces.	True
RootDir	Full path to the directory containing the input and output directories for the project.	True
InputFolder	Input directory name contained in the RootDir.	True
OutputFolder	Output directory name contained in the RootDir.	True
RefDir	Directory name where the reference data is contained in the input directory.	True
pet_dir	Directory name where the root PET module directories are kept in the inputs directory.	True
RunoffDir	Directory name where the root runoff module directories are kept in the inputs directory.	True
RoutingDir	Directory name where the root routing module directories are kept in the inputs directory.	True
DiagDir	Directory name where the diagnostics directory is contained in the input directory.	True
AccWatDir	Directory name where the accessible water input file directory is contained.	True
HydActDir	Directory name where the hydropower potential input file directory is contained.	True
HistFlag	If True, channel storage and soil moisture files are saved; if False, channel storage and soil moisture files are loaded when using the GWAM runoff module.	True
n_basin	The number of basins in the input data; integer.	True
StartYear	Start year of the run as an integer in YYYY format.	True
EndYear	End year of the run as an integer in YYYY format.	True
output_vars	Which variables to output, any of: 'pet' (potential evapotranspiration), 'aet' (actual evapotranspiration), 'q' (runoff), 'soilmoisture' (soil moisture), 'avgchflow' (average channel flow).	True
OutputFormat	The format to save the outputs in; 0 = NetCDF Classic, 1 = CSV, 2 = Matlab, 3 = Parquet.	True
OutputUnit	The unit to save the runoff outputs in; 0 = mm/time, 1 = km3/time, where time is either month or year.	True
OutputInYear	0 = output in month; 1 = aggregate into annual result.	True
AggregateRunoffBasin	Create output file that has runoff aggregated by basin. 0 = False, 1 = True.	True
AggregateRunoffCountry	Create output file that has runoff aggregated by country. 0 = False, 1 = True.	True
AggregateRunoffGCAMRegion	Create output file that has runoff aggregated by GCAM region. 0 = False, 1 = True.	True
PerformDiagnostics	1 = perform diagnostics, 0 = pass.	True
CreateTimeSeriesPlot	1 = create plots, 0 = pass.	True
CalculateDroughtStats	Default is 0 for False, 1 for True	True
CalculateAccessibleWater	1 = calculate accessible water, 0 = pass.	True
CalculateHydropowerPotential	1 = calculate hydropower potential, 0 = pass.	True
CalculateHydropowerActual	1 = calculate hydropower actual, 0 = pass.	True
Calibrate	1 = run ABCD runoff calibration module, 0 = pass.	True

Get Started with Xanthos

Set up Xanthos using the following steps:

1. Install Xanthos from GitHub using:

   python -m pip install git+https://github.com/JGCRI/xanthos.git

2. Download the example data using the following in a Python prompt:

   import xanthos
   
   # the directory that you want to download and extract the example data to
   data_dir = "<my data download location>"
   
   # download and unzip the package data to your local machine
   xanthos.get_package_data(data_dir)

3. Setup your configuration file (.ini). Examples are located in the "example" directory that you just downloaded. Be sure to change the following variables to represent the local path to your example data: RootDir, TempMinFile, PrecipitationFile.

4. To run Xanthos:

   import xanthos
   
   # the path and file name that my example configuration (.ini) file was downloaded to
   config_file = '<path to my example config file>/pm_abcd_mrtm.ini'
   
   # run Xanthos 
   xanthos.run_model(config_file)