Merge branch 'feature/CO2_times_endpoints' into 'master'

CO2 endpoints response content

See merge request caimira/caimira!532

caimira/docs/mkdocs/docs/code/rest_api.md

@@ -169,9 +169,9 @@ Currently, the REST API contains two routing categories that provide the generat
 
 #### CO₂ Results
 
-??? Abstract "POST **/co2/transition_times** (suggested ventilation transition times)"
+??? Abstract "POST **/co2/transition_times** (suggested transition times)"
     
-    * **Description**: Endpoint that allows users to retrieve the suggested ventilation times based on the CO₂ input data. Data is processed by the CAiMIRA engine, and the results are returned in the response.
+    * **Description**: Endpoint that allows users to retrieve the suggested times based on the CO₂ input data (occupancy and ventilation transition times). Data is processed by the CAiMIRA engine, and the results are returned in the response.
 
     ??? note "Example body"
 
@@ -187,19 +187,6 @@ Currently, the REST API contains two routing categories that provide the generat
                 "room_capacity": 10
             }
 
-        In case of success (`200`), the response will contain the following structure:
-
-            {
-                "status": "success",
-                "message": "Results generated successfully",
-                "results": [
-                    8.5,
-                    10.167,
-                    12.467,
-                    13.0
-                ]
-            }
-
     For the full list of accepted inputs and respective values please refer to CAiMIRA's official defaults in GitLab repository [here](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/calculator/validators/defaults.py?ref_type=heads).
 
     ??? "**Example cURL** (with the above body)"
@@ -218,6 +205,31 @@ Currently, the REST API contains two routing categories that provide the generat
                 "room_capacity": 10,
             }'
 
+    ??? "**Example response**"
+
+        In case of success (`200`), the response will contain the following structure:
+
+            {
+                "status": "success",
+                "message": "Results generated successfully",
+                "results": {
+                    "occupancy_times": [
+                        8.5,
+                        13.0
+                    ],
+                    "ventilation_times": [
+                        10.167,
+                        12.467
+                    ],
+                    "total_times": [
+                        8.5,
+                        10.167,
+                        12.467,
+                        13.0
+                    ]
+                }
+            }
+
 ??? Abstract "POST **/co2/report** (CO₂ report data generation)"
     
     * **Description**: Core endpoint that allows users to submit data for the CO₂ report generation. Data is processed by the CAiMIRA engine, and the results are returned in the response.
@@ -260,6 +272,39 @@ Currently, the REST API contains two routing categories that provide the generat
                 "fitting_ventilation_states":"[8.5,10.167,12.467,13.0]"
             }'
 
+    ??? "**Example response**"
+
+        In case of success (`200`), the response will contain the following structure:
+
+            {
+                "status": "success",
+                "message": "Results generated successfully",
+                "results": {
+                    "exhalation_rate": 0.3317476241040026,
+                    "ventilation_values": [
+                        6.520768146832283e-05,
+                        6.350639949708053,
+                        ...
+                    ],
+                    "room_capacity": 10,
+                    "ventilation_ls_values": [
+                        0.0010867946911387138,
+                        105.84399916180087,
+                        ...
+                    ],
+                    "ventilation_lsp_values": [
+                        0.00010867946911387139,
+                        10.584399916180086,
+                        ...
+                    ],
+                    "predictive_CO2": [
+                        440.44,
+                        440.44,
+                        ...
+                    ]
+                }
+            }
+
 ### Development
 
 For testing new releases, use the PyPI Test instance by running the following command (directory independent):

caimira/src/caimira/api/controller/co2_report_controller.py

@@ -17,25 +17,31 @@ def generate_report(model: CO2DataModel) -> typing.Dict:
     return dict(model.CO2_fit_params())
 
 
-def generate_transition_times(CO2model: CO2DataModel, vent_transition_times: list) -> list:
+def request_CO2_transition_times(form_data: dict) -> dict:
-    # The entire ventilation changes consider the initial and final occupancy state change
+    """
-    occupancy_transition_times = list(CO2model.occupancy.transition_times)
+    Calculate and return the transition times related to CO2 levels including
-    all_vent_transition_times: list = sorted(
+    the ventilation transition times (identified from the change point algorithm)
-        [occupancy_transition_times[0]] +
+    and relevant occupancy transition times (first and last occurrences).
-        [occupancy_transition_times[-1]] +
+    """
-        vent_transition_times)
+    data_registry = DataRegistry()
-    return all_vent_transition_times
 
-
+    form_obj = generate_form_obj(form_data=form_data, data_registry=data_registry)
-def request_CO2_transition_times(form_data: typing.Dict) -> list:
+    CO2model = generate_model(form_obj=form_obj)
-    data_registry: DataRegistry = DataRegistry()
-
-    form_obj: CO2FormData = generate_form_obj(form_data=form_data, data_registry=data_registry)
-    CO2model: CO2DataModel = generate_model(form_obj=form_obj)
-    vent_transition_times: list = form_obj.find_change_points()
-    all_vent_transition_times: list = generate_transition_times(CO2model, vent_transition_times)
     
-    return all_vent_transition_times
+    # Occupancy transition times
+    occupancy_transition_times = list(CO2model.occupancy.transition_times)
+    relevant_occupancy_times = [occupancy_transition_times[0]] + [occupancy_transition_times[-1]]
+    # Ventilation transition times
+    vent_transition_times = form_obj.find_change_points()
+    ventilation_times = sorted(vent_transition_times)
+    # Total transition times
+    total_times = sorted(relevant_occupancy_times + ventilation_times)
+    
+    return {
+        "occupancy_times": occupancy_transition_times,
+        "ventilation_times": ventilation_times,
+        "total_times": total_times
+    }
 
 
 def request_CO2_report(form_data: typing.Dict) -> typing.Dict: