Skip to content

instance_sampling

UniformInstanceAttributeSampling

Bases: OutliersGenerator

Randomly generates outliers by sampling from existing instances attributes uniformly at random.

Each appended outlier row is a per-cell bootstrap: every cell copies the value of a random real row (via :class:badgers.core.sampling.InstanceSampler), so values are individually plausible while the row as a whole never existed.

The generator has no seed rows, so a selector has nothing to select on: selector is accepted for API uniformity but IGNORED (a warning is emitted; n_outliers remains the only count knob). The count must not exceed the dataset size (a larger count raises).

Source code in badgers/generators/tabular_data/outliers/instance_sampling.py
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
class UniformInstanceAttributeSampling(OutliersGenerator):
    """
    Randomly generates outliers by sampling from existing instances attributes uniformly at random.

    Each appended outlier row is a per-cell bootstrap: every cell copies
    the value of a random real row (via
    :class:`badgers.core.sampling.InstanceSampler`), so values are
    individually plausible while the row as a whole never existed.

    The generator has no seed rows, so a selector has nothing to select on:
    ``selector`` is accepted for API uniformity but IGNORED (a warning is
    emitted; ``n_outliers`` remains the only count knob). The count must
    not exceed the dataset size (a larger count raises).
    """

    def __init__(self, random_generator):
        """
        Initialize the UniformInstanceAttributeSampling with a random number generator.

        :param random_generator: An instance of numpy's random number generator (required; no default).
        """
        super().__init__(random_generator)

    @preprocess_inputs
    def generate(self, X, n_outliers: int = 10, *, selector=None):
        """
        Randomly generates outliers by sampling from existing instances attributes uniformly at random.

        :param X: the input features (pandas DataFrame or numpy array).
        :param n_outliers: The number of outliers to generate (must not exceed the number of rows of X).
        :param selector: accepted for API uniformity, ignored (this generator has no seed rows; the copy pool stays all of X).
        :return: The augmented feature matrix with added outliers.
        """
        if selector is not None:
            warnings.warn(
                "UniformInstanceAttributeSampling has no seed rows: the "
                "selector is ignored (the copy pool stays all of X) and "
                "n_outliers keeps counting the appended rows.",
                UserWarning,
                stacklevel=2,
            )
        if n_outliers > len(X):
            raise ValueError(
                f"n_outliers must not exceed the number of rows of X "
                f"({len(X)}), got {n_outliers}")
        if n_outliers <= 0:
            raise ValueError(f"n_outliers must be a positive count, got {n_outliers}")

        outliers = InstanceSampler().sample(
            self.random_generator, X, columns=list(range(X.shape[1])),
            n_samples=n_outliers,
        )

        # Append outliers to original data
        Xt = np.vstack([X, outliers])

        self._set_outlier_labels(len(X), n_outliers)
        return Xt

__init__(random_generator)

Initialize the UniformInstanceAttributeSampling with a random number generator.

Parameters:

Name Type Description Default
random_generator

An instance of numpy's random number generator (required; no default).

required
Source code in badgers/generators/tabular_data/outliers/instance_sampling.py
25
26
27
28
29
30
31
def __init__(self, random_generator):
    """
    Initialize the UniformInstanceAttributeSampling with a random number generator.

    :param random_generator: An instance of numpy's random number generator (required; no default).
    """
    super().__init__(random_generator)

generate(X, n_outliers=10, *, selector=None)

Randomly generates outliers by sampling from existing instances attributes uniformly at random.

Parameters:

Name Type Description Default
X

the input features (pandas DataFrame or numpy array).

required
n_outliers int

The number of outliers to generate (must not exceed the number of rows of X).

10
selector

accepted for API uniformity, ignored (this generator has no seed rows; the copy pool stays all of X).

None

Returns:

Type Description

The augmented feature matrix with added outliers.

Source code in badgers/generators/tabular_data/outliers/instance_sampling.py
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@preprocess_inputs
def generate(self, X, n_outliers: int = 10, *, selector=None):
    """
    Randomly generates outliers by sampling from existing instances attributes uniformly at random.

    :param X: the input features (pandas DataFrame or numpy array).
    :param n_outliers: The number of outliers to generate (must not exceed the number of rows of X).
    :param selector: accepted for API uniformity, ignored (this generator has no seed rows; the copy pool stays all of X).
    :return: The augmented feature matrix with added outliers.
    """
    if selector is not None:
        warnings.warn(
            "UniformInstanceAttributeSampling has no seed rows: the "
            "selector is ignored (the copy pool stays all of X) and "
            "n_outliers keeps counting the appended rows.",
            UserWarning,
            stacklevel=2,
        )
    if n_outliers > len(X):
        raise ValueError(
            f"n_outliers must not exceed the number of rows of X "
            f"({len(X)}), got {n_outliers}")
    if n_outliers <= 0:
        raise ValueError(f"n_outliers must be a positive count, got {n_outliers}")

    outliers = InstanceSampler().sample(
        self.random_generator, X, columns=list(range(X.shape[1])),
        n_samples=n_outliers,
    )

    # Append outliers to original data
    Xt = np.vstack([X, outliers])

    self._set_outlier_labels(len(X), n_outliers)
    return Xt