Improve RawIO Documentation #1508
Description
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.