VECTRI Hands-On: Configuring Model Parameters¶

What you'll learn:

• Configure model parameters using command line (-v)
• Use vectri.options file for parameter management
• Understand parameter override order
• Run sensitivity experiments across different parameter categories
• Verify parameter changes in output files

This hands-on guide shows how to configure, override, and test model parameters in VECTRI using:

• Command line input (-v)
• vectri.options file

It also provides mini-experiments to change a parameter and observe the effect across:

• Simulation parameters
• Vector / Parasite (disease) parameters
• Hydrology parameters
• Host / Population parameters
• Intervention parameters

0) Assumptions & Example Files¶

You have a run directory containing tutorial-like inputs such as:

If needed, create an input folder:

mkdir -p input

1) The Three Ways to Control Parameters¶

The manual summarizes 3 ways:

This guide focuses on methods (1) and (2).

2) Method A — Command Line Input (-v)¶

2.1 Syntax¶

Use the -v option with a comma-separated string:

vectri -v "param1=val,param2=val"

Example used in initialization:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "nloopspinup=3,nlenspinup=365" -o out_spinup_test.nc

2.2 Confirm Your Settings Were Applied¶

After the run, check the global attributes:

ncdump -h out_spinup_test.nc | grep -i spinup

You should see the parameter values in the global attributes.

3) Method B — vectri.options File¶

3.1 Where It Lives¶

The file should be placed at:

./input/vectri.options

Create the directory:

mkdir -p input

Create and open the file:

nano input/vectri.options

Or use your preferred editor:

vi input/vectri.options

3.2 Format¶

You can list parameters either:

• Comma-separated, or
• One per line (easiest to read)

Example (one per line):

nloopspinup=3
nlenspinup=365

Example (comma-separated):

nloopspinup=3,nlenspinup=365

Run using the file:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -o out_options_file_test.nc

3.3 Warning from the Manual¶

ncdump -h out_options_file_test.nc | grep -i spinup

4) Override Order (Important)¶

The manual explains:

• VECTRI builds a namelist where it loads:
• vectri.options values first
• then command line -v values

So if you specify the same parameter twice, -v wins.

4.1 Quick Demonstration¶

Put this in input/vectri.options:

nloopspinup=1

Then run:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "nloopspinup=3" -o out_override_demo.nc

Verify the override:

ncdump -h out_override_demo.nc | grep -i nloopspinup

You should see 3 (the command-line value, not the file value).

5) Parameter Tables¶

These defaults apply to An. gambiae and Plas. falciparum unless you switch vector/disease modes.

5.1 Simulation Parameters¶

5.2 Vector Parameters¶

5.3 Disease (Parasite/Host Infection) Parameters¶

5.4 Hydrology Parameters¶

5.5 Population / Host Parameters¶

5.6 Intervention Parameters¶

6) Change a Parameter and See the Effect (Mini-Labs)¶

The goal here is not to produce definitive epidemiological conclusions, but to help you verify that your configuration workflow works.

6.1 Baseline Run¶

Create output directories:

mkdir -p outputs logs

Run baseline simulation:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -o outputs/base.nc -z logs/base.log

Record defaults stored in the output:

ncdump -h outputs/base.nc | head -n 200

6.2 Lab A — Toy Temperature Increase¶

Use rtemperature_offset:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rtemperature_offset=1.0" -o outputs/temp_plus1K.nc -z logs/temp_plus1K.log

Confirm the parameter was applied:

ncdump -h outputs/temp_plus1K.nc | grep -i rtemperature_offset

6.3 Lab B — Toy Rainfall Change¶

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rrainfall_factor=1.2" -o outputs/rain_x1p2.nc -z logs/rain_x1p2.log

6.4 Lab C — Vector Biting Intensity¶

Change rbiteratio:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rbiteratio=0.8" -o outputs/bite_ratio_0p8.nc -z logs/bite_ratio_0p8.log

6.5 Lab D — Host Clearance¶

Change rhostclear:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rhostclear=10" -o outputs/hostclear_10.nc -z logs/hostclear_10.log

6.6 Lab E — Hydrology Sensitivity¶

Change wperm_default:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "wperm_default=1e-4" -o outputs/wperm_1e-4.nc -z logs/wperm_1e-4.log

6.7 Lab F — Intervention Decay¶

Change rbednet_tau:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rbednet_tau=700" -o outputs/bednet_tau_700.nc -z logs/bednet_tau_700.log

7) Checking Differences in Outputs (Quick Patterns)¶

Because output variable names can vary, start by listing variables:

import xarray as xr

ds = xr.open_dataset("outputs/base.nc")
print(list(ds.data_vars))

7.1 Compute Simple Global Means¶

import xarray as xr

base = xr.open_dataset("outputs/base.nc")
test = xr.open_dataset("outputs/temp_plus1K.nc")

common = sorted(set(base.data_vars).intersection(test.data_vars))
v = common[0] if common else None

print("Common variable used for demo:", v)

if v:
    print("Base mean:", float(base[v].mean()))
    print("Test mean:", float(test[v].mean()))

Save as compare_outputs.py:

python compare_outputs.py

8) Using vectri.options for a Structured Experiment Set¶

If you plan a block of experiments, set a "default" configuration:

cp -f vectri_calibrated.options input/vectri.options 2>/dev/null || true

Edit the options file:

nano input/vectri.options

Add, for example:

nloopspinup=2
nlenspinup=365
rrainfall_factor=1.0
rtemperature_offset=0.0

Run with file defaults:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -o outputs/options_default.nc

Then override one thing on the command line:

$VECTRI/vectri -c example_sys5.nc -d example_data.nc -v "rrainfall_factor=1.1" -o outputs/options_plus_rain.nc

This is the "mix-n-match" workflow described in the manual.

9) Practical Tips for Teaching & Reproducibility¶

ncdump -h outputs/your_run.nc | grep -i your_param

10) Summary¶

You now have a working pattern to:

📝 Exercises¶

Exercise 1: Parameter Verification¶

1. Run a simulation with a custom parameter using -v
2. Verify the parameter appears in the output global attributes
3. Compare with the default value

Exercise 2: Options File Workflow¶

1. Create an input/vectri.options file with 3–4 parameters
2. Run a simulation using the file
3. Override one parameter using -v
4. Verify the override worked

Exercise 3: Temperature Sensitivity¶

1. Run baseline simulation
2. Run with rtemperature_offset=2.0
3. Compare EIR or vector density between runs

Exercise 4: Hydrology Experiment¶

1. Run baseline
2. Run with wperm_default=1e-5 and wperm_default=1e-3
3. Compare pond fraction and larval density

🔗 Additional Resources¶

• VECTRI Documentation
• VECTRI Manual (PDF)
• VECTRI Command Line Tutorial