Protocol Modules

Configuration management for ophthalmic treatment protocol simulations.

This module handles loading and merging configuration files for simulation runs, including protocol definitions, parameter sets, and simulation settings.

Key Components

SimulationConfig : Dataclass for storing simulation configuration ConfigurationManager : Main class for loading and merging configurations

Configuration Files

  • base_parameters.yaml : Common parameters for all protocols

  • protocol_definitions/ : Protocol-specific definitions

  • parameter_sets/ : Protocol-specific parameters

  • simulation_configs/ : Complete simulation configurations

Examples

>>> manager = ConfigurationManager()
>>> config = manager.load_simulation_config('test_simulation')
>>> full_config = manager.get_full_configuration('test_simulation')
class protocols.config_parser.SimulationConfig(name, protocol_agent, protocol_type, parameter_set, simulation_type, duration_days, num_patients, random_seed, save_results, database, plots, verbose, resources=None)[source]

Bases: object

Configuration for a simulation run.

Variables:

  • name (str) – Name of the simulation configuration

  • protocol_agent (str) – Name of the treatment agent (e.g., ‘Aflibercept’)

  • protocol_type (str) – Type of protocol (e.g., ‘standard’, ‘intensive’)

  • parameter_set (str) – Name of parameter set to use

  • simulation_type (str) – Type of simulation (‘abs’ or ‘des’)

  • duration_days (int) – Duration of simulation in days

  • num_patients (int) – Number of patients to simulate

  • random_seed (int) – Random seed for reproducibility

  • save_results (bool) – Whether to save results to database

  • database (str) – Database path/name for results

  • plots (bool) – Whether to generate plots

  • verbose (bool) – Enable verbose output

  • resources (Dict[str, Any], optional) – Additional resource definitions

Parameters:

  • name (str)

  • protocol_agent (str)

  • protocol_type (str)

  • parameter_set (str)

  • simulation_type (str)

  • duration_days (int)

  • num_patients (int)

  • random_seed (int)

  • save_results (bool)

  • database (str)

  • plots (bool)

  • verbose (bool)

  • resources (Dict[str, Any])

name: str
protocol_agent: str
protocol_type: str
parameter_set: str
simulation_type: str
duration_days: int
num_patients: int
random_seed: int
save_results: bool
database: str
plots: bool
verbose: bool
resources: Dict[str, Any] = None
__init__(name, protocol_agent, protocol_type, parameter_set, simulation_type, duration_days, num_patients, random_seed, save_results, database, plots, verbose, resources=None)
Parameters:

  • name (str)

  • protocol_agent (str)

  • protocol_type (str)

  • parameter_set (str)

  • simulation_type (str)

  • duration_days (int)

  • num_patients (int)

  • random_seed (int)

  • save_results (bool)

  • database (str)

  • plots (bool)

  • verbose (bool)

  • resources (Dict[str, Any])

Return type:

None

class protocols.config_parser.ConfigurationManager(base_path='protocols')[source]

Bases: object

Parameters:

base_path (str)

__init__(base_path='protocols')[source]
Parameters:

base_path (str)

load_simulation_config(config_name)[source]

Load a simulation configuration from YAML.

Parameters:

config_name (str) – Name of configuration file (without .yaml extension)

Returns:

Configuration dataclass instance

Return type:

SimulationConfig

Examples

>>> manager = ConfigurationManager()
>>> config = manager.load_simulation_config('test_simulation')
>>> print(config.protocol_agent)
'Aflibercept'
get_full_configuration(config_name)[source]

Get complete merged configuration for a simulation.

Combines: - Simulation configuration - Protocol definition - Parameter sets - Clinical model parameters (if present)

Parameters:

config_name (str) – Name of configuration file (without .yaml extension)

Returns:

Dictionary containing all configuration components with keys: - ‘config’: SimulationConfig - ‘protocol’: Protocol definition - ‘parameters’: Merged parameters

Return type:

Dict[str, Any]

Examples

>>> manager = ConfigurationManager()
>>> full_config = manager.get_full_configuration('test_simulation')
>>> print(full_config['parameters']['injection_interval_weeks'])
4

Protocol configuration parser for macular simulation.

This module handles loading and parsing protocol configuration files (YAML format) into structured Python objects. It provides validation and type conversion for:

  • Protocol definitions (treatment phases, visit types, decision criteria)

  • Parameter sets (vision, treatment response, disease progression parameters)

  • Simulation configurations (protocol selection, patient counts, duration)

Key Classes

ProtocolParser: Main class for loading and validating protocol configurations SimulationConfig: Container for complete simulation configuration

Examples

Load a simulation configuration: >>> parser = ProtocolParser() >>> config = parser.load_simulation_config(“test_simulation”) >>> print(config.protocol.protocol_name) “Test Protocol”

Validate a protocol definition: >>> protocol = parser._load_protocol_definition(“eylea”, “standard”) >>> protocol.validate() True

class protocols.protocol_parser.SimulationConfig(**kwargs)[source]

Bases: object

Container for complete simulation configuration.

This class holds all configuration parameters needed to run a simulation, including protocol definitions, parameter sets, and simulation settings.

Variables:

  • name (str) – Name of the simulation configuration

  • protocol_agent (str) – Name of the treatment agent (e.g. “eylea”)

  • protocol_type (str) – Type of protocol (e.g. “standard”, “intensive”)

  • parameter_set (str) – Name of parameter set to use

  • simulation_type (str) – Type of simulation (“abs” or “des”)

  • duration_days (int) – Simulation duration in days

  • num_patients (int) – Number of patients to simulate

  • random_seed (int) – Random seed for reproducibility

  • save_results (bool) – Whether to save results to database

  • database (str) – Database path/connection string

  • plots (bool) – Whether to generate plots

  • verbose (bool) – Verbose output flag

  • start_date (str) – Simulation start date (YYYY-MM-DD)

  • description (str) – Description of simulation

  • protocol (Optional[TreatmentProtocol]) – Loaded protocol definition

  • parameters (Optional[Dict[str, Any]]) – Merged parameter set including: - vision parameters - treatment response parameters - disease progression parameters - resource parameters

name: str
protocol_agent: str
protocol_type: str
parameter_set: str
simulation_type: str
duration_days: int
num_patients: int
random_seed: int
save_results: bool
database: str
plots: bool
verbose: bool
start_date: str
description: str
protocol: Optional[TreatmentProtocol] = None
parameters: Optional[Dict[str, Any]] = None
__init__(**kwargs)[source]

Initialize configuration with provided kwargs.

Parameters:

**kwargs (dict) – Configuration parameters as keyword arguments

class protocols.protocol_parser.ProtocolParser(base_path='protocols')[source]

Bases: object

Parser for protocol configurations that creates protocol objects.

This class handles loading and validating protocol configuration files, including: - Protocol definitions (phases, visit types, decision criteria) - Parameter sets (vision, treatment, disease parameters) - Simulation configurations

Parameters:

base_path (str, optional) – Base path for protocol files (default: “protocols”)

load_simulation_config(config_name)[source]

Load complete simulation configuration

Parameters:

config_name (str)

Return type:

SimulationConfig

get_full_configuration(config_name)[source]

Get configuration with protocol objects and parameters

Parameters:

config_name (str)

Return type:

Dict[str, Any]

__init__(base_path='protocols')[source]
Parameters:

base_path (str)

load_simulation_config(config_name)[source]

Load and validate a simulation configuration from YAML file.

Parameters:

config_name (str) – Name of configuration file (without .yaml extension)

Returns:

Configured simulation settings with loaded protocol

Return type:

SimulationConfig

Raises:

ValueError – If configuration is invalid or validation fails

Examples

>>> parser = ProtocolParser()
>>> config = parser.load_simulation_config("test_simulation")
>>> print(config.protocol.protocol_name)
"Test Protocol"
get_full_configuration(config_name)[source]

Get complete validated configuration including protocol objects and parameters.

Parameters:

config_name (str) – Name of configuration file (without .yaml extension)

Returns:

Dictionary containing: - “config”: SimulationConfig object - “protocol”: TreatmentProtocol object - “parameters”: Merged parameter dictionary

Return type:

Dict[str, Any]

Raises:

ValueError – If configuration is invalid or validation fails

Examples

>>> parser = ProtocolParser()
>>> full_config = parser.get_full_configuration("test_simulation")
>>> print(full_config["protocol"].phases["loading"].duration_weeks)
12
protocols.protocol_parser.load_protocol(config_name)[source]

Legacy function to load protocol configuration (deprecated).

Parameters:

config_name (str) – Name of configuration file (without .yaml extension)

Returns:

Same as get_full_configuration()

Return type:

Dict[str, Any]

Note

This exists for backwards compatibility. New code should use ProtocolParser.get_full_configuration() directly.