IntraSiteInterpolation advance usage

Global Maximum Balancing

# Balance all sites to the single largest class count found anywhere:

import numpy as np

from uniharmony.datasets import make_multisite_classification
from uniharmony.interpolation import IntraSiteInterpolation


X, y, sites = make_multisite_classification(balance_per_site=[0.3, 0.7])
isi = IntraSiteInterpolation(balance_strategy="global_max", interpolator="random", random_state=42)

X_balanced, y_balanced = isi.fit_resample(X, y, sites=sites)
print(f"Global target count: {isi.target_count_}")

2026-06-10 10:54:20 [debug    ] Total Samples to generate 1000
2026-06-10 10:54:20 [debug    ] Total Samples to generate per site [500 500]
2026-06-10 10:54:20 [debug    ] Using the same balance_per_site for all sites.
2026-06-10 10:54:20 [info     ] `balance_per_site` is: [[0.3, 0.7], [0.3, 0.7]]
2026-06-10 10:54:20 [info     ] Overall class balance across sites: [0.3 0.7]
2026-06-10 10:54:20 [info     ] For site 0
2026-06-10 10:54:20 [info     ] Generating 500 samples
2026-06-10 10:54:20 [debug    ] Balance [0.3, 0.7] for site 0
2026-06-10 10:54:20 [debug    ] Site 0, site effect strength [3.0, 3.0]
2026-06-10 10:54:20 [info     ] For site 1
2026-06-10 10:54:20 [info     ] Generating 500 samples
2026-06-10 10:54:20 [debug    ] Balance [0.3, 0.7] for site 1
2026-06-10 10:54:20 [debug    ] Site 1, site effect strength [3.0, 3.0]
2026-06-10 10:54:20 [info     ] Generated 1000 samples across 2 sites
2026-06-10 10:54:20 [info     ] Class distribution: [300 700]
2026-06-10 10:54:20 [info     ] Site distribution: [500 500]
2026-06-10 10:54:20 [info     ] [ISI] Starting fit_resample
2026-06-10 10:54:20 [debug    ] [ISI] N target for global_max strategy = 350
2026-06-10 10:54:20 [info     ] [ISI] Processing site 0
2026-06-10 10:54:20 [debug    ] [ISI] For site 0, N target for per_site strategy = 350
2026-06-10 10:54:20 [info     ] [ISI] Processing site 1
2026-06-10 10:54:20 [debug    ] [ISI] For site 1, N target for per_site strategy = 350
Global target count: 350

Covariates

Stratified Interpolation with Covariates

# Preserve demographic distributions while balancing classes.
# Synthetic samples are interpolated only between participants matching on all covariates:
rng = np.random.default_rng(54)
n_samples = 1000
X, y, sites = make_multisite_classification(n_samples=n_samples, balance_per_site=[0.3, 0.7])
sex = rng.integers(0, 2, (n_samples, 1))
age = rng.standard_normal((n_samples, 1)) * 10 + 50
isi = IntraSiteInterpolation(balance_strategy="per_site", random_state=42)

X_balanced, y_balanced = isi.fit_resample(
    X, y, sites=sites, categorical_covariate=sex, continuous_covariate=age, n_bins_cont_cov=2
)  # Age binned with 5 bins

2026-06-10 10:54:20 [debug    ] Total Samples to generate 1000
2026-06-10 10:54:20 [debug    ] Total Samples to generate per site [500 500]
2026-06-10 10:54:20 [debug    ] Using the same balance_per_site for all sites.
2026-06-10 10:54:20 [info     ] `balance_per_site` is: [[0.3, 0.7], [0.3, 0.7]]
2026-06-10 10:54:20 [info     ] Overall class balance across sites: [0.3 0.7]
2026-06-10 10:54:20 [info     ] For site 0
2026-06-10 10:54:20 [info     ] Generating 500 samples
2026-06-10 10:54:20 [debug    ] Balance [0.3, 0.7] for site 0
2026-06-10 10:54:20 [debug    ] Site 0, site effect strength [3.0, 3.0]
2026-06-10 10:54:20 [info     ] For site 1
2026-06-10 10:54:20 [info     ] Generating 500 samples
2026-06-10 10:54:20 [debug    ] Balance [0.3, 0.7] for site 1
2026-06-10 10:54:20 [debug    ] Site 1, site effect strength [3.0, 3.0]
2026-06-10 10:54:20 [info     ] Generated 1000 samples across 2 sites
2026-06-10 10:54:20 [info     ] Class distribution: [300 700]
2026-06-10 10:54:20 [info     ] Site distribution: [500 500]
2026-06-10 10:54:20 [info     ] [ISI] Starting fit_resample
2026-06-10 10:54:20 [debug    ] Using 1 categorical covariates
2026-06-10 10:54:20 [debug    ] No tolerance specified, using exact matching
2026-06-10 10:54:20 [debug    ] Using 1 continuous covariates with tolerance: [0.]
2026-06-10 10:54:20 [info     ] [ISI] Processing site 0
2026-06-10 10:54:20 [debug    ] [ISI] For site 0, N target for per_site strategy = 350
2026-06-10 10:54:20 [info     ] [ISI] Processing site 1
2026-06-10 10:54:20 [debug    ] [ISI] For site 1, N target for per_site strategy = 350