pulse2percept.utils.base

PrettyPrint, Frozen, Parametrized, Data, bijective26_name, cached, gamma, unique

Functions

bijective26_name(i)	Bijective base-26 numeration
cached(f)	Cached property decorator
freeze_class(set[, normalize])	Freezes a class Raise an error when trying to set an undeclared name, or when calling from a method other than Frozen.__init__ or the __init__ method of a class derived from Frozen
gamma(n, tau, tsample[, tol])	Returns the impulse response of n cascaded leaky integrators
has_own_attr(obj, name)	Whether obj has an attribute name, without running its getter

Classes

Data(data[, axes, metadata])	N-dimensional data container
Frozen()	"Frozen" classes (and subclasses) do not allow for new class attributes to be set outside the constructor.
Parametrized(**params)	Abstract base class for objects with user-settable parameters
PrettyPrint()	An abstract class that provides a way to prettyprint all class attributes, inspired by scikit-learn.

Exceptions

FreezeError

Exception class used to raise when trying to add attributes to Frozen Classes of type Frozen do not allow for new attributes to be set outside the constructor.

class pulse2percept.utils.base.PrettyPrint

An abstract class that provides a way to prettyprint all class attributes, inspired by scikit-learn.

Classes deriving from PrettyPrint are required to implement a _pprint_params method that returns a dictionary containing all the attributes to prettyprint.

Examples

>>> from pulse2percept.utils import PrettyPrint
>>> class MyClass(PrettyPrint):
...     def __init__(self, a, b):
...         self.a = a
...         self.b = b
...
...     def _pprint_params(self):
...         return {'a': self.a, 'b': self.b}
>>> MyClass(1, 2)
MyClass(a=1, b=2)

exception pulse2percept.utils.base.FreezeError

Exception class used to raise when trying to add attributes to Frozen Classes of type Frozen do not allow for new attributes to be set outside the constructor.

add_note()

Exception.add_note(note) – add a note to the exception

name

attribute name

obj

object

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

pulse2percept.utils.base.has_own_attr(obj, name)

Whether obj has an attribute name, without running its getter

hasattr invokes a property or other descriptor just to answer the question, which for a deprecated_alias means a spurious deprecation warning every time an attribute is merely probed. Looking the name up on the type instead settles the same question without ever reading the instance’s value.

Note that this does not consult __getattr__, so it answers “does the object own this attribute”, not the broader “can this attribute be read”.

Added in version 0.10.0.

pulse2percept.utils.base.freeze_class(set, normalize=None)

Freezes a class Raise an error when trying to set an undeclared name, or when calling from a method other than Frozen.__init__ or the __init__ method of a class derived from Frozen

Parameters:

• set (callable) – The __setattr__ to delegate to once the assignment is allowed.

• normalize (callable, optional) –

  normalize(self, name, value), called before the assignment when value carries a physical unit, and returning the value to store. See _normalize_param.

  This is a parameter rather than a wrapper around set_attr on purpose: both this function and is_built() locate their caller by stack depth, and inserting another __setattr__ frame between the caller and this one would move it.

class pulse2percept.utils.base.Frozen

“Frozen” classes (and subclasses) do not allow for new class attributes to be set outside the constructor. On attempting to add a new attribute, the class will raise a FreezeError.

class pulse2percept.utils.base.Parametrized(**params)

Abstract base class for objects with user-settable parameters

Provides the following functionality:

• Pretty-print class attributes (via _pprint_params and PrettyPrint)

• User-settable parameters must be listed in get_default_params

• New class attributes can only be added in the constructor (enforced via Frozen and FreezeError)

• Value-based equality and deep copying that understand NumPy arrays

• Parameters can declare the physical unit they are stored in (via get_param_units), so that a unitful value assigned to one is converted before it is stored

Added in version 0.10.0.

abstract get_default_params()

Return a dict of user-settable parameters

get_param_units()

Return a dict of the units that parameters are stored in

Maps a parameter name to the Unit that the implementation assumes it is expressed in. A Quantity assigned to such a parameter is checked against that unit and rescaled to it, so that

FadingTemporal(tau=100)
FadingTemporal(tau=100 * ms)
FadingTemporal(tau=0.1 * s)

all store the same float. Bare numbers keep their documented meaning and are passed through untouched.

Parameters absent from this dict take plain numbers: they are either dimensionless (thresh_percept) or empirical fit parameters whose dimension the implementation does not actually commit to. Declaring a unit is a statement about what the equations assume, so a parameter should only appear here when that is documented or unambiguous.

This dict is not restricted to the names in get_default_params: it describes every physical attribute this object normalizes. A constructor argument assigned straight to self – DefaultSizeModel takes rho that way – belongs here too, and is converted like any other.

Subclasses extend rather than replace it:

def get_param_units(self):
    return {**super().get_param_units(), 'dt': ms, 'tau': ms}

Added in version 0.10.0.

set_params(**params)

Set the parameters of this object

class pulse2percept.utils.base.Data(data, axes=None, metadata=None)

N-dimensional data container

Added in version 0.6.

Parameters:

• data (np.ndarray) – An N-dimensional NumPy array containing the data to store

• axes (dict or tuple, optional) – For each dimension in data, specify axis name and labels.

• metadata (dict, optional) – A dictionary that can store arbitrary metadata

pulse2percept.utils.base.gamma(n, tau, tsample, tol=0.01)

Returns the impulse response of n cascaded leaky integrators

This function calculates the impulse response of n cascaded leaky integrators with constant of proportionality 1/tau: y = (t/theta).^(n-1).*exp(-t/theta)/(theta*factorial(n-1))

Parameters:

• n (int) – Number of cascaded leaky integrators

• tau (float) – Decay constant of leaky integration (seconds). Equivalent to the inverse of the constant of proportionality.

• tsample (float) – Sampling time step (seconds).

• tol (float) – Cut the kernel to size by ignoring function values smaller than a fraction tol of the peak value.

pulse2percept.utils.base.cached(f)

Cached property decorator

Decorator can be added to the property of a class to maintain a cache. This is useful when computing the property is computationall expensive. The property will only be computed on first call, and subsequent calls will refer to the cached result.

Important

When making use of a cached property, the class should also maintain a _cache_active flag set to True or False.

Added in version 0.7.

pulse2percept.utils.base.bijective26_name(i)

Bijective base-26 numeration

Creates the “alphabetic number” for a given integer i following bijective base-26 numeration: A-Z, AA-AZ, BA-BZ, … ZA-ZZ, AAA-AAZ, ABA-ABZ, …

Parameters:

i (int) – Regular number to be translated into an alphabetic number

Returns:

name – Alphabetic number

Return type:

string

Examples

>>> bijective26_name(0)
'A'

>>> bijective26_name(26)
'AA'