search

NeuralEnsemble / python-neo

Neo is a package for representing electrophysiology data in Python, together with support for reading a wide range of neurophysiology file formats
http://neo.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
322 stars 247 forks source link

Improve RawIO Documentation #1508

Open zm711 opened 3 months ago

zm711 commented 3 months ago

Which page is the problem on? RawIO stuff What is the problem? We have a good object model for the Neo Hierarchy (in my opinion), but what the rawio terms mean in relationship to the rest of the Neo hierarchy has raised some confusion and may need some refinement. See #1507. And associated spikeinterface issue

To summarize in plexon we have combined the Wideband and the filtered data into the same stream which means that the user needs to use a channel slice to not duplicate their data. Although this technically fits within the Neo stream definition (same t_start, same dtype, same sampling_rate) I think this is a mistake. But during the conversation about this issue, and other issues that people have raised that our documentation isn't quite doing enough to disambiguate block vs segment vs stream vs channel stuff. Another example is that our low-level functions use stream_index when these are arbitrary numbers rather than stream_name which likely has salience to the end-user. We should make it clearer for how people can link name and index so they can make sure they get the correct data if using the rawio api.

Suggestions for fixing the problem We give examples of these but we may be better served including a glossary to help define the interaction between block/segment vs stream/channel to help people understand the rules. And maybe we should have a discussion ourselves to decide if we should be even more restrictive for what a stream is.

We should make it clearer for how people can link name and index so they can make sure they get the correct data if using the rawio api.

Feel free to add on if there is something I missed @h-mayorquin.

zm711 commented 3 months ago

Also Sam, Alessio, and Heberto (+me) discussed finding a way to make stream more logical to the end user and perhaps using the concept of a "buffer/buffer stream" as a rawio concept for developers vs using the stream_id (with associated names) as something more accessible to end-users.

h-mayorquin commented 6 days ago

Clarify the meaning of sampling frequency and starting time (as in this issue https://github.com/NeuralEnsemble/python-neo/issues/1569) to indicate which ones belong to a stream and which ones are general. Where this should go on the documentation?