Ventilation length predictor
============================

The aim is to define a proper way of air change rate regulation. The regulation is ensured by natural ventilation
that is energy efficient, requires little maintenance, has low initial costs, and
is environmentally friendly. Natural ventilation should be used wherever and whenever is possible
apart from areas where the quality of the air outside the house is worse than indoor air quality.
A predictor enables to predict how long ventilation should be performed to decrease a given quantity to the required
value.

The configuration parameters in the examples below can be changed
in the configuration file ``config.ini``
that is described in section :ref:`installation.config_file`.

CO2
---

The predictor is based on the equation which can be used to calculate a decrease of a carbon dioxide concentration
during a time interval.

Initialize general models from local database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A local database was created for debugging purposes. The database includes
pre-processed data that enables fast computing of required attributes.
The example of a model created using data stored in the database follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/co2_init_general_models_from_local_db.py
   :language: python


It is required to create a dataset that contains the same number of events when a window was open and when it was closed.
To select the events when the window was closed the variable ``no_event_shift`` is defined.
Its value can be set using
the parameter ``attrs.no_event.time_shift``.
A model is created using
the function ``training_file_co2`` that uses ``SVM`` classifier (``sklearn`` library). The created model is
written to a binary file using the ``write_model`` function.

The example of a command which can be used to create a model using data stored in the database is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/co2_init_general_models_from_local_db.py

Initialize general models from a remote server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The example of a model created using data saved on the server follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/co2_init_general_models.py
   :language: python

At first, it is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
Then it is required to create a dataset that contains the same number of events when a window was open and
when it was closed. To select the events when the window was closed the variable ``no_event_shift`` is defined.
Its value can be set using
the parameter ``attrs.no_event.time_shift``.
Devices that were used to gather data are stored in the variable ``devs``. Latitude and longitude that enable to get weather data according to
a sensor position are stored in the variable ``lat`` and ``lon``. The API key allows to get weather data from server and
it is obtained by the function ``wunderground_api_key``. A model is created using the function ``training_file_co2``
that uses ``SVM`` classifier (``sklearn`` library). The created model is written to a binary file using
the ``write_model`` function.

The example of a command which can be used to create a model using data saved
on the remote server is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/co2_init_general_models.py

Predictor
^^^^^^^^^
The example of the model usage for predicting how long ventilation should be performed follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/co2_predictor.py
   :language: python

It is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
Prediction is performed on the basis of data measured during a given time interval. Time that defines
end of a time interval is stored in the variable ``actual_time``. Latitude and longitude that enable to get weather data
according to a sensor position are stored in the variable ``lat`` and ``lon``. The API key allows to get weather data
from server and it is obtained by the function ``wunderground_api_key``. The sensors used to gather data are stored
in the variable ``devs``. Prediction how long ventilation should be performed to decrease the concentration
of carbon dioxide to a given value is performed by the function ``predictor`` and the result is stored
in the variable ``notification``.

An output of the prediction is a notification that contains basic information described in the section
:ref:`Notifications <notification.notification>` and the following information:

* **current_value** - current value of CO2 [ppm],
* **estimate_time** - a time when a carbon dioxide concentration will reach a given value [min],
* **final_value** - value of CO2 that should be reached after ventilation [ppm],
* **type** - what quantity is used for prediction (carbon dioxide).

The example of a notification follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/co2_notification.doc.json
   :language: json

The example of a command which can be used to the use of a model for
prediction how long ventilation should be performed is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/co2_predictor.py


Temperature and humidity
------------------------
The model for prediction is based on a decrease in humidity during ventilation for the selected time intervals.
It was necessary to consider specific humidity that can be easily converted to relative humidity.

Initialize general models from local database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A local database was created for debugging purposes. The database includes
pre-processed data that enables fast computing of required attributes.
The example of a model created using data stored in the database follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/t_h_init_general_models_from_local_db.py
   :language: python

It is required to create a dataset that contains the same number of events when a window was open and when it was closed.
To select the events when the window was closed the variable ``no_event_shift`` is defined.
Its value can be set using
the parameter ``attrs.no_event.time_shift``.
A model is created using
the function ``training_file_t_h`` that uses ``SVM`` classifier (``sklearn`` library). The created model is
written to a binary file using the ``write_model`` function.

The example of a command which can be used to create a model using data stored in the database is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/t_h_init_general_models_from_local_db.py

Initialize general models from a remote server
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The example of a model created using data saved on the server follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/t_h_init_general_models.py
   :language: python

At first, it is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
Then it is required to create a dataset that contains the same number of events when a window was open and
when it was closed. To select the events when the window was closed the variable ``no_event_shift`` is defined.
Its value can be set using
the parameter ``attrs.no_event.time_shift``.
Devices that were used to gather data are stored in the variable ``devs``. Latitude and longitude that enable to get weather data according to
a sensor position are stored in the variable ``lat`` and ``lon``. The API key allows to get weather data from server and
it is obtained by the function ``wunderground_api_key``. A model is created using the function ``training_file_t_h``
that uses ``SVM`` classifier (``sklearn`` library). The created model is written to a binary file using
the ``write_model`` function.

The example of a command which can be used to create a model using data saved
on the remote server is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/t_h_init_general_models.py

Predictor
^^^^^^^^^
The example of the model usage for predicting how long ventilation should be performed follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/t_h_predictor.py
   :language: python

It is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
Prediction is performed on the basis of data measured during a given time interval. Time that defines
end of a time interval is stored in the variable ``actual_time``. Latitude and longitude that enable to get weather data
according to a sensor position are stored in the variable ``lat`` and ``lon``. The API key allows to get weather data
from server and it is obtained by the function ``wunderground_api_key``. The sensors used to gather data are stored
in the variable ``devs``. Prediction how long ventilation should be performed to decrease humidity to a given value
is performed by the function ``predictor`` and the result is stored in the variable ``notification``.

An output of the prediction is a notification that contains basic information described in the section
:ref:`Notifications <notification.notification>` and the following information:

* **current_value** - current value of humidity [%],
* **estimate_time** - a time when humidity will reach a given value [min],
* **final_value** - value of humidity that should be reached after ventilation [%],
* **type** - what quantity is used for prediction (humidity).

The example of a notification follows.

.. literalinclude:: ../../examples2/0302_ventilation_predictor/t_h_notification.doc.json
   :language: json

The example of a command which can be used to the use of a model for
prediction how long ventilation should be performed is below.

.. code-block:: bash

   python examples2/0302_ventilation_predictor/t_h_predictor.py
