Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarification of Device Wiring #211

Open
nmtimme opened this issue Aug 22, 2023 · 9 comments
Open

Clarification of Device Wiring #211

nmtimme opened this issue Aug 22, 2023 · 9 comments
Labels
question Further information is requested

Comments

@nmtimme
Copy link

nmtimme commented Aug 22, 2023

Hello

I'm running into some issues with properly setting up the probe variable for a Cambridge probe recording in open ephys.

I'm mainly confused by wiring_to_device and device_channel_indices. Does wiring_to_device just set device_channel_indices or does it do something else too? I see how to load the specific probe we have in probe interface, but the wiring_to_device functionality is confusing. I don't think our Intan headstage is available and I don't see how to control for plug in orientation (headstage side vs. fold on the probe connector). Also, does device_channel_indices[i] = j mean probe channel i corresponds to open ephys channel j or vice versa? Does position[i] determine the position of probe channel i or open ephys channel i? If this information is posted somewhere in the documentation and I missed it, I'm sorry!

I'd appreciate any clarification people can provide. Thank you!

~Nick

@alejoe91 alejoe91 added the question Further information is requested label Aug 23, 2023
@alejoe91
Copy link
Member

Hi Nick,

I know that these concepts can be very confusing!

The wiring_to_device just sets the device_channel_indices, i.e., it applies a channel map to the probe.

To clarify: device_channel_indices[i] = j means that the i-th contact of the probe (at position probe.contact_positions[i]) corresponds to the j-th trace. This mapping is given by the wiring of the contact through the connector and the headstage.

I would recommend reading section 1 of this tutorial for a more detailed explanation: https://github.com/SpikeInterface/spiketutorials/blob/master/Official_Tutorial_SI_0.94_May2022/SpikeInterface_Tutorial.ipynb

@h-mayorquin
Copy link
Collaborator

Hi, @nmtimme
We are always trying to build better documentation. I am wondering if this diagram helps you in clarying this confusion and whether you have any feedback to improve upon it:

diagram

Also, tagging @zm711 as he always has good feedback in documentation.

@zm711
Copy link
Contributor

zm711 commented Sep 23, 2023

@h-mayorquin

tl;dr
I think that looks great! At least add a set of traces to indicate that the device channel indices will be the actual traces (on the computer) since they are connected to the device. Add some sort of clarification about contact indices in the chart.

Long-winded portion:
I think that goes a long way. The chart is missing the contact indices and the device channel indices though. So adding 6 traces to the side might be beneficial to understand the device channel indices are just the actual raw recording data.

Also the chart is organized by contact indices without explaining them. For instance what is the real difference between contact indices and contact ids. (basically the contact indices aren't clearly labeled in the figure--so they need at least a note to explain what they are for the user).

A final note that may just be how I think of mapping so you can disregard if you think the majority of people think differently:

I would probably actually organize the chart by device channel indices (ie the data matrix that their recording experiment returns) and say that we need to trace back that matrix to the actual contacts, but I don't think there is a problem with starting from the probe and going to the computer. But really the sorters are asking the question of what are the locations of your data matrix (which hopefully isn't scrambled based on the contacts). I think the confusion is that users see the matrix of data and see that the probe is numbered and assume they are the same.

@h-mayorquin
Copy link
Collaborator

h-mayorquin commented Sep 23, 2023

I think that looks great! At least add a set of traces to indicate that the device channel indices will be the actual traces (on the computer) since they are connected to the device. Add some sort of clarification about contact indices in the chart.

How do you envisiong a sketch of this? Like matplotlib traces with a number on them to the right of this figure?
wiring

This is an svg that you can download. Feel free to add something if you have some skills with svg. I will think abou tthis.

I would probably actually organize the chart by device channel indices (ie the data matrix that their recording experiment returns) and say that we need to trace back that matrix to the actual contacts, but I don't think there is a problem with starting from the probe and going to the computer. But really the sorters are asking the question of what are the locations of your data matrix (which hopefully isn't scrambled based on the contacts). I think the confusion is that users see the matrix of data and see that the probe is numbered and assume they are the same.

This is a good point but given that this is probeinterface I prefer a probe-first story. Maybe we can have another arrangment in spikeinterface...

Also the chart is organized by contact indices without explaining them. For instance what is the real difference between contact indices and contact ids. (basically the contact indices aren't clearly labeled in the figure--so they need at least a note to explain what they are for the user).

I wouldn't know how to illustrate contact or device indices. They are not a physical / hardware thing. They are an enumerating trick that we use in probinterface because we repesent the contact ids and the channel ids (the true device labels) with an array/list. I was actually weary of mentioning them at all...

But maybe I lack imagination, the only solution that I had in mind is to put an extra number in the probe and device but I felt that would be even more confusing....

Thanks a bunch, I will keep thinking about this.

@zm711
Copy link
Contributor

zm711 commented Sep 23, 2023

How do you envisiong a sketch of this? Like matplotlib traces with a number on them to the right of this figure?

Exactly just a numbered set of traces.

Feel free to add something if you have some skills with svg. I will think abou tthis.

I have no skills. Haha.

This is a good point but given that this is probeinterface I prefer a probe-first story. Maybe we can have another arrangment in spikeinterface...

Fair point. Either way you go end to end, so I don't think it's essential to flip order.

I wouldn't know how to illustrate contact or device indices. They are not a physical / hardware thing. They are an enumerating trick that we use in probinterface because we repesent the contact ids and the channel ids (the true device labels) with an array/list. I was actually weary of mentioning them at all...

I would vote for not showing contact indices then. If they aren't meant for the user api then don't confuse the user with them. I do think device indices are important because they are directly related to the data the user is seeing, but my solution again is just showing a numbered set of matplot lib traces. (Again I'm such a terrible artist I would actively make it worse if I tried anything).

@zm711
Copy link
Contributor

zm711 commented Sep 25, 2023

@h-mayorquin

Just to make it clear I could image a miniature version of this (which is from the spikeinterface docs) added to the end of the figure with the channels labeled with 1-6 to indicate that we are going from probe to data (but of course the probe numbers and the trace numbers are not the same and thus must be "translated" by the wiring).
image

@h-mayorquin
Copy link
Collaborator

Thanks, @zm711. I just had a discussion with Alessio about this and he gave me a bunch of tips on how to improve this. I will include some traces and remove the contact indices as you suggested.

I will be kind of slow because we have a retreat at work next week and I have been working on this on my free time so far.

@zm711
Copy link
Contributor

zm711 commented Sep 25, 2023

Hey @h-mayorquin,
No worries. Enjoy the retreat! I think anyone with enough artistic ability to make meaningful graphics is a hero :)

@nmtimme
Copy link
Author

nmtimme commented Oct 6, 2023

@alejoe91 Thank you for that information! (Also, I'm sorry for the slow response! I used that information and got the sorting pipeline working and in that process, responding fell of my radar.) I would close the issue, but it seems like others are using this space to talk about the diagram.

I must confess that I find that diagram a bit confusing (I agree with @zm711's assessments). I found @alejoe91's text description sufficient, but nice pictures are always helpful too. For our lab, I created spreadsheets like this to help with the mapping:

image

This is an ASSY-158-F Cambridge Probe implanted with the plug ribbon on the animal's left being connected with an Intan headstage. To create the device_channel_indices variable, you line up the channels (red to red, blue to blue, green to green, etc.).

So, device_channel_indices[31] = 49 (noting that python starts counting at 0 so the probe channel number of 32 -> 31 and open ephys (our recording system) starts at channel 1). Anyway, I hope this helps and thank you to everyone for your help!

~Nick

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
question Further information is requested
Projects
None yet
Development

No branches or pull requests

4 participants