Merge pull request #780 from UWB-Biocomputing/ISSUE-768]-Update-Comments-for-911-Classes

[ISSUE-768] Update comments for 911 input generation code

Author: stiber

Tools/InputGeneration/ClusterPointProcess/cluster_point_process.py

@@ -1,3 +1,4 @@
+# Import necessary libraries
 import numpy as np
 import math
 import lxml.etree as et
@@ -7,7 +8,17 @@
 from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QLineEdit, QPushButton, QVBoxLayout, QFileDialog, QMessageBox, QDialog, QDialogButtonBox, QGridLayout
 from cluster_point_process_functions import primprocess, add_types, secprocess, add_vertex_events
 
-# Class used for setting type_ratios in the GUI for the cluster point process
+# source venv/bin/activate
+# python3 cluster_point_process.py
+
+# This script provides a GUI to configure and generate synthetic 911 call data using a cluster point process model.
+# It integrates primary and secondary event generation with user-configurable parameters.
+
+
+# ------------------------------
+# Class: TypeRatioDialog
+# ------------------------------
+# Provides a dialog to input ratios for different 911 call types (Law, EMS, Fire).
 class TypeRatioDialog(QDialog):
     def __init__(self):
         super().__init__()
@@ -17,7 +28,8 @@ def __init__(self):
 
     def init_ui(self):
         layout = QVBoxLayout()
-
+        
+        # Labels and input fields for call type ratios
         self.labels = ["Law", "EMS", "Fire"]
         self.entries = {}
         for label_text in self.labels:
@@ -28,6 +40,7 @@ def init_ui(self):
             layout.addWidget(label)
             layout.addWidget(entry)
 
+        # OK and Cancel buttons
         button_box = QDialogButtonBox(QDialogButtonBox.Cancel | QDialogButtonBox.Ok)
         button_box.accepted.connect(self.accept)
         button_box.rejected.connect(self.on_cancel_clicked)
@@ -37,6 +50,7 @@ def init_ui(self):
         self.backup_initial_values()  # Save initial values
 
     def accept(self):
+        """Validates and processes user inputs when OK is clicked."""
         invalid_fields = []
         for label, entry in self.entries.items():
             text = entry.text().strip()
@@ -51,18 +65,22 @@ def accept(self):
                     invalid_fields.append(label)
 
         if invalid_fields:
+            # Show an error message for invalid inputs
             error_message = "Invalid or empty values in the following fields:\n"
             for field in invalid_fields:
                 error_message += f"- {field}\n"
             QMessageBox.warning(self, "Input Error", error_message)
         else:
+            # Store validated results
             self.result = {label: float(entry.text().strip()) for label, entry in self.entries.items()}
             super().accept()
 
     def backup_initial_values(self):
+        """Stores initial values to restore them if the user cancels."""
         self.initial_values = {label: entry.text() for label, entry in self.entries.items()}
 
     def on_cancel_clicked(self):
+        """Restores initial values if the dialog is canceled."""
         for label, entry in self.entries.items():
             current_text = entry.text().strip()
             if not current_text:  # If the field is empty, reset to initial value
@@ -71,19 +89,25 @@ def on_cancel_clicked(self):
 
         self.reject()  # Close the dialog
 
-# Class used for setting prototype values in the GUI for the cluster point process
+# ------------------------------
+# Class: PrototypesDialog
+# ------------------------------
+# Allows the user to define prototype configurations for secondary event generation.
 class PrototypesDialog(QDialog):
     def __init__(self):
         super().__init__()
         self.setWindowTitle("Set Prototypes")
         self.init_ui()
 
     def init_ui(self):
+        """Sets up the layout and input fields for prototype configurations."""
         layout = QGridLayout()
         self.entries = {}
 
+        # Labels for prototype parameters
         labels = ["mu_r:", "sdev_r:", "mu_intensity:", "sdev_intensity:"]
 
+        # Add input fields for four prototypes
         for i in range(4):
             prototype_label = QLabel(f"Prototype {i}:")
             layout.addWidget(prototype_label, i, 0)
@@ -94,6 +118,7 @@ def init_ui(self):
                 layout.addWidget(QLabel(label), i, j * 2 + 1)
                 layout.addWidget(entry, i, j * 2 + 2)
 
+         # OK and Cancel buttons
         button_box = QDialogButtonBox(QDialogButtonBox.Ok | QDialogButtonBox.Cancel)
         button_box.accepted.connect(self.accept)
         button_box.rejected.connect(self.reject)
@@ -102,6 +127,7 @@ def init_ui(self):
         self.setLayout(layout)
 
     def accept(self):
+        """Validates and processes user inputs when OK is clicked."""
         invalid_fields = []
         for label, entry in self.entries.items():
             text = entry.text().strip()
@@ -116,6 +142,7 @@ def accept(self):
                     invalid_fields.append(label)
 
         if invalid_fields:
+            # Show an error message for invalid inputs
             error_message = "Invalid or empty values in the following fields:\n"
             for field in invalid_fields:
                 error_message += f"- {field}\n"
@@ -129,40 +156,43 @@ def __init__(self):
         super().__init__()
         self.setWindowTitle("911 Call Data Generator")
         # Input dialog for type_ratio and prototypes
+        # These will allow the user to input custom type ratios and prototypes via separate dialogs
         self.type_ratio_dialog = None
         self.prototypes_dialog = None
 
         # Dictionary for holding type_ratio and prototypes
-        self.type_ratios = {}
-        self.prototypes = {}
+        self.type_ratios = {} # Example: {'Law': 0.64, 'EMS': 0.18, 'Fire': 0.18}
+        self.prototypes = {} # Example: {0: {'mu_r': 0.0005, 'sdev_r': 0.0001}, ...}
 
         self.init_ui()
 
     def init_ui(self):
         layout = QVBoxLayout()
 
-        # Graph File input field
+        # Input field for selecting the graph file (.graphml)
         graph_file_label = QLabel("Select Graph File (.graphml):")
         self.graph_file_label = QLineEdit()
         layout.addWidget(graph_file_label)
         layout.addWidget(self.graph_file_label)
 
+        # Button to browse and select a graph file
         graph_file_button = QPushButton("Browse")
         graph_file_button.clicked.connect(self.browse_file)
         layout.addWidget(graph_file_button)
 
-        # Input labels for GUI
+        # Input labels and fields for various parameters
+        # These fields collect user inputs for parameters like event timing, duration, etc.
         self.labels = [
-            "Graph ID:",
-            "First (seconds):",
-            "Last (seconds):",
-            "Mean Time Interval (seconds):",
-            "Dead Time after Event (seconds):",
-            "Mean Call Interval after incident (seconds):",
-            "Mean Duration (seconds):",
-            "Minimum Duration (seconds):",
-            "Mean Patience Time (seconds):",
-            "Mean On-Site Time (seconds):",
+            "Graph ID:", # Insert graph labels
+            "First (seconds):", #  The time of the first event or call in the dataset, measured in seconds from a reference point (e.g., the start of the logging period).
+            "Last (seconds):", # The time of the last event or call in the dataset, measured in seconds from the same reference point.
+            "Mean Time Interval (seconds):", # The average time interval between consecutive 911 calls, measured in seconds.
+            "Dead Time after Event (seconds):", # The average time period after an event during which no new events or calls are expected to occur, measured in seconds. This could represent a cooldown period or a time when the system is not actively logging new calls.
+            "Mean Call Interval after incident (seconds):", #  The average time interval between the end of an incident and the next 911 call, measured in seconds. This could be used to model the frequency of follow-up calls or related incidents.
+            "Mean Duration (seconds):", # The average duration of a 911 call or incident, measured in seconds. This includes the time from the start of the call to its conclusion.
+            "Minimum Duration (seconds):", # The shortest duration of a 911 call or incident in the dataset, measured in seconds. This could be used to filter out very short or incomplete calls.
+            "Mean Patience Time (seconds):", # The average time a caller is willing to wait on hold before hanging up, measured in seconds. This metric is important for understanding caller behavior and optimizing call center operations.
+            "Mean On-Site Time (seconds):", # The average time emergency responders spend on-site at an incident, measured in seconds. This includes the time from arrival at the scene to departure.
         ]
 
         self.entries = {}
@@ -174,24 +204,27 @@ def init_ui(self):
             layout.addWidget(label)
             layout.addWidget(entry)
 
-        # Buttons for opening dialogs (Type Ratio, Prototype)
+        # Button to open the "Set Type Ratios" dialog
         set_type_ratio_button = QPushButton("Set Type Ratios")
         set_type_ratio_button.clicked.connect(self.show_type_ratio_dialog)
         layout.addWidget(set_type_ratio_button)
 
+        # Button to open the "Set Prototypes" dialog
         set_prototypes_button = QPushButton("Set Prototypes")
         set_prototypes_button.clicked.connect(self.show_prototypes_dialog)
         layout.addWidget(set_prototypes_button)
 
-        # Submit button
+        # Button to start the event generation process
         generate_button = QPushButton("Generate Events")
         generate_button.clicked.connect(self.generate_events)
         layout.addWidget(generate_button)
 
+        # Set the layout of the UI
         self.setLayout(layout)
         self.show()
 
     def show_type_ratio_dialog(self):
+        # Opens a dialog to allow the user to set type ratios
         if not self.type_ratio_dialog:
             self.type_ratio_dialog = TypeRatioDialog()
 
@@ -200,14 +233,16 @@ def show_type_ratio_dialog(self):
             self.type_ratios = {label: float(entry.text()) for label, entry in self.type_ratio_dialog.entries.items()}
 
     def show_prototypes_dialog(self):
+        # Opens a dialog to allow the user to set prototypes
         if not self.prototypes_dialog:
             self.prototypes_dialog = PrototypesDialog()
 
         if self.prototypes_dialog.exec_() == QDialog.Accepted:
+            # Extract and reformat prototype values
             prototypes_entries = self.prototypes_dialog.entries.items()
             prototypes_values = {label: float(entry.text()) for label, entry in prototypes_entries}
 
-            # Reformatting the prototypes dictionary
+            # Organize prototype data into nested dictionaries
             self.prototypes = {}
             for label, value in prototypes_values.items():
                 split_label = label.split(' - ')
@@ -220,7 +255,9 @@ def show_prototypes_dialog(self):
                 self.prototypes[prototype_num][var_name] = value
 
     # Function that allows user to browse local files
+
     def browse_file(self):
+         # Allows the user to browse and select a .graphml file
         options = QFileDialog.Options()
         options |= QFileDialog.DontUseNativeDialog
         file_dialog = QFileDialog()
@@ -242,9 +279,11 @@ def browse_file(self):
     # Handles invalid inputs (string instead of int, wrong file 
     # type but not invalid logic)
     def generate_events(self):
+        # Validates inputs and triggers the event generation process
         error_message = ""
         invalid_fields = []
 
+        # Validate user input fields
         for label_text, entry in self.entries.items():
             if label_text != "Select Region Grid (.graphml):":
                 text = entry.text().strip()
@@ -256,27 +295,30 @@ def generate_events(self):
                     except ValueError:
                         invalid_fields.append(label_text)
 
+        # Check if type ratios and prototypes are set
         if not self.type_ratios and not self.prototypes:
             error_message += "Please set Type Ratio and Prototype values before generating events."
         elif not self.type_ratios:
             error_message += "Please set Type Ratio values before generating events."
         elif not self.prototypes:
             error_message += "Please set Prototype values before generating events."
 
-        # Error handling
+        # Validate the graph file input
         graph_file = self.graph_file_label.text().strip()
         if not graph_file:
             invalid_fields.append("Select Region Grid (.graphml):")
         elif not graph_file.endswith(".graphml"):
             invalid_fields.append("Select Region Grid (.graphml) must be a .graphml file.")
 
+        # Handle errors and display warnings
         if invalid_fields:
             error_message = "Invalid or empty values in the following fields: (float values only)\n"
             for field in invalid_fields:
                 error_message += f"- {field}\n"
 
-        # Event handling
+        # Proceed with event generation if inputs are valid
         try:
+            # Extract user inputs and use them for event generation
             if error_message:
                 raise ValueError(error_message)
 
@@ -297,13 +339,16 @@ def generate_events(self):
                 # PRIMARY EVENTS
                 ###########################################################################
                 # Start your event generation process here based on the valid inputs
-                graph = nx.read_graphml('../../gis2graph/graph_files/spd.graphml')
+                graph_file_path = os.path.join('..', '..', 'gis2graph', 'graph_files', 'spd.graphml')
+                graph = nx.read_graphml(graph_file_path)
                 graph_id = str(self.entries["Graph ID:"].text())
                 graph_attribute = graph.nodes[graph_id]['segments']
                 graph_grid = np.array(eval(graph_attribute))
 
+               
+
                 # Seed numpy random number to get consistent results
-                np.random.seed(20)
+                np.random.seed(20) ## change it when i make the test set to something else
 
                 # Call primprocess using the inputs from the interface
                 incidents = primprocess(first, last, mu, pp_dead_t, graph_grid)