=======================
Neo 0.9.0 release notes
=======================

10th November 2020


Group and ChannelView replace Unit and ChannelIndex
---------------------------------------------------

Experience with :class:`ChannelIndex` and :class:`Unit` has shown that these classes are
often confusing and difficult to understand.
In particular, :class:`ChannelIndex` was trying to provide three different functionalities in a
single object:

- providing information about individual traces within :class:`AnalogSignals` like the channel id and the channel name (labelling)
- grouping a subset of traces within an :class:`AnalogSignal` via the ``index`` attribute (masking)
- linking between / grouping :class:`AnalogSignals` (grouping)

while grouping :class:`SpikeTrains` required a different class, :class:`Unit`.
For more pointers to the difficulties this created, and some of the limitations of this approach,
see `this Github issue`_.

With the aim of making the three functionalities of labelling, masking and grouping
both easier to use and more flexible, we have replaced :class:`ChannelIndex` and :class:`Unit`
with:

- array annotations (*labelling*) - already available since Neo 0.8
- :class:`~neo.core.ChannelView` (*masking*) - defines subsets of channels within an `AnalogSignal` using a mask
- :class:`~neo.core.Group`  (*grouping*) - allows any Neo object except :class`Segment` and :class:`Block` to be grouped

For some guidance on migrating from :class:`ChannelIndex`/:class:`Unit`
to :class:`Group` and :class:`ChannelView` see :doc:`../grouping`.

Python 3 only
-------------

We have now dropped support for Python 2.7 and Python 3.5, and for versions of NumPy older than 1.13.
In future, we plan to follow NEP29_ + one year, i.e. we will support Python and NumPy versions
for one year longer than recommended in NEP29. This was `discussed here`_.

Change in default behaviour for grouping channels in IO modules
---------------------------------------------------------------

Previously, when reading multiple related signals (same length, same units) from a file,
some IO classes would by default create a separate, single-channel :class:`AnalogSignal` per signal,
others would combine all related signals into one multi-channel :class:`AnalogSignal`.

From Neo 0.9.0, the default for all IO classes is to create a one multi-channel :class:`AnalogSignal`.
To get the "multiple single-channel signals" behaviour, use::

    io.read(signal_group_mode="split-all")

Other new or modified features
------------------------------

  * added methods :func:`rectify()`, :func:`downsample` and :func:`resample` to :class:`AnalogSignal`
  * :func:`SpikeTrain.merge()` can now merge multiple spiketrains
  * the utility function :func:`cut_block_by_epochs()` gives a new :class:`Block` now
    rather than modifying the block in place
  * some missing properties such as ``t_start`` were added to :class:`ImageSequence`,
    and ``sampling_period`` was renamed to ``frame_duration``
  * :func:`AnalogSignal.time_index()` now accepts arrays of times, not just a scalar.

See all `pull requests`_ included in this release and the `list of closed issues`_.

Bug fixes and improvements in IO modules
----------------------------------------

  * NeoMatlabIO (support for signal annotations)
  * NeuralynxIO (fix handling of empty .nev files)
  * AxonIO (support EDR3 header, fix channel events bug)
  * Spike2IO (fix rounding problem, fix for v9 SON files)
  * MicromedIO (fix label encoding)


Acknowledgements
----------------

Thanks to Julia Sprenger, Samuel Garcia, Andrew Davison, Alexander Kleinjohann, Hugo van Kemenade,
Achilleas Koutsou, Jeffrey Gill, Corentin Fragnaud, Aitor Morales-Gregorio, Rémi Proville,
Robin Gutzen, Marin Manuel, Simon Danner, Michael Denker, Peter N. Steinmetz, Diziet Asahi and
Lucien Krapp for their contributions to this release.

.. _`list of closed issues`: https://github.com/NeuralEnsemble/python-neo/issues?q=is%3Aissue+milestone%3A0.9.0+is%3Aclosed
.. _`pull requests`: https://github.com/NeuralEnsemble/python-neo/pulls?q=is%3Apr+is%3Aclosed+merged%3A%3E2019-09-30+milestone%3A0.9.0
.. _NEP29: https://numpy.org/neps/nep-0029-deprecation_policy.html
.. _`discussed here`: https://github.com/NeuralEnsemble/python-neo/issues/788
.. _`this Github issue`: https://github.com/NeuralEnsemble/python-neo/issues/456