API Reference / preprocessing / sampling /

reservoir.py

ReservoirSampler filter.

Reservoir sampling for streaming/large datasets.

Classes

ReservoirSampler

class preprocessing.sampling.reservoir.ReservoirSampler(ResamplingTransformer)

Reservoir sampling for random sampling from large datasets.

Implements Algorithm R (Vitter, 1985) for uniform random sampling without replacement. Useful for streaming data or when dataset is too large to fit in memory.
Constructor 
__init__(
    self,
    sample_size: int = 100,
    random_state: Optional[int] = None,
)

Parameters

sample_size
int = 100
Number of instances to sample.
random_state
int
Random seed for reproducibility.
python 
>>> import numpy as np
>>> from tuiml.preprocessing.sampling import ReservoirSampler
python 
>>> X = np.arange(1000).reshape(-1, 1)
>>> y = np.zeros(1000)
python 
>>> # Sample 100 instances
>>> sampler = ReservoirSampler(sample_size=100, random_state=42)
>>> X_sample, y_sample = sampler.fit_transform(X, y)
>>> len(X_sample)
100

Notes

This implementation is deterministic given a random_state. For true streaming applications, you would typically process data one instance at a time.

References

Vitter, J. S. (1985). Random sampling with a reservoir. ACM Transactions on Mathematical Software, 11(1), 37-57.

Methods

get_parameter_schema (cls)
fit (self, X: np.ndarray, y: Optional[np.ndarray]=None) -> 'ReservoirSampler'

Fit the sampler.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input data. Unused: reservoir sampling needs no fitted state.
y
np.ndarray
Ignored, present for API consistency.
Returns
self
object
The fitted sampler.
transform (self, X: np.ndarray, y: Optional[np.ndarray]=None) -> Tuple[np.ndarray, Optional[np.ndarray]]

Draw a fixed-size uniform sample in a single pass.

Parameters
X
np.ndarray of shape (n_samples, n_features)
Input data.
y
np.ndarray of shape (n_samples,)
Target values, sampled with the same indices when given.
Returns
X_sampled
np.ndarray
At most sample_size rows drawn uniformly from X.
y_sampled
np.ndarray or None
Matching targets, or None when y was not supplied.
__repr__ (self) -> str