Code documentation
**************************

.. automodule:: eecr


Setting up the EnergyOptimizer object
=====================================

The first step is to create the EnergyOptimizer object and update it with the properties of the desired dataset. 
All these properties can be set either in the constructor or one-by-one with setter functions. Warning: do not manually 
change any method variables without using the appropriate functions.  

.. automodule:: eecr.eeoptimizer

.. autoclass:: EnergyOptimizer
   :members: __init__, set_sequence, set_path, set_settings, set_dca_costs

Summarizing its properties
==========================
Use these functions for a quick look-up into created EnergyOptimizer object. 

.. autoclass:: EnergyOptimizer
   :members: quality, energy_quality, summary

Searching for and evaluating configurations
===========================================
The meat of the module. It is able to automatically find three types of energy-efficient
solutions and predict their performance.

First type of solutions are the SCA configurations. Such a configuration is a list of settings
(e.g. [s1, s2, s3]) where settings can be any hashable object. A configuration represents a
system that works as follows: context c1 is detected, system switches to using setting s1, and
keeps using it until a context change is detected. Then if the context c_i is detected the
setting s_i is used (s_i is the i-th setting in the given configuration).

Second type of solutions are the DCA configurations. Such a configuration is a list of integers
(e.g. [5,4,2]). A configuration represents a system that works as follows: context c1 is
detected and the system stop working for (s_i)-1 time periods (s_i is the i-th entry in
the configuration). Then it works for one
(or more if so explicitly specified) time periods. The last classified context in this
active period determines the length of the next sleeping period.

Third type of solutions are the SCA-DCA configurations. They essentially do both: switching
both the setting in use and the length of the sleeping period. They are represented in the
form (SCA_configuration, DCA_configuration).

Any such configuration can be evaluated using two different mechanism. One is the simulation,
and the other is the mathematical prediction (based on the dataset properties).
The latter approach is usually roughly 100 times faster and almost as accurate. In all cases
the evaluations of configurations  are returned as the list of tuples [(q1,e1), (q2,e2), ...]
where ``q`` represents the quality metrics of choice (e.g. accuracy) and ``e`` represents
the energy cost.

All functions in this segment follow roughly the same pattern of naming, parameters and
return types. Methods that evaluate configurations have the form similar to
func:`~EnergyOptimizer.sca_model` - evaluates SCA configurations using the
mathematical model. Methods that automatically find the configurations
have the form similar to: func:`~EnergyOptimizer.find_sca_tradeoffs` - automatically finds
SCA configurations.

.. autoclass:: EnergyOptimizer
   :members: sca_real, sca_simple, sca_model, find_sca_tradeoffs, find_sca_static, find_sca_random, dca_real, 
             dca_model, find_dca_static, find_dca_tradeoffs, find_dca_random, sca_dca_real, sca_dca_model,
             find_sca_dca_tradeoffs

Saving and loading data
=======================
To avoid repeated processing of the data, many components can be quickly saved and loaded. Many functions have this 
functionality already built-in by using the ``name`` parameter. In addition, the following functions are specialized for the
task. Make sure the path is correctly set before using them. Additionally note, that all saving and loading uses pickle 
in the background.

.. autoclass:: EnergyOptimizer
   :members: load_data_config, load_data, load_config, load_solution, save_data, save_solution, save_config


Automatic settings generators
=============================
Sometimes the generation of settings can be automated. Two of the methods listed
(:func:`~EnergyOptimizer.add_csdt_weighted`, :func:`~EnergyOptimizer.add_csdt_borders`)
automate only settings represented by the cost-sensitive decision trees. The last
one (:func:`~EnergyOptimizer.add_subsets`), automates the task of creating settings where
each setting represents using a different attribute subset.

.. autoclass:: EnergyOptimizer
   :members: add_subsets, add_csdt_weighted, add_csdt_borders

Visualizing solutions 
=====================
Most functions in the ee.eeutility module are meant for internal use.
However, the  :func:`~ee.eeutility.draw_tradeoffs` provides an easy way
to visualize the results achieved with other methods.

.. automodule:: eecr.eeutility
   :members: draw_tradeoffs

Alternative search methods
==========================
Methods below are based on the related work, but solve the same kind of problem as
the methodology presented in this module. They are here included as possible
alternatives and for easier comparison of the approaches.

.. automodule:: eecr.eeoptimizer
   :noindex:

.. autoclass:: EnergyOptimizer
   :members: find_simple_tradeoffs, find_coh_tradeoffs, find_aimd_tradeoffs

Cost-sensitive decision trees
=============================
Cost-sensitive trees are a version of the decision tree classifier that is interested in
both attribute informativeness and attribute costs when building the tree. To explain
it briefly: at each tree  node – instead  of  checking  each  attribute’s
information gain  or  a  similar  metric – we  compare  the  expected  cost
of misclassification if this node becomes a leaf, with the expected cost of
the attribute and misclassification if the attribute is used to  further  divide
the  instances.  The  attribute  that  reduces  the expected cost the most, if any,
then expands this node.

This particular implementation of the cost-sensitive trees is optimized for the
tasks in context-recognition.  It can be used as a stand-alone method for reducing the
energy consumption or it can be used in conjuction with other methods described in this
module.

.. automodule:: eecr.cstree

.. autoclass:: CostSensitiveTree
   :members: __init__, fit, predict, show, show_sensors