Utils
======

This module contains methods needed for the construction of the constrained objective
space and to analyze and interpret the results obtained by BFS.

Methods
---------

**circle_points**

::
    
    circle_points(r,n)
    
This function, first presented by [Lin2019]_, is used to divide the objective space 
into *k* regions. The idea is to create regions that have the same angle. Since 
we normalize our objective functions before applying BFS, we can use a balanced space 
where all regions are equal.

**Parameters**

r: int 
    Radius of the circle to be created. To get a space between 0 and 1, r should be equal to 1.
   
n: int
    Number of preference vectors to be generated. n should be 1 value higher than
    the number of regions desired. For instance, if we want a space split into 
    10 regions, n should be equal to 11.

**Returns**

List of the preference vectors' cootdinates. 

----------

**s_score**

::

    s_score(network_weights, sparsity_level, bfs_bool)

This function defines a sparsity metric used to measure the number of weights
that are null or almost null in a network.

**Parameters**

network_weights: list
    List of a network's weights (weights of all layers, biases and other initialized parameters).

sparsity_level: float
    Threshold value below which a connection's weight is considered equal to 0. 

bfs_bool: boolean
    Boolean to indicate whether the method from which the weights were extracted 
    is BFS. If we are working with BFS results, then bfs_bool should be set to True.


**Returns**

Float indicating the proprotion of weights that were pruned. This value will always be
between 0 and 1. 

----------

**average_fs_score**

::

    average_fs_score(network_weights, features_name, relevant_features)
    
This method defines a feature selection metric that can only be used when the 
important feature in a dataset are known. Its value can be between 0 and 1. 

**Parameters**

network_weights: list
    List of a network's weights (weights of all layers, biases and other initialized parameters).
    
features_name: list
    List of the name of all features.

relevant_features: list
    List of the name of each relevant feature.

**Returns**

A float that represents the feature selection score after a model has been training.

---------- 

**individual_fs_score**

::

    individual_fs_score(network_weights, feature_name)

This method is used for feature ranking. It can be used whether the dataset has 
already known relevant features or non, as it will return the features' contributions'
to prediction task sorted in decreasing order from highest to lowest. 

**Parameters**

network_weights: list
    List of a network's weights (weights of all layers, biases and other initialized parameters).
    
feature_name: list
    List of the name of all features.

**Returns**

Dataframe containing all features with their feature importance value ranked 
from highest to lowest.

----------

.. [Lin2019] Lin, X., Zhen, H. L., Li, Z., Zhang, Q. F., & Kwong, S. (2019). 
            Pareto multi-task learning. Advances in neural information 
            processing systems, 32.