imblearn-resc 0.1.0__tar.gz

imblearn_resc-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: imblearn_resc
+Version: 0.1.0
+Summary: Resampling based on Sample Concatenation (Re-SC) algorithms for imbalanced learning
+Author-email: maksimkins <maks.aleshkov.04@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/maksimkins/resampling-methods
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: imbalanced-learn>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# imblearn-resc
+
+**Re-SC (Resampling based on Sample Concatenation)** algorithms for imbalanced learning. 
+
+This package is fully compatible with the `scikit-learn` and `imbalanced-learn` ecosystems. It addresses class imbalance by mapping data into a higher-dimensional (2d) concatenated feature space, utilizing either density-weighted random sampling (`ReSC`) or K-Means clustering (`KMeansReSC`) to safely resample the majority and minority classes.
+
+## 📦 Installation
+
+You can install `imblearn-resc` directly from PyPI using pip:
+
+```bash
+pip install imblearn-resc
+```
+
+*Requires Python >=3.11, scikit-learn >=1.4.0, and imbalanced-learn >=0.12.0*
+
+---
+
+## 🚀 Quick Start & Usage
+
+Because Re-SC algorithms map your original features ($d$) into a concatenated feature space ($2d$), **you must always pair the Sampler with the `ReSCTransformer` inside an `imblearn` Pipeline.**
+
+* **The Sampler** (`ReSC` or `KMeansReSC`) transforms the training data during `.fit_resample()`.
+* **The Transformer** (`ReSCTransformer`) bypasses the training data, but safely duplicates the test data features ($x \rightarrow [x, x]$) during `.predict()` so your classifier receives the correct dimensions.
+
+### Example: Complete Pipeline
+
+Here is a full, runnable example of how to use `ReSC` and `KMeansReSC` with a standard machine learning classifier.
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import classification_report
+
+# 1. Import the pipeline from imbalanced-learn (NOT standard sklearn!)
+from imblearn.pipeline import Pipeline
+
+# 2. Import the Re-SC Samplers and Transformer
+from imblearn_resc.oversampling import ReSC, KMeansReSC
+from imblearn_resc.preprocessing import ReSCTransformer
+
+# Generate a highly imbalanced dummy dataset (10% minority, 90% majority)
+X, y = make_classification(
+    n_classes=2, class_sep=2, weights=[0.1, 0.9], 
+    n_informative=3, n_redundant=1, flip_y=0,
+    n_features=5, n_clusters_per_class=1, 
+    n_samples=1000, random_state=42
+)
+
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+# ==========================================
+# Option A: Standard ReSC Pipeline
+# ==========================================
+pipeline_resc = Pipeline([
+    ('sampler', ReSC(M=1.5, k=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_resc.fit(X_train, y_train)
+y_pred_resc = pipeline_resc.predict(X_test)
+
+print("ReSC Classification Report:")
+print(classification_report(y_test, y_pred_resc))
+
+
+# ==========================================
+# Option B: KMeansReSC Pipeline
+# ==========================================
+pipeline_kmeans = Pipeline([
+    ('sampler', KMeansReSC(M=1.5, num_candidates_to_test=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_kmeans.fit(X_train, y_train)
+y_pred_kmeans = pipeline_kmeans.predict(X_test)
+
+print("KMeansReSC Classification Report:")
+print(classification_report(y_test, y_pred_kmeans))
+```
+
+## 🧠 Key Parameters
+
+### `ReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`k`** *(int, default=5)*: Number of nearest neighbors used to calculate majority sample weights.
+* **`alpha`** *(float, default=0.05)*: Significance level for the Z-test used to compute the required statistical sample size.
+
+### `KMeansReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`num_candidates_to_test`** *(int, default=5)*: How many 'k' values (clusters) to test during geometric tuning using the Silhouette Score.

imblearn_resc-0.1.0/README.md

@@ -0,0 +1,96 @@
+# imblearn-resc
+
+**Re-SC (Resampling based on Sample Concatenation)** algorithms for imbalanced learning. 
+
+This package is fully compatible with the `scikit-learn` and `imbalanced-learn` ecosystems. It addresses class imbalance by mapping data into a higher-dimensional (2d) concatenated feature space, utilizing either density-weighted random sampling (`ReSC`) or K-Means clustering (`KMeansReSC`) to safely resample the majority and minority classes.
+
+## 📦 Installation
+
+You can install `imblearn-resc` directly from PyPI using pip:
+
+```bash
+pip install imblearn-resc
+```
+
+*Requires Python >=3.11, scikit-learn >=1.4.0, and imbalanced-learn >=0.12.0*
+
+---
+
+## 🚀 Quick Start & Usage
+
+Because Re-SC algorithms map your original features ($d$) into a concatenated feature space ($2d$), **you must always pair the Sampler with the `ReSCTransformer` inside an `imblearn` Pipeline.**
+
+* **The Sampler** (`ReSC` or `KMeansReSC`) transforms the training data during `.fit_resample()`.
+* **The Transformer** (`ReSCTransformer`) bypasses the training data, but safely duplicates the test data features ($x \rightarrow [x, x]$) during `.predict()` so your classifier receives the correct dimensions.
+
+### Example: Complete Pipeline
+
+Here is a full, runnable example of how to use `ReSC` and `KMeansReSC` with a standard machine learning classifier.
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import classification_report
+
+# 1. Import the pipeline from imbalanced-learn (NOT standard sklearn!)
+from imblearn.pipeline import Pipeline
+
+# 2. Import the Re-SC Samplers and Transformer
+from imblearn_resc.oversampling import ReSC, KMeansReSC
+from imblearn_resc.preprocessing import ReSCTransformer
+
+# Generate a highly imbalanced dummy dataset (10% minority, 90% majority)
+X, y = make_classification(
+    n_classes=2, class_sep=2, weights=[0.1, 0.9], 
+    n_informative=3, n_redundant=1, flip_y=0,
+    n_features=5, n_clusters_per_class=1, 
+    n_samples=1000, random_state=42
+)
+
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+# ==========================================
+# Option A: Standard ReSC Pipeline
+# ==========================================
+pipeline_resc = Pipeline([
+    ('sampler', ReSC(M=1.5, k=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_resc.fit(X_train, y_train)
+y_pred_resc = pipeline_resc.predict(X_test)
+
+print("ReSC Classification Report:")
+print(classification_report(y_test, y_pred_resc))
+
+
+# ==========================================
+# Option B: KMeansReSC Pipeline
+# ==========================================
+pipeline_kmeans = Pipeline([
+    ('sampler', KMeansReSC(M=1.5, num_candidates_to_test=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_kmeans.fit(X_train, y_train)
+y_pred_kmeans = pipeline_kmeans.predict(X_test)
+
+print("KMeansReSC Classification Report:")
+print(classification_report(y_test, y_pred_kmeans))
+```
+
+## 🧠 Key Parameters
+
+### `ReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`k`** *(int, default=5)*: Number of nearest neighbors used to calculate majority sample weights.
+* **`alpha`** *(float, default=0.05)*: Significance level for the Z-test used to compute the required statistical sample size.
+
+### `KMeansReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`num_candidates_to_test`** *(int, default=5)*: How many 'k' values (clusters) to test during geometric tuning using the Silhouette Score.

imblearn_resc-0.1.0/imblearn_resc/oversampling/KMeansReSC/__init__.py

@@ -0,0 +1,3 @@
+from ._resc_kmeans import KMeansReSC
+
+__all__ = ["KMeansReSC"]

imblearn_resc-0.1.0/imblearn_resc/oversampling/KMeansReSC/_resc_kmeans.py

@@ -0,0 +1,117 @@
+from typing import Optional, Union, List, Tuple
+from numbers import Real, Integral
+
+import numpy as np
+from numpy.typing import NDArray
+
+from sklearn.utils import check_random_state
+from sklearn.utils._param_validation import Interval
+
+from imblearn.base import BaseSampler
+
+from .utils._resc_kmeans_utils import (
+    get_set_n_kmeans_re_sc, 
+    kmeans_re_sc_concatenation
+)
+
+class KMeansReSC(BaseSampler):
+    """
+    Resampling based on Sample Concatenation (Re-SC) using K-Means clustering.
+    
+    This algorithm addresses class imbalance by mapping the data into a higher-dimensional 
+    (2d) concatenated feature space. It identifies "safe" majority samples using KNN, 
+    determines the optimal number of clusters (k) via Silhouette Score, and uses the 
+    resulting K-Means cluster centers as the majority subset (Set_N).
+
+    Attributes:
+        M (float): The maximum acceptable imbalance ratio threshold for the resulting dataset.
+        num_candidates_to_test (int): How many 'k' values to test during geometric tuning.
+        random_state (int, RandomState instance, default=None): Controls the randomization of the algorithm.
+
+    Methods:
+        _fit_resample(X, y): Core resampling logic that executes KMeansReSC and returns concatenated arrays.
+        get_feature_names_out(input_features): Generates output feature names for the 2d concatenated space.
+    """
+    _sampling_type = 'over-sampling'
+    _parameter_constraints = {
+        "M": [Interval(Real, 0, None, closed="left")],
+        "num_candidates_to_test": [Interval(Integral, 1, None, closed="left")],
+        "random_state": ["random_state"]
+    }
+    def __init__(self, M=1.5, num_candidates_to_test=5, random_state=None):
+        super().__init__()
+        self.M = M
+        self.num_candidates_to_test = num_candidates_to_test
+        self.random_state = random_state
+
+    def _fit_resample(
+        self, 
+        X: NDArray[np.float64], 
+        y: NDArray[np.int_]
+    ) -> Tuple[NDArray[np.float64], NDArray[np.int_]]:
+        """
+        Executes resampling logic for KMeansReSC.
+
+        Args:
+            X (numpy.typing.NDArray[np.float64]): 2D matrix containing the features of the original training dataset.
+            y (numpy.typing.NDArray[np.int_]): 1D array containing the target labels.
+
+        Returns:
+            Tuple[numpy.typing.NDArray[np.float64], numpy.typing.NDArray[np.int_]]: 
+                A tuple containing the resampled feature matrix (mapped to a 2d space) 
+                and the corresponding label array.
+
+        Raises:
+            ValueError: If the dataset does not contain at least two distinct classes.
+        """
+        random_state_obj = check_random_state(self.random_state)
+        seed = random_state_obj.randint(0, 2**31 - 1)
+        
+        labels, counts = np.unique(y, return_counts=True)
+        if len(labels) < 2:
+            raise ValueError("The target 'y' needs to have at least two classes.")
+            
+        min_label = labels[np.argmin(counts)]
+        maj_label = labels[np.argmax(counts)]
+
+        X_set_n = get_set_n_kmeans_re_sc(
+            X=X,
+            y=y,
+            min_label=min_label,
+            maj_label=maj_label,
+            M=self.M,
+            num_candidates_to_test=self.num_candidates_to_test,
+            random_state=seed
+        )
+
+        X_resampled, y_resampled = kmeans_re_sc_concatenation(
+            X_min=X[y == min_label], 
+            X_maj=X[y == maj_label], 
+            X_set_n=X_set_n,
+            min_label=min_label,
+            maj_label=maj_label
+        )
+
+        return X_resampled, y_resampled
+
+    def get_feature_names_out(
+        self, 
+        input_features: Optional[Union[List[str], NDArray[np.object_]]] = None
+    ) -> NDArray[np.object_]:
+        """
+        Get output feature names for transformation. 
+
+        Args:
+            input_features (Optional[Union[List[str], numpy.typing.NDArray[np.object_]]]): 
+                Original input feature names. If None, generic names are generated.
+
+        Returns:
+            numpy.typing.NDArray[np.object_]: An array of strings containing the new feature 
+                names for the 2d concatenated space.
+        """
+        if input_features is None:
+            input_features = [f"x{i}" for i in range(self.n_features_in_)]
+
+        out_features = [f"{name}_1" for name in input_features] + [f"{name}_2" for name in input_features]
+
+        return np.asarray(out_features, dtype=object)

imblearn_resc-0.1.0/imblearn_resc/oversampling/KMeansReSC/utils/_resc_kmeans_utils.py

@@ -0,0 +1,180 @@
+from typing import Tuple, List
+
+import numpy as np
+from numpy.typing import NDArray
+
+from sklearn.cluster import KMeans
+from sklearn.neighbors import KNeighborsClassifier
+from sklearn.metrics import silhouette_score
+
+def find_best_k_geometric(
+    X_maj: NDArray[np.float64], 
+    k_candidates: List[int],
+    random_state: int
+) -> int:
+    """
+    Finds the optimal number of clusters (k) using the Silhouette Score.
+
+    Evaluates a list of candidate values for k by applying K-Means clustering 
+    and selecting the value that maximizes the Silhouette Score. If only one 
+    valid candidate is provided or all candidates are invalid, it provides a 
+    safe fallback.
+
+    Args:
+        X_maj (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the majority class.
+        k_candidates (List[int]): A list of integer candidate values for the number of clusters (k) to test.
+        random_state (int): Seed used by the random number generator for K-Means initialization to ensure reproducibility.
+
+    Returns:
+        int: The optimal number of clusters (k) selected from the candidates.
+    """
+    if len(k_candidates) == 1:
+        single_k = k_candidates[0] if k_candidates[0] != 0 else 1  
+        return single_k
+
+    best_k = None
+    best_score = -2.0 
+    
+    for k in k_candidates:
+        if k < 2 or k >= len(X_maj):
+            continue
+            
+        kmeans = KMeans(n_clusters=k, random_state=random_state, n_init='auto')
+        cluster_labels = kmeans.fit_predict(X_maj)
+        
+        score = silhouette_score(X_maj, cluster_labels)
+        
+        if score > best_score:
+            best_score = score
+            best_k = k
+            
+    if best_k is None:
+        best_k = max(1, k_candidates[0])
+        
+    return best_k
+
+
+def get_set_n_kmeans_re_sc(
+    X: NDArray[np.float64],
+    y: NDArray[np.int_],
+    min_label: int,
+    maj_label: int,
+    M: float = 1.5,
+    num_candidates_to_test: int = 5,
+    random_state: int = 42
+) -> NDArray[np.float64]:
+    """
+    Generates the Set_N subset using K-Means clustering on 'safe' majority samples.
+
+    This function identifies 'safe' majority samples using a KNN classifier (samples 
+    with >= 90% probability of belonging to the majority class). It then dynamically 
+    generates a list of candidate values for the number of clusters based on the 
+    imbalance ratio bounds, finds the optimal k using the Silhouette Score, and 
+    returns the resulting K-Means cluster centers to be used as Set_N.
+
+    Args:
+        X (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the entire training dataset.
+        y (numpy.typing.NDArray[np.int_]): 1D NumPy array containing the target labels.
+        min_label (int): The target label assigned to the minority class.
+        maj_label (int): The target label assigned to the majority class.
+        M (float, optional): The maximum acceptable imbalance ratio threshold. Defaults to 1.5.
+        num_candidates_to_test (int, optional): The number of candidate values for k to evaluate during geometric tuning. Defaults to 5.
+        random_state (int, optional): Seed used by the random number generator for reproducibility. Defaults to 42.
+
+    Returns:
+        numpy.typing.NDArray[np.float64]: A 2D NumPy array containing the features of the generated majority subset (the K-Means cluster centers).
+
+    Raises:
+        ValueError: If either the minority or majority class contains zero samples.
+    """
+    X_min = X[y == min_label]
+    X_maj = X[y == maj_label]
+    
+    n_maj = len(X_maj)
+    n_min = len(X_min)
+    
+    if n_maj == 0 or n_min == 0:
+        raise ValueError("Both minority and majority classes must have at least one sample.")
+    
+    n1 = int((n_min ** 2) / n_maj)
+    upper_bound = int(M * n1)
+    
+    knn = KNeighborsClassifier(n_neighbors=5)
+    knn.fit(X, y)
+    
+    maj_class_idx = np.where(knn.classes_ == maj_label)[0][0]
+    
+    probs = knn.predict_proba(X_maj)
+    prob_majority = probs[:, maj_class_idx]
+    
+    safe_mask = prob_majority >= 0.9
+    X_maj_safe = X_maj[safe_mask]
+    
+    if len(X_maj_safe) == 0:
+        X_maj_safe = X_maj 
+        
+    step = max(1, (upper_bound - n1) // max(1, (num_candidates_to_test - 1)))
+    candidates = list(range(n1, upper_bound + 1, step))
+    
+    best_k = find_best_k_geometric(X_maj_safe, candidates, random_state)
+    best_k = min(best_k, len(X_maj_safe))
+    
+    kmeans = KMeans(n_clusters=best_k, random_state=random_state, n_init='auto')
+    kmeans.fit(X_maj_safe)
+    
+    X_set_n = kmeans.cluster_centers_
+    
+    return X_set_n
+
+def kmeans_re_sc_concatenation(
+    X_min: NDArray[np.float64], 
+    X_maj: NDArray[np.float64], 
+    X_set_n: NDArray[np.float64],
+    min_label: int = 1,
+    maj_label: int = -1
+) -> Tuple[NDArray[np.float64], NDArray[np.int_]]:
+    """
+    Concatenates pairs of samples from the same class to map the dataset into a 2d dimensional space.
+
+    Args:
+        X_min (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the minority class.
+        X_maj (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the original majority class.
+        X_set_n (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the selected majority subset.
+        min_label (int, optional): The target label assigned to the minority class.
+        maj_label (int, optional): The target label assigned to the majority class.
+
+    Returns:
+        Tuple[numpy.typing.NDArray[np.float64], numpy.typing.NDArray[np.int_]]: 
+            A tuple containing:
+            - X_resampled: The concatenated 2D NumPy array with 2 * d features.
+            - y_resampled: The 1D NumPy array containing the target labels for the new samples.
+
+    Raises:
+        ValueError: If X_min is empty, as the minority class must contain at least one sample.
+    """
+    m = len(X_min)
+    if m == 0:
+        raise ValueError("X_min cannot be empty. Minority class must have at least one sample.")
+    
+    P_repeat = np.repeat(X_min, m, axis=0)
+    P_tile = np.tile(X_min, (m, 1))
+    P_c = np.hstack([P_repeat, P_tile]) 
+    
+    y_p_c = np.full(len(P_c), min_label, dtype=np.int_)
+
+    M = len(X_maj)
+    k = len(X_set_n)
+    
+    if k > 0:
+        N_repeat = np.repeat(X_maj, k, axis=0)  
+        Set_N_tile = np.tile(X_set_n, (M, 1)) 
+        N_c = np.hstack([N_repeat, Set_N_tile])
+        y_n_c = np.full(len(N_c), maj_label, dtype=np.int_)
+        
+        X_c_array = np.vstack([P_c, N_c])
+        y_c_array = np.hstack([y_p_c, y_n_c])
+    else:
+        X_c_array = P_c
+        y_c_array = y_p_c
+
+    return X_c_array, y_c_array

imblearn_resc-0.1.0/imblearn_resc/oversampling/ReSC/__init__.py

@@ -0,0 +1,3 @@
+from ._resc import ReSC
+
+__all__ = ["ReSC"]

imblearn_resc-0.1.0/imblearn_resc/oversampling/ReSC/_resc.py

@@ -0,0 +1,131 @@
+from typing import Optional, Union, List, Tuple
+from numbers import Real, Integral
+
+import numpy as np
+from numpy.typing import NDArray
+
+from sklearn.utils import check_random_state
+from sklearn.utils._param_validation import Interval
+
+from imblearn.base import BaseSampler
+
+from .utils._resc_utils import (
+    calculate_set_n_size_re_sc,
+    get_set_n_random_weighted_re_sc,
+    re_sc_concatenation
+)
+
+
+class ReSC(BaseSampler):
+    """
+    Resampling based on Sample Concatenation (Re-SC) using density-weighted random sampling.
+    
+    This algorithm addresses class imbalance by mapping the data into a higher-dimensional 
+    (2d) concatenated feature space. It over-samples the minority class by concatenating 
+    minority samples with themselves, and under-samples the majority class by pairing 
+    original majority samples with a statistically determined subset (Set_N).
+
+    Attributes:
+        M (float): The maximum acceptable imbalance ratio threshold for the resulting dataset.
+        k (int): Number of nearest neighbors used to calculate majority sample weights.
+        alpha (float): Significance level for the Z-test used to compute the required statistical sample size.
+        epsilon (float): Acceptable tolerance error for representing the majority class distribution.
+        random_state (int, RandomState instance, default=None): Controls the randomization of the algorithm.
+
+    Methods:
+        _fit_resample(X, y): Core resampling logic that executes Re-SC1 and returns concatenated arrays.
+        get_feature_names_out(input_features): Generates output feature names for the 2d concatenated space.
+    """
+    _sampling_type = 'over-sampling'
+    _parameter_constraints = {
+        "M": [Interval(Real, 0, None, closed="left")],          
+        "k": [Interval(Integral, 1, None, closed="left")],      
+        "alpha": [Interval(Real, 0, 1, closed="both")],         
+        "epsilon": [Interval(Real, 0, None, closed="neither")], 
+        "random_state": ["random_state"]                        
+    }
+    def __init__(self, M=1.5, k=5, alpha=0.05, epsilon=0.05, random_state=None):
+        super().__init__()
+        self.M = M
+        self.k = k
+        self.alpha = alpha
+        self.epsilon = epsilon
+        self.random_state = random_state
+
+    def _fit_resample(
+        self, 
+        X: NDArray[np.float64], 
+        y: NDArray[np.int_]
+    ) -> Tuple[NDArray[np.float64], NDArray[np.int_]]:
+        """
+        Executes resampling logic for Re-SC.
+
+        Args:
+            X (numpy.typing.NDArray[np.float64]): 2D matrix containing the features of the original training dataset.
+            y (numpy.typing.NDArray[np.int_]): 1D array containing the target labels.
+
+        Returns:
+            Tuple[numpy.typing.NDArray[np.float64], numpy.typing.NDArray[np.int_]]: 
+                A tuple containing the resampled feature matrix (mapped to a 2d space) 
+                and the corresponding label array.
+
+        Raises:
+            ValueError: If the dataset does not contain at least two distinct classes.
+        """ 
+        random_state = check_random_state(self.random_state)
+        np.random.seed(random_state.randint(0, 2**31 - 1))
+        
+        labels, counts = np.unique(y, return_counts=True)
+        if len(labels) < 2:
+            raise ValueError("The target 'y' needs to have at least two classes.")
+            
+        min_label = labels[np.argmin(counts)]
+        maj_label = labels[np.argmax(counts)]
+
+        X_min = X[y == min_label]
+        X_maj = X[y == maj_label]
+
+        target_size = calculate_set_n_size_re_sc(
+            X_maj=X_maj, 
+            P=len(X_min), 
+            alpha=self.alpha, 
+            epsilon=self.epsilon, 
+            M=self.M
+        )
+        X_set_n = get_set_n_random_weighted_re_sc(
+            X=X, 
+            y=y, 
+            n_size=target_size, 
+            k=self.k
+        )
+        X_resampled, y_resampled = re_sc_concatenation(
+            X_min=X_min, 
+            X_maj=X_maj, 
+            X_set_n=X_set_n,
+            min_label=min_label,
+            maj_label=maj_label
+        )
+
+        return X_resampled, y_resampled
+
+    def get_feature_names_out(
+        self, 
+        input_features: Optional[Union[List[str], NDArray[np.object_]]] = None
+    ) -> NDArray[np.object_]:
+        """
+        Get output feature names for transformation. 
+
+        Args:
+            input_features (Optional[Union[List[str], numpy.typing.NDArray[np.object_]]]): 
+                Original input feature names. If None, generic names are generated.
+
+        Returns:
+            numpy.typing.NDArray[np.object_]: An array of strings containing the new feature 
+                names for the 2d concatenated space.
+        """
+        if input_features is None:
+            input_features = [f"x{i}" for i in range(self.n_features_in_)]
+
+        out_features = [f"{name}_1" for name in input_features] + [f"{name}_2" for name in input_features]
+
+        return np.asarray(out_features, dtype=object)

imblearn_resc-0.1.0/imblearn_resc/oversampling/ReSC/utils/_resc_utils.py

@@ -0,0 +1,184 @@
+from typing import Tuple
+
+import numpy as np
+from numpy.typing import NDArray
+
+import scipy.stats as stats
+
+from sklearn.neighbors import NearestNeighbors
+
+def calculate_set_n_size_re_sc(
+    X_maj: NDArray[np.float64], 
+    P: int, 
+    alpha: float = 0.05, 
+    epsilon: float = 0.05, 
+    M: float = 1.5
+) -> int:
+    """
+    Calculates the target size for the majority subset (Set_N) in the Re-SC algorithm.
+
+    Args:
+        X_maj (numpy.typing.NDArray[np.float64]): 2D NumPy array containing features of the majority class.
+        P (int): number of samples in the minority class.
+        alpha (float): significance level for the Z-test used to compute statistical sample size.
+        epsilon (float): acceptable tolerance error for representing the majority class distribution
+        M (float): acceptable imbalance ratio threshold.
+
+    Returns:
+        int: The calculated number of majority samples for Set_N.
+
+    Raises:
+        ValueError: If X_maj is an empty array. 
+    """ 
+    n_maj: int = len(X_maj)
+    if n_maj == 0:
+        raise ValueError("X_maj cannot be empty.")
+    
+    n1 = (P ** 2) / n_maj
+    z_score = stats.norm.ppf(1 - alpha / 2)
+    sigma = np.std(X_maj, ddof=1) 
+    z_sq = z_score ** 2
+    sigma_sq = sigma ** 2
+    epsilon_sq = epsilon ** 2
+    
+    numerator = n_maj * z_sq * sigma_sq 
+    denominator = (n_maj * epsilon_sq) + (z_sq * sigma_sq) 
+    n2 = numerator / denominator
+
+    if n1 == 0: 
+        return int(n2)
+    
+    Pr = n2 / n1
+
+    if Pr < 1:
+        set_n_size = n1
+    elif 1 <= Pr <= M:
+        set_n_size = n2
+    else: 
+        set_n_size = M * n1
+        
+    return int(np.ceil(set_n_size))
+
+def get_set_n_random_weighted_re_sc(
+    X: NDArray[np.float64], 
+    y: NDArray[np.int_], 
+    n_size: int, 
+    k: int = 5
+) -> NDArray[np.float64]:
+    """
+    Selects a subset of majority class samples (Set_N) using a density-weighted random sampling strategy.
+
+    Args:
+        X (numpy.typing.NDArray[np.float64]): 2D NumPy array containing entire training dataset.
+        y (numpy.typing.NDArray[np.int_]): 1D NumPy array containing labels.
+        n_size (int): number of majority samples to select.
+        k (int, optional): number of nearest neighbors to evaluate for the weighting mechanism. Defaults to 5.
+
+    Returns:
+        numpy.typing.NDArray[np.float64]: A 2D NumPy array containing selected majority subset.
+
+    Raises:
+        ValueError: If there are no majority samples present in the dataset.
+        ValueError: If no valid majority samples are found.
+    """
+    labels, counts = np.unique(y, return_counts=True)
+    maj_label = labels[np.argmax(counts)]
+
+    maj_mask = (y == maj_label)
+    maj_indices = np.where(maj_mask)[0]
+    
+    if len(maj_indices) == 0:
+        raise ValueError("No majority samples found in the dataset.")
+    
+    X_mean = np.mean(X, axis=0)
+    X_std = np.std(X, axis=0)
+    X_std[X_std == 0] = 1.0 
+    X_norm = (X - X_mean) / X_std
+    
+    knn = NearestNeighbors(n_neighbors=k + 1).fit(X_norm)
+    
+    X_maj_norm = X_norm[maj_indices]
+    distances, neighbor_idxs = knn.kneighbors(X_maj_norm)
+    
+    weights = []
+    valid_indices = []
+    
+    for i, n_idxs in enumerate(neighbor_idxs):
+        actual_neighbors = n_idxs[1:]  
+        maj_neighbor_count = np.sum(y[actual_neighbors] == maj_label)
+        weight = maj_neighbor_count / k
+
+        if weight > 0:
+            weights.append(weight)
+            valid_indices.append(maj_indices[i])
+            
+    weights_arr = np.array(weights, dtype=np.float64)
+    valid_indices_arr = np.array(valid_indices, dtype=np.int_)
+    
+    if len(weights_arr) == 0:
+        raise ValueError("No valid majority samples found (all are surrounded by minority class).")
+        
+    probs = weights_arr / np.sum(weights_arr)
+    actual_n_size = min(n_size, len(valid_indices_arr))
+
+    selected_indices = np.random.choice(
+        valid_indices_arr, 
+        size=actual_n_size, 
+        replace=False, 
+        p=probs
+    )
+    
+    return X[selected_indices]
+
+def re_sc_concatenation(
+    X_min: NDArray[np.float64], 
+    X_maj: NDArray[np.float64], 
+    X_set_n: NDArray[np.float64],
+    min_label: int = 1,
+    maj_label: int = -1
+) -> Tuple[NDArray[np.float64], NDArray[np.int_]]:
+    """
+    Concatenates pairs of samples from the same class to map the dataset into a 2d dimensional space.
+
+    Args:
+        X_min (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the minority class.
+        X_maj (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the original majority class.
+        X_set_n (numpy.typing.NDArray[np.float64]): 2D NumPy array containing the features of the selected majority subset.
+        min_label (int, optional): The target label assigned to the minority class.
+        maj_label (int, optional): The target label assigned to the majority class.
+
+    Returns:
+        Tuple[numpy.typing.NDArray[np.float64], numpy.typing.NDArray[np.int_]]: 
+            A tuple containing:
+            - X_resampled: The concatenated 2D NumPy array with 2 * d features.
+            - y_resampled: The 1D NumPy array containing the target labels for the new samples.
+
+    Raises:
+        ValueError: If X_min is empty, as the minority class must contain at least one sample.
+    """
+    m = len(X_min)
+    if m == 0:
+        raise ValueError("X_min cannot be empty. Minority class must have at least one sample.")
+    
+    P_repeat = np.repeat(X_min, m, axis=0)
+    P_tile = np.tile(X_min, (m, 1))
+    P_c = np.hstack([P_repeat, P_tile]) 
+    
+    y_p_c = np.full(len(P_c), min_label, dtype=np.int_)
+
+    M = len(X_maj)
+    k = len(X_set_n)
+    
+    if k > 0:
+        N_repeat = np.repeat(X_maj, k, axis=0)  
+        Set_N_tile = np.tile(X_set_n, (M, 1)) 
+        N_c = np.hstack([N_repeat, Set_N_tile])
+        y_n_c = np.full(len(N_c), maj_label, dtype=np.int_)
+        
+        X_c_array = np.vstack([P_c, N_c])
+        y_c_array = np.hstack([y_p_c, y_n_c])
+    else:
+        X_c_array = P_c
+        y_c_array = y_p_c
+
+    return X_c_array, y_c_array

imblearn_resc-0.1.0/imblearn_resc/oversampling/__init__.py

@@ -0,0 +1,4 @@
+from .ReSC import ReSC
+from .KMeansReSC import KMeansReSC
+
+__all__ = ["ReSC", "KMeansReSC"]

imblearn_resc-0.1.0/imblearn_resc/preprocessing/__init__.py

@@ -0,0 +1,3 @@
+from ._resc_transformer import ReSCTransformer
+
+__all__ = ["ReSCTransformer"]

imblearn_resc-0.1.0/imblearn_resc/preprocessing/_resc_transformer.py

@@ -0,0 +1,55 @@
+from typing import Optional, Union, List
+
+import numpy as np
+from numpy.typing import NDArray
+
+from sklearn.base import BaseEstimator, TransformerMixin
+from sklearn.utils.validation import check_is_fitted, check_array, validate_data
+
+
+class ReSCTransformer(TransformerMixin, BaseEstimator):
+    """
+    Transforms test data into a 2d concatenated space for prediction with Re-SC models.
+    
+    This transformer must be placed immediately after a Re-SC sampler in a Pipeline.
+    - During training (fit_transform), it receives data that the Sampler has already 
+      mapped to 2d space, so it simply passes it through.
+    - During testing (predict), the Sampler is bypassed, so this Transformer receives 
+      data in the original d space. It duplicates the features (x -> [x, x]) to 
+      match the 2d space the classifier expects.
+    """
+
+    def __init__(self):
+        pass
+
+    def fit(self, X: NDArray[np.float64], y: Optional[NDArray] = None) -> 'ReSCTransformer':
+        X = validate_data(self, X=X, reset=True, accept_sparse=False)
+        self.original_d_ = self.n_features_in_ // 2
+        self.is_fitted_ = True
+
+        return self
+
+    def transform(self, X: NDArray[np.float64]) -> NDArray[np.float64]:
+        check_is_fitted(self, 'is_fitted_')
+        X = check_array(X, accept_sparse=False)
+
+        if X.shape[1] == self.original_d_:
+            return np.hstack([X, X])
+
+        X = validate_data(self, X, reset=False, accept_sparse=False)
+
+        return X
+
+    def get_feature_names_out(
+        self, 
+        input_features: Optional[Union[List[str], NDArray[np.object_]]] = None
+    ) -> NDArray[np.object_]:
+        check_is_fitted(self, 'is_fitted_')
+        
+        if input_features is None:
+            input_features = [f"x{i}" for i in range(self.original_d_)]
+
+        out_features = [f"{name}_1" for name in input_features] + \
+                       [f"{name}_2" for name in input_features]
+
+        return np.asarray(out_features, dtype=object)

imblearn_resc-0.1.0/imblearn_resc.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: imblearn_resc
+Version: 0.1.0
+Summary: Resampling based on Sample Concatenation (Re-SC) algorithms for imbalanced learning
+Author-email: maksimkins <maks.aleshkov.04@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/maksimkins/resampling-methods
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: scikit-learn>=1.4.0
+Requires-Dist: imbalanced-learn>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# imblearn-resc
+
+**Re-SC (Resampling based on Sample Concatenation)** algorithms for imbalanced learning. 
+
+This package is fully compatible with the `scikit-learn` and `imbalanced-learn` ecosystems. It addresses class imbalance by mapping data into a higher-dimensional (2d) concatenated feature space, utilizing either density-weighted random sampling (`ReSC`) or K-Means clustering (`KMeansReSC`) to safely resample the majority and minority classes.
+
+## 📦 Installation
+
+You can install `imblearn-resc` directly from PyPI using pip:
+
+```bash
+pip install imblearn-resc
+```
+
+*Requires Python >=3.11, scikit-learn >=1.4.0, and imbalanced-learn >=0.12.0*
+
+---
+
+## 🚀 Quick Start & Usage
+
+Because Re-SC algorithms map your original features ($d$) into a concatenated feature space ($2d$), **you must always pair the Sampler with the `ReSCTransformer` inside an `imblearn` Pipeline.**
+
+* **The Sampler** (`ReSC` or `KMeansReSC`) transforms the training data during `.fit_resample()`.
+* **The Transformer** (`ReSCTransformer`) bypasses the training data, but safely duplicates the test data features ($x \rightarrow [x, x]$) during `.predict()` so your classifier receives the correct dimensions.
+
+### Example: Complete Pipeline
+
+Here is a full, runnable example of how to use `ReSC` and `KMeansReSC` with a standard machine learning classifier.
+
+```python
+from sklearn.datasets import make_classification
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.model_selection import train_test_split
+from sklearn.metrics import classification_report
+
+# 1. Import the pipeline from imbalanced-learn (NOT standard sklearn!)
+from imblearn.pipeline import Pipeline
+
+# 2. Import the Re-SC Samplers and Transformer
+from imblearn_resc.oversampling import ReSC, KMeansReSC
+from imblearn_resc.preprocessing import ReSCTransformer
+
+# Generate a highly imbalanced dummy dataset (10% minority, 90% majority)
+X, y = make_classification(
+    n_classes=2, class_sep=2, weights=[0.1, 0.9], 
+    n_informative=3, n_redundant=1, flip_y=0,
+    n_features=5, n_clusters_per_class=1, 
+    n_samples=1000, random_state=42
+)
+
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+# ==========================================
+# Option A: Standard ReSC Pipeline
+# ==========================================
+pipeline_resc = Pipeline([
+    ('sampler', ReSC(M=1.5, k=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_resc.fit(X_train, y_train)
+y_pred_resc = pipeline_resc.predict(X_test)
+
+print("ReSC Classification Report:")
+print(classification_report(y_test, y_pred_resc))
+
+
+# ==========================================
+# Option B: KMeansReSC Pipeline
+# ==========================================
+pipeline_kmeans = Pipeline([
+    ('sampler', KMeansReSC(M=1.5, num_candidates_to_test=5, random_state=42)),
+    ('transformer', ReSCTransformer()),             # <--- Mandatory!
+    ('classifier', RandomForestClassifier(random_state=42))
+])
+
+# Train and Predict
+pipeline_kmeans.fit(X_train, y_train)
+y_pred_kmeans = pipeline_kmeans.predict(X_test)
+
+print("KMeansReSC Classification Report:")
+print(classification_report(y_test, y_pred_kmeans))
+```
+
+## 🧠 Key Parameters
+
+### `ReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`k`** *(int, default=5)*: Number of nearest neighbors used to calculate majority sample weights.
+* **`alpha`** *(float, default=0.05)*: Significance level for the Z-test used to compute the required statistical sample size.
+
+### `KMeansReSC`
+* **`M`** *(float, default=1.5)*: The maximum acceptable imbalance ratio threshold for the resulting dataset.
+* **`num_candidates_to_test`** *(int, default=5)*: How many 'k' values (clusters) to test during geometric tuning using the Silhouette Score.

imblearn_resc-0.1.0/imblearn_resc.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+imblearn_resc/__init__.py
+imblearn_resc.egg-info/PKG-INFO
+imblearn_resc.egg-info/SOURCES.txt
+imblearn_resc.egg-info/dependency_links.txt
+imblearn_resc.egg-info/requires.txt
+imblearn_resc.egg-info/top_level.txt
+imblearn_resc/oversampling/__init__.py
+imblearn_resc/oversampling/KMeansReSC/__init__.py
+imblearn_resc/oversampling/KMeansReSC/_resc_kmeans.py
+imblearn_resc/oversampling/KMeansReSC/utils/__init__.py
+imblearn_resc/oversampling/KMeansReSC/utils/_resc_kmeans_utils.py
+imblearn_resc/oversampling/ReSC/__init__.py
+imblearn_resc/oversampling/ReSC/_resc.py
+imblearn_resc/oversampling/ReSC/utils/__init__.py
+imblearn_resc/oversampling/ReSC/utils/_resc_utils.py
+imblearn_resc/preprocessing/__init__.py
+imblearn_resc/preprocessing/_resc_transformer.py

imblearn_resc-0.1.0/imblearn_resc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

imblearn_resc-0.1.0/imblearn_resc.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy>=1.24.0
+scipy>=1.10.0
+scikit-learn>=1.4.0
+imbalanced-learn>=0.12.0
+
+[dev]
+pytest>=7.0.0

imblearn_resc-0.1.0/imblearn_resc.egg-info/top_level.txt

@@ -0,0 +1 @@
+imblearn_resc

imblearn_resc-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "imblearn_resc"
+version = "0.1.0"
+description = "Resampling based on Sample Concatenation (Re-SC) algorithms for imbalanced learning"
+authors = [
+    {name = "maksimkins", email = "maks.aleshkov.04@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "numpy>=1.24.0",
+    "scipy>=1.10.0",
+    "scikit-learn>=1.4.0",
+    "imbalanced-learn>=0.12.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/maksimkins/resampling-methods"
+
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]  
+include = ["imblearn_resc*"]
+
+[tool.pytest.ini_options]
+pythonpath = ["."]

imblearn_resc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+