diff --git a/caimira/docs/Dockerfile b/caimira/docs/Dockerfile index 22055d85..36d4302b 100644 --- a/caimira/docs/Dockerfile +++ b/caimira/docs/Dockerfile @@ -26,7 +26,7 @@ WORKDIR /app/docs # Run the Python script to update markdown files, move it, and generate UML diagram RUN python3 style_docs.py \ && mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ -&& pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs ../src/caimira/calculator/models/models.py +&& pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs/code_documentation ../src/caimira/calculator/models/models.py # Mkdocs directory WORKDIR /app/docs/mkdocs diff --git a/caimira/docs/mkdocs/docs/LICENSE.md b/caimira/docs/mkdocs/docs/LICENSE.md new file mode 100644 index 00000000..de49c2af --- /dev/null +++ b/caimira/docs/mkdocs/docs/LICENSE.md @@ -0,0 +1,13 @@ +Copyright 2020-2021 CERN. All rights not expressly granted are reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/caimira/docs/mkdocs/docs/code_documentation/index.md b/caimira/docs/mkdocs/docs/code_documentation/index.md deleted file mode 100644 index 41ac56a3..00000000 --- a/caimira/docs/mkdocs/docs/code_documentation/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Code-related Documentation - -* [CAiMIRA REST API](rest_api.md) -* [CAiMIRA Models](models.md) diff --git a/caimira/docs/mkdocs/docs/code_documentation/rest_api.md b/caimira/docs/mkdocs/docs/code_documentation/rest_api.md index 295daa0c..7839bb94 100644 --- a/caimira/docs/mkdocs/docs/code_documentation/rest_api.md +++ b/caimira/docs/mkdocs/docs/code_documentation/rest_api.md @@ -210,9 +210,11 @@ The deployment process varies depending on whether changes are pushed to branche ### Branch and Tag-based Deployment For branch pushes: + * All branches (except `live/caimira-test`) trigger the **test** stage in the CI/CD pipeline, ensuring the code passes all necessary tests before it is deployed. For tag creation: + * When a new tag is created, the pipeline skips the previous tests, and it builds `Docker` images, storing them in GitLab's container registry. The images can be manually deployed to the OKD platform for the `PROD` - production environment. ### OKD Platform Deployment @@ -220,6 +222,3 @@ The `cern_caimira` package, which contains the CERN-specific UI, is deployed dir ### Versioning and Tags The repository follows a *semantic versioning* scheme, with tags named according to the `MAJOR.MINOR.PATCH` format (e.g., `v5.0.0`). - - - \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/index.md b/caimira/docs/mkdocs/docs/index.md index e76a38cb..525ff34d 100644 --- a/caimira/docs/mkdocs/docs/index.md +++ b/caimira/docs/mkdocs/docs/index.md @@ -6,13 +6,16 @@ It includes details on the diameter-dependent mathematical model and the code de # Contents: -* [Project Overview](project_overview.md) - -* [Diameter-dependent Model](full_diameter_dependence.md) - -* [Code-related Documentation](code_documentation/index.md) - - * [CAiMIRA REST API](code_documentation/rest_api.md) - * [CAiMIRA Models](code_documentation/models.md) - -* [Open Source Acknowledgments](open_source_acknowledgments.md) \ No newline at end of file +* [Project Overview]() + * [About](project_overview/about.md) + * [Installation](project_overview/installation.md) + * [Deployment](project_overview/deployment.md) + * [User Guide]() + * [Quick Guide](project_overview/user_guide/quick_guide.md) + * [Full Guide](project_overview/user_guide/full_guide.md) + * [Open Source Acknowledgments](project_overview/open_source_acknowledgments.md) + +* [Code Documentation]() + * [Diameter Normalization](code_documentation/diameter_normalization.md) + * [REST API](code_documentation/rest_api.md) + * [Models Module](code_documentation/models.md) \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/project_overview.md b/caimira/docs/mkdocs/docs/project_overview.md deleted file mode 100644 index b5418862..00000000 --- a/caimira/docs/mkdocs/docs/project_overview.md +++ /dev/null @@ -1,487 +0,0 @@ -# CAiMIRA - CERN Airborne Model for Risk Assessment - -CAiMIRA is a risk assessment tool developed to model the concentration of viruses in enclosed spaces, in order to inform space-management decisions. - -CAiMIRA models the concentration profile of potential virions in enclosed spaces , both as background (room) concentration and during close-proximity interactions, with clear and intuitive graphs. -The user can set a number of parameters, including room volume, exposure time, activity type, mask-wearing and ventilation. -The report generated indicates how to avoid exceeding critical concentrations and chains of airborne transmission in spaces such as individual offices, meeting rooms and labs. - -The risk assessment tool simulates the airborne spread SARS-CoV-2 virus in a finite volume, assuming a homogenous mixture and a two-stage exhaled jet model, and estimates the risk of COVID-19 infection therein. -The results DO NOT include the other known modes of SARS-CoV-2 transmission, such as fomite or blood-bound. -Hence, the output from this model is only valid when the other recommended public health & safety instructions are observed, such as good hand hygiene and other barrier measures. - -The model used is based on scientific publications relating to airborne transmission of infectious diseases, dose-response exposures and aerosol science, as of February 2022. -It can be used to compare the effectiveness of different airborne-related risk mitigation measures. - -Note that this model applies a deterministic approach, i.e., it is assumed at least one person is infected and shedding viruses into the simulated volume. -Nonetheless, it is also important to understand that the absolute risk of infection is uncertain, as it will depend on the probability that someone infected attends the event. -The model is most useful for comparing the impact and effectiveness of different mitigation measures such as ventilation, filtration, exposure time, physical activity, amount and nature of close-range interactions and -the size of the room, considering both long- and short-range airborne transmission modes of COVID-19 in indoor settings. - -This tool is designed to be informative, allowing the user to adapt different settings and model the relative impact on the estimated infection probabilities. -The objective is to facilitate targeted decision-making and investment through comparisons, rather than a singular determination of absolute risk. -While the SARS-CoV-2 virus is in circulation among the population, the notion of 'zero risk' or 'completely safe scenario' does not exist. -Each event modelled is unique, and the results generated therein are only as accurate as the inputs and assumptions. - -## Authors -CAiMIRA was developed by following members of CERN - European Council for Nuclear Research (visit [https://home.cern/](https://home.cern/)): - -Andre Henriques1, Luis Aleixo1, Marco Andreini1, Gabriella Azzopardi2, James Devine3, Philip Elson4, Nicolas Mounet2, Markus Kongstein Rognlien2,6, Nicola Tarocco5 - -1HSE Unit, Occupational Health & Safety Group, CERN
-2Beams Department, Accelerators and Beam Physics Group, CERN
-3Experimental Physics Department, Safety Office, CERN
-4Beams Department, Controls Group, CERN
-5Information Technology Department, Collaboration, Devices & Applications Group, CERN
-6Norwegian University of Science and Technology (NTNU)
- -### Reference and Citation - -**For the use of the CAiMIRA web app** - -CAiMIRA – CERN Airborne Model for Indoor Risk Assessment tool - -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6520431.svg)](https://doi.org/10.5281/zenodo.6520431) - -© Copyright 2020-2021 CERN. All rights not expressly granted are reserved. - -**For use of the CAiMIRA model** - -Henriques A, Mounet N, Aleixo L, Elson P, Devine J, Azzopardi G, Andreini M, Rognlien M, Tarocco N, Tang J. (2022). Modelling airborne transmission of SARS-CoV-2 using CARA: risk assessment for enclosed spaces. _Interface Focus 20210076_. [https://doi.org/10.1098/rsfs](https://doi.org/10.1098/rsfs).2021.0076 - -Reference on the Short-range expiratory jet model from: -Jia W, Wei J, Cheng P, Wang Q, Li Y. (2022). Exposure and respiratory infection risk via the short-range airborne route. _Building and Environment_ *219*: 109166. -[https://doi.org/10.1016/j.buildenv.2022.109166](https://doi.org/10.1016/j.buildenv.2022.109166) - -***Open Source Acknowledgments*** - -For a detailed list of the open-source dependencies used in this project along with their respective licenses, please refer to [Open Source Acknowledgments](open_source_acknowledgments.md). This includes both the core dependencies specified in the project's requirements and their transitive dependencies. - -The information also features a distribution diagram of licenses and a brief description of each of them. - -## Applications - -### Calculator - -A risk assessment tool which simulates the airborne spread of the SARS-CoV-2 virus for space managers. - - -### CAiMIRA Expert App and CO₂ App - -A tool to interact with various parameters of the CAiMIRA model. - - -## Disclaimer - -CAiMIRA has not undergone review, approval or certification by competent authorities, and as a result, it cannot be considered as a fully endorsed and reliable tool, namely in the assessment of potential viral emissions from infected hosts to be modelled. - -The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. -In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. - - -## Running CAiMIRA locally - -The easiest way to run a version of CAiMIRA Calculator is to use docker. A pre-built -image of CAiMIRA is made available at [https://gitlab.cern.ch/caimira/caimira/container_registry](https://gitlab.cern.ch/caimira/caimira/container_registry). -In order to run CAiMIRA locally with docker, run the following: - - $ docker run -it -p 8080:8080 gitlab-registry.cern.ch/caimira/caimira/calculator - -This will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/). - - -## Folder structure - -The project contains two different Python packages: - -- `caimira`: Contains all the backend logic and the calculator model. It is the package published in PyPI. -- `cern_caimira`: Imports and uses the backend package (`caimira`) and includes CERN-specific UI implementation. - -The folder layout follows best practices as described [here](https://ianhopkinson.org.uk/2022/02/understanding-setup-py-setup-cfg-and-pyproject-toml-in-python/). - - -## Development guide - -CAiMIRA is also mirrored to Github if you wish to collaborate on development and can be found at: [https://github.com/CERN/caimira](https://github.com/CERN/caimira) - -### Installing CAiMIRA in editable mode - -In order to install the CAiMIRA's backend logic, create your own virtualenv and, from the root directory of the project, run: - -``` -cd caimira -pip install -e . -``` - -In order to install the CERN-specific UI version, that links to the previously installed backend, activate your virtualenv and, from the root directory of the project, run: - -``` -cd cern_caimira -pip install -e . -``` - -### Running the Calculator app in development mode - -This example describes how to run the calculator with the CERN-specific UI. In the root directory of the project: - -``` -python -m cern_caimira.apps.calculator -``` - -To run with a specific template theme created: - -``` -python -m cern_caimira.apps.calculator --theme=cern_caimira/src/cern_caimira/apps/templates/{theme} -``` - -To run the entire app in a different `APPLICATION_ROOT` path: - -``` -python -m cern_caimira.apps.calculator --app_root=/myroot -``` - -To run the calculator on a different URL path: - -``` -python -m cern_caimira.apps.calculator --prefix=/mycalc -``` - -Each of these commands will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/). - -### Documentation - -To compile and view CAiMIRA's documentation, follow these steps: - -### 1. Install CAiMIRA with Documentation Dependencies - -First, ensure CAiMIRA is installed along with the `doc` dependencies: - -``` -cd caimira -pip install -e .[doc] -``` - -### 2. Generate Code Documentation in Markdown - -Use `sphinx` with `sphinx_markdown_builder` to generate the documentation in `Markdown` format: - -``` -cd docs/sphinx -sphinx-build -b markdown . _build/markdown -``` - -### 3. Customize and Organize Documentation - -Run the `style_docs.py` script to apply custom styles, move required files, and generate a UML diagram: - -``` -python style_docs.py \ -&& mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ -&& pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs ../src/caimira/calculator/models/models.py -``` - -### 4. Start the documentation server - -To view the documentation locally, use MkDocs to serve it: - -``` -cd ../mkdocs -python -m mkdocs serve --dev-addr=0.0.0.0:8080 -``` - -The documentation can now be accessed at [http://0.0.0.0:8080/](http://0.0.0.0:8080/). - -### Running the CAiMIRA Expert-App or CO2-App apps in development mode - -#### Disclaimer - -The `ExpertApplication` and `CO2Application` are no longer actively maintained but will remain in the codebase for legacy purposes. -Please note that the functionality of these applications might be compromised due to deprecation issues. - -#### Running the Applications - -These applications only work within Jupyter notebooks. Attempting to run them outside of a Jupyter environment may result in errors or degraded functionality. - -##### Prerequisites - -Make sure you have the needed dependencies installed: - -``` -pip install notebook jupyterlab -``` - -Running with Visual Studio Code (VSCode): - -1. Ensure you have the following extensions installed in VSCode: `Jupyter` and `Python`. - -2. Open VSCode and navigate to the directory containing the notebook. - -3. Open the notebook (e.g. `caimira/apps/expert/caimira.ipynb`) and run the cells by clicking the `run` button next to each cell. - -### Running the tests - -The project contains test files that separately test the functionality of the `caimira` backend and `cern_caimira` UI. - -To test the `caimira` package, from the root repository of the project: - -``` -cd caimira -pip install -e .[test] -python -m pytest -``` - -To test the `cern_caimira` package, from the root repository of the project: - -``` -cd cern_caimira -pip install -e .[test] -python -m pytest -``` - -### Running the profiler - -CAiMIRA includes a profiler designed to identify performance bottlenecks. The profiler is enabled when the environment variable `CAIMIRA_PROFILER_ENABLED` is set to 1. - -When visiting [http://localhost:8080/profiler](http://localhost:8080/profiler), you can start a new session and choose between [PyInstrument](https://github.com/joerick/pyinstrument) or [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile). The app includes two different profilers, mainly because they can give different information. - -Keep the profiler page open. Then, in another window, navigate to any page in CAiMIRA, for example generate a new report. Refresh the profiler page, and click on the `Report` link to see the profiler output. - -The sessions are stored in a local file in the `/tmp` folder. To share it across multiple web nodes, a shared storage should be added to all web nodes. The folder can be customized via the environment variable `CAIMIRA_PROFILER_CACHE_DIR`. - -### CAiMIRA API Usage - -From the root directory of the project: - -1. Run the backend API: - - ``` - python -m caimira.api.app - ``` - -2. The Tornado server will run on port `8081`. - -To test the API functionality, you can send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the request body. For an example of the required inputs, see [the baseline raw form data](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). - -The response format will be: - -```json -{ - "status": "success", - "message": "Results generated successfully", - "report_data": { - ... - }, - ... -} -``` - -For further details please refer to the [REST API official documentation](../code_documentation/rest_api/). - -### Building the whole environment for local development - -``` -docker build -f app-config/api-app/Dockerfile -t api-app . -docker build -f app-config/calculator-app/Dockerfile -t calculator-app . -docker build ./app-config/auth-service -t auth-service -``` - -If you are using a computer with ARM CPU (Mac M1/2/3), then add the arg `--platform linux/arm64` to the docker build cmd. - -If you need to debug the Docker build, add the args `--no-cache --progress=plain` to see a more verbose output in your terminal. - -Get the client secret from the CERN Application portal for the `caimira-test` app. See [CERN-SSO-integration](#cern-sso-integration) for more info. -``` -read CLIENT_SECRET -``` - -Define some env vars (copy/paste): -``` -export COOKIE_SECRET=$(openssl rand -hex 50) -export OIDC_SERVER=https://auth.cern.ch/auth -export OIDC_REALM=CERN -export CLIENT_ID=caimira-test -export CLIENT_SECRET=$CLIENT_SECRET -``` - -Run docker compose: -``` -cd app-config -CURRENT_UID=$(id -u):$(id -g) docker compose up -``` - -Then visit [http://localhost:8080/](http://localhost:8080/). - -### Setting up the application on OpenShift - -The [https://cern.ch/caimira](https://cern.ch/caimira) application is running on CERN's OpenShift platform. In order to set it up for the first time, we followed the documentation at [https://paas.docs.cern.ch/](https://paas.docs.cern.ch/). In particular we: - - * Added the OpenShift application deploy key to the GitLab repository - * Created a Python 3.12 (the highest possible at the time of writing) application in OpenShift - * Configured a generic webhook on OpenShift, and call that from the CI of the GitLab repository - -### Updating the caimira-test.web.cern.ch instance - -We have a replica of [https://caimira.web.cern.ch](https://caimira.web.cern.ch) running on [http://caimira-test.web.cern.ch](http://caimira-test.web.cern.ch). Its purpose is to simulate what will happen when -a feature is merged. To push your changes to caimira-test, simply push your branch to `live/caimira-test` and the CI pipeline will trigger the -deployment. To push to this branch, there is a good chance that you will need to force push - you should always force push with care and -understanding why you are doing it. Syntactically, it will look something like (assuming that you have "upstream" as your remote name, -but it may be origin if you haven't configured it differently): - - git push --force upstream name-of-local-branch:live/caimira-test - - -## OpenShift templates - -### First setup - -First, get the [oc](https://docs.okd.io/3.11/cli_reference/get_started_cli.html) client and then login: - -```console -$ oc login https://api.paas.okd.cern.ch -``` - -Then, switch to the project that you want to update: - -```console -$ oc project caimira-test -``` - -Create a new service account in OpenShift to access GitLab container registry: - -```console -$ oc create serviceaccount gitlabci-deployer -serviceaccount "gitlabci-deployer" created -``` - -Grant `edit` permission to the service account to run `oc set image` from CI an update the tag to deploy: -``` -$ oc policy add-role-to-user edit -z gitlabci-deployer -``` - -Get the service account token for GitLab: -``` -# We will refer to the output of this command as `test-token` -$ oc serviceaccounts get-token gitlabci-deployer -<...test-token...> -``` - -Add the token to GitLab to allow GitLab to access OpenShift and define/change image stream tags. Go to `Settings` -> `CI / CD` -> `Variables` -> click on `Expand` button and create the variable `OPENSHIFT_CAIMIRA_TEST_DEPLOY_TOKEN`: insert the token `<...test-token...>`. - -For CI usage, we also suggest creating a service account: - -```console -oc create sa gitlab-config-checker -``` - -Under ``User Management`` -> ``RoleBindings`` create a new `RoleBinding` to grant `View` access to the `gitlab-config-checker` service account: - -* name: `gitlab-config-checker-view-role` -* role name: `view` -* service account: `gitlab-config-checker` - -To get this new user's authentication token go to ``User Management`` -> ``Service Accounts`` -> `gitlab-config-checker` and locate the token in the newly created secret associated with the user (in this case ``gitlab-config-checker-token-XXXX``). Copy the `token` value from `Data`. - -Create the various configurations: - -```console -$ cd app-config/openshift - -$ oc process -f configmap.yaml | oc create -f - -$ oc process -f services.yaml | oc create -f - -$ oc process -f deployments.yaml | oc create -f - -``` - -Manually create the **route** to access the website, see `routes.example.yaml`. -After having created the route, make sure that you extend the HTTP request timeout annotation: the -report generation can take more time than the default 30 seconds. - -``` -$ oc annotate route caimira-route --overwrite haproxy.router.openshift.io/timeout=60s -``` - -### CERN SSO integration - -The SSO integration uses OpenID credentials configured in [CERN Applications portal](https://application-portal.web.cern.ch/). -How to configure the application: - -* Application Identifier: `caimira-test` -* Homepage: `https://caimira-test.web.cern.ch` -* Administrators: `caimira-dev` -* SSO Registration: - * Protocol: `OpenID (OIDC)` - * Redirect URI: `https://caimira-test.web.cern.ch/auth/authorize` - * Leave unchecked all the other checkboxes -* Define new roles: - * Name: `CERN Users` - * Role Identifier: `external-users` - * Leave unchecked checkboxes - * Minimum Level Of Assurance: `CERN (highest)` - * Assign role to groups: `cern-accounts-primary` e-group - * Name: `External accounts` - * Role Identifier: `admin` - * Leave unchecked checkboxes - * Minimum Level Of Assurance: `Any (no restrictions)` - * Assign role to groups: `caimira-app-external-access` e-group - * Name: `Allowed users` - * Role Identifier: `allowed-users` - * Check `This role is required to access my application` - * Minimum Level Of Assurance:`Any (no restrictions)` - * Assign role to groups: `cern-accounts-primary` and `caimira-app-external-access` e-groups - -Copy the client id and client secret and use it below. - -```console -$ COOKIE_SECRET=$(openssl rand -hex 50) -$ oc create secret generic \ - --from-literal="CLIENT_ID=$CLIENT_ID" \ - --from-literal="CLIENT_SECRET=$CLIENT_SECRET" \ - --from-literal="COOKIE_SECRET=$COOKIE_SECRET" \ - auth-service-secrets -``` - -### External APIs - -- **Geographical location:** - There is one external API call to fetch required information related to the geographical location inserted by a user. - The documentation for this geocoding service is available at [https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) . - Please note that there is no need for keys on this API call. It is **free-of-charge**. - -- **Humidity and Inside Temperature:** - for the `CERN theme` as the authorised sensors are installed at CERN." - -- **ARVE:** - The ARVE Swiss Air Quality System provides trusted air data for commercial buildings in real-time and analyzes it with the help of AI and machine learning algorithms to create actionable insights. - - Create secret: - - ```console - $ read ARVE_CLIENT_ID - $ read ARVE_CLIENT_SECRET - $ read ARVE_API_KEY - $ oc create secret generic \ - --from-literal="ARVE_CLIENT_ID=$ARVE_CLIENT_ID" \ - --from-literal="ARVE_CLIENT_SECRET=$ARVE_CLIENT_SECRET" \ - --from-literal="ARVE_API_KEY=$ARVE_API_KEY" \ - arve-api - ``` - -- **CERN Data Service:** - The CERN data service collects data from various sources and expose them via a REST API endpoint. - - The service is enabled when the environment variable `DATA_SERVICE_ENABLED` is set to 1. - -## Update configuration - -If you need to **update** existing configuration, then modify this repository and after having logged in, run: - -```console -$ cd app-config/openshift - - -$ oc process -f configmap.yaml | oc replace -f - -$ oc process -f services.yaml | oc replace -f - -$ oc process -f deployments.yaml | oc replace -f - -``` - -Be aware that if you create/recreate the environment you must manually create a **route** in OpenShift, -specifying the respective annotation to be exposed outside CERN. diff --git a/caimira/docs/mkdocs/docs/project_overview/about.md b/caimira/docs/mkdocs/docs/project_overview/about.md new file mode 100644 index 00000000..32a773a3 --- /dev/null +++ b/caimira/docs/mkdocs/docs/project_overview/about.md @@ -0,0 +1,105 @@ +Currently, the existing public health measures point to the importance of proper building and environmental engineering control measures, such as proper Indoor Air Quality (IAQ). This pandemic clearly raised increased awareness on airborne transmission of respiratory viruses in indoor settings. Out of the main modes of viral transmission, the airborne route of SARS-CoV-2 seems to have a significant importance to the spread of COVID-19 infections world-wide, hence proper guidance to building engineers or facility managers, on how to prevent on-site transmission, is essential. + +For information on the Airborne Transmission of SARS-CoV-2, feel free to check out the special issue on the Interface Focus journal from Royal Society publishing: [Interface Focus: Volume 12, Issue 2](https://royalsocietypublishing.org/toc/rsfs/2022/12/2) and an CERN HSE Seminar: [https://cds.cern.ch/record/2743403](https://cds.cern.ch/record/2743403). + +## What is CAiMIRA? + +CAiMIRA stands for CERN Airborne Model for Indoor Risk Assessment, a tool developed to assess and model the concentration of airborne viruses in enclosed spaces, specifically focusing on the SARS-CoV-2 virus. Originally named CARA (COVID Airborne Risk Assessment), CAiMIRA was first developed in early 2020 to quantify the risk of long-range airborne spread of SARS-CoV-2 in workplaces. Over time, the model has expanded to include short-range transmission, allowing for comprehensive simulations of both background (room) concentration and close-proximity interactions. + +CAiMIRA features applications with varying flexibility in setting input parameters: + +- CAiMIRA Calculator App +- CAiMIRA Expert App (deprecated) + +These applications produce clear and intuitive graphs, enabling users to adjust settings such as room volume, exposure time, activity type, mask-wearing, and ventilation levels. The tool generates reports indicating how users can avoid exceeding critical concentrations and reduce airborne transmission chains in spaces like individual offices, meeting rooms, and laboratories. + +The mathematical and physical model simulates the airborne spread of SARS-CoV-2 in a finite volume, using a homogenous mixture assumption and a two-stage exhaled jet model to estimate the risk of COVID-19 airborne transmission. Results do not account for other SARS-CoV-2 transmission modes, such as fomite or blood-bound transmission, meaning the output is only valid when paired with public health measures like good hand hygiene and barrier practices. + +The model is based on scientific publications on infectious disease transmission, virology, epidemiology, and aerosol science, as of February 2022. Its methodology, mathematical equations, and parameters are detailed in a peer-reviewed publication, Modelling airborne transmission of SARS-CoV-2 using CARA: risk assessment for enclosed spaces. The short-range model component draws from Jia et al. (2022), Exposure and respiratory infection risk via the short-range airborne route. This foundation enables CAiMIRA to compare the effectiveness of different airborne risk mitigation measures. + +CAiMIRA’s methodology is divided into key steps: + +- Estimating the emission rate of virions +- Estimating the removal rate of virions +- Modeling the concentration of virions within a specified volume over time +- Calculating the dose of inhaled infectious viruses during exposure +- Estimating the probability of COVID-19 infection and the potential number of new cases arising from an event + +The model assumes a deterministic approach—at least one individual is infected and shedding virus into the simulated environment. While it calculates the infection probability for specific scenarios, the model's primary utility is in comparing the relative impact of different preventive measures, such as ventilation, filtration, exposure time, physical activity, and close-range interactions. + +Although CAiMIRA allows users to calculate the infection probability for a specific event given pre-set protection measures, its primary function is to facilitate comparisons between different mitigation, helping users decide on measures to reduce airborne infection risks. Examples include: + +- Comparing slight versus full window openings +- Evaluating intermittent versus continuous ventilation +- Assessing the impact of using FFP2 masks over Type I surgical masks or Cloth masks +- Determining maximum occupancy based on HEPA filter use + +This approach supports informed decision-making and optimized investment by showing the relative effectiveness of each measure. Importantly, while CAiMIRA can guide users in reducing risk, it does not provide an absolute “zero risk” or “completely safe scenario”. + +Risk is unique to each event and setting, influenced by variables such as probability of exposure and input assumptions. + +## Collaboration with the World Health Organization (WHO) + +The tool has attracted the attention of many international organisations, including the World Health Organization (WHO) and the United Nations Office at Geneva (UNOG). In June 2021, CERN shared its own approach towards risk assessments for occupational hazards, which was at the time called CARA, to WHO's COVID Expert Panel. + +As a result, WHO has invited CERN to become a member of a multidisciplinary expert group of international experts called ARIA, which will work to define a standardised algorithm to quantify airborne transmission risk in indoor settings. This will ensure that the model inculdes not only the science related to aerosol science but also the virological effects, such as host-pathogen interaction. + +The collaboration takes place within CERNs wide-ranging engagement with other international organisations, promoting shared solutions to societal challenges. + +## Authors +CAiMIRA was developed by the following members of CERN - European Council for Nuclear Research (visit [https://home.cern/](https://home.cern/)) and WHO - World Health Organization: + +Andre Henriques1, Luis Aleixo1, Marco Andreini1, Gabriella Azzopardi2, James Devine3, Philip Elson4, Nicolas Mounet2, Markus Kongstein Rognlien2,6, Nicola Tarocco5, Luca Fontana7, Alice Simniceanu7 + +1HSE Unit, Occupational Health & Safety Group, CERN
+2Beams Department, Accelerators and Beam Physics Group, CERN
+3Experimental Physics Department, Safety Office, CERN
+4Beams Department, Controls Group, CERN
+5Information Technology Department, Collaboration, Devices & Applications Group, CERN
+6Norwegian University of Science and Technology (NTNU)
+7World Health Organization (WHO)
+ +#### Other contributors + +Anna Efimova1,2, Anel Massalimova1,3, Cole Austin Coughlin1,4, Germain Personne5 + +1Summer Student Programme, CERN
+2M.V. Lomonosov Moscow State University
+3National Research Nuclear University "MEPhI"
+4University of Manitoba
+5Université Clermont Auvergne
+ +## Reference and Citation + +**For the use of the CAiMIRA web app** + +CAiMIRA – CERN Airborne Model for Indoor Risk Assessment tool + +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6520431.svg)](https://doi.org/10.5281/zenodo.6520431) + +© Copyright 2020-2021 CERN. All rights not expressly granted are reserved. + +**For use of the CAiMIRA model** + +Henriques A, Mounet N, Aleixo L, Elson P, Devine J, Azzopardi G, Andreini M, Rognlien M, Tarocco N, Tang J. (2022). Modelling airborne transmission of SARS-CoV-2 using CARA: risk assessment for enclosed spaces. _Interface Focus 20210076_. [https://doi.org/10.1098/rsfs.2021.0076](https://doi.org/10.1098/rsfs.2021.0076) + +Reference on the Short-range expiratory jet model from: +Jia W, Wei J, Cheng P, Wang Q, Li Y. (2022). Exposure and respiratory infection risk via the short-range airborne route. _Building and Environment_ *219*: 109166. +[https://doi.org/10.1016/j.buildenv.2022.109166](https://doi.org/10.1016/j.buildenv.2022.109166) + +***Open Source Acknowledgments*** + +For a detailed list of the open-source dependencies used in this project along with their respective licenses, please refer to [Open Source Acknowledgments](open_source_acknowledgments.md). This includes both the core dependencies specified in the project's requirements and their transitive dependencies. + +The information also features a distribution diagram of licenses and a brief description of each of them. + +## Acknowledgements + +We wish to thank CERN at the different Departments working on the project: Occupational Health & Safety and Environmental Protection Unit, Information Technology Department, Beams Department, Experimental Physics Department, Industry, Procurement and Knowledge Transfer Department and International Relations Sector for their support to the study. We also wish to thank our collaborators at the World Health Organization (WHO) for thier endless support to this project, in particular to the members of the ARIA Expert Group. + +## Disclaimer + +CAiMIRA has not undergone review, approval or certification by competent authorities, and as a result, it cannot be considered as a fully endorsed and reliable tool, namely in the assessment of potential viral emissions from infected hosts to be modelled. + +The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and non-infringement. +In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/project_overview/deployment.md b/caimira/docs/mkdocs/docs/project_overview/deployment.md new file mode 100644 index 00000000..457680d7 --- /dev/null +++ b/caimira/docs/mkdocs/docs/project_overview/deployment.md @@ -0,0 +1,140 @@ +The [https://cern.ch/caimira](https://cern.ch/caimira) application is running on CERN's OpenShift platform. In order to set it up for the first time, we followed the documentation at [https://paas.docs.cern.ch/](https://paas.docs.cern.ch/). In particular we: + + * Added the OpenShift application deploy key to the GitLab repository + * Created a Python 3.12 (the highest possible at the time of writing) application in OpenShift + * Configured a generic webhook on OpenShift, and call that from the CI of the GitLab repository + +## OpenShift templates + +For the first setup, get the [oc](https://docs.okd.io/3.11/cli_reference/get_started_cli.html) client and then login: + +```console +$ oc login https://api.paas.okd.cern.ch +``` + +Then, switch to the project that you want to update: + +```console +$ oc project caimira-test +``` + +Create a new service account in OpenShift to access GitLab container registry: + +```console +$ oc create serviceaccount gitlabci-deployer +serviceaccount "gitlabci-deployer" created +``` + +Grant `edit` permission to the service account to run `oc set image` from CI an update the tag to deploy: +``` +$ oc policy add-role-to-user edit -z gitlabci-deployer +``` + +Get the service account token for GitLab: +``` +# We will refer to the output of this command as `test-token` +$ oc serviceaccounts get-token gitlabci-deployer +<...test-token...> +``` + +Add the token to GitLab to allow GitLab to access OpenShift and define/change image stream tags. Go to `Settings` -> `CI / CD` -> `Variables` -> click on `Expand` button and create the variable `OPENSHIFT_CAIMIRA_TEST_DEPLOY_TOKEN`: insert the token `<...test-token...>`. + +For CI usage, we also suggest creating a service account: + +```console +oc create sa gitlab-config-checker +``` + +Under ``User Management`` -> ``RoleBindings`` create a new `RoleBinding` to grant `View` access to the `gitlab-config-checker` service account: + +* name: `gitlab-config-checker-view-role` +* role name: `view` +* service account: `gitlab-config-checker` + +To get this new user's authentication token go to ``User Management`` -> ``Service Accounts`` -> `gitlab-config-checker` and locate the token in the newly created secret associated with the user (in this case ``gitlab-config-checker-token-XXXX``). Copy the `token` value from `Data`. + +Create the various configurations: + +```console +$ cd app-config/openshift + +$ oc process -f configmap.yaml | oc create -f - +$ oc process -f services.yaml | oc create -f - +$ oc process -f deployments.yaml | oc create -f - +``` + +Manually create the **route** to access the website, see `routes.example.yaml`. +After having created the route, make sure that you extend the HTTP request timeout annotation: the +report generation can take more time than the default 30 seconds. + +``` +$ oc annotate route caimira-route --overwrite haproxy.router.openshift.io/timeout=60s +``` + +## CERN SSO integration + +The SSO integration uses OpenID credentials configured in [CERN Applications portal](https://application-portal.web.cern.ch/). +How to configure the application: + +* Application Identifier: `caimira-test` +* Homepage: `https://caimira-test.web.cern.ch` +* Administrators: `caimira-dev` +* SSO Registration: + * Protocol: `OpenID (OIDC)` + * Redirect URI: `https://caimira-test.web.cern.ch/auth/authorize` + * Leave unchecked all the other checkboxes +* Define new roles: + * Name: `CERN Users` + * Role Identifier: `external-users` + * Leave unchecked checkboxes + * Minimum Level Of Assurance: `CERN (highest)` + * Assign role to groups: `cern-accounts-primary` e-group + * Name: `External accounts` + * Role Identifier: `admin` + * Leave unchecked checkboxes + * Minimum Level Of Assurance: `Any (no restrictions)` + * Assign role to groups: `caimira-app-external-access` e-group + * Name: `Allowed users` + * Role Identifier: `allowed-users` + * Check `This role is required to access my application` + * Minimum Level Of Assurance:`Any (no restrictions)` + * Assign role to groups: `cern-accounts-primary` and `caimira-app-external-access` e-groups + +Copy the client id and client secret and use it below. + +```console +$ COOKIE_SECRET=$(openssl rand -hex 50) +$ oc create secret generic \ + --from-literal="CLIENT_ID=$CLIENT_ID" \ + --from-literal="CLIENT_SECRET=$CLIENT_SECRET" \ + --from-literal="COOKIE_SECRET=$COOKIE_SECRET" \ + auth-service-secrets +``` + +## Updating OpenShift configuration + +If you need to **update** existing configuration, then modify this repository and after having logged in, run: + +```console +$ cd app-config/openshift + + +$ oc process -f configmap.yaml | oc replace -f - +$ oc process -f services.yaml | oc replace -f - +$ oc process -f deployments.yaml | oc replace -f - +``` + +Be aware that if you create/recreate the environment you must manually create a **route** in OpenShift, +specifying the respective annotation to be exposed outside CERN. + + +## Updating the TEST instance + +We have a replica of [https://caimira.web.cern.ch](https://caimira.web.cern.ch) running on [http://caimira-test.web.cern.ch](http://caimira-test.web.cern.ch). Its purpose is to simulate what will happen when +a feature is merged. To push your changes to caimira-test, simply push your branch to `live/caimira-test` and the CI pipeline will trigger the +deployment. To push to this branch, there is a good chance that you will need to force push - you should always force push with care and +understanding why you are doing it. Syntactically, it will look something like (assuming that you have "upstream" as your remote name, +but it may be origin if you haven't configured it differently): + + git push --force upstream name-of-local-branch:live/caimira-test + diff --git a/caimira/docs/mkdocs/docs/project_overview/installation.md b/caimira/docs/mkdocs/docs/project_overview/installation.md new file mode 100644 index 00000000..1c579785 --- /dev/null +++ b/caimira/docs/mkdocs/docs/project_overview/installation.md @@ -0,0 +1,230 @@ +## Docker + +### Using the pre-built image + +The easiest way to run a version of CAiMIRA Calculator is to use docker. A pre-built +image of CAiMIRA is made available at [https://gitlab.cern.ch/caimira/caimira/container_registry](https://gitlab.cern.ch/caimira/caimira/container_registry). +In order to run CAiMIRA locally with docker, run the following: + + $ docker run -it -p 8080:8080 gitlab-registry.cern.ch/caimira/caimira/calculator + +This will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/). + +### Building the whole environment + +To build the whole environment for local development, from the root directory of the project, run: + +``` +docker build -f app-config/api-app/Dockerfile -t api-app . +docker build -f app-config/calculator-app/Dockerfile -t calculator-app . +docker build ./app-config/auth-service -t auth-service +``` + +If you are using a computer with ARM CPU (Mac M1/2/3), then add the arg `--platform linux/arm64` to the docker build cmd. + +If you need to debug the Docker build, add the args `--no-cache --progress=plain` to see a more verbose output in your terminal. + +Get the client secret from the CERN Application portal for the `caimira-test` app. See [CERN-SSO-integration](deployment.md#cern-sso-integration) for more info. +``` +read CLIENT_SECRET +``` + +Define some env vars (copy/paste): +``` +export COOKIE_SECRET=$(openssl rand -hex 50) +export OIDC_SERVER=https://auth.cern.ch/auth +export OIDC_REALM=CERN +export CLIENT_ID=caimira-test +export CLIENT_SECRET=$CLIENT_SECRET +``` + +Run docker compose: +``` +cd app-config +CURRENT_UID=$(id -u):$(id -g) docker compose up +``` + +Then visit [http://localhost:8080/](http://localhost:8080/). + +## Development mode + +CAiMIRA is mirrored to Github if you wish to collaborate on development and can be found at: [https://github.com/CERN/caimira](https://github.com/CERN/caimira) + +### Folder structure + +The project contains two different Python packages: + +- `caimira`: Contains all the backend logic and the calculator model. It is the package published in PyPI. +- `cern_caimira`: Imports and uses the backend package (`caimira`) and includes CERN-specific UI implementation. + +The folder layout follows best practices as described [here](https://ianhopkinson.org.uk/2022/02/understanding-setup-py-setup-cfg-and-pyproject-toml-in-python/). + +### Installing and running CAiMIRA + +Installing CAiMIRA in editable mode and running the Calculator App. + +#### Installing + +In order to install the CAiMIRA's backend logic, create your own `virtualenv` and, from the root directory of the project, run: + +``` +cd caimira +pip install -e . +``` + +In order to install the CERN-specific UI version, that links to the previously installed backend, activate your `virtualenv` and, from the root directory of the project, run: + +``` +cd cern_caimira +pip install -e . +``` + +#### Running + +This example describes how to run the calculator with the CERN-specific UI. In the root directory of the project: + +``` +python -m cern_caimira.apps.calculator +``` + +To run with a specific template theme created: + +``` +python -m cern_caimira.apps.calculator --theme=cern_caimira/src/cern_caimira/apps/templates/{theme} +``` + +To run the entire app in a different `APPLICATION_ROOT` path: + +``` +python -m cern_caimira.apps.calculator --app_root=/myroot +``` + +To run the calculator on a different URL path: + +``` +python -m cern_caimira.apps.calculator --prefix=/mycalc +``` + +Each of these commands will start a local version of CAiMIRA, which can be visited at [http://localhost:8080/](http://localhost:8080/). + +#### REST API + +To use the REST API, from the root directory of the project: + +1. Run the backend API: + + ``` + python -m caimira.api.app + ``` + +2. The Tornado server will run on port `8081`. + +To test the API functionality, you can send a `POST` request to `http://localhost:8081/virus_report` with the required inputs in the request body. For an example of the required inputs, see [the baseline raw form data](https://gitlab.cern.ch/caimira/caimira/blob/master/caimira/src/caimira/calculator/validators/virus/virus_validator.py#L565). + +The response format will be: + +```json +{ + "status": "success", + "message": "Results generated successfully", + "report_data": { + ... + }, + ... +} +``` + +For further details please refer to the [REST API documentation page](../code_documentation/rest_api.md). + +#### Running the Expert-Apps + +The CAiMIRA Expert App and the CO2 App are tools to dynamically interact with various parameters of the CAiMIRA model. + +##### Disclaimer + +The `ExpertApplication` and `CO2Application` are no longer actively maintained but will remain in the codebase for legacy purposes. +Please note that the functionality of these applications might be compromised due to deprecation issues. + +##### Running the Applications + +These applications only work within Jupyter notebooks. Attempting to run them outside of a Jupyter environment may result in errors or degraded functionality. + +Make sure you have the needed dependencies installed: + +``` +pip install notebook jupyterlab +``` + +Running with Visual Studio Code (VSCode): + +1. Ensure you have the following extensions installed in VSCode: `Jupyter` and `Python`. + +2. Open VSCode and navigate to the directory containing the notebook. + +3. Open the notebook (e.g. `caimira/apps/expert/caimira.ipynb`) and run the cells by clicking the `run` button next to each cell. + + +### Installing and running tests + +The project contains test files that separately test the functionality of the `caimira` backend and `cern_caimira` UI. + +To test the `caimira` package, from the root repository of the project: + +``` +cd caimira +pip install -e .[test] +python -m pytest +``` + +To test the `cern_caimira` package, from the root repository of the project: + +``` +cd cern_caimira +pip install -e .[test] +python -m pytest +``` + +### Running the profiler + +CAiMIRA includes a profiler designed to identify performance bottlenecks. The profiler is enabled when the environment variable `CAIMIRA_PROFILER_ENABLED` is set to 1. + +When visiting [http://localhost:8080/profiler](http://localhost:8080/profiler), you can start a new session and choose between [PyInstrument](https://github.com/joerick/pyinstrument) or [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile). The app includes two different profilers, mainly because they can give different information. + +Keep the profiler page open. Then, in another window, navigate to any page in CAiMIRA, for example generate a new report. Refresh the profiler page, and click on the `Report` link to see the profiler output. + +The sessions are stored in a local file in the `/tmp` folder. To share it across multiple web nodes, a shared storage should be added to all web nodes. The folder can be customized via the environment variable `CAIMIRA_PROFILER_CACHE_DIR`. + +### Compiling and viewing the docs + +To compile and view CAiMIRA's documentation, follow these steps: + +1. Install CAiMIRA with Documentation Dependencies + + First, ensure CAiMIRA is installed along with the `doc` dependencies: + + cd caimira + pip install -e .[doc] + +2. Generate Code Documentation in Markdown + + Use `sphinx` with `sphinx_markdown_builder` to generate the documentation in `Markdown` format: + + cd docs/sphinx + sphinx-build -b markdown . _build/markdown + +3. Customize and Organize Documentation + + Run the `style_docs.py` script to apply custom styles, move required files, and generate a UML diagram: + + python style_docs.py \ + && mv sphinx/_build/markdown/index.md mkdocs/docs/code_documentation/models.md \ + && pyreverse -o png -p UML-CAiMIRA --output-directory mkdocs/docs ../src/caimira/calculator/models/models.py + +4. Start the documentation server + + To view the documentation locally, use MkDocs to serve it: + + cd ../mkdocs + python -m mkdocs serve --dev-addr=0.0.0.0:8080 + + The documentation can now be accessed at [http://0.0.0.0:8080/](http://0.0.0.0:8080/). diff --git a/caimira/docs/mkdocs/docs/open_source_acknowledgments.md b/caimira/docs/mkdocs/docs/project_overview/open_source_acknowledgments.md similarity index 79% rename from caimira/docs/mkdocs/docs/open_source_acknowledgments.md rename to caimira/docs/mkdocs/docs/project_overview/open_source_acknowledgments.md index ca84fd2a..5c93eb0e 100644 --- a/caimira/docs/mkdocs/docs/open_source_acknowledgments.md +++ b/caimira/docs/mkdocs/docs/project_overview/open_source_acknowledgments.md @@ -1,12 +1,10 @@ -# Open Source Acknowledgments - -# Disclaimer +#### Disclaimer The following list includes the open-source dependencies used in this project, along with their respective licenses. It covers both the core dependencies explicitly specified in the project's requirements, as well as their transitive dependencies (dependencies of dependencies). Including transitive dependencies is essential to acknowledge the full spectrum of open-source contributions that contribute to the functionality of this project. It also ensures compliance with open-source licenses and recognizes the efforts of all contributors, even those indirectly involved. -## CAiMIRA tool is Open Source +## External Libraries ??? "Back-end (Python) Dependencies" ??? "Front-end (JavaScript) Dependencies" @@ -34,10 +32,6 @@ Including transitive dependencies is essential to acknowledge the full spectrum ??? "Other references" - #### Arve - - - Endpoint: `https://www.arveair.com/terms-and-conditions/` - #### Rest Countries - License: [MP License 2.0](https://gitlab.com/restcountries/restcountries/-/blob/master/LICENSE?ref_type=heads) @@ -67,11 +61,43 @@ Including transitive dependencies is essential to acknowledge the full spectrum - Endpoint: `https://www.covid19.admin.ch/en/epidemiologic/case/d/development?epiRelDev=abs` + ### External APIs + + - **Geographical location**: + + There is one external API call to fetch required information related to the geographical location inserted by a user. + The documentation for this geocoding service is available at [https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm](https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm) . + Please note that there is no need for keys on this API call. It is **free-of-charge**. + + - **Humidity and Inside Temperature**: + + For the `CERN theme` as the authorized sensors are installed at CERN. + + - **ARVE**: + + The ARVE Swiss Air Quality System provides trusted air data for commercial buildings in real-time and analyzes it with the help of AI and machine learning algorithms to create actionable insights. Terms and Conditions available here [https://www.arveair.com/terms-and-conditions/](https://www.arveair.com/terms-and-conditions/). + + Create secret: + + $ read ARVE_CLIENT_ID + $ read ARVE_CLIENT_SECRET + $ read ARVE_API_KEY + $ oc create secret generic \ + --from-literal="ARVE_CLIENT_ID=$ARVE_CLIENT_ID" \ + --from-literal="ARVE_CLIENT_SECRET=$ARVE_CLIENT_SECRET" \ + --from-literal="ARVE_API_KEY=$ARVE_API_KEY" \ + arve-api + + - **CERN Data Service**: + + The CERN data service collects data from various sources and expose them via a REST API endpoint. + The service is enabled when the environment variable `DATA_SERVICE_ENABLED` is set to 1. + ### License Distribution -![License Distribution](license_distribution.png) +![License Distribution Pie Chart](license_distribution.png) -### License information +## List of Open Source Licenses The list of open-source dependencies provided here includes licenses for both direct dependencies and dependencies of dependencies. This comprehensive list covers a wide range of licenses, each with its own terms and conditions. Below is a summary of the most frequently encountered licenses along with their descriptions and usage: diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md b/caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md new file mode 100644 index 00000000..c97bd73d --- /dev/null +++ b/caimira/docs/mkdocs/docs/project_overview/user_guide/full_guide.md @@ -0,0 +1,207 @@ +## CAiMIRA Calculator + +This guide helps on how to use the calculator app. For more information on the Airborne Transmission of SARS-CoV-2, feel free to check out the HSE Seminar: [https://cds.cern.ch/record/2743403](https://cds.cern.ch/record/2743403) + +The methodology, mathematical equations and parameters of the model are described here in the CERN Report: [CERN-OPEN-2021-004](https://cds.cern.ch/record/2756083) + +??? "Disclaimer" + + CAiMIRA is a risk assessment tool developed to model the concentration of viruses in enclosed spaces, in order to inform space-management decisions. + + CAiMIRA models the concentration profile of virions in enclosed spaces with clear and intuitive graphs. The user can set a number of parameters, including room volume, exposure time, activity type, mask-wearing and ventilation. The report generated indicates how to avoid exceeding critical concentrations and chains of airborne transmission in spaces such as individual offices, meeting rooms and labs. + + The risk assessment tool simulates the airborne spread SARS-CoV-2 virus in a finite volume, assuming homogenous mixing for the long-range component and a two-stage jet model for short-range, and estimates the risk of COVID-19 airborne transmission therein. The results DO NOT include other known modes of SARS-CoV-2 transmission, such as contact or fomite. Hence, the output from this model is only valid when the other recommended public health & safety instructions are observed, such as adequate physical distancing, good hand hygiene and other barrier measures. + + The model used is based on scientific publications relating to airborne transmission of infectious diseases, dose-response exposures and aerosol science, as of February 2021. It can be used to compare the effectiveness of different airborne-related risk mitigation measures. + + Note that this model applies a deterministic approach, i.e., it is assumed at least one person is infected and shedding viruses into the simulated volume. Nonetheless, it is also important to understand that the absolute risk of infection is uncertain, as it will depend on the probability that someone infected attends the event. The model is most useful for comparing the impact and effectiveness of different mitigation measures such as ventilation, filtration, exposure time, physical activity, amount and nature of close-range interactions and the size of the room, considering both long- and short-range airborne transmission modes of COVID-19 in indoor settings. + + This tool is designed to be informative, allowing the user to adapt different settings and model the relative impact on the estimated infection probabilities. The objective is to facilitate targeted decision-making and investment through comparisons, rather than a singular determination of absolute risk. While the SARS-CoV-2 virus is in circulation among the population, the notion of 'zero risk' or 'completely safe scenario' does not exist. Each event modelled is unique, and the results generated therein are only as accurate as the inputs and assumptions. + + CAiMIRA has not undergone review, approval or certification by competent authorities, and as a result, it cannot be considered as a fully endorsed and reliable tool, namely in the assessment of potential viral emissions from infected hosts to be modelled. + +### Simulation Name & Room number + +In order to be able to trace back the simulations in your workplace risk assessments, performed with the tool, you can give each one a unique name - for example "Office use on Tuesday mornings". The simulation name has no bearing on the calculation. + +A room number is included, if you do not wish to use a formal room number any reference will do - for example "57/2-004". + +### Virus Data + +Please choose the correct virus strain or any reported Variant of Concern (VOC) from the list. Changing this setting alters the properties of the virus which are used for the simulation. This has a significant effect on the probability of infection. The choices are: + +- **SARS-CoV-2 (nominal strain)**, covering typical strains and variants which are not of concern from an epidemiologic point of view of the virus; +- **SARS-CoV-2 (Alpha VOC)**, first identified in the UK at the end of 2020 which is found to be approximately 1.5x more transmissible compared to the non-VOCs; +- **SARS-CoV-2 (Beta VOC)**, first identified in South Africa in May 2020 which is found to be approximately 1.25x more transmissible compared to the non-VOCs; +- **SARS-CoV-2 (Gamma VOC)**, first identified in Brazil in January 2021 which is found to be approximately 2.2x more transmissible compared to the non-VOCs. +- **SARS-CoV-2 (Delta VOC)**, first identified in India towards the end of 2020 which is found to be approximately 60% more transmissible compared to the ALPHA VOC. +- **SARS-CoV-2 (Omicron VOC)**, first identified in South Africa in November 2021 which is found to be at least 2.53x more transmissible compared to the DELTA VOC. + +The user can modify the selected variant from the default, according to the prevalence of the different variants in the local area, e.g. for [Geneva](https://www.covid19.admin.ch/fr/epidemiologic/virus-variants?detGeo=GE). + +N.B. The transmission data for the Gamma variant has been taken from a study data gathered in Manaus, Brazil where the variant was first observed. The local population in Manaus had very high levels of Covid-19 antibodies (>67%) in recent months. This factor has been taken into account by the authors of the study, via statistical adjustments to the transmission value (i.e. it has been increased, to account for spread in a population with significant acquired Covid-19 immunity). However, this value may be revised in the future as more studies of the Gamma VOC transmission in different geographical locations become available. + +#### Vaccine effectiveness + +The vaccination input corresponds to the vaccine type(s) administrated to the exposed population, assuming every exposed (or the occupant in question) has received the vaccine cocktail selected by the user. The respective vaccine effectiveness values were extracted from data available in [Results of COVID-19 Vaccine Effectiveness Studies: An Ongoing Systematic Review - Updated September 8, 2022](https://view-hub.org/resources), using this [script](https://gitlab.cern.ch/caimira/caimira/-/blob/master/caimira/src/caimira/scripts/data/vaccine_effectiveness.py). + +### Room Data + +Please enter either the room volume (in m³) or both the floor area (m²) and the room height (m). This information is available via GIS Portal ([https://gis.cern.ch/gisportal/](https://gis.cern.ch/gisportal/)). + +#### Room heating system + +The use of central heating (e.g. radiators) reduces relative humidity of the indoor air, which can decrease the decay rate of viral infectivity. If your space is heated with such water radiators, select 'Yes'. If your space does not have such heating, or they are not in use in the period of the simulation (e.g. summer), select 'No'. + +### Ventilation type + +There are three main options: + +#### Mechanical ventilation + +If the room has mechanical ventilation, supplying fresh air from outside (either a local or centralized system), you should select this option. In order to make an accurate calculation you will need to know either the flow rate of fresh air supplied in the room or th total number of air changes per hour with fresh air. + +Please bear in mind that any of the two inputs only consider the supply of fresh air. If a portion of air is recirculated, it shall not be accounted for in the inputs. + +#### Natural ventilation + +Natural ventilation refers to rooms which have openable windows. There are many possibilities to calculate natural ventilation air flows, for simplification this tool assumes a single-sided natural ventilation scheme which is a conservative approach for the purpose of this tool. + +Please choose the type of window (see illustration below): + +- Sliding or side-hung +- Top- or bottom-hung + +![How to determine the window type](img/window_type.PNG) + +Please enter the number, height and width and opening distance of the windows (in m). If there are multiple windows of different sizes, you should take an average. + +The window opening distance (in m) is: + +- In the case of Sliding or Side-Hung option, the length the window is moved open. Window opening distance example (image of open window and measuring tape): + + ![How to measure window opening distance](img/window_opening.png) + +- In case of Top- or Bottom-Hung, the distance between the fixed frame and the movable glazed part when open. + +**Notes**: If you are unsure about the opening distance for the window, it is recommended to choose a conservative value (5 cms, 0.05m or 10cms, 0.10m). If you open the window at different distances throughout the day, choose an average value. +When using natural ventilation, the circulation of air is simulated as a function of the difference between the temperature inside the room and the outside air temperature. The average outdoor temperature for each hour of the day has been computed for every month of the year based on historical data for Geneva, Switzerland. It is therefore very important to enter the correct time and date in the event data section. Finally, you must specify if the windows are open permanently (at all the times), or periodically (in intervals for a certain duration during the course of the day) - e.g. open the window for 10 minutes (duration) every 60 minutes (frequency). + +#### No ventilation + +This option assumes there is neither Mechanical nor Natural ventilation in the simulation. + +#### HEPA filtration + +A HEPA filter is a high efficiency particulate matter filter, which removes small airborne particles from the air. They can be very useful for removing particles with viruses from the air in an enclosed space. The calculator allows you to simulate the installation of a HEPA air filter within the room. The recommended airflow rate for the HEPA filter should correspond to a total air exchange rate of 3 - 6 ACH (the higher the better, even beyond 6). + +### Event data + +Here we capture the information about the event being simulated. First enter the number of occupants in the space, if you have a (small) variation in the number of people, please input the average or consider using the expert tool. Within the number of people occupying the space, you should specify how many are infected. + +In case one would like to simulate an event happening at a given time and location, where the epidemiological situation is known, the tool allows for an estimation of the probability of on-site transmission, considering the chances that a given person in the event is infected. The user will need to select **Probabilistic event**, input the number of inhabitants and the the weekly (7-day rolling average) value of new reported laboratory - ⁠confirmed cases at the event location, as well as the confidence level of these inputs. The 7-day rolling average consists in the average of the previous 3 days to subsequent 3 days, generally reported by the different public health authorities (e.g. in Switzerland [here](https://www.covid19.admin.ch/en/epidemiologic/case/d/development?epiRelDev=abs)). These two inputs need to the related, i.e. the values of reported new cases and the number of inhabitants shall correspond to the a same geographical location. For example: + +- Population of Geneva, CH: 508 000 inhabitants +- New lab reported cases in the canton of Geneva: 1000 (7-day rolling average) + +The confidence level allows for an ascertainment bias to the data. The user can add the following options: + +- High - mandatory population wide surveillance +- Medium - recommended population-wide surveillance +- Low - surveillance only for symptomatic patients + +Depending on the epidemiological situation in the chosen location, the public health surveillance can be more or less active. The confidence level will provide an ascertainment bias to the data collected by the user. +The higher the incidence rate (i.e. new cases / population) the higher are the chances of having at least one infected occupant participating to the event. + +For general and recurrent layout simply select the **Deterministic exposure** option. As an example, for a shared office with 4 people, where one person is infected, we enter 4 occupants and 1 infected person. + +#### Activity type + +There are a few predefined activities in the tool at present. + +- **Office** - All persons seated, talking occasionally (1/3rd of the time, with normal breathing the other 2/3rds of the time). Everyone (exposed and infected occupants) is treated the same in this model. +- **Small meeting** - Less than 10 participants. All persons seated, having a conversation (approximately each occupant is 1/N % of the time talking, where N is the number of occupants). Everyone (exposed and infected occupants) is treated the same in this model. +- **Large Meeting** - 10 or more participants. Similar to a seminar with 'speakers and audience'. Infected occupant(s) is standing and speaking 1/3rd of the time, while the other occupants are seated. +- **Library** - All persons seated, breathing only (not talking), all the time. +- **Call Centre** - All persons seated, all talking simultaneously, all the time. This is a conservative profile, i.e. will show an increased P(i) compared to office/meeting activity. Everyone (exposed and infected occupants) is treated the same in this model. +- **Control Room (day shift)** - All persons seated, all talking 50% of the time. This is a conservative profile, i.e. will show an increased P(i) compared to office/meeting activity. Everyone (exposed and infected occupants) is treated the same in this model. +- **Control Room (night shift)** - All persons seated, all talking 10% of the time. Everyone (exposed and infected occupants) is treated the same in this model. +- **Lab** - Based on a typical lab or technical working area, all persons are doing light activity and talking 50% of the time. Everyone (exposed and infected occupants) is treated the same in this model. +- **Workshop** - Based on a mechanical assembly workshop or equipment installation scenario, all persons are doing moderate activity and talking 50% of the time. This activity is equally applicable to bicycling, or walking on a gradient, in the LHC tunnels. Everyone (exposed and infected occupants) is treated the same in this model. +- **Conference/Training (speaker infected)** - Based on a typical conference/training course scenario. One individual (the speaker/trainer) is standing and talking, with all other individuals seated and talking quietly (whispering). In this case it is assumed that the infected person is the speaker/trainer, because this is the worst case in terms of viral shedding. +- **Conference/Training (attendee infected)** - All individuals seated and breathing. In this case it is assumed that the infected person is not the speaker/trainer. +- **Gym** - All persons are doing heavy exercise and breathing (not talking). Everyone (exposed and infected occupants) is treated the same in this model. + +### Timings + +You should enter the time (hours:minutes) for the start and end of the simulation period (i.e. 8:30 to 17:30 for a typical office day). It is important to enter the correct times for the simulation, in particular when using natural ventilation. It is possible to specify a different time for the entry and exit of both the exposed and infected person, however for most cases (where we do not know apriori which of the occupants is infected), it is recommended to set these to the same values as the activity start and end. + +#### When is the event? + +This is included for completeness in all simulations, however it is of particular relevance to those using natural ventilation because of variations in outside air temperature. + +Only the month is used by the model to retrieve the average outdoor air temperatures for the Geneva region. + +### Breaks + +#### Lunch break + +You have the option to specify a lunch break. This will be useful if you plan to simulate a typical full working day. During the lunch break it is assumed that all occupants will leave the simulated space (to go eat lunch somewhere else - restaurant or break room). If you plan to eat lunch in the same area where you have been working, you should select 'No' even if a lunch break will be taken, since the risk of infection is related to the occupation of the simulated space. See 'Split Breaks' if the occupants do not break at the same time. + +It should also be noted that the infection probabilities presented in the report does not take into account any potential exposures during the break times. + +#### Coffee breaks + +You have the option to choose 0(No breaks), 2 or 4 coffee breaks during the simulated period. It is assumed that all occupants vacate the space during the break period. If coffee breaks are taken in-situ, this option should be set to 'No breaks'. + +When enabled, the breaks are spread equally throughout the day - for example if we simulate the period from 9:00 to 18:00, with a lunch break from 13:00 to 14:00 and considering 2 coffee breaks, the tool will schedule the first coffee break around 11:00 and the second around 16:00. The exact timing of the breaks within the day is not particularly critical to an accurate simulation, so you do not need to be concerned about major differences if you take a coffee break at 10:00 instead of 11:00. The variation of coffee breaks can be altered in 5 minute increments up to 30 minutes in length. Note that this doesn't necessarily have to be a coffee break, it can represent any period where the simulated space is vacated. See 'Split Breaks' if the occupants do not break at the same time. + +It should also be noted that the infection probabilities presented in the report does not take into account any potential exposures during the break times. + +#### Split breaks + +You have the option to specify whether the exposed and infected person(s) break at the same time. If not, then you can input separate breaks. This is particularly different when specifying coffee breaks as they are spread evenly throughout the activity times specified. + +If we take an example where the exposed person(s) activity time is from 9:00 to 18:00 and the infected person(s) is from 10:00 to 17:00, with both having a lunch break from 13:00 to 14:00 and have 2 coffee breaks each, we can have two different results: + +1. Specify the default situation where both exposed and infected persons(s) have their breaks at the same time: in this case the coffee break times are calculated based on the activity time of the exposed - both will have their first coffee break around 11:00 and the second around 16:00. + +2. Specify separate breaks for the infected person(s): in this case the coffee breaks will be calculated based on the different activity times (i.e. exposed from 9:00 to 18:00 and infected from 10:00 to 17:00) - the exposed person(s) will have their first coffee break around 11:00 and the second around 16:00, whereas the infected will have their first coffee break around 11:30 and the second around 15:30. + +### Face masks + +The model allows for a simulation with either a continuous wearing of face masks throughout the duration of the event, or have the removed at all times - i.e. all occupants (infected and exposed alike) wear or not masks for the duration of the simulation. Please bear in mind the user inputs shall be aligned with the current applicable public health & safety instructions. Please check what are the applicable rules, before deciding which assumptions are used for the simulation. + +If you have selected the Conference/Training activity type, this equates to the speaker/trainer and all participants either wearing masks throughout the conference/training (Yes), or removing them when seated/standing at their socially distanced positions within the conference/training room (No). Please confirm what are the applicable rules, before deciding which assumptions are used for the simulation + +For the time being only the Type 1 surgical, FFP2, and Cloth masks can be selected. + +### Report + +When you have entered all the necessary information, please click on the Generate Report button to execute the model. With the implementation of Monte Carlo simulations, the browser might take a few seconds to react. + +The report will open in your web browser. It contains a summary of all the input data, which will allow the simulation to be repeated if required in the future as we improve the model. + +#### Results + +This part of the report shows the P(I) or probability of one exposed person getting infected. It is estimated based on the emission rate of virus into the simulated volume, and the amount which is inhaled by exposed individuals. This probability is valid for the simulation duration - i.e. the start and end time. If you are using the natural ventilation option, the simulation is only valid for the selected month, because the following or preceding month will have a different average temperature profile. The expected number of new cases for the simulation is calculated based on the probability of infection, multiplied by the number of exposed occupants. + +The graph shows the variation in the concentration of virions within the simulated volume. It is determined by: + +- The presence of the infected person, who emits airborne viruses in the volume. +- The emission rate is related to the type of activity of the infected person (sitting, light exercise), their level of vocalisation (breathing, speaking or shouting). +- The accumulation of virions in the volume, which is driven, among other factors, by ventilation (if applicable). + - In a mechanical ventilation scenario, the removal rate is constant, based on fresh airflow supply in and out of the simulated space. + - Under natural ventilation conditions, the effectiveness of ventilation relies upon the hourly temperature difference between the inside and outside air temperature. + - A HEPA filter removes virions from the air at a constant rate and is modelled in the same way as mechanical ventilation, however air passed through a HEPA filter is recycled (i.e. it is not fresh air). + +#### QR code + +At the end of the report you can find a unique QR code / hyperlink for this report. This provides an automatic way to review the calculator form with the corresponding specified parameters. This allows for: + +- sharing reports by either scanning or clicking on the QR code to obtain a shareable link. +- easily regenerating reports with any new versions of the CAiMIRA model released in the future. + +### Conclusion + +This tool provides informative comparisons for COVID-19 airborne risk only - see Disclaimer. If you have any comments on your experience with the app, or feedback for potential improvements, please share them with the development team - [send email](mailto:caimira-dev@cern.ch). \ No newline at end of file diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_opening.png b/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_opening.png new file mode 100644 index 00000000..5b96b169 Binary files /dev/null and b/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_opening.png differ diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_type.PNG b/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_type.PNG new file mode 100644 index 00000000..8d7d7405 Binary files /dev/null and b/caimira/docs/mkdocs/docs/project_overview/user_guide/img/window_type.PNG differ diff --git a/caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md b/caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md new file mode 100644 index 00000000..c12b51ac --- /dev/null +++ b/caimira/docs/mkdocs/docs/project_overview/user_guide/quick_guide.md @@ -0,0 +1,46 @@ +## CAiMIRA Calculator + +This tool simulates the airborne spread of SARS-CoV-2 virus in a finite volume and estimates the risk of COVID-19 infection. It is based on current scientific data and can be used to compare the effectiveness of different mitigation measures. + +### Virus data + +SARS-CoV-2 covers the original "wild type" strain of the virus and three variants of concern (VOC): +- Alpha (also known as B.1.1.7, first identified in UK, Sept 2020), +- Beta (also known as B.1.351, first identified in South Africa, May 2020). +- Gamma (also known as P.1, first identified in Brazil/Japan, Jan 2021). +- Delta (also known as B.1.617.2, first identified in India, Oct 2020). +- Omicron (also known as B.1.1.529, first identified in South Africa, November 2021). + +Modify the default as necessary, according to local area prevalence e.g. for [Geneva](https://www.covid19.admin.ch/fr/epidemiologic/virus-variants?geo=GE). + +### Ventilation data + +- Mechanical ventilation = the HVAC supply of fresh air. Check the flow rates with the concerned technical department. +- Natural ventilation = the type of window opening. The opening distance is between the fixed frame and movable part when open (commonly used values are window height of 1.6m and window opening between 0.15m and 0.6m). In case of periodic opening, specify the duration (e.g. 10 min) per hour. +- HEPA filtration = the air flow of the device. The following values are based on the different fan velocities of a specific commercial device proposed by the HSE Unit: + - Level 6 (max) = 430 m3/h (noisy), + - Level 5 = 250 m3/h (ok w.r.t. noise, recommended), + - Level 4 = 130 m3/h (silent), + - Level 3 = 95 m3/h (silent). + +### Activity types + +The type of activity applies to both the infected and exposed persons: +- Office = all seated, talking 33% of the time, +- Small meeting (< 10 occ.) = all seated, talking time shared between all persons, +- Large meeting (>= 10 occ.) = speaker is standing and speaking 33% of the time, other occupants are seated, +- Call Centre = all seated, continuous talking, +- Control Room (day shift) = all seated, talking 50% of the time, +- Control Room (night shift) = all seated, talking 10% of the time, +- Library = all seated, no talking, just breathing, +- Laboratory = light physical activity, talking 50% of the time, +- Workshop = moderate physical activity, talking 50% of the time, +- Conference/Training (speaker infected) = speaker/trainer standing and talking, rest seated and talking quietly. Speaker/Trainer assumed infected (worst case scenario), +- Conference/Training (attendee infected) = someone in the audience is infected, all are seated and breathing. +- Gym = heavy exercise, no talking, just breathing. + +### Activity breaks + +If coffee breaks are included, they are spread out evenly throughout the day, in addition to any lunch break (if applicable). + +Refer to the [Full Guide](full_guide.md) for more detailed explanations on how to use this tool. \ No newline at end of file diff --git a/caimira/docs/mkdocs/mkdocs.yml b/caimira/docs/mkdocs/mkdocs.yml index be4a94bd..e426338a 100644 --- a/caimira/docs/mkdocs/mkdocs.yml +++ b/caimira/docs/mkdocs/mkdocs.yml @@ -4,18 +4,25 @@ theme: nav: - Home: index.md - - Project Overview: project_overview.md - - Diameter-dependent Model: full_diameter_dependence.md - - Code-related Documentation: - - CAiMIRA REST API: code_documentation/rest_api.md - - CAiMIRA models: code_documentation/models.md - - Open Source Acknowledgments: open_source_acknowledgments.md + - Project Overview: + - About: project_overview/about.md + - Installation: project_overview/installation.md + - Deployment: project_overview/deployment.md + - User Guide: + - Quick Guide: project_overview/user_guide/quick_guide.md + - Full Guide: project_overview/user_guide/full_guide.md + - Open Source Acknowledgments: project_overview/open_source_acknowledgments.md + - License: LICENSE.md + - Code Documentation: + - Diameter Normalization: code_documentation/diameter_normalization.md + - REST API: code_documentation/rest_api.md + - Models Module: code_documentation/models.md markdown_extensions: - pymdownx.arithmatex: generic: true - toc: - toc_depth: '1-2' + toc_depth: '1-3' - admonition - pymdownx.details diff --git a/caimira/docs/style_docs.py b/caimira/docs/style_docs.py index 3b694007..0cfc99fd 100644 --- a/caimira/docs/style_docs.py +++ b/caimira/docs/style_docs.py @@ -199,7 +199,7 @@ def main(): print(f"File '{index_file_path}' does not exist, skipping update.") # Path to the open source acknowledgements markdown file to be updated - acknowledgements_file_path = 'mkdocs/docs/open_source_acknowledgments.md' + acknowledgements_file_path = 'mkdocs/docs/project_overview/open_source_acknowledgments.md' if os.path.isfile(acknowledgements_file_path): # Retrieve package details @@ -209,7 +209,7 @@ def main(): add_python_dependencies_section(acknowledgements_file_path, package_details) # Generate the pie chart - output_image_path = 'mkdocs/docs/license_distribution.png' + output_image_path = 'mkdocs/docs/project_overview/license_distribution.png' generate_license_distribution_pie_chart(package_details, output_image_path) else: print(f"File '{acknowledgements_file_path}' does not exist, skipping update.")