Quick and Simple Way to Run Factorial Experiments

This guide demonstrates how to set up and run factorial experiments using apsimNGpy, pandas, and seaborn. Factorial experiments involve systematically varying multiple factors to observe their effects on outputs such as crop yield.

Setting Up the Environment

First, import the necessary libraries:

import pandas as pd
import seaborn as sns
sns.set_style('whitegrid')
from matplotlib import pyplot as plt
from apsimNGpy.core.base_data import load_default_simulations
from apsimNGpy.core.apsim import ApsimModel

Creating an Experiment

Load the default maize simulations and initialize APSIM:

# get path to the default simulations in APSIM
_apsim = load_default_simulations(crop='Maize', simulations_object=False)
# instantiate
apsim = ApsimModel(_apsim)
# same as:
apsim  = ApsimModel('Maize)

Create an experiment with permutation enabled:

apsim.create_experiment(permutation=True, verbose=False)  # Default is a permutation experiment

Adding Factors

Add nitrogen levels as a continuous factor:

apsim.add_factor(specification="[Fertilise at sowing].Script.Amount = 0 to 200 step 20", factor_name='Nitrogen')

Add population density as a categorical factor:

apsim.add_factor(specification="[Sow using a variable rule].Script.Population = 4, 10, 2, 7, 6",
                 factor_name='Population')

Running the Experiment

Execute the simulation and visualize results:

apsim.run(report_name='Report')
df = apsim.results
df[['population']] = pd.Categorical(['Population'])
sns.catplot(x='Nitrogen', y='Yield', hue='Population', data=df, kind='box')
plt.show()

Factorial Experiment with Cultivar Replacements

Hint

To conduct a factorial experiment involving cultivar modifications, a crop replacement must be added.

Load the maize simulations again and initialize APSIM:

_apsim = load_default_simulations(crop='Maize', simulations_object=False)
apsimC = ApsimModel(_apsim)

Create an experiment with permutation enabled:

apsimC.create_experiment(permutation=True, verbose=False)  # Default is a permutation experiment

Add nitrogen and population density factors:

apsimC.add_factor(specification="[Fertilise at sowing].Script.Amount = 0 to 200 step 20", factor_name='Nitrogen')
apsimC.add_factor(specification="[Sow using a variable rule].Script.Population = 4, 10, 2, 7, 6",
                  factor_name='Population')

Replace the crop with an alternative maize cultivar:

apsimC.add_crop_replacements(_crop='Maize')

Add a factor for radiation use efficiency (RUE):

apsimC.add_factor(specification='[Maize].Leaf.Photosynthesis.RUE.FixedValue = 1.0, 1.23, 4.3', factor_name='RUE')

Run the experiment and visualize the impact of RUE on yield:

apsimC.run()
sns.catplot(x='Nitrogen', y='Yield', hue='RUE', data=apsimC.results, kind='bar')
plt.show()

Conclusion.

This tutorial demonstrated how to set up and run factorial experiments using apsimNGpy. By systematically varying multiple factors (e.g., nitrogen levels, population density, and RUE), we can analyze their effects on the target variable effectively.

Note

⚠️ Note: The Experiment module, introduced in apsimNGpy v0.3.9.7, addresses recent structural changes in APSIM file structure changes. While the older create_experiment method in ApsimModel is retained for backward compatibility, users working with newer APSIM models should use the ExperimentManager class for building factorial designs. It offers full support for modern model experiment editing

The ExperimentManager API in apsimNGpy provides a high-level interface to build factorial experiments programmatically using APSIM. It is ideal for users who want to automate the creation of simulation treatments by varying input parameters or management scripts — all without manually editing .apsimx files.

Note

This feature is especially useful for agronomists and researchers running large design-of-experiment (DoE) simulations.

Quick Overview

The ExperimentManager class wraps an existing APSIM model and allows you to:

Clone and isolate a base simulation
Add multiple input factors (e.g., fertilizer rate, sowing density)
Generate permutations or combinations of those factors
Export the updated .apsimx file with fully configured experiments

Getting Started

First, create an Experiment object by loading a base model:

from apsimNGpy.core.experimentmanager import ExperimentManager

exp = ExperimentManager("Maize", out_path="Maize_experiment.apsimx")

Then initialize the experiment block:

exp.init_experiment(permutation=True)

Adding Input Factors

Each factor describes a script path and a set of values to assign in the experiment. You can add one or more factors like this:

exp.add_factor("[Manager Script].Script.Amount = 0 to 200 step 50")
exp.add_factor("[Sowing Rule].Script.RowSpacing = 100, 300, 600", factor_name="RowSpacing")

Finalizing the Experiment

Once all factors are defined, finalize the setup and save the modified model. Please note this is entirely optional, add_factor is a stand alone method, once you have finished adding factors, you can call the run to retrieve the results, without calling finalize. finalize is wa built as safe guard for immutability

exp.finalize()

This writes a new .apsimx file that contains a complete factorial experiment, ready to run in APSIM or via automation tools.

API Summary

ExperimentManager: Main entry point to create and manipulate factorial designs.
init_experiment(): Prepares the experiment node structure in the model.
add_factor(): Adds a new varying parameter or script-defined rule.
finalize(): Validates and commits the experiment structure to the model.