diff --git a/caimira/docs/mkdocs/docs/code/rest_api.md b/caimira/docs/mkdocs/docs/code/rest_api.md index 8fc583b4..91c53174 100644 --- a/caimira/docs/mkdocs/docs/code/rest_api.md +++ b/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): diff --git a/caimira/src/caimira/api/controller/co2_report_controller.py b/caimira/src/caimira/api/controller/co2_report_controller.py index d6285916..2b558b13 100644 --- a/caimira/src/caimira/api/controller/co2_report_controller.py +++ b/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: - # The entire ventilation changes consider the initial and final occupancy state change - occupancy_transition_times = list(CO2model.occupancy.transition_times) - all_vent_transition_times: list = sorted( - [occupancy_transition_times[0]] + - [occupancy_transition_times[-1]] + - vent_transition_times) - return all_vent_transition_times +def request_CO2_transition_times(form_data: dict) -> dict: + """ + Calculate and return the transition times related to CO2 levels including + the ventilation transition times (identified from the change point algorithm) + and relevant occupancy transition times (first and last occurrences). + """ + data_registry = DataRegistry() - -def request_CO2_transition_times(form_data: typing.Dict) -> list: - 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) + form_obj = generate_form_obj(form_data=form_data, data_registry=data_registry) + CO2model = generate_model(form_obj=form_obj) - 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: