1
0

0.5.0.rst 5.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. =======================
  2. Neo 0.5.0 release notes
  3. =======================
  4. 22nd March 2017
  5. For Neo 0.5, we have taken the opportunity to simplify the Neo object model.
  6. Although this will require an initial time investment for anyone who has written code with
  7. an earlier version of Neo, the benefits will be greater simplicity, both in your own code and
  8. within the Neo code base, which should allow us to move more quickly in fixing bugs, improving
  9. performance and adding new features.
  10. More detail on these changes follows:
  11. Merging of "single-value" and "array" versions of data classes
  12. ==============================================================
  13. In previous versions of Neo, we had :class:`AnalogSignal` for one-dimensional (single channel)
  14. signals, and :class:`AnalogSignalArray` for two-dimensional (multi-channel) signals.
  15. In Neo 0.5.0, these have been merged under the name :class:`AnalogSignal`.
  16. :class:`AnalogSignal` has the same behaviour as the old :class:`AnalogSignalArray`.
  17. It is still possible to create an :class:`AnalogSignal` from a one-dimensional array, but
  18. this will be converted to an array with shape `(n, 1)`, e.g.:
  19. .. code-block:: python
  20. >>> signal = neo.AnalogSignal([0.0, 0.1, 0.2, 0.5, 0.6, 0.5, 0.4, 0.3, 0.0],
  21. ... sampling_rate=10*kHz,
  22. ... units=nA)
  23. >>> signal.shape
  24. (9, 1)
  25. Multi-channel arrays are created as before, but using :class:`AnalogSignal` instead of
  26. :class:`AnalogSignalArray`:
  27. .. code-block:: python
  28. >>> signal = neo.AnalogSignal([[0.0, 0.1, 0.2, 0.5, 0.6, 0.5, 0.4, 0.3, 0.0],
  29. ... [0.0, 0.2, 0.4, 0.7, 0.9, 0.8, 0.7, 0.6, 0.3]],
  30. ... sampling_rate=10*kHz,
  31. ... units=nA)
  32. >>> signal.shape
  33. (9, 2)
  34. Similarly, the :class:`Epoch` and :class:`EpochArray` classes have been merged into an
  35. array-valued class :class:`Epoch`, ditto for :class:`Event` and :class:`EventArray`, and the
  36. :class:`Spike` class, whose main function was to contain the waveform data for an individual spike,
  37. has been suppressed; waveform data are now available as the :attr:`waveforms` attribute
  38. of the :class:`SpikeTrain` class.
  39. Recording channels
  40. ==================
  41. As a consequence of the removal of "single-value" data classes, information on recording channels
  42. and the relationship between analog signals and spike trains is also stored differently.
  43. In Neo 0.5, we have introduced a new class, :class:`ChannelIndex`, which replaces both
  44. :class:`RecordingChannel` and :class:`RecordingChannelGroup`.
  45. In older versions of Neo, a :class:`RecordingChannel` object held metadata about a logical
  46. recording channel (a name and/or integer index) together with references to one or more
  47. :class:`AnalogSignal`\s recorded on that channel at different points in time
  48. (different :class:`Segment`\s); redundantly, the :class:`AnalogSignal` also had a
  49. :attr:`channel_index` attribute, which could be used in addition to or instead of creating a
  50. :class:`RecordingChannel`.
  51. Metadata about :class:`AnalogSignalArray`\s could be contained in a :class:`RecordingChannelGroup`
  52. in a similar way, i.e. :class:`RecordingChannelGroup` functioned as an array-valued version of
  53. :class:`RecordingChannel`, but :class:`RecordingChannelGroup` could also be used to group together
  54. individual :class:`RecordingChannel` objects.
  55. With Neo 0.5, information about the channel names and ids of an :class:`AnalogSignal` is contained
  56. in a :class:`ChannelIndex`, e.g.:
  57. .. code-block:: python
  58. >>> signal = neo.AnalogSignal([[0.0, 0.1, 0.2, 0.5, 0.6, 0.5, 0.4, 0.3, 0.0],
  59. ... [0.0, 0.2, 0.4, 0.7, 0.9, 0.8, 0.7, 0.6, 0.3]],
  60. ... [0.0, 0.1, 0.3, 0.6, 0.8, 0.7, 0.6, 0.5, 0.3]],
  61. ... sampling_rate=10*kHz,
  62. ... units=nA)
  63. >>> channels = neo.ChannelIndex(index=[0, 1, 2],
  64. ... channel_names=["chan1", "chan2", "chan3"])
  65. >>> signal.channel_index = channels
  66. In this use, it replaces :class:`RecordingChannel`.
  67. :class:`ChannelIndex` may also be used to group together a subset of the channels of a
  68. multi-channel signal, for example:
  69. .. code-block:: python
  70. >>> channel_group = neo.ChannelIndex(index=[0, 2])
  71. >>> channel_group.analogsignals.append(signal)
  72. >>> unit = neo.Unit() # will contain the spike train recorded from channels 0 and 2.
  73. >>> unit.channel_index = channel_group
  74. Checklist for updating code from 0.3/0.4 to 0.5
  75. ===============================================
  76. To update your code from Neo 0.3/0.4 to 0.5, run through the following checklist:
  77. 1. Change all usages of :class:`AnalogSignalArray` to :class:`AnalogSignal`.
  78. 2. Change all usages of :class:`EpochArray` to :class:`Epoch`.
  79. 3. Change all usages of :class:`EventArray` to :class:`Event`.
  80. 4. Where you have a list of (single channel) :class:`AnalogSignal`\s all of the same length,
  81. consider converting them to a single, multi-channel :class:`AnalogSignal`.
  82. 5. Replace :class:`RecordingChannel` and :class:`RecordingChannelGroup` with
  83. :class:`ChannelIndex`.
  84. .. note:: in points 1-3, the data structure is still an array, it just has a shorter name.
  85. Other changes
  86. =============
  87. * added :class:`NixIO` (`about the NIX format`_)
  88. * added :class:`IgorIO`
  89. * added :class:`NestIO` (for data files produced by the `NEST simulator`_)
  90. * :class:`NeoHdf5IO` is now read-only. It will read data files produced by earlier versions
  91. of Neo, but another HDF5-based IO, e.g. :class:`NixIO`, should be used for writing data.
  92. * many fixes/improvements to existing IO modules. All IO modules should now work with Python 3.
  93. .. https://github.com/NeuralEnsemble/python-neo/issues?utf8=✓&q=is%3Aissue%20is%3Aclosed%20created%3A%3E2014-02-01%20
  94. .. _`about the NIX format`: https://github.com/G-Node/nix/wiki
  95. .. _`NEST simulator`: http://nest-simulator.org