add comments to flicker.py explaining process.

These comments explain how each 'section' works with the data. There
mostly here for when I come back to this months/years from now and
I've forgotten how this code works. The other scenarios this is for --
although very unlikely -- is other people new to the project and need
a helping hand.

src/flicker.py

@@ -7,20 +7,63 @@ def main():
     rps_above_thresh = "data/results/readings_above_threshold.csv"
     flicker_list = "data/results/flicker_list.csv"
     filtered_flickers = "data/results/filtered_flicker_entries.csv"
-    
+
+    # Step 1
+    # ======
+    # Load the raw data, taken from the exported database.
     raw_data = io_services.load_raw_data(raw_data_path)
     # log_services.print_list(raw_data)
+
+    # Step 2
+    # ======
+    # Tally-up how many readings occured for each second in the
+    # raw data. For example, for the period between 2021-04-23
+    # 07:03:57 and 2021-04-23 07:03:58, how many readings did the
+    # system take? Was it 1, 3, Etc.
     time_tallies = data_services.tally_readings_per_second(raw_data)
     # log_services.print_dictionary(time_tallies)
+
+    # Step 3
+    # ======
+    # Count the number of tallies derived from step 2. So, how
+    # many time did the system take 2 readings-per-second, how many
+    # times did the system 3 readings-per-second Etc.
     rps_totals = data_services.total_count_for_each_reading_per_second(time_tallies)
     # log_services.print_dictionary(rps_totals)
     io_services.save_rps_totals(rps_totals, rps_save_path)
-    rps_above_herz = data_services.get_rps_above(4, time_tallies)
+
+    # Step 4
+    # ======
+    # List out all the time periods which had more than the
+    # specified readings-per-second. The default value is any time
+    # period with more than 4 readings-per-second but you can change
+    # it (it's a function argument).
+    rps_above_hertz = data_services.get_rps_above(4, time_tallies)
     # log_services.print_list(rps_above_two)
-    io_services.save_rps_above_threshold(rps_above_herz, rps_above_thresh)
-    flicker_entries = data_services.find_flickers(rps_above_herz, raw_data)
+    io_services.save_rps_above_threshold(rps_above_hertz, rps_above_thresh)
+
+    # Step 5
+    # ======
+    # Using the list of time periods derived in step 4
+    # (rps_above_hertz), create a new list from the raw data (step
+    # 1). Filter out the time periods created in step 4 and include
+    # all their readings for that time period (I.E. second). An
+    # example of this is: The list created in step 4 shows the time
+    # period between 2021-04-23 07:03:57 and 2021-04-23 07:03:58 has 4
+    # readings so note the (start) time and how the readings recorded
+    # in that period.
+    flicker_entries = data_services.find_flickers(rps_above_hertz, raw_data)
     # log_services.print_dictionary(flicker_tallies)
     io_services.save_rps_totals(flicker_entries, flicker_list)
+
+    # Step 6
+    # =======
+    # This step filters out the time periods which pass the hertz
+    # threshold to those which have at least one reading in its (1
+    # second period) grouping to cause the light to turn on in the
+    # gallery ('gallery1'). If this list contains any readings, you
+    # can review them to make sure the light doesn't turn on and off
+    # enough times to potentially cause a photo-epileptic seizure.
     filtered_flicker_entries = data_services.find_readings_with_lights_on(flicker_entries)
     # log_services.print_list(filtered_flicker_entries)
     io_services.save_filtered_flickers(filtered_flicker_entries, filtered_flickers)