# Hetero Feature Binning

Feature binning or data binning is a data pre-processing technique. It
can be use to reduce the effects of minor observation errors, calculate
information values and so on.

Currently, we provide quantile binning and bucket binning methods. To
achieve quantile binning approach, we have used a special data structure
mentioned in this
[paper](https://www.researchgate.net/profile/Michael_Greenwald/publication/2854033_Space-Efficient_Online_Computation_of_Quantile_Summaries/links/0f317533ee009cd3f3000000/Space-Efficient-Online-Computation-of-Quantile-Summaries.pdf).
Feel free to check out the detail algorithm in the paper.

As for calculating the federated iv and woe values, the following figure
can describe the principle properly.

![Figure 1 (Federated Feature Binning
Principle)](../images/binning_principle.png)

As the figure shows, B party which has the data labels encrypt its
labels with Addiction homomorphic encryption and then send to A. A
static each bin's label sum and send back. Then B can calculate woe and
iv base on the given information.

For multiple hosts, it is similar with one host case. Guest sends its
encrypted label information to all hosts, and each of the hosts
calculates and sends back the static info.

![Figure 2： Multi-Host Binning
Principle](../images/multiple_host_binning.png)

For optimal binning, each party use quantile binning or bucket binning
find initial split points. Then Guest will send encrypted labels to
Host. Host use them calculate histogram of each bin and send back to
Guest. Then start optimal binning methods.

![Figure 3： Multi-Host Binning
Principle](../images/optimal_binning.png)

There exist two kinds of methods, merge-optimal binning and
split-optimal binning. When choosing metrics as iv, gini or chi-square,
merge type optimal binning will be used. On the other hand, if ks chosen, split type optimal binning will be used.

Below lists all metrics of optimal binning:

| Optimal Binning Metric Type 	| Input Data Case                                                                                                                                                                                                                    	|
|-----------------------------	|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|
| chi-square                  	| [dense input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-optim-chi-square.py) <br> [sparse input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-optimal-chi-square.py) 	|
| gini                        	| [dense input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-optim-gini.py) <br> [sparse input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-optimal-gini.py)             	|
| iv                          	| [dense input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-optim-iv.py) <br> [sparse input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-optimal-iv.py)                 	|
| ks                          	| [dense input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-optim-ks.py) <br> [sparse input](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-optimal-ks.py)                 	|

Binning module supports multi-class data to calculate iv and woe too. To
achieve it, one-vs-rest mechanism is used. Each label will be chosen
iteratively as event case. All other cases will be treated as non-event
cases. Therefore, we can obtain a set of iv\&woe result for each label
case.

## Features

1.  Support Quantile Binning based on quantile summary algorithm.
2.  Support Bucket Binning.
3.  Support missing value input by ignoring them.
4.  Support sparse data format generated by dataio component.
5.  Support calculating woe and iv as well as counting positive and
    negative cases for each bin.
6.  Support transforming data into bin indexes or woe value.
7.  Support multiple-host binning.
8.  Support 4 types of optimal binning.
9.  Support asymmetric binning methods on Host & Guest sides.
10. Support multi-class iv\&woe calculation.

Below lists supported features:

| Cases                                	| Scenario                                                                                                                                                                                                                                                                                                                                                                 	|
|--------------------------------------	|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	|
| Input Data with Missing Value        	| [bucket binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-bucket-missing-value.py) <br> [quantile binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-missing-value.py)                                                                                                                                        	|
| Input Data with Categorical Features 	| [bucket binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-multi-host-bucket.py) <br> [quantile binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-category-binning.py) <br> [optimal binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-asymmetric.py)                           	|
| Input Data in Sparse Format          	| [bucket binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-bucket-binning.py) <br> [quantile binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-quantile-binning.py) <br> [optimal binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-sparse-optimal-chi-square.py) 	|
| Input Data with Multi-Class(label)   	| [single host](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-multiclass.py) <br> [multi-host](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-multiclass-multihost.py)                                                                                                                                                    	|
| Output Data Transformed              	| [bin index](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-bucket-binning.py) <br> [woe value(guest-only)](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-woe-binning.py)                                                                                                                                                	|
| Skip Statistic Calculation           	| [bucket binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-bucket-binning.py) <br> [quantile binning](../../examples/pipeline/hetero_feature_binning/pipeline-hetero-binning-skip-statistic.py)                                                                                                                                             	|


<!-- mkdocs
## Param

::: federatedml.param.feature_binning_param
    rendering:
      heading_level: 3
      show_source: true
      show_root_heading: true
      show_root_toc_entry: false
      show_root_full_path: false
 -->