smote_variants

The project organizes its Jupyter notebooks into two distinct categories based on their purpose and maintenance status:

• development/ folder: Contains code snippets used during the development of the package. These are not maintained and are not guaranteed to be executable at all times.
• illustration/ folder: Contains notebooks used for testing and illustrating the various functionalities of the smote_variants package.

The smote_variants.noise_removal module provides several classes for prototype selection and noise filtering to clean imbalanced datasets. All noise removal classes follow a consistent API pattern:

1. Instantiate the filter class (e.g., TomekLinkRemoval()).
2. Call the .remove_noise(X, y) method on the instance.

The method returns a tuple (X_samp, y_samp) containing the cleaned feature matrix and target vector.

Available noise removal algorithms include:

• TomekLinkRemoval
• CondensedNearestNeighbors
• OneSidedSelection
• CNNTomekLinks
• NeighborhoodCleaningRule
• EditedNearestNeighbors

>>> # Example using TomekLinkRemoval
>>> noise_filter = smote_variants.noise_removal.TomekLinkRemoval()
>>> X_samp, y_samp = noise_filter.remove_noise(X, y)

Multiclass oversampling in this library follows a sequential approach to balance classes. It selects minority classes one-by-one and oversamples them to match the cardinality of the original majority class. During each step, the 'majority class' used for the binary oversampling process is defined as the union of the original majority class and all classes that have already been oversampled.

Requirement: This technique is only compatible with binary oversampling methods that:

1. Do not change the majority class.
2. Include a proportion parameter to explicitly specify the number of samples to be generated.

Classification performance is highly sensitive to the number of minority samples generated. Simply balancing the dataset (making the number of minority and majority samples equal) is often not the optimal choice because it can distort the density near the decision boundary.

To optimize this, use the proportion parameter available in almost all implemented techniques. The number of minority samples generated is calculated as:

number_of_samples = proportion * (N_maj - N_min)

Where N_maj is the number of majority samples and N_min is the number of minority samples.

Recommendation: Perform cross-validated model selection for the proportion parameter using a range such as [0.1, 0.2, 0.5, 1.0, 2.0, 5.0]. Setting proportion=1.0 will balance the dataset.

The evaluation and model selection scripts support parallel execution via the n_jobs parameter:

• If n_jobs=1: The scripts call sklearn algorithms to run in parallel.
• If n_jobs > 1: The sklearn implementations run sequentially, while the oversampling and classification jobs themselves are executed in parallel using n_jobs processes.

You can contribute new oversampling techniques to the smote_variants package by participating in a voluntary competition. To participate:

1. Implement: Develop your oversampling technique following the smote_variants package structure (refer to the new_oversampler documentation for implementation details).
2. Evaluate: Test your technique locally against the current best-performing oversamplers in the package.
3. Submit: If your results are convincing, send your code to the maintainers or submit a pull request to merge it into the package.

Submissions will be re-tested by the maintainers, and oversamplers will be ranked based on their performance results.

After implementing your oversampler, verify that it handles all edge cases by using the test_template.ipynb notebook. Follow the instructions within the notebook to configure it for your new algorithm and execute the cells. If the implementation is correct, all tests in the notebook should pass.

# Execute test_template.ipynb to verify edge case handling

Before installing smote_variants, ensure the following Python packages are available in your environment:

• joblib
• numpy
• pandas
• sklearn
• scipy
• minisom
• keras (with any backend)

You can install the smote_variants package directly from PyPI using pip.

> pip install smote_variants

You can install the package by cloning the repository or by installing directly from the GitHub URL.

# Option 1: Clone and install locally
> git clone git@github.com:gykovacs/smote_variants.git
> cd smote_variants
> pip install .

# Option 2: Install directly via pip
> pip install git+https://github.com:gykovacs/smote_variants.git