basefromrawio.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331
  1. """
  2. BaseFromRaw
  3. ======
  4. BaseFromRaw implement a bridge between the new neo.rawio API
  5. and the neo.io legacy that give neo.core object.
  6. The neo.rawio API is more restricted and limited and do not cover tricky
  7. cases with asymetrical tree of neo object.
  8. But if a format is done in neo.rawio the neo.io is done for free
  9. by inheritance of this class.
  10. Furthermore, IOs that inherits this BaseFromRaw also have the ability
  11. of the lazy load with proxy objects.
  12. """
  13. import collections
  14. import warnings
  15. import numpy as np
  16. from neo import logging_handler
  17. from neo.core import (AnalogSignal, Block,
  18. Epoch, Event,
  19. IrregularlySampledSignal,
  20. Group,
  21. Segment, SpikeTrain, Unit)
  22. from neo.io.baseio import BaseIO
  23. from neo.io.proxyobjects import (AnalogSignalProxy,
  24. SpikeTrainProxy, EventProxy, EpochProxy,
  25. ensure_signal_units, check_annotations,
  26. ensure_second, proxyobjectlist)
  27. import quantities as pq
  28. class BaseFromRaw(BaseIO):
  29. """
  30. This implement generic reader on top of RawIO reader.
  31. Arguments depend on `mode` (dir or file)
  32. File case::
  33. reader = BlackRockIO(filename='FileSpec2.3001.nev')
  34. Dir case::
  35. reader = NeuralynxIO(dirname='Cheetah_v5.7.4/original_data')
  36. Other arguments are IO specific.
  37. """
  38. is_readable = True
  39. is_writable = False
  40. supported_objects = [Block, Segment, AnalogSignal,
  41. SpikeTrain, Unit, Group, Event, Epoch]
  42. readable_objects = [Block, Segment]
  43. writeable_objects = []
  44. support_lazy = True
  45. name = 'BaseIO'
  46. description = ''
  47. extentions = []
  48. mode = 'file'
  49. _prefered_signal_group_mode = 'group-by-same-units' # 'split-all'
  50. _default_group_mode_have_change_in_0_9 = False
  51. def __init__(self, *args, **kargs):
  52. BaseIO.__init__(self, *args, **kargs)
  53. self.parse_header()
  54. def read_block(self, block_index=0, lazy=False,
  55. create_group_across_segment=None,
  56. signal_group_mode=None, load_waveforms=False):
  57. """
  58. :param block_index: int default 0. In case of several block block_index can be specified.
  59. :param lazy: False by default.
  60. :param create_group_across_segment: bool or dict
  61. If True :
  62. * Create a neo.Group to group AnalogSignal segments
  63. * Create a neo.Group to group SpikeTrain across segments
  64. * Create a neo.Group to group Event across segments
  65. * Create a neo.Group to group Epoch across segments
  66. With a dict the behavior can be controlled more finely
  67. create_group_across_segment = { 'AnalogSignal': True, 'SpikeTrain': False, ...}
  68. :param signal_group_mode: 'split-all' or 'group-by-same-units' (default depend IO):
  69. This control behavior for grouping channels in AnalogSignal.
  70. * 'split-all': each channel will give an AnalogSignal
  71. * 'group-by-same-units' all channel sharing the same quantity units ar grouped in
  72. a 2D AnalogSignal
  73. :param load_waveforms: False by default. Control SpikeTrains.waveforms is None or not.
  74. """
  75. if signal_group_mode is None:
  76. signal_group_mode = self._prefered_signal_group_mode
  77. if self._default_group_mode_have_change_in_0_9:
  78. warnings.warn('default "signal_group_mode" have change in version 0.9:'
  79. 'now all channels are group together in AnalogSignal')
  80. l = ['AnalogSignal', 'SpikeTrain', 'Event', 'Epoch']
  81. if create_group_across_segment is None:
  82. # @andrew @ julia @michael ?
  83. # I think here the default None could give this
  84. create_group_across_segment = {
  85. 'AnalogSignal': True, #because mimic the old ChannelIndex for AnalogSignals
  86. 'SpikeTrain': False, # False by default because can create too many object for simulation
  87. 'Event': False, # not implemented yet
  88. 'Epoch': False, # not implemented yet
  89. }
  90. elif isinstance(create_group_across_segment, bool):
  91. # bool to dict
  92. v = create_group_across_segment
  93. create_group_across_segment = { k: v for k in l}
  94. elif isinstance(create_group_across_segment, dict):
  95. # put False to missing keys
  96. create_group_across_segment = {create_group_across_segment.get(k, False) for k in l}
  97. else:
  98. raise ValueError('create_group_across_segment must be bool or dict')
  99. # annotations
  100. bl_annotations = dict(self.raw_annotations['blocks'][block_index])
  101. bl_annotations.pop('segments')
  102. bl_annotations = check_annotations(bl_annotations)
  103. bl = Block(**bl_annotations)
  104. # Group for AnalogSignals
  105. if create_group_across_segment['AnalogSignal']:
  106. all_channels = self.header['signal_channels']
  107. channel_indexes_list = self.get_group_signal_channel_indexes()
  108. sig_groups = []
  109. for channel_index in channel_indexes_list:
  110. for i, (ind_within, ind_abs) in self._make_signal_channel_subgroups(
  111. channel_index, signal_group_mode=signal_group_mode).items():
  112. group = Group(name='AnalogSignal group {}'.format(i))
  113. # @andrew @ julia @michael : do we annotate group across segment with this arrays ?
  114. group.annotate(ch_names=all_channels[ind_abs]['name'].astype('U')) # ??
  115. group.annotate(channel_ids=all_channels[ind_abs]['id']) # ??
  116. bl.groups.append(group)
  117. sig_groups.append(group)
  118. if create_group_across_segment['SpikeTrain']:
  119. unit_channels = self.header['unit_channels']
  120. st_groups = []
  121. for c in range(unit_channels.size):
  122. group = Group(name='SpikeTrain group {}'.format(i))
  123. group.annotate(unit_name=unit_channels[c]['name'])
  124. group.annotate(unit_id=unit_channels[c]['id'])
  125. unit_annotations = self.raw_annotations['unit_channels'][c]
  126. unit_annotations = check_annotations(unit_annotations)
  127. group.annotations.annotate(**unit_annotations)
  128. bl.groups.append(group)
  129. st_groups.append(group)
  130. if create_group_across_segment['Event']:
  131. # @andrew @ julia @michael :
  132. # Do we need this ? I guess yes
  133. raise NotImplementedError()
  134. if create_group_across_segment['Epoch']:
  135. # @andrew @ julia @michael :
  136. # Do we need this ? I guess yes
  137. raise NotImplementedError()
  138. # Read all segments
  139. for seg_index in range(self.segment_count(block_index)):
  140. seg = self.read_segment(block_index=block_index, seg_index=seg_index,
  141. lazy=lazy, signal_group_mode=signal_group_mode,
  142. load_waveforms=load_waveforms)
  143. bl.segments.append(seg)
  144. # create link between group (across segment) and data objects
  145. for seg in bl.segments:
  146. if create_group_across_segment['AnalogSignal']:
  147. for c, anasig in enumerate(seg.analogsignals):
  148. sig_groups[c].add(anasig)
  149. if create_group_across_segment['SpikeTrain']:
  150. for c, sptr in enumerate(seg.spiketrains):
  151. st_groups[c].add(sptr)
  152. bl.create_many_to_one_relationship()
  153. return bl
  154. def read_segment(self, block_index=0, seg_index=0, lazy=False,
  155. signal_group_mode=None, load_waveforms=False, time_slice=None,
  156. strict_slicing=True):
  157. """
  158. :param block_index: int default 0. In case of several blocks block_index can be specified.
  159. :param seg_index: int default 0. Index of segment.
  160. :param lazy: False by default.
  161. :param signal_group_mode: 'split-all' or 'group-by-same-units' (default depend IO):
  162. This control behavior for grouping channels in AnalogSignal.
  163. * 'split-all': each channel will give an AnalogSignal
  164. * 'group-by-same-units' all channel sharing the same quantity units ar grouped in
  165. a 2D AnalogSignal
  166. :param load_waveforms: False by default. Control SpikeTrains.waveforms is None or not.
  167. :param time_slice: None by default means no limit.
  168. A time slice is (t_start, t_stop) both are quantities.
  169. All object AnalogSignal, SpikeTrain, Event, Epoch will load only in the slice.
  170. :param strict_slicing: True by default.
  171. Control if an error is raised or not when t_start or t_stop
  172. is outside the real time range of the segment.
  173. """
  174. if lazy:
  175. assert time_slice is None,\
  176. 'For lazy=True you must specify time_slice when LazyObject.load(time_slice=...)'
  177. assert not load_waveforms,\
  178. 'For lazy=True you must specify load_waveforms when SpikeTrain.load(load_waveforms=...)'
  179. if signal_group_mode is None:
  180. signal_group_mode = self._prefered_signal_group_mode
  181. # annotations
  182. seg_annotations = dict(self.raw_annotations['blocks'][block_index]['segments'][seg_index])
  183. for k in ('signals', 'units', 'events'):
  184. seg_annotations.pop(k)
  185. seg_annotations = check_annotations(seg_annotations)
  186. seg = Segment(index=seg_index, **seg_annotations)
  187. # AnalogSignal
  188. signal_channels = self.header['signal_channels']
  189. if signal_channels.size > 0:
  190. channel_indexes_list = self.get_group_signal_channel_indexes()
  191. for channel_indexes in channel_indexes_list:
  192. for i, (ind_within, ind_abs) in self._make_signal_channel_subgroups(
  193. channel_indexes,
  194. signal_group_mode=signal_group_mode).items():
  195. # make a proxy...
  196. anasig = AnalogSignalProxy(rawio=self, global_channel_indexes=ind_abs,
  197. block_index=block_index, seg_index=seg_index)
  198. if not lazy:
  199. # ... and get the real AnalogSIgnal if not lazy
  200. anasig = anasig.load(time_slice=time_slice, strict_slicing=strict_slicing)
  201. # TODO magnitude_mode='rescaled'/'raw'
  202. anasig.segment = seg
  203. seg.analogsignals.append(anasig)
  204. # SpikeTrain and waveforms (optional)
  205. unit_channels = self.header['unit_channels']
  206. for unit_index in range(len(unit_channels)):
  207. # make a proxy...
  208. sptr = SpikeTrainProxy(rawio=self, unit_index=unit_index,
  209. block_index=block_index, seg_index=seg_index)
  210. if not lazy:
  211. # ... and get the real SpikeTrain if not lazy
  212. sptr = sptr.load(time_slice=time_slice, strict_slicing=strict_slicing,
  213. load_waveforms=load_waveforms)
  214. # TODO magnitude_mode='rescaled'/'raw'
  215. sptr.segment = seg
  216. seg.spiketrains.append(sptr)
  217. # Events/Epoch
  218. event_channels = self.header['event_channels']
  219. for chan_ind in range(len(event_channels)):
  220. if event_channels['type'][chan_ind] == b'event':
  221. e = EventProxy(rawio=self, event_channel_index=chan_ind,
  222. block_index=block_index, seg_index=seg_index)
  223. if not lazy:
  224. e = e.load(time_slice=time_slice, strict_slicing=strict_slicing)
  225. e.segment = seg
  226. seg.events.append(e)
  227. elif event_channels['type'][chan_ind] == b'epoch':
  228. e = EpochProxy(rawio=self, event_channel_index=chan_ind,
  229. block_index=block_index, seg_index=seg_index)
  230. if not lazy:
  231. e = e.load(time_slice=time_slice, strict_slicing=strict_slicing)
  232. e.segment = seg
  233. seg.epochs.append(e)
  234. seg.create_many_to_one_relationship()
  235. return seg
  236. def _make_signal_channel_subgroups(self, channel_indexes,
  237. signal_group_mode='group-by-same-units'):
  238. """
  239. For some RawIO channel are already splitted in groups.
  240. But in any cases, channel need to be splitted again in sub groups
  241. because they do not have the same units.
  242. They can also be splitted one by one to match previous behavior for
  243. some IOs in older version of neo (<=0.5).
  244. This method aggregate signal channels with same units or split them all.
  245. """
  246. all_channels = self.header['signal_channels']
  247. if channel_indexes is None:
  248. channel_indexes = np.arange(all_channels.size, dtype=int)
  249. channels = all_channels[channel_indexes]
  250. groups = collections.OrderedDict()
  251. if signal_group_mode == 'group-by-same-units':
  252. all_units = np.unique(channels['units'])
  253. for i, unit in enumerate(all_units):
  254. ind_within, = np.nonzero(channels['units'] == unit)
  255. ind_abs = channel_indexes[ind_within]
  256. groups[i] = (ind_within, ind_abs)
  257. elif signal_group_mode == 'split-all':
  258. for i, chan_index in enumerate(channel_indexes):
  259. ind_within = [i]
  260. ind_abs = channel_indexes[ind_within]
  261. groups[i] = (ind_within, ind_abs)
  262. else:
  263. raise (NotImplementedError)
  264. return groups