topo.misc.distribution

Module

Distribution class

class topo.misc.distribution.DSF_BimodalPeaks(**params)[source]

Bases: topo.misc.distribution.DescriptiveBimodalStatisticFn

Return the two peak values of distributions in the given matrix

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DSF_BimodalVonMisesFit(**params)[source]

Bases: topo.misc.distribution.VonMisesStatisticFn

Return the two modes of distributions in the given matrix, by fit with von Mises function

The results of the main mode are available in self.{preference,selectivity,good_of_fit}, while the second mode results are in the first element of the self.more_modes list, as a dictionary with keys preference,selectivity,good_of_fit.

param Number worst_fit (allow_None=False, bounds=(0.0, None), constant=False, default=0.5, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)
worst good-of-fitness value for accepting the distribution as mono- or bi-modal
param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DSF_MaxValue(**params)[source]

Bases: topo.misc.distribution.DescriptiveStatisticFn

Return the peak value of the given distribution

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DSF_TopTwoValues(**params)[source]

Bases: topo.misc.distribution.DescriptiveBimodalStatisticFn

Return the two max values of distributions in the given matrix

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DSF_VonMisesFit(**params)[source]

Bases: topo.misc.distribution.VonMisesStatisticFn

Return the main mode of distribution in the given matrix, by fit with von Mises function

param Number worst_fit (allow_None=False, bounds=(0.0, None), constant=False, default=0.5, inclusive_bounds=(True, True), instantiate=False, pickle_default_value=True, precedence=None, readonly=False)
worst good-of-fitness value for accepting the distribution as monomodal
param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DSF_WeightedAverage(**params)[source]

Bases: topo.misc.distribution.DescriptiveStatisticFn

Return the main mode of the given distribution

The prefence value ia a continuous, interpolated equivalent of the max_value_bin(). For a cyclic distribution, this is the direction of the vector sum (see vector_sum()). For a non-cyclic distribution, this is the arithmetic average of the data on the bin_axis, where each bin is weighted by its value. Such a computation will generally produce much more precise maps using fewer test stimuli than the discrete method. However, weighted_average methods generally require uniform and full-range sampling, which is not always feasible. For measurements at evenly-spaced intervals over the full range of possible parameter values, weighted_averages are a good measure of the underlying continuous-valued parameter preference, assuming that neurons are tuned broadly enough (and/or sampled finely enough) that they respond to at least two of the tested parameter values. This method will not usually give good results when those criteria are not met, i.e. if the sampling is too sparse, not at evenly-spaced intervals, or does not cover the full range of possible values. In such cases max_value_bin should be used, and the number of test patterns will usually need to be increased instead.

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.DescriptiveBimodalStatisticFn(**params)[source]

Bases: topo.misc.distribution.DescriptiveStatisticFn

Abstract class for descriptive statistics of two-modes distributions

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
second_max_value_bin(d)[source]

Return the bin with the second largest value. If there is one bin only, return it. This is not a correct result, however it is practical for plotting compatibility, and it will not mistakenly be claimed as secondary maximum, by forcing its selectivity to 0.0

second_peak(d)[source]

Return preference and selectivity of the second peak in the distribution.

It is just the combination of second_peak_bin() and second_peak_selectivity(), with the advantage of avoiding a duplicate call of second_peak_bin(), if the user is interested in both preference and selectivity, as often is the case.

second_peak_bin(d)[source]

Return the bin with the second peak in the distribution. Unlike second_max_value_bin(), it does not return a bin which is the second largest value, if laying on a wing of the first peak, the second peak is returned only if the distribution is truly multimodal. If it isn’t, return the first peak (for compatibility with numpy array type, and plotting compatibility), however the correspondong selectivity will be forced to 0.0

second_peak_selectivity(d)[source]

Return the selectivity of the second peak in the distribution.

If the distribution has only one peak, return 0.0, and this value is also usefl to discriminate the validity of second_peak_bin()

second_selectivity(d)[source]

Return the selectivity of the second largest value in the distribution. If there is one bin only, the selectivity is 0, since there is no second peack at all, and this value is also used to discriminate the validity of second_max_value_bin() Selectivity is computed in two ways depending on whether the variable is a cyclic, as in selectivity()

class topo.misc.distribution.DescriptiveStatisticFn(**params)[source]

Bases: topo.misc.distribution.DistributionStatisticFn

Abstract class for basic descriptive statistics

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
selectivity(d)[source]

Return a measure of the peakedness of the distribution. The calculation differs depending on whether this is a cyclic variable. For a cyclic variable, returns the magnitude of the vector_sum() divided by the sum_value() (see _vector_selectivity for more details). For a non-cyclic variable, returns the max_value_bin()) as a proportion of the sum_value() (see _relative_selectivity for more details).

vector_sum(d)[source]

Return the vector sum of the distribution as a tuple (magnitude, avgbinnum).

Each bin contributes a vector of length equal to its value, at a direction corresponding to the bin number. Specifically, the total bin number range is mapped into a direction range [0,2pi].

For a cyclic distribution, the avgbinnum will be a continuous measure analogous to the max_value_bin() of the distribution. But this quantity has more precision than max_value_bin() because it is computed from the entire distribution instead of just the peak bin. However, it is likely to be useful only for uniform or very dense sampling; with sparse, non-uniform sampling the estimates will be biased significantly by the particular samples chosen.

The avgbinnum is not meaningful when the magnitude is 0, because a zero-length vector has no direction. To find out whether such cases occurred, you can compare the value of undefined_vals before and after a series of calls to this function.

class topo.misc.distribution.Distribution(axis_bounds=(0.0, 6.283185307179586), cyclic=False, keep_peak=False)[source]

Bases: object

Holds a distribution of the values f(x) associated with a variable x.

A Distribution is a histogram-like object that is a dictionary of samples. Each sample is an x:f(x) pair, where x is called the bin and f(x) is called the value(). Each bin’s value is typically maintained as the sum of all the values that have been placed into it.

The bin axis is continuous, and can represent a continuous quantity without discretization. Alternatively, this class can be used as a traditional histogram by either discretizing the bin number before adding each sample, or by binning the values in the final Distribution.

Distributions are bounded by the specified axis_bounds, and can either be cyclic (like directions or hues) or non-cyclic. For cyclic distributions, samples provided outside the axis_bounds will be wrapped back into the bound range, as is appropriate for quantities like directions. For non-cyclic distributions, providing samples outside the axis_bounds will result in a ValueError.

In addition to the values, can also return the counts, i.e., the number of times that a sample has been added with the given bin.

Not all instances of this class will be a true distribution in the mathematical sense; e.g. the values will have to be normalized before they can be considered a probability distribution.

If keep_peak=True, the value stored in each bin will be the maximum of all values ever added, instead of the sum. The distribution will thus be a record of the maximum value seen at each bin, also known as an envelope.

add(new_data)[source]

Add a set of new data in the form of a dictionary of (bin, value) pairs. If the bin already exists, the value is added to the current value. If the bin doesn’t exist, one is created with that value.

Bin numbers outside axis_bounds are allowed for cyclic=True, but otherwise a ValueError is raised.

If keep_peak=True, the value of the bin is the maximum of the current value and the supplied value. That is, the bin stores the peak value seen so far. Note that each call will increase the total_value and total_count (and thus decrease the value_mag() and count_mag()) even if the value doesn’t happen to be the maximum seen so far, since each data point still helps improve the sampling and thus the confidence.

bins()[source]

Return a list of bins that have been populated.

count_mag(bin)[source]

Return the count of a single bin as a proportion of total_count.

counts()[source]

Return a list of values.

Various statistics can then be calculated if desired:

sum(counts) (total of all counts) max(counts) (highest count in any bin)

Note that the bin-order of values returned does not necessarily match that returned by values().

get_count(bin)[source]

Return the count from the specified bin.

(Return None if there is no such bin.)

get_value(bin)[source]

Return the value of the specified bin.

(Return None if there is no such bin.)

max_value_bin()[source]

Return the bin with the largest value.

sub_distr(distr)[source]

Subtract the given distribution from the current one. Only existing bins are modified, new bins in the given distribution are discarded without raising errors.

Note that total_value and total_count are not affected, and keep_peak is ignored, therefore analysis relying on these values should not call this method.

value_mag(bin)[source]

Return the value of a single bin as a proportion of total_value.

values()[source]

Return a list of values.

Various statistics can then be calculated if desired:

sum(vals) (total of all values) max(vals) (highest value in any bin)

Note that the bin-order of values returned does not necessarily match that returned by counts().

weighted_sum()[source]

Return the sum of each value times its bin.

class topo.misc.distribution.DistributionStatisticFn(**params)[source]

Bases: param.parameterized.Parameterized

Base class for various functions performing statistics on a distribution

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
class topo.misc.distribution.Pref(**args)[source]

Bases: dict

This class simply collects named arguments into a dictionary

the main purpose is to make pretty readable the output of DistributionStatisticFn functions. In addition, trap missing keys

class topo.misc.distribution.VonMisesStatisticFn(**params)[source]

Bases: topo.misc.distribution.DistributionStatisticFn

Base class for von Mises statistics

param NumericTuple selectivity_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting measure of the distribution peakedness, typically the selectivity of a unit to its preferred feature value. The tuple specifies (offset, multiplier) of the output scaling
param NumericTuple value_scale (constant=False, default=(0.0, 1.0), instantiate=False, length=2, pickle_default_value=True, precedence=None, readonly=False)
Scaling of the resulting value of the distribution statistics, typically the preference of a unit to feature values. The tuple specifies (offset, multiplier) of the output scaling
fit_v2m(distribution)[source]

computes the best fit of the bivariate von Mises function in the semi-circle. Return the tuple: (

orientation1_preference, orientation1_selectivity, goodness_of_fit1, orientation2_preference, orientation2_selectivity, goodness_of_fit2

) See fit_vm() for considerations about selectivity and goodness_of_fit

fit_vm(distribution)[source]

computes the best fit of the monovariate von Mises function in the semi-circle. Return a tuple with the orientation preference, in the same range of axis_bounds, the orientation selectivity, and an estimate of the goodness-of-fit, as the variance of the predicted orientation preference. The selectivity is given by the bandwith parameter of the von Mises function, modified for compatibility with other selectivity computations in this class. The bandwith parameter is transposed in logaritmic scale, and is normalized by the maximum value for the number of bins in the distribution, in order to give roughly 1.0 for a distribution with one bin at 1.0 an all the other at 0.0, and 0.0 for uniform distributions. The normalizing factor of the selectivity is fit for the total number of bins, using fit parameters computed offline. There are conditions that prevents apriori the possibility to fit the distribution:

  • not enough bins, at least 4 are necessary
  • the distribution is too flat, below the noise level
and conditions of aposteriori failures:
  • “ier” flag returned by leastsq out of ( 1, 2, 3, 4 )
  • no estimated Jacobian around the solution
  • negative bandwith (the peak of the distribution is convex)

Note that these are the minimal conditions, their fulfillment does not warrant unimodality, is up to the user to check the goodness-of-fit value for an accurate acceptance of the fit.

von2_mises(pars, x)[source]

Compute a simplified bimodal von Mises function

Two superposed von Mises functions, with different peak and bandwith values

von_mises(pars, x)[source]

Compute a simplified von Mises function.

Original formulation in Richard von Mises, “Wahrscheinlichkeitsrechnung und ihre Anwendungen in der Statistik und theoretischen Physik”, 1931, Deuticke, Leipzig; see also Mardia, K.V. and Jupp, P.E., ” Directional Statistics”, 1999, J. Wiley, p.36; http://en.wikipedia.org/wiki/Von_Mises_distribution The two differences are that this function is a continuous probability distribution on a semi-circle, while von Mises is on the full circle, and that the normalization factor, which is the inverse of the modified Bessel function of first kind and 0 degree in the original, is here a fit parameter.

Table Of Contents

This Page