acoupipe.sampler

Random processes to sample values according to a specified random distribution (random variable).

Sampler Module Purpose

A manipulation of object characteristics according to a certain random distribution can be achieved by using the BaseSampler derived classes included in the sampler.py module. All BaseSampler derived classes represent random processes that can be used to manipulate the attributes of Acoular’s objects according to a specified distribution. A random process is defined by a random variable and a corresponding random state. Both properties are attributes of all BaseSampler derived classes. AcouPipe offers a variety of different types of samplers in the sampler.py module. The random variable that can be passed to class instances of the sampler module must either be derived from or be part of the scipy.stats module.

This example illustrates how the RMS value of two white noise signals can be sampled according to a normal distribution. For this purpose, an instance of the BaseSampler derived NumericAttributeSampler class is used. The two WNoiseGenerator objects are given as targets to the sampler object. New RMS values following a normal distribution are assigned to the WNoiseGenerator objects each time the sample method of the NumericAttributeSampler object is evaluated.

import acoular as ac
from acoupipe.sampler import NumericAttributeSampler
from scipy.stats import norm

random_var = norm(loc=1.,scale=.5)

n1 = ac.WNoiseGenerator( sample_freq=24000,
                numsamples=24000*5,
                rms=1.0,
                seed=1 )

n2 = ac.WNoiseGenerator( sample_freq=24000,
                numsamples=24000*5,
                rms=.5,
                seed=2 )

rms_sampler = NumericAttributeSampler(
                target=[n1,n2],
                attribute='rms',
                random_var=random_var,
                random_state=10)

rms_sampler.sample()
print(n1.rms, n2.rms)

The output of the example is:

1.6657932520647591 1.3576394871992028

Module Contents

class acoupipe.sampler.BaseSampler

Bases: traits.api.HasPrivateTraits

Base class that represents a random process.

This class has no functionality and should not be used in practice. Manipulates attributes of an instance or a list of instances according to a specified random distribution.

rvs(size=1): Random variable sampling (for internal use).

sample(): Utilizes rvs() function to draw random values from random_var (no functionality in this class).

class acoupipe.sampler.NumericAttributeSampler

Bases: BaseSampler

Samples attributes of numeric type (e.g. int, float).

This class samples attributes of numeric type (e.g. int, float) of an instance or a list of instances according to a specified random distribution. The attribute to be sampled is specified by attribute. The sampled values are normalized to the range [0,1] if normalize is set to True. The sampled values are ordered in ascending or descending order for all objects in the target list if order is set to “ascending” or “descending”. If no value is set (order =None), no ordering is performed.

order_samples(samples): Order drawn values (Internal function).

sample()

Random sampling of the target instance attribute.

Utilizes rvs() function to draw random values from random_var that are going to be assigned to the target instance attribute via internal set_value() method.

class acoupipe.sampler.SetSampler

Bases: BaseSampler

Draws one or multiple values from a given set of values.

This class draws one or multiple values from a given set of values. The set of values is specified by set. The number of samples to be drawn is specified by numsamples. The attribute to be sampled is specified by attribute. A list with sample probabilities can be specified by probabilities. The attribute replace specifies if the same object in set can be drawn multiple times.

rvs(size=1): Random variable sampling (for internal use).

sample()

Random sampling of the target instance attribute.

Utilizes rvs() function to draw random values from set that are going to be assigned to the target instance attribute attribute via internal set_value() method.

class acoupipe.sampler.SourceSetSampler

Bases: SetSampler

Draws one or multiple sources of type acoular.SamplesGenerator from a given set of sources.

From a given set of sources (type acoular.SamplesGenerator), SourceSetSampler draws one or multiple sources from this set and assigns those to one or more SourceMixer instances. The number of sources to be drawn is specified by nsources. The attribute to be sampled is specified by attribute.

sample()

Random sampling of sources.

Utilizes rvs() function to draw sources from set that are going to be assigned to the acoular.SourceMixer instance.

class acoupipe.sampler.ContainerSampler

Bases: BaseSampler

Special case of a Sampler to enable the use of an arbitrary sampling function.

Takes an arbitrary callable with the signature ‘<Signature (numpy.random.RandomState)>’ or ‘<Signature (numpy.random.Generator)>’. The callable is evoked via the sample() method of this class. The output of the callable is assigned to the target attribute.

rvs(): Evokes the random_func.

sample()

Random sampling.

this function utilizes rvs() function to evaluate the random_func. The output of the random_func can be accessed with the target attribute.

class acoupipe.sampler.LocationSampler

Bases: BaseSampler

Base class that represents a random process.

This class has no functionality and should not be used in practice. Manipulates attributes of an instance or a list of instances according to a specified random distribution.

rvs(): Random variable sampling (for internal use).

sample(): Random sampling of locations.

class acoupipe.sampler.PointSourceSampler

Bases: LocationSampler

Random process that samples the locations of one or more instances of type PointSource.

sample_loc(target): Sample a single target location (internal use).

rvs(size=1): Random variable sampling (for internal use).

sample(): Random sampling of acoular.PointSource locations.

class acoupipe.sampler.MicGeomSampler

Bases: BaseSampler

Random disturbance of microphone positions of a acoular.MicGeom object.

rotate(): Rotates the microphone array.

translate(): Translate the microphone array.

deviate(): Deviates the individual microphone positions.

sample(): Random sampling of microphone positions.