omnibus comment changes (#1105)

* utils: typo

* healthsystem: typo

* co: comments about consumable items

* healthsyst: comment moved to where it belongs

* minor typos

* healthsystem: correct argument name arg_service_availability

* brc: changes in comments based on discussion with Andrew in #1098

* hs: typos/minor corrections

* formatting_demog_data: minor changes is comments

* ac: minor comment updates

---------

Co-authored-by: Tim Hallett <[email protected]>

src/scripts/data_file_processing/formatting_demography_data.py

@@ -69,7 +69,7 @@
 a1['Region'] = a1['Region'].ffill()
 a1 = a1.drop(region_names)
 
-# Check that the everything is ok:
+# Check that everything is ok:
 # Sum of districts = Total for Nation
 assert a1.drop(columns='Region').sum().astype(int).equals(national_total.astype(int))
 
@@ -343,7 +343,7 @@
 pop_2010.sum()  # 14M
 district_breakdown = table[['District', 'Count']].groupby(['District']).sum() / table['Count'].sum()
 
-# There will be a a neater way to do this, but....
+# There will be a neater way to do this, but....
 init_pop_list = list()
 
 for Sex in ['M', 'F']:
@@ -560,7 +560,7 @@ def reformat_date_period_for_wpp(wpp_import):
 lt[['Variant', 'Period', 'Sex', 'Age_Grp', 'death_rate']].to_csv(
     path_for_saved_files / 'ResourceFile_Pop_DeathRates_WPP.csv', index=False)
 
-# Expand the the life-table to create a row for each age year, for ease of indexing in the simulation
+# Expand the life-table to create a row for each age year, for ease of indexing in the simulation
 mort_sched = lt.copy()
 
 mort_sched['low_age'], mort_sched['high_age'] = mort_sched['Age_Grp'].str.split('-', 1).str

src/tlo/analysis/utils.py

@@ -265,7 +265,7 @@ def get_multiplier(_draw, _run):
                                            )['tlo.methods.population']['scaling_factor']['scaling_factor'].values[0]
 
     if custom_generate_series is None:
-        # If there is no `custom_generate_series` provided, it implies that function required selects a the specified
+        # If there is no `custom_generate_series` provided, it implies that function required selects the specified
         # column from the dataframe.
         assert column is not None, "Must specify which column to extract"
 

src/tlo/methods/breast_cancer.py

@@ -574,7 +574,7 @@ class BreastCancerMainPollingEvent(RegularEvent, PopulationScopeEventMixin):
 
     def __init__(self, module):
         super().__init__(module, frequency=DateOffset(months=1))
-        # scheduled to run every 3 months: do not change as this is hard-wired into the values of all the parameters.
+        # scheduled to run every month: do not change as this is hard-wired into the values of all the parameters.
 
     def apply(self, population):
         df = population.props  # shortcut to dataframe
@@ -645,7 +645,7 @@ def __init__(self, module, person_id):
 
         self.TREATMENT_ID = "BreastCancer_Investigation"
         self.EXPECTED_APPT_FOOTPRINT = self.make_appt_footprint({"Over5OPD": 1, "Mammography": 1})
-        self.ACCEPTED_FACILITY_LEVEL = '3'  # Mammography only available at level 3 and above.
+        self.ACCEPTED_FACILITY_LEVEL = '3'  # Biopsy only available at level 3 and above.
 
     def apply(self, person_id, squeeze_factor):
         df = self.sim.population.props

src/tlo/methods/contraception.py

@@ -750,6 +750,7 @@ def get_item_code_for_each_contraceptive(self):
         get_items_from_pkg = self.sim.modules['HealthSystem'].get_item_codes_from_package_name
 
         _cons_codes = dict()
+        # items for each method that requires an HSI to switch to
         _cons_codes['pill'] = get_items_from_pkg('Pill')
         _cons_codes['male_condom'] = get_items_from_pkg('Male condom')
         _cons_codes['other_modern'] = get_items_from_pkg('Female Condom')
@@ -759,6 +760,7 @@ def get_item_code_for_each_contraceptive(self):
         _cons_codes['implant'] = get_items_from_pkg('Implant')
         _cons_codes['female_sterilization'] = get_items_from_pkg('Female sterilization')
         assert set(_cons_codes.keys()) == set(self.states_that_may_require_HSI_to_switch_to)
+        # items used when initiating a modern reliable method after not using or switching from non-reliable method
         _cons_codes['co_initiation'] = get_items_from_pkg('Contraception initiation')
 
         return _cons_codes

src/tlo/methods/healthsystem.py

@@ -353,7 +353,7 @@ def initialise(self):
             # If there are bed-days specified, add (if needed) the in-patient admission and in-patient day Appointment
             # Types.
             # (HSI that require a bed for one or more days always need such appointments, but this may have been
-            # missed in the declaration of the `EXPECTED_APPPT_FOOTPRINT` in the HSI.)
+            # missed in the declaration of the `EXPECTED_APPT_FOOTPRINT` in the HSI.)
             # NB. The in-patient day Appointment time is automatically applied on subsequent days.
             if sum(self.BEDDAYS_FOOTPRINT.values()):
                 self.EXPECTED_APPT_FOOTPRINT = health_system.bed_days.add_first_day_inpatient_appts_to_footprint(
@@ -672,7 +672,7 @@ def __init__(
         self.list_fasttrack = []  # provided so that there is a default even before simulation is run
 
         # Store the argument provided for service_availability
-        self.arg_service_availabily = service_availability
+        self.arg_service_availability = service_availability
         self.service_availability = ['*']  # provided so that there is a default even before simulation is run
 
         # Check that the capabilities coefficient is correct
@@ -1162,10 +1162,10 @@ def get_service_availability(self) -> List[str]:
         """Returns service availability. (Should be equal to what is specified by the parameter, but overwrite with what
         was provided in argument if an argument was specified -- provided for backward compatibility/debugging.)"""
 
-        if self.arg_service_availabily is None:
+        if self.arg_service_availability is None:
             service_availability = self.parameters['Service_Availability']
         else:
-            service_availability = self.arg_service_availabily
+            service_availability = self.arg_service_availability
 
         assert isinstance(service_availability, list)
 
@@ -1996,7 +1996,7 @@ def run_population_level_events(self, _list_of_population_hsi_event_tuples: List
     def run_individual_level_events_in_mode_0_or_1(self,
                                                    _list_of_individual_hsi_event_tuples:
                                                    List[HSIEventQueueItem]) -> List:
-        """Run a list of individual level events. Returns: list of events that did not run (maybe an empty a list)."""
+        """Run a list of individual level events. Returns: list of events that did not run (maybe an empty list)."""
         _to_be_held_over = list()
         assert self.mode_appt_constraints in (0, 1)
 
@@ -2194,9 +2194,9 @@ class HealthSystemScheduler(RegularEvent, PopulationScopeEventMixin):
 
     If the event is to be run, then the following events occur:
         * The HSI event itself is run.
-        * The occurence of the event is logged
+        * The occurrence of the event is logged
         * The resources used are 'occupied' (if individual level HSI event)
-        * Other disease modules are alerted of the occurence of the HSI event (if individual level HSI event)
+        * Other disease modules are alerted of the occurrence of the HSI event (if individual level HSI event)
 
     Here is where we can have multiple types of assumption regarding how these capabilities are modelled.
     """
@@ -2262,7 +2262,7 @@ def _get_events_due_today(self,) -> Tuple[List, List]:
 
                 if next_event_tuple.priority == self.module.lowest_priority_considered:
                     # Check the priority
-                    # If the next event is not due and has lowest allowed priority, then stop looking
+                    # If the next event is not due and has the lowest allowed priority, then stop looking
                     # through the heapq as all other events will also not be due.
                     break
 
@@ -2312,7 +2312,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
         set_capabilities_still_available = {k for k, v in capabilities_monitor.items() if v > 0.0}
 
         # Here use different approach for appt_mode_constraints = 2: rather than collecting events
-        # due today all at once, run event immediately at time of querying. This ensure that no
+        # due today all at once, run event immediately at time of querying. This ensures that no
         # artificial "midday effects" are introduced when evaluating priority policies.
 
         # To avoid repeated dataframe accesses in subsequent loop, assemble set of alive
@@ -2365,7 +2365,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
 
                     if next_event_tuple.priority == self.module.lowest_priority_considered:
                         # Check the priority
-                        # If the next event is not due and has lowest allowed priority, then stop looking
+                        # If the next event is not due and has the lowest allowed priority, then stop looking
                         # through the heapq as all other events will also not be due.
                         break
 
@@ -2386,7 +2386,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
                         # based on queue information, and we assume no squeeze ever takes place.
                         squeeze_factor = 0.
 
-                        # Check if any of the officers required have ran out.
+                        # Check if any of the officers required have run out.
                         out_of_resources = False
                         for officer, call in original_call.items():
                             # If any of the officers are not available, then out of resources
@@ -2466,7 +2466,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
                             # Subtract this from capabilities used so-far today
                             capabilities_monitor.subtract(updated_call)
 
-                            # If any of the officers have ran out of time by performing this hsi,
+                            # If any of the officers have run out of time by performing this hsi,
                             # remove them from list of available officers.
                             for officer, call in updated_call.items():
                                 if capabilities_monitor[officer] <= 0:
@@ -2479,7 +2479,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
                                                   f"officers than expected_footprint.")
                                         )
 
-                            # Update today's footprint based on actuall call and squeeze factor
+                            # Update today's footprint based on actual call and squeeze factor
                             self.module.running_total_footprint -= original_call
                             self.module.running_total_footprint += updated_call
 
@@ -2503,7 +2503,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
         # were exhausted, so here ensure if any events expired were left unchecked they are properly
         # removed from the queue, and did_not_run() is invoked for all postponed events.
         # (This should still be more efficient than querying the queue as done in mode_appt_constraints
-        #  = 0 and 1 while ensuring mid-day effects are avoided.)
+        #  = 0 and 1 while ensuring midday effects are avoided.)
         while len(self.module.HSI_EVENT_QUEUE) > 0:
 
             next_event_tuple = hp.heappop(self.module.HSI_EVENT_QUEUE)
@@ -2532,7 +2532,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
 
                 if next_event_tuple.priority == self.module.lowest_priority_considered:
                     # Check the priority
-                    # If the next event is not due and has lowest allowed priority, then stop looking
+                    # If the next event is not due and has the lowest allowed priority, then stop looking
                     # through the heapq as all other events will also not be due.
                     break
 
@@ -2545,7 +2545,7 @@ def process_events_mode_2(self, hold_over: List[HSIEventQueueItem]) -> None:
                 if is_pop_level_hsi_event:
                     list_of_population_hsi_event_tuples_due_today.append(next_event_tuple)
                 else:
-                    # In previous iteration, have already ran all the events for today that could run
+                    # In previous iteration, have already run all the events for today that could run
                     # given capabilities available, so put back any remaining events due today to the
                     # hold_over queue as it would not be possible to run them today.
 
@@ -2663,13 +2663,13 @@ def _reset_internal_stores(self) -> None:
         self._treatment_ids = defaultdict(int)  # Running record of the `TREATMENT_ID`s of `HSI_Event`s
         self._appts = defaultdict(int)  # Running record of the Appointments of `HSI_Event`s that have run
         self._appts_by_level = {_level: defaultdict(int) for _level in ('0', '1a', '1b', '2', '3', '4')}
+        # <--Same as `self._appts` but also split by facility_level
 
         # Log HSI_Events that never ran to monitor shortcoming of Health System
         self._never_ran_treatment_ids = defaultdict(int)  # As above, but for `HSI_Event`s that never ran
         self._never_ran_appts = defaultdict(int)  # As above, but for `HSI_Event`s that have never ran
         self._never_ran_appts_by_level = {_level: defaultdict(int) for _level in ('0', '1a', '1b', '2', '3', '4')}
 
-        # <--Same as `self._appts` but also split by facility_level
         self._frac_time_used_overall = []  # Running record of the usage of the healthcare system
         self._squeeze_factor_by_hsi_event_name = defaultdict(list)  # Running record the squeeze-factor applying to each
         #                                                           treatment_id. Key is of the form:

src/tlo/methods/labour.py

@@ -2723,7 +2723,7 @@ def apply(self, mother_id):
         # =============================================== BIRTH ====================================================
         # If the mother is alive and still pregnant OR has died but the foetus has survived we generate a child.
 
-        # Live women are scheduled to move to the postpartum event to determine if they experiences any additional
+        # Live women are scheduled to move to the postpartum event to determine if they experience any additional
         # complications
 
         if (person.is_alive and person.is_pregnant and not person.la_intrapartum_still_birth) or \