stimuli_data

 1"""
 2This module defines the StimuliData class, responsible for managing the names
 3or identifiers assigned to the substances associated with each valve.
 4
 5It provides a simple dictionary-based storage for these names and methods to
 6update them based on GUI input and retrieve their current values. It also
 7includes a helper method for pairing stimuli names.
 8"""
 9
10import logging
11
12logger = logging.getLogger(__name__)
13
14
15class StimuliData:
16    """
17    Manages the names or identifiers associated with stimuli delivered by each valve.
18
19    This class holds a dictionary mapping a standardized key (e.g., "Valve 1 Substance")
20    to the user-defined name for the substance in that valve (e.g., "Quinine", "Water").
21    It facilitates updating these names from the GUI and retrieving them when needed,
22    for example, during schedule generation or data logging.
23
24    Attributes
25    ----------
26    - **`stimuli_vars`** (*dict[str, str]*): Dictionary storing the substance name for each valve.
27        Keys are formatted like "Valve X Substance", and values are the user-defined names.
28
29    Methods
30    -------
31    - `update_model`(...)
32        Updates the substance name in `stimuli_vars` for a given valve based on GUI input.
33    - `get_default_value`(...)
34        Retrieves the current substance name for a given valve key.
35    """
36
37    def __init__(self) -> None:
38        """
39        Initializes the StimuliData object.
40
41        Creates the `stimuli_vars` dictionary and populates it with default
42        placeholder names for each of the 8 possible valves currently supported (e.g., "Valve 1 Substance").
43        """
44        self.stimuli_vars = {
45            f"Valve {1} Substance": "Valve 1 Substance",
46            f"Valve {2} Substance": "Valve 2 Substance",
47            f"Valve {3} Substance": "Valve 3 Substance",
48            f"Valve {4} Substance": "Valve 4 Substance",
49            f"Valve {5} Substance": "Valve 5 Substance",
50            f"Valve {6} Substance": "Valve 6 Substance",
51            f"Valve {7} Substance": "Valve 7 Substance",
52            f"Valve {8} Substance": "Valve 8 Substance",
53        }
54
55    def update_model(self, variable_name: str, value: str | None) -> None:
56        """
57        Updates the stored substance name for a specific valve.
58
59        Checks if the provided `variable_name` exists as a key in the
60        `stimuli_vars` dictionary. If it exists and the `value` is not None,
61        it updates the dictionary entry with the new name.
62
63        Parameters
64        ----------
65        - **variable_name** (*str*): The key identifying the valve whose substance name is being updated (e.g., "Valve 3 Substance").
66        - **value** (*str | None*): The new substance name (string) provided by the user, or None if the input was empty/invalid.
67        """
68        if value is not None:
69            if variable_name in self.stimuli_vars.keys():
70                self.stimuli_vars[variable_name] = value
71
72    def get_default_value(self, variable_name: str) -> str:
73        """
74        Retrieves the current substance name associated with a valve key.
75
76        Used primarily to populate GUI fields with their initial/current values.
77
78        Parameters
79        ----------
80        - **variable_name** (*str*): The key identifying the valve whose substance name is requested (e.g., "Valve 1 Substance").
81
82        Returns
83        -------
84        - *str*: The current substance name associated with the key, or an empty string ("") if the key is not found in `stimuli_vars`.
85        """
86        if variable_name in self.stimuli_vars.keys():
87            return self.stimuli_vars[variable_name]
88        else:
89            return ""