Window opening detector
=======================
The aim is to design a system
detecting window opening events on the basis of a carbon dioxide concentration or humidity change.
The window opening detector according to a carbon dioxide concentration is based only on the course of indoor
carbon dioxide concentration because indoor and outside relative humidity
and temperature did not influence the success rate of a detector. The detector based on humidity considers also
the course of temperature.

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
---
Today, people spend a considerable part of their life in office and living spaces.
Therefore it is necessary to maintain healthy indoor environment.
The concentration of carbon dioxide is an indicator of the quality of the indoor environment.
Excessive concentration can cause fatigue, headache or sore throat.
The long-term effect of high concentration of carbon dioxide
on the human body can lead to asthma and other respiratory diseases.
The concentration of carbon dioxide can be influenced by ventilation.
If the ventilation is performed right, no health problems with the respiratory tract
and with the concentration of people occur.
Moreover, ventilation only for the necessary time contributes to saving energy.

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/0300_open_detector/co2_init_general_models_from_local_db.py
   :language: python


The dataset in the example is created using columns of the table ``measured_filtered_peto``, the columns are stored in the variable ``OPEN_CO2``.
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``.
The variable ``directory`` that can be set using the parameter ``generic.directory`` denotes directory where a created model will be stored.
A model is created using
the function ``training_set_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

   python3 examples2/0300_open_detector/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/0300_open_detector/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``. 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 ``generic_training_file`` 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/0300_open_detector/co2_init_general_models.py


Initialize adapted model
^^^^^^^^^^^^^^^^^^^^^^^^
The example of a model adapted to a given room follows.


.. literalinclude:: ../../examples2/0300_open_detector/co2_init_adapted_model.py
   :language: python

It is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
The current time is stored in the variable ``actual_time``. The API key allows to get weather data from server and it is obtained
by the function ``wunderground_api_key``. The function ``prepare_adapted_co2`` creates a model using data gathered by devices
up to the current time. The devices are stored in the variable ``out_dev``. To create the model data from the general model can be also used.
This option can be enabled or disabled using the parameter ``adapted.combined_with_generic_data`` in the configuration file ``config.ini``. If the parameter is
set to ``Yes``, data from the general model will be used, if it is set to ``No``, data will not be used.
The resulting model is stored in the directory ``adapted_data`` by default.

The example of a command which can be used to adapt a model to a certain room is below.

.. code-block:: bash

   python examples2/0300_open_detector/co2_init_adapted_model.py


Detector
^^^^^^^^
The example of the use of a model for window opening detection follows.

.. literalinclude:: ../../examples2/0300_open_detector/co2_detector.py
   :language: python


It is necessary
to set clients that can communicate with a remote server using the function ``setup_clients``.
Detection 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 sensor used to gather data is stored in the variable ``devs``.
Estimation if a window was open or not based on the concentration of carbon dioxide at the given time is performed by
the function ``estimate_open_co2`` and the result is stored in the variable ``notification``.

An output of a detection is a notification that contains basic information described
in the section :ref:`Notifications <notification.notification>` and
information if a window was open or not which is stored in the key ``estimate_open``.

.. literalinclude:: ../../examples2/0300_open_detector/co2_notification.doc.json
   :language: json


The example of a command which can be used to the use of a model for
window opening detection is below.

.. code-block:: bash

   python examples2/0300_open_detector/co2_detector.py


Temperature and humidity
------------------------
People spend about 90 % of their life indoors.
Therefore it is necessary to maintain a healthy indoor environment that is significantly affected by humidity.
It is possible to determine the common symptoms of excessive humidity in buildings.
For example, people can suffer from allergy or asthma thanks to airborne dust mites and
mould spores that are spread in the excessively humid air. A big difference between indoor and outdoor temperature
can cause condensation when water drops or fog can occur on the window glass. Mould spots and musty odours indicate
the presence of mould and mildew that can result in health problems. A humid environment encourages mildew,
mould and bacterial growth that negatively influence indoor air quality. Ventilation is able to remove pollutants and
humidity forming indoors or reduce their concentrations to admissible levels for the occupant health and comfort.
It should be energy efficient, preserve indoor air quality and it should not harm the occupants or the building.

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/0300_open_detector/t_h_init_general_models_from_local_db.py
   :language: python


The dataset in the example is created using columns of the table ``measured_filtered_klarka``, the columns are stored in the variable ``OPEN_T_H``.
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``.
The variable ``directory`` that can be set using the parameter ``generic.directory`` denotes directory where a created model
will be stored.
A model is created using
the function ``training_set_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

   python3 examples2/0300_open_detector/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/0300_open_detector/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``. 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 ``generic_training_file`` 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/0300_open_detector/t_h_init_general_models.py


Initialize adapted model
^^^^^^^^^^^^^^^^^^^^^^^^
The example of a model adapted to a given room follows.

.. literalinclude:: ../../examples2/0300_open_detector/t_h_init_adapted_model.py
   :language: python


It is necessary to set clients that can communicate with a remote server using the function ``setup_clients``.
Adaptation 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``. The function ``prepare_adapted_data_t_h`` creates a model using data gathered by devices
up to the current time. To create the model data from the general model can also be used.
This option can be enabled or disabled using the parameter ``enable`` or ``disable``. The resulting model is stored in the directory ``adapted_data`` by default.

The example of a command which can be used to adapt a model to a certain room is below.

.. code-block:: bash

   python examples2/0300_open_detector/t_h_init_adapted_model.py


Detector
^^^^^^^^
The example of the use of a model for window opening detection follows.

.. literalinclude:: ../../examples2/0300_open_detector/t_h_detector.py
   :language: python


It is necessary
to set clients that can communicate with a remote server using the function ``setup_clients``. Detection 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``.
Estimation if a window was open or not based on the humidity and the temperature at the given time is performed by
the function ``estimate_open_t_h`` and the result is stored in the variable ``notification``.

An output of a detection is a notification that contains basic information described
in the section :ref:`Notifications <notification.notification>` and
information if a window was open or not which is stored in the key ``estimate_open``.

.. literalinclude:: ../../examples2/0300_open_detector/t_h_notification.doc.json
   :language: json

The example of a command which can be used to the use of a model for
window opening detection is below.

.. code-block:: bash

   python examples2/0300_open_detector/t_h_detector.py

