refactor(class): renamed Trial to Runner, run_trial() to run_reps(), trial to experiment, trial_results_df to run_results_df, etc.

Author: amyheather

README.md

@@ -184,10 +184,12 @@ This section describes the purposes of each class in the simulation.
     * `generate_patient_arrivals()` to handle patient creation, then sending them on to `attend_clinic()`.
     * `interval_audit()` to record utilisation and wait times at specified intervals during the simulation.
 
-**Trial Class Usage:**
+**Runner Class Usage:**
 
-* **Single Run:** Use `trial.run_single()` to execute a single model run.
-* **Multiple Runs:** Use `trial.run_trial()` to perform multiple replications of the model.
+Having set up `experiment = Runner()`...
+
+* **Single Run:** Use `experiment.run_single()` to execute a single model run.
+* **Multiple Runs:** Use `experiment.run_reps()` to perform multiple replications of the model.
 
 <br>
 

docs/hsma_changes.md

@@ -132,9 +132,9 @@ param.patient_inter = 10
 model = Model(param)
 ```
 
-## Saving trial results
+## Saving replication results
 
-To save trial-level results in the HSMA models, an empty dataframe is initialised during the __init__ method of the `Trial` class.
+To save results from each run in the HSMA models, an empty dataframe is initialised during the __init__ method of the `Trial` class (equivalent to the `Runner` class in this template).
 
 ```
 self.df_trial_results = pd.DataFrame()
@@ -164,7 +164,7 @@ In the template, results are instead saved as a dictionary into a list as the ru
 Also, some of the calculations have been performed directly during the `run_single()` method, instead of from a seperate method `calculate_run_results()`. This is to help simplify the code, as it makes clear how each metric was calculated in one place, rather than needing to refer elsewhere.
 
 ```
-trial_results = {
+run_results = {
     'run_number': run,
     'scenario': self.param.scenario_name,
     'arrivals': len(patient_results),
@@ -176,7 +176,7 @@ trial_results = {
 
 ...
 
-self.trial_results_df = pd.DataFrame(trial_results_list)
+self.run_results_df = pd.DataFrame(run_results_list)
 ```
 
 ## Extra features

images/model_structure.drawio

@@ -67,7 +67,7 @@
    "outputs": [],
    "source": [
     "# Import required packages\n",
-    "from simulation.model import Defaults, Trial\n",
+    "from simulation.model import Defaults, Runner\n",
     "import os\n",
     "import time"
    ]
@@ -131,9 +131,9 @@
     "param.scenario_name = 0\n",
     "param.cores = 1\n",
     "\n",
-    "# Run the trial\n",
-    "trial = Trial(param)\n",
-    "trial.run_trial()"
+    "# Run the replications\n",
+    "experiment = Runner(param)\n",
+    "experiment.run_reps()"
    ]
   },
   {
@@ -286,8 +286,8 @@
    ],
    "source": [
     "# Patient-level results\n",
-    "display(trial.patient_results_df)\n",
-    "trial.patient_results_df.to_csv(\n",
+    "display(experiment.patient_results_df)\n",
+    "experiment.patient_results_df.to_csv(\n",
     "    os.path.join(tests, 'patient.csv'), index=False)"
    ]
   },
@@ -396,10 +396,10 @@
     }
    ],
    "source": [
-    "# Trial-level results\n",
-    "display(trial.trial_results_df)\n",
-    "trial.trial_results_df.to_csv(\n",
-    "    os.path.join(tests, 'trial.csv'), index=False)"
+    "# Run results\n",
+    "display(experiment.run_results_df)\n",
+    "experiment.run_results_df.to_csv(\n",
+    "    os.path.join(tests, 'run.csv'), index=False)"
    ]
   },
   {
@@ -577,8 +577,8 @@
    ],
    "source": [
     "# Interval audit results\n",
-    "display(trial.interval_audit_df)\n",
-    "trial.interval_audit_df.to_csv(\n",
+    "display(experiment.interval_audit_df)\n",
+    "experiment.interval_audit_df.to_csv(\n",
     "    os.path.join(tests, 'interval.csv'), index=False)"
    ]
   },
@@ -667,8 +667,8 @@
    ],
    "source": [
     "# Overall results\n",
-    "display(trial.overall_results_df)\n",
-    "trial.overall_results_df.to_csv(\n",
+    "display(experiment.overall_results_df)\n",
+    "experiment.overall_results_df.to_csv(\n",
     "    os.path.join(tests, 'overall.csv'), index=True)"
    ]
   },

images/model_structure.png

@@ -22,20 +22,20 @@
     more details.
 
 Typical usage example:
-    trial = Trial(param=Defaults())
-    trial.run_trial()
-    print(trial.trial_results_df)
+    experiment = Runner(param=Defaults())
+    experiment.run_reps()
+    print(experiment.run_results_df)
 """
 
 from joblib import Parallel, delayed
-from simulation.logging import SimLogger
 import numpy as np
 import pandas as pd
 import scipy.stats as st
 import simpy
+from simulation.logging import SimLogger
 
 
-class Defaults():
+class Defaults:
     """
     Default parameters for simulation.
 
@@ -433,25 +433,28 @@ def run(self):
         self.results_list = [x.__dict__ for x in self.patients]
 
 
-class Trial:
+class Runner:
     """
-    Manages multiple simulation runs.
+    Run the simulation.
+
+    Manages simulation runs, either running the model once or multiple times
+    (replications).
 
     Attributes:
         param (Defaults):
             Simulation parameters.
         patient_results_df (pandas.DataFrame):
             Dataframe to store patient-level results.
-        trial_results_df (pandas.DataFrame):
-            Dataframe to store trial-level results.
+        run_results_df (pandas.DataFrame):
+            Dataframe to store results from each run.
         interval_audit_df (pandas.DataFrame):
             Dataframe to store interval audit results.
         overall_results_df (pandas.DataFrame):
-            Dataframe to store average results from runs of the trial.
+            Dataframe to store average results from across the runs.
     """
     def __init__(self, param):
         '''
-        Initialise a new instance of the trial class.
+        Initialise a new instance of the Runner class.
 
         Arguments:
             param (Defaults):
@@ -461,7 +464,7 @@ def __init__(self, param):
         self.param = param
         # Initialise empty dataframes to store results
         self.patient_results_df = pd.DataFrame()
-        self.trial_results_df = pd.DataFrame()
+        self.run_results_df = pd.DataFrame()
         self.interval_audit_df = pd.DataFrame()
         self.overall_results_df = pd.DataFrame()
 
@@ -475,8 +478,8 @@ def run_single(self, run):
 
         Returns:
             dict:
-                A dictionary containing the patient-level results, trial-level
-                results, and interval audit results.
+                A dictionary containing the patient-level results, results
+                from each run, and interval audit results.
         """
         # Run model
         model = Model(param=self.param, run_number=run)
@@ -486,8 +489,8 @@ def run_single(self, run):
         patient_results = pd.DataFrame(model.results_list)
         patient_results['run'] = run
 
-        # Create dictionary recording the trial-level results
-        trial_results = {
+        # Create dictionary recording the run results
+        run_results = {
             'run_number': run,
             'scenario': self.param.scenario_name,
             'arrivals': len(patient_results),
@@ -504,16 +507,15 @@ def run_single(self, run):
 
         return {
             'patient': patient_results,
-            'trial': trial_results,
+            'run': run_results,
             'interval_audit': interval_audit_df
         }
 
-    def run_trial(self):
+    def run_reps(self):
         """
         Execute a single model configuration for multiple runs/replications.
 
-        This is known as a trial, experiment, batch or scenario. These can be
-        run sequentially or in parallel.
+        These can be run sequentially or in parallel.
         """
         # Sequential execution
         if self.param.cores == 1:
@@ -528,28 +530,28 @@ def run_trial(self):
         # Seperate results from each run into appropriate lists
         patient_results_list = [
             result['patient'] for result in all_results]
-        trial_results_list = [
-            result['trial'] for result in all_results]
+        run_results_list = [
+            result['run'] for result in all_results]
         interval_audit_list = [
             result['interval_audit'] for result in all_results]
 
         # Convert lists into dataframes
         self.patient_results_df = pd.concat(patient_results_list,
                                             ignore_index=True)
-        self.trial_results_df = pd.DataFrame(trial_results_list)
+        self.run_results_df = pd.DataFrame(run_results_list)
         self.interval_audit_df = pd.concat(interval_audit_list,
                                            ignore_index=True)
 
-        # Calculate average results and uncertainty from across all trials
+        # Calculate average results and uncertainty from across all runs
         uncertainty_metrics = {}
-        trial_col = self.trial_results_df.columns
+        run_col = self.run_results_df.columns
 
-        # Loop through the trial-level performance measure columns
+        # Loop through the run performance measure columns
         # Calculate mean, standard deviation and 95% confidence interval
-        for col in trial_col[~trial_col.isin(['run_number', 'scenario'])]:
+        for col in run_col[~run_col.isin(['run_number', 'scenario'])]:
             uncertainty_metrics[col] = dict(zip(
                 ['mean', 'std_dev', 'lower_95_ci', 'upper_95_ci'],
-                summary_stats(self.trial_results_df[col])
+                summary_stats(self.run_results_df[col])
             ))
         # Convert to dataframe
         self.overall_results_df = pd.DataFrame(uncertainty_metrics)

notebooks/analysis.ipynb

@@ -12,7 +12,7 @@
 
 """
 
-from simulation.model import Defaults, Trial
+from simulation.model import Defaults, Runner
 import pandas as pd
 from pathlib import Path
 
@@ -34,26 +34,26 @@ def test_reproduction():
     param.scenario_name = 0
     param.cores = 1
 
-    # Run the trial
-    trial = Trial(param)
-    trial.run_trial()
+    # Run the replications
+    experiment = Runner(param)
+    experiment.run_reps()
 
     # Compare patient-level results
     exp_patient = pd.read_csv(
         Path(__file__).parent.joinpath('exp_results/patient.csv'))
-    pd.testing.assert_frame_equal(trial.patient_results_df, exp_patient)
+    pd.testing.assert_frame_equal(experiment.patient_results_df, exp_patient)
 
-    # Compare trial-level results
-    exp_trial = pd.read_csv(
-        Path(__file__).parent.joinpath('exp_results/trial.csv'))
-    pd.testing.assert_frame_equal(trial.trial_results_df, exp_trial)
+    # Compare run results
+    exp_run = pd.read_csv(
+        Path(__file__).parent.joinpath('exp_results/run.csv'))
+    pd.testing.assert_frame_equal(experiment.run_results_df, exp_run)
 
     # Compare interval audit results
     exp_interval = pd.read_csv(
         Path(__file__).parent.joinpath('exp_results/interval.csv'))
-    pd.testing.assert_frame_equal(trial.interval_audit_df, exp_interval)
+    pd.testing.assert_frame_equal(experiment.interval_audit_df, exp_interval)
 
     # Compare overall results
     exp_overall = pd.read_csv(
         Path(__file__).parent.joinpath('exp_results/overall.csv'), index_col=0)
-    pd.testing.assert_frame_equal(trial.overall_results_df, exp_overall)
+    pd.testing.assert_frame_equal(experiment.overall_results_df, exp_overall)