Source code for brian2.hears

"""
This is only a bridge for using Brian 1 hears with Brian 2.

.. deprecated:: 2.2.2.2
    Use the `brian2hears <https://brian2hears.readthedocs.io/>`_ package instead.

NOTES:

* Slicing sounds with Brian 2 units doesn't work, you need to either use Brian 1 units or replace calls to
  ``sound[:20*ms]`` with ``sound.slice(None, 20*ms)``, etc.

TODO: handle properties (e.g. sound.duration)

Not working examples:

* time_varying_filter1 (care with units)
"""


try:
    import brian as b1
    import brian.hears as b1h
except ImportError:
    raise ImportError(
        "brian2.hears is deprecated and will be removed in a future release, please use"
        " the brian2hears package available at https://brian2hears.readthedocs.io/. If"
        " you really want to keep using it, note: brian2.hears is a bridge between"
        " Brian 2 and the version of Brian Hears from Brian 1, you need to have Brian 1"
        " installed to use it."
    )

from inspect import isclass, ismethod

from numpy import asarray, ndarray

from brian2.core.clocks import Clock
from brian2.core.operations import network_operation
from brian2.groups.neurongroup import NeuronGroup
from brian2.units import second
from brian2.units.fundamentalunits import Quantity
from brian2.utils.logger import get_logger

logger = get_logger(__name__)

logger.warn(
    "brian2.hears is deprecated and will be removed in a future release, please use the"
    " brian2hears package available at https://brian2hears.readthedocs.io/. If you"
    " really want to keep using it, note that it is a bridge between Brian 2 and Brian"
    " Hears from Brian 1. This is not guaranteed to work in all cases that brian.hears"
    " works. See the limitations in the online documentation."
)


[docs] def convert_unit_b1_to_b2(val): return Quantity.with_dimensions(float(val), val.dim._dims)
[docs] def convert_unit_b2_to_b1(val): return b1.Quantity.with_dimensions(float(val), val.dim._dims)
[docs] def modify_arg(arg): """ Modify arguments to make them compatible with Brian 1. - Arrays of units are replaced with straight arrays - Single values are replaced with Brian 1 equivalents - Slices are handled so we can use e.g. sound[:20*ms] The second part was necessary because some functions/classes test if an object is an array or not to see if it is a sequence, but because brian2.Quantity derives from ndarray this was causing problems. """ if isinstance(arg, Quantity): if len(arg.shape) == 0: arg = b1.Quantity.with_dimensions(float(arg), arg.dim._dims) else: arg = asarray(arg) elif isinstance(arg, slice): arg = slice(modify_arg(arg.start), modify_arg(arg.stop), modify_arg(arg.step)) return arg
[docs] def wrap_units(f): """ Wrap a function to convert units into a form that Brian 1 can handle. Also, check the output argument, if it is a ``b1h.Sound`` wrap it. """ def new_f(*args, **kwds): newargs = [] newkwds = {} for arg in args: newargs.append(modify_arg(arg)) for k, v in kwds.items(): newkwds[k] = modify_arg(v) rv = f(*newargs, **newkwds) if rv.__class__ == b1h.Sound: rv.__class__ = BridgeSound elif isinstance(rv, b1.Quantity): rv = Quantity.with_dimensions(float(rv), rv.dim._dims) return rv return new_f
[docs] def wrap_units_property(p): fget = p.fget fset = p.fset fdel = p.fdel if fget is not None: fget = wrap_units(fget) if fset is not None: fset = wrap_units(fset) if fdel is not None: fdel = wrap_units(fdel) new_p = property(fget, fset, fdel) return new_p
[docs] def wrap_units_class(_C): """ Wrap a class to convert units into a form that Brian 1 can handle in all methods """ class new_class(_C): for _k in _C.__dict__: _v = getattr(_C, _k) if hasattr(ndarray, _k) and getattr(ndarray, _k) is _v: continue if ismethod(_v): _v = wrap_units(_v) exec(f"{_k} = _v") elif isinstance(_v, property): _v = wrap_units_property(_v) exec(f"{_k} = _v") del _k del _v return new_class
WrappedSound = wrap_units_class(b1h.Sound)
[docs] class BridgeSound(WrappedSound): """ We add a new method slice because slicing with units can't work with Brian 2 units. """
[docs] def slice(self, *args): return self.__getitem__(slice(*args))
Sound = BridgeSound
[docs] class FilterbankGroup(NeuronGroup): def __init__(self, filterbank, targetvar, *args, **kwds): self.targetvar = targetvar self.filterbank = filterbank self.buffer = None filterbank.buffer_init() # Sanitize the clock - does it have the right dt value? if "clock" in kwds: if int(1 / kwds["clock"].dt) != int(filterbank.samplerate): raise ValueError("Clock should have 1/dt=samplerate") kwds["clock"] = Clock(dt=float(kwds["clock"].dt) * second) else: kwds["clock"] = Clock(dt=1 * second / float(filterbank.samplerate)) buffersize = kwds.pop("buffersize", 32) if not isinstance(buffersize, int): buffersize = int(buffersize * self.samplerate) self.buffersize = buffersize self.buffer_pointer = buffersize self.buffer_start = -buffersize NeuronGroup.__init__(self, filterbank.nchannels, *args, **kwds) @network_operation(clock=self.clock, when="start") def apply_filterbank_output(): if self.buffer_pointer >= self.buffersize: self.buffer_pointer = 0 self.buffer_start += self.buffersize self.buffer = self.filterbank.buffer_fetch( self.buffer_start, self.buffer_start + self.buffersize ) setattr(self, targetvar, self.buffer[self.buffer_pointer, :]) self.buffer_pointer += 1 self.contained_objects.append(apply_filterbank_output)
[docs] def reinit(self): NeuronGroup.reinit(self) self.filterbank.buffer_init() self.buffer_pointer = self.buffersize self.buffer_start = -self.buffersize
handled_explicitly = {"Sound", "FilterbankGroup"} __all__ = [k for k in b1h.__dict__ if not k.startswith("_")] for k in __all__: if k in handled_explicitly: continue curobj = getattr(b1h, k) if callable(curobj): if isclass(curobj): curobj = wrap_units_class(curobj) else: curobj = wrap_units(curobj) exec(f"{k} = curobj") __all__.extend( [ "convert_unit_b1_to_b2", "convert_unit_b2_to_b1", ] )