HyperImpute

https://hyperimpute.readthedocs.io/en/latest/
Admin
HyperImpute is a library that simplifies data imputation algorithm selection for ML pipelines by...
Tokens:26,572
Snippets:213
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install HyperImpute from PyPI

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Install the HyperImpute library using pip. This is the recommended method for most users.

```bash
$ pip install hyperimpute

```

--------------------------------

### Install Testing Dependencies

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Use this command to install the necessary dependencies for testing HyperImpute.

```bash
pip install .[testing]
```

--------------------------------

### Install HyperImpute from Source

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Install HyperImpute directly from its source code using pip. This is useful for development or when needing the latest unreleased changes.

```bash
$ pip install .

```

--------------------------------

### Instantiate and Use Linear Regression Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_linear_regression.html

Demonstrates how to get the linear regression plugin and use it to fit and predict on a dataset. Requires scikit-learn for data loading.

```python
from hyperimpute.plugins.prediction import Predictions
from sklearn.datasets import load_iris


plugin = Predictions(category="regression").get("linear_regression")
X, y = load_iris(return_X_y=True)
plugin.fit_predict(X, y) # returns the probabilities for each class

```

--------------------------------

### SoftImpute Plugin Example

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_softimpute.html

Demonstrates how to initialize and use the SoftImpute imputer plugin to transform data with missing values.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("softimpute")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Initialize and Use CatBoostRegressorPlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_catboost_regressor.html

Instantiate the CatBoostRegressorPlugin for regression tasks and demonstrate its fit and predict functionality using the Iris dataset. This example shows how to get the plugin and then apply it to sample data.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="regression").get("catboost_regressor")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class

```

--------------------------------

### SoftImpute Plugin Usage Example

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_softimpute.html

Shows the typical usage of the SoftImpute imputer plugin, including initialization and the fit_transform method.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("softimpute")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
              0             1             2             3
```

--------------------------------

### Instantiate and use MicePlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_mice.html

Instantiate the MicePlugin and use it to fit and transform data with missing values. This example demonstrates a basic usage scenario.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("mice")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Instantiate and Use Neural Nets Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_neural_nets.html

Demonstrates how to get the neural nets classifier plugin and use it to fit and predict probabilities on a dataset. Requires scikit-learn for dataset loading.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="classifiers").get("neural_nets")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class

```

--------------------------------

### Instantiate and Use Logistic Regression Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_logistic_regression.html

Demonstrates how to get the logistic_regression plugin and use it to fit and predict probabilities on the Iris dataset. This is useful for performing classification tasks.

```python
from hyperimpute.plugins.prediction import Predictions
plugin = Predictions(category="classifiers").get("logistic_regression")
from sklearn.datasets import load_iris
X, y = load_iris(return_X_y=True)
plugin.fit_predict(X, y) # returns the probabilities for each class
```

--------------------------------

### Instantiate and Use EM Imputer

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_EM.html

Demonstrates how to import the Imputers class, get the EM plugin, and apply it to a dataset with missing values using fit_transform. Ensure numpy is imported for NaN values.

```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("EM")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Median Imputation Example

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_median.html

Demonstrates how to use the Median Imputation plugin to fill missing values in a DataFrame. Instantiate the plugin via the Imputers class and then call fit_transform.

```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("median")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
     0    1    2    3
0  1.0  1.0  1.0  1.0
1  1.0  2.0  2.0  1.0
2  1.0  2.0  2.0  1.0
3  2.0  2.0  2.0  2.0


```

--------------------------------

### Instantiate and Use Neural Nets Regression Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_neural_nets_regression.html

Demonstrates how to get the neural nets regression plugin and use it to fit and predict on a dataset. This is useful for regression tasks where a neural network approach is desired.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="regression").get("neural_nets_regression")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class
```

--------------------------------

### GAIN Imputation Plugin Example

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_gain.html

Instantiate and use the GAIN imputer plugin to transform a dataset with missing values. Requires numpy and the Imputers class from hyperimpute.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("gain")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Mean Imputation Example

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_mean.html

Demonstrates how to use the Mean Imputation plugin to fill missing values in a dataset. Instantiate the plugin and apply fit_transform to a NumPy array containing NaNs.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("mean")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Specify Baseline Models for HyperImpute

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Configure HyperImpute to use specific baseline models for classification and regression during the imputation process. This example sets 'logistic_regression' and 'linear_regression' as seeds.

```python
import pandas as pd
import numpy as np
from hyperimpute.plugins.imputers import Imputers

X = pd.DataFrame([[1, 1, 1, 1], [4, 5, np.nan, np.nan], [3, 3, 9, 9], [2, 2, 2, 2]])

plugin = Imputers().get(
    "hyperimpute",
    optimizer="hyperband",
    classifier_seed=["logistic_regression"],
    regression_seed=["linear_regression"],
)

out = plugin.fit_transform(X.copy())
print(out)

```

--------------------------------

### PluginLoader Class

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.core.base_plugin.html

Manages the loading and retrieval of plugins. It can add new plugins, get specific plugins by name, list available plugins, and reload the plugin registry.

```APIDOC
## class PluginLoader

Bases: `object`

### Methods

*   `add(_name: str, _cls: Type) -> PluginLoader`
*   `get(_name: str, *args: Any, **kwargs: Any) -> Any`
*   `get_type(_name: str) -> Type`
*   `list() -> List[str]`
*   `reload() -> PluginLoader`
*   `types() -> List[Type]`

### Internal Methods

*   `_load_single_plugin(_plugin: str) -> None`
```

--------------------------------

### Write a New Custom Imputation Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Create a custom imputation plugin by subclassing ImputerPlugin and implementing the required methods. This example shows how to wrap scikit-learn's KNNImputer as a HyperImpute plugin.

```python
from sklearn.impute import KNNImputer
from hyperimpute.plugins.imputers import Imputers, ImputerPlugin

imputers = Imputers()

knn_imputer = "custom_knn"

class KNN(ImputerPlugin):
    def __init__(self) -> None:
        super().__init__()
        self._model = KNNImputer(n_neighbors=2, weights="uniform")

    @staticmethod
    def name():
        return knn_imputer

    @staticmethod
    def hyperparameter_space():
        return []

    def _fit(self, *args, **kwargs):
        self._model.fit(*args, **kwargs)
        return self

    def _transform(self, *args, **kwargs):
        return self._model.transform(*args, **kwargs)

imputers.add(knn_imputer, KNN)

assert imputers.get(knn_imputer) is not None

```

--------------------------------

### Benchmark Imputation Models on a Dataset

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Compare the performance of different imputation models on a dataset using the compare_models utility. This example benchmarks 'hyperimpute' against 'ice' and 'missforest' on the Iris dataset under MAR scenarios.

```python
from sklearn.datasets import load_iris
from hyperimpute.plugins.imputers import Imputers
from hyperimpute.utils.benchmarks import compare_models

X, y = load_iris(as_frame=True, return_X_y=True)

imputer = Imputers().get("hyperimpute")

compare_models(
    name="example",
    evaluated_model=imputer,
    X_raw=X,
    ref_methods=["ice", "missforest"],
    scenarios=["MAR"],
    miss_pct=[0.1, 0.3],
    n_iter=2,
)

```

--------------------------------

### Instantiate and Use RandomForestPlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_random_forest.html

Demonstrates how to instantiate the RandomForestPlugin and use it for fitting and predicting on a dataset. Requires importing the Predictions class and loading a dataset.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="classifiers").get("random_forest")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y)

```

--------------------------------

### Instantiate and Use CatBoost Classifier

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_catboost.html

Demonstrates how to instantiate the CatBoost classifier plugin and use it for fitting and predicting probabilities on a dataset. Requires importing the Predictions class and a dataset like Iris.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="classifiers").get("catboost")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class

```

--------------------------------

### Instantiate and Use XGBoost Plugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_xgboost.html

Demonstrates how to instantiate the XGBoost plugin and use it for fitting and predicting on a dataset. Requires importing the Predictions class and a dataset like Iris.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="classifiers").get("xgboost")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y)
```

--------------------------------

### Instantiate and Use XGBoostRegressorPlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_xgboost_regressor.html

Demonstrates how to instantiate the XGBoost regressor plugin and use it for fitting and predicting on a dataset. Requires importing the Predictions class and a dataset.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="regressors").get("xgboost")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y)
```

--------------------------------

### MicePlugin Initialization and Usage

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_mice.html

Demonstrates how to initialize the MICE imputation plugin and use its fit_transform method with sample data.

```APIDOC
## MicePlugin

### Description
Imputation plugin for completing missing values using the Multivariate Iterative chained equations and multiple imputations.

### Parameters
* **n_imputations** (int) - Optional - number of multiple imputations to perform.
* **max_iter** (int) - Optional - maximum number of imputation rounds to perform.
* **tol** (float) - Optional - tolerance for convergence.
* **initial_strategy** (int) - Optional - strategy for initial imputation.
* **imputation_order** (int) - Optional - order of imputation.
* **random_state** (int) - Optional - seed for the pseudo random number generator.

### Method
Multivariate Iterative chained equations(MICE) methods model each feature with missing values as a function of other features in a round-robin fashion. For each step of the round-robin imputation, we use a BayesianRidge estimator, which does a regularized linear regression. The class sklearn.impute.IterativeImputer is able to generate multiple imputations of the same incomplete dataset. We can then learn a regression or classification model on different imputations of the same dataset. Setting sample_posterior=True for the IterativeImputer will randomly draw values to fill each missing value from the Gaussian posterior of the predictions. If each IterativeImputer uses a different random_state, this results in multiple imputations, each of which can be used to train a predictive model. The final result is the average of all the n_imputation estimates.

### Request Example
```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("mice")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

### Response
#### Success Response (200)
- **imputed_data** (numpy.ndarray) - The dataset with missing values imputed.

#### Response Example
```json
{
  "imputed_data": [[1.0, 1.0, 1.0, 1.0], [1.2, 1.3, 1.4, 1.5], [1.0, 2.0, 2.0, 1.0], [2.0, 2.0, 2.0, 2.0]]
}
```
```

--------------------------------

### ClassifierPlugin.get_args

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.base.html

Retrieves the arguments used to initialize the plugin.

```APIDOC
## get_args() -> dict

### Description
Retrieves the arguments used to initialize the plugin.

### Parameters
None

### Returns
* **args** (dict) – A dictionary containing the plugin's arguments.

### Request Example
None

### Response Example
None
```

--------------------------------

### Instantiate and use MIWAE Imputer

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Instantiate the MIWAE imputer plugin and use it to fit and transform data with missing values. Requires numpy for NaN representation.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("miwae")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### weights_init

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Initializes weights for a given layer.

```APIDOC
## weights_init(layer: Any) -> None

Initializes weights for a given layer.
```

--------------------------------

### Instantiate and use MiraclePlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miracle.html

Instantiate the MiraclePlugin and use it to fit and transform data with missing values. Requires numpy for NaN values.

```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers
plugin = Imputers().get("miracle")
plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

--------------------------------

### Random Forest Regressor Plugin Usage

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_random_forest_regressor.html

Demonstrates how to instantiate and use the RandomForestRegressionPlugin for fitting and predicting on a dataset. Ensure the necessary imports are available.

```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="regression").get("random_forest")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y)
```

--------------------------------

### MIWAEPlugin Constructor

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Initializes the MIWAE imputation plugin with specified hyperparameters.

```APIDOC
## MIWAEPlugin

### Description
MIWAE imputation plugin.

### Parameters
- **n_epochs** (int) - Optional - Number of training iterations. Defaults to 500.
- **batch_size** (int) - Optional - Batch size. Defaults to 256.
- **latent_size** (int) - Optional - dimension of the latent space. Defaults to 1.
- **n_hidden** (int) - Optional - number of hidden units. Defaults to 1.
- **K** (int) - Optional - number of IS during training. Defaults to 2.
- **random_state** (int) - Optional - random seed. Defaults to 0.

### Example
```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("miwae")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

### Reference
“MIWAE: Deep Generative Modelling and Imputation of Incomplete Data”, Pierre-Alexandre Mattei, Jes Frellsen
Original code: https://github.com/pamattei/miwae
```

--------------------------------

### Initialize Weights for a Layer

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Initializes the weights for a given layer. This is a utility function specific to the MIWAE implementation.

```python
weights_init(layer)
```

--------------------------------

### _BasicNet

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_neural_nets.html

Basic neural net implementation.

```APIDOC
## _BasicNet

### Description
Basic neural net.

### Parameters
* **n_unit_in** (int) - Number of features.
* **categories** (int) - Number of categories.
* **n_layers_hidden** (int) - Number of hypothesis layers (n_layers_hidden x n_units_hidden + 1 x Linear layer).
* **n_units_hidden** (int) - Number of hidden units in each hypothesis layer.
* **nonlin** (str, default 'elu') - Nonlinearity to use in NN. Can be ‘elu’, ‘relu’, ‘selu’ or ‘leaky_relu’.
* **lr** (float) - Learning rate for optimizer. step_size equivalent in the JAX version.
* **weight_decay** (float) - L2 (ridge) penalty for the weights.
* **n_iter** (int) - Maximum number of iterations.
* **batch_size** (int) - Batch size.
* **n_iter_print** (int) - Number of iterations after which to print updates and check the validation loss.
* **random_state** (int) - Random state used.
* **val_split_prop** (float) - Proportion of samples used for validation split (can be 0).
* **patience** (int) - Number of iterations to wait before early stopping after decrease in validation loss.
* **n_iter_min** (int) - Minimum number of iterations to go through before starting early stopping.
* **clipping_value** (int, default 1) - Gradients clipping value.
```

--------------------------------

### Execute Tests

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Run the tests for HyperImpute using the pytest command.

```bash
pytest -vsx
```

--------------------------------

### MedianPlugin Usage

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_median.html

Demonstrates how to instantiate and use the MedianPlugin for data imputation. The plugin replaces NaN values with the median of their respective columns.

```APIDOC
## MedianPlugin

### Description
Imputation plugin for completing missing values using the Median Imputation strategy. The Median Imputation strategy replaces the missing values using the median along each column.

### Method
```python
plugin = Imputers().get("median")
plugin.fit_transform(data)
```

### Parameters
#### Request Body
- **X** (DataFrame) - The input data with missing values.

### Request Example
```python
import numpy as np
from hyperimpute.plugins.imputers import Imputers

data = [[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]]
plugin = Imputers().get("median")
result = plugin.fit_transform(data)
print(result)
```

### Response
#### Success Response (DataFrame)
- The input DataFrame with missing values imputed using the median strategy.

#### Response Example
```
     0    1    2    3
0  1.0  1.0  1.0  1.0
1  1.0  2.0  2.0  1.0
2  1.0  2.0  2.0  1.0
3  2.0  2.0  2.0  2.0
```
```

--------------------------------

### List Available Imputers

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Instantiate the Imputers class and call the list() method to see all available imputation algorithms supported by HyperImpute.

```python
from hyperimpute.plugins.imputers import Imputers

imputers = Imputers()

imputers.list()

```

--------------------------------

### MIWAEPlugin Methods

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Core methods of the MIWAE imputation plugin.

```APIDOC
## MIWAEPlugin Methods

### `_fit(X: DataFrame, *args: Any, **kwargs: Any) -> MIWAEPlugin`

Fits the MIWAE model to the data.

### `_miwae_impute(iota_x: Tensor, mask: Tensor, L: int) -> Tensor`

Performs imputation using the trained MIWAE model.

### `_miwae_loss(iota_x: Tensor, mask: Tensor) -> Tensor`

Calculates the MIWAE loss.

### `_transform(X: DataFrame) -> DataFrame`

Transforms the data using the fitted MIWAE model.

### `_hyperparameter_space(*args: Any, **kwargs: Any) -> List[Params]`

Returns the hyperparameter space for the MIWAE plugin.

### `_name() -> str`

Returns the name of the MIWAE plugin.
```

--------------------------------

### CatBoostRegressorPlugin

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_catboost_regressor.html

Regression plugin based on the CatBoost framework. CatBoost provides a gradient boosting framework which attempts to solve for Categorical features using a permutation driven alternative compared to the classical algorithm. It uses Ordered Boosting to overcome over fitting and Symmetric Trees for faster execution.

```APIDOC
## CatBoostRegressorPlugin

### Description
Regression plugin based on the CatBoost framework. CatBoost provides a gradient boosting framework which attempts to solve for Categorical features using a permutation driven alternative compared to the classical algorithm. It uses Ordered Boosting to overcome over fitting and Symmetric Trees for faster execution.

### Example
```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="regression").get("catboost_regressor")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class
```

### Methods
- `_fit(X: DataFrame, *args: Any, **kwargs: Any) -> CatBoostRegressorPlugin`
- `_predict(X: DataFrame, *args: Any, **kwargs: Any) -> DataFrame`
- `_predict_proba(X: DataFrame, *args: Any, **kwargs: Any) -> DataFrame`
- `grow_policies: List[Optional[str]]`
- `_hyperparameter_space(*args: Any, **kwargs: Any) -> List[Params]`
- `_name() -> str`
```

--------------------------------

### RandomForestPlugin Methods and Attributes

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_random_forest.html

Lists the internal methods and attributes of the RandomForestPlugin, including fit, predict, predict_proba, and configurable parameters like criterions and features.

```python
_abc_impl _ = <_abc_data object>_
```

```python
_fit(_X : DataFrame, _* args: Any, _** kwargs: Any_) -> RandomForestPlugin_
```

```python
_predict(_X : DataFrame, _* args: Any, _** kwargs: Any_) -> DataFrame_
```

```python
_predict_proba(_X : DataFrame, _* args: Any, _** kwargs: Any_) -> DataFrame_
```

```python
criterions _ = ['gini', 'entropy']_
```

```python
features _ = ['sqrt', 'log2', None]_
```

```python
_static _hyperparameter_space(_* args: Any, _** kwargs: Any_) -> List[Params]_
```

```python
module_relative_path _: Optional[Path]_
```

```python
_static _name() -> str_
```

--------------------------------

### Serializable Class Methods

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.utils.serialization.html

Provides methods for loading and saving models, both from bytes and dictionaries, and for managing serialization versions.

```APIDOC
## Class: Serializable

### Description
Utility class for model persistence.

### Methods
- `_load(buff: bytes) -> Any`
- `_load_dict(representation: dict) -> Any`
- `save() -> dict`
- `save_dict() -> dict`
- `save_to_file(path: Path) -> bytes`
- `_version() -> str`
- `_add_version(obj: Any) -> Any`
- `_check_version(obj: Any) -> Any`
- `load(buff: bytes) -> Any`
- `load_from_file(path: Union[str, Path]) -> Any`
- `save(model: Any) -> bytes`
- `save_to_file(path: Union[str, Path], model: Any) -> Any`
```

--------------------------------

### EM Imputer Usage

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_EM.html

This snippet shows how to instantiate and use the EM imputer plugin for data imputation.

```APIDOC
## EM Imputer

### Description

The EM Imputer uses the Expectation-Maximization algorithm for imputing missing values.

### Parameters

#### convergence_threshold
- **convergence_threshold** (float) - Optional - Minimum ratio difference between iterations before stopping.

### Request Example
```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("EM")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
```

### Reference
“Maximum Likelihood from Incomplete Data via the EM Algorithm”, A. P. Dempster, N. M. Laird and D. B. Rubin
```

--------------------------------

### MIWAEPlugin Hyperparameter Space

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Defines the hyperparameter space for the MIWAE plugin. This static method returns a list of possible parameters for tuning.

```python
MIWAEPlugin._hyperparameter_space()
```

--------------------------------

### Linear Regression Plugin Solvers

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.regression.plugin_linear_regression.html

Lists the available solvers that can be used with the Linear Regression plugin. These options control the underlying algorithm for solving the linear regression problem.

```python
solvers _ = ['auto', 'svd', 'cholesky', 'lsqr', 'sparse_cg', 'sag', 'saga']_
```

--------------------------------

### XGBoost Plugin - Hyperparameter Space

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_xgboost.html

This static method defines the hyperparameter space for the XGBoost plugin, which is used during hyperparameter search. It returns a list of possible parameter configurations.

```python
>>> from hyperimpute.plugins.prediction.classifiers.plugin_xgboost import _XGBoostPlugin
>>> _XGBoostPlugin.hyperparameter_space()
```

--------------------------------

### Integer Parameter

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.core.params.html

Represents an integer parameter with a specified range and optional step.

```APIDOC
## class Integer(name: str, low: int, high: int, step: int = 1)

### Description
Represents an integer parameter with a specified lower and upper bound, and an optional step.

### Methods
- **get()**: Returns the bounds and step of the integer parameter.
- **sample(trial: Trial)**: Samples an integer value within the bounds based on the trial.
- **sample_np()**: Samples an integer value using NumPy.
```

--------------------------------

### SoftImpute Plugin Class

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_softimpute.html

The SoftImputePlugin class provides an interface for using the SoftImpute imputer within the hyperimpute framework. It inherits from ImputerPlugin and delegates the core imputation logic to the SoftImpute class.

```APIDOC
## Class: _SoftImputePlugin

### Description
Imputation plugin for completing missing values using the SoftImpute strategy.

### Method
Details in the SoftImpute class implementation.

### Parameters
* **maxit** (int, default=1000) - maximum number of imputation rounds to perform.
* **convergence_threshold** (float, default=1e-5) - Minimum ratio difference between iterations before stopping.
* **max_rank** (int, default=2) - Perform a truncated SVD on each iteration with this value as its rank.
* **shrink_lambda** (float, default=0) - Value by which we shrink singular values on each iteration. If it’s missing, it is calibrated using cross validation.
* **cv_len** (int, default=3) - the length of the grid on which the cross-validation is performed.
* **random_state** (int, default=0) - Controls the random number generation for reproducibility.

### Example
```python
>>> import numpy as np
>>> from hyperimpute.plugins.imputers import Imputers
>>> plugin = Imputers().get("softimpute")
>>> plugin.fit_transform([[1, 1, 1, 1], [np.nan, np.nan, np.nan, np.nan], [1, 2, 2, 1], [2, 2, 2, 2]])
              0             1             2             3
```
```

--------------------------------

### GainImputation Helper Functions

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_gain.html

Helper functions for the GAIN imputation strategy, including sampling methods for hint vectors, random samples, and mini-batches.

```APIDOC
## GainImputation Helper Functions

### Methods
#### sample_M
Hint Vector Generation.

Parameters:
* **m** (int) - number of rows.
* **n** (int) - number of columns.
* **p** (float) - hint rate.

Returns:
* np.ndarray - generated random values.

#### sample_Z
Random sample generator for Z.

Parameters:
* **m** (int) - number of rows.
* **n** (int) - number of columns.

Returns:
* np.ndarray - generated random values.

#### sample_idx
Mini-batch generation.

Parameters:
* **m** (int) - number of rows.
* **n** (int) - number of columns.

Returns:
* np.ndarray - generated random indices.
```

--------------------------------

### CatBoostPlugin Class

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.prediction.classifiers.plugin_catboost.html

The CatBoostPlugin class provides a classification plugin based on the CatBoost framework. It leverages gradient boosting with a permutation-driven approach for categorical features, Ordered Boosting to prevent overfitting, and Symmetric Trees for efficient execution.

```APIDOC
## Class: CatBoostPlugin

### Description
Classification plugin based on the CatBoost framework. CatBoost provides a gradient boosting framework which attempts to solve for Categorical features using a permutation driven alternative compared to the classical algorithm. It uses Ordered Boosting to overcome over fitting and Symmetric Trees for faster execution.

### Parameters

* **learning_rate** (float) - The learning rate used for training.
* **depth** (int) - 
* **iterations** (int) - 
* **grow_policy** (int) - 
* **_n_estimators** (Optional[int]) - Default: 10
* **_l2_leaf_reg** (float) - Default: 3
* **_min_data_in_leaf** (int) - Default: 1
* **_random_strength** (float) - Default: 1
* **_model** (Optional[Any]) - 
* **_hyperparam_search_iterations** (Optional[int]) - 
* **_random_state** (int) - Default: 0
* **_**kwargs** (Any) - 

### Methods

* **_fit** (_X : DataFrame_, _* args: Any_, _** kwargs: Any_) -> CatBoostPlugin
  Fits the CatBoost model to the data.

* **_predict** (_X : DataFrame_, _* args: Any_, _** kwargs: Any_) -> DataFrame
  Predicts class labels using the fitted CatBoost model.

* **_predict_proba** (_X : DataFrame_, _* args: Any_, _** kwargs: Any_) -> DataFrame
  Predicts class probabilities using the fitted CatBoost model.

* **grow_policies** : List[Optional[str]]
  Available grow policies for CatBoost.

* **_static _hyperparameter_space** (_* args: Any_, _** kwargs: Any_) -> List[Params]
  Returns the hyperparameter space for the CatBoost plugin.

* **_static _name**() -> str
  Returns the name of the CatBoost plugin.

### Example
```python
>>> from hyperimpute.plugins.prediction import Predictions
>>> plugin = Predictions(category="classifiers").get("catboost")
>>> from sklearn.datasets import load_iris
>>> X, y = load_iris(return_X_y=True)
>>> plugin.fit_predict(X, y) # returns the probabilities for each class
```
```

--------------------------------

### Use HyperImpute within an SKLearn Pipeline

Source: https://hyperimpute.readthedocs.io/en/latest/index.html

Integrate a HyperImpute imputer into an scikit-learn Pipeline. This allows for seamless imputation before applying a machine learning model, such as a RandomForestRegressor.

```python
import pandas as pd
import numpy as np

from sklearn.pipeline import Pipeline
from sklearn.ensemble import RandomForestRegressor

from hyperimpute.plugins.imputers import Imputers

X = pd.DataFrame([[1, 1, 1, 1], [4, 5, np.nan, np.nan], [3, 3, 9, 9], [2, 2, 2, 2]])
y = pd.Series([1, 2, 1, 2])

imputer = Imputers().get("hyperimpute")

estimator = Pipeline(
    [
        ("imputer", imputer),
        ("forest", RandomForestRegressor(random_state=0, n_estimators=100)),
    ]
)

estimator.fit(X, y)

```

--------------------------------

### MIWAEPlugin Static Attributes

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Static attributes of the MIWAE imputation plugin.

```APIDOC
## MIWAEPlugin Static Attributes

### `module_relative_path: Optional[Path]`

The relative path of the module.

### `plugin`

alias of `MIWAEPlugin`
```

--------------------------------

### Plugin Class

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.core.base_plugin.html

The base class for all plugins. Derived classes must implement type(), name(), and hyperparameter_space(). Internal methods like _fit(), _transform(), and _predict() are called by their public counterparts.

```APIDOC
## class Plugin

Bases: `Serializable`

Base class for all plugins. Each derived class must implement the following methods:

*   `type()` - a static method that returns the type of the plugin. e.g., imputation, preprocessing, prediction, etc.
*   `subtype()` - optional method that returns the subtype of the plugin. e.g. Potential subtypes:
    * preprocessing: feature_scaling, dimensionality reduction
    * prediction: classifiers, prediction, survival analysis
*   `name()` - a static method that returns the name of the plugin. e.g., EM, mice, etc.
*   `hyperparameter_space()` - a static method that returns the hyperparameters that can be tuned during the optimization. The method will return a list of Params derived objects.
*   `_fit()` - internal method, called by fit on each training set.
*   `_transform()` - internal method, called by transform. Used by imputation or preprocessing plugins.
*   `_predict()` - internal method, called by predict. Used by classification/prediction plugins.

If any method implementation is missing, the class constructor will fail.

### Abstract Methods

*   `__fit(_X: DataFrame_, *args: Any, **kwargs: Any) -> Plugin`
*   `__predict(_X: DataFrame_, *args: Any, **kwargs: Any) -> DataFrame`
*   `__transform(_X: DataFrame_) -> DataFrame`
*   `_hyperparameter_space(*args: Any, **kwargs: Any) -> List[Params]`
*   `_name() -> str`
*   `_subtype() -> str`
*   `_type() -> str`

### Public Methods

*   `fit(_X: DataFrame_, *args: Any, **kwargs: Any) -> Any`
*   `fit_predict(_X: DataFrame_, *args: Any, **kwargs: Any) -> DataFrame`
*   `fit_transform(_X: DataFrame_, *args: Any, **kwargs: Any) -> DataFrame`
*   `predict(_X: DataFrame_, *args: Any, **kwargs: Any) -> DataFrame`
*   `transform(_X: DataFrame_) -> DataFrame`

### Class Methods

*   `_fqdn() -> str`
*   `_hyperparameter_space_fqdn(*args: Any, **kwargs: Any) -> List[Params]`
*   `_sample_hyperparameters(_trial: Trial, *args: Any, **kwargs: Any) -> Dict[str, Any]`
*   `_sample_hyperparameters_fqdn(_trial: Trial, *args: Any, **kwargs: Any) -> Dict[str, Any]`
*   `_sample_hyperparameters_np(*args: Any, **kwargs: Any) -> Dict[str, Any]`
```

--------------------------------

### MIWAE Plugin Name

Source: https://hyperimpute.readthedocs.io/en/latest/generated/hyperimpute.plugins.imputers.plugin_miwae.html

Returns the static name of the MIWAE plugin. This is used for identification within the Imputers class.

```python
MIWAEPlugin._name()
```
Tokens:
Raw