|
1 | | -# probe-library |
2 | | - |
3 | | -[](LICENSE) |
4 | | - |
5 | | -[](https://github.com/semantic-release/semantic-release) |
6 | | - |
7 | | - |
8 | | - |
9 | | - |
10 | | -## Usage |
11 | | - - To use this template, click the green `Use this template` button and `Create new repository`. |
12 | | - - After github initially creates the new repository, please wait an extra minute for the initialization scripts to finish organizing the repo. |
13 | | - - To enable the automatic semantic version increments: in the repository go to `Settings` and `Collaborators and teams`. Click the green `Add people` button. Add `svc-aindscicomp` as an admin. Modify the file in `.github/workflows/tag_and_publish.yml` and remove the if statement in line 65. The semantic version will now be incremented every time a code is committed into the main branch. |
14 | | - - To publish to PyPI, enable semantic versioning and uncomment the publish block in `.github/workflows/tag_and_publish.yml`. The code will now be published to PyPI every time the code is committed into the main branch. |
15 | | - - The `.github/workflows/test_and_lint.yml` file will run automated tests and style checks every time a Pull Request is opened. If the checks are undesired, the `test_and_lint.yml` can be deleted. The strictness of the code coverage level, etc., can be modified by altering the configurations in the `pyproject.toml` file and the `.flake8` file. |
16 | | - - Please make any necessary updates to the README.md and CITATION.cff files |
17 | | - |
18 | | -## Level of Support |
19 | | -Please indicate a level of support: |
20 | | - - [ ] Supported: We are releasing this code to the public as a tool we expect others to use. Issues are welcomed, and we expect to address them promptly; pull requests will be vetted by our staff before inclusion. |
21 | | - - [ ] Occasional updates: We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests. |
22 | | - - [ ] Unsupported: We are not currently supporting this code, but simply releasing it to the community AS IS but are not able to provide any guarantees of support. The community is welcome to submit issues, but you should not expect an active response. |
23 | | - |
24 | | -## Release Status |
25 | | -GitHub's tags and Release features can be used to indicate a Release status. |
26 | | - |
27 | | - - Stable: v1.0.0 and above. Ready for production. |
28 | | - - Beta: v0.x.x or indicated in the tag. Ready for beta testers and early adopters. |
29 | | - - Alpha: v0.x.x or indicated in the tag. Still in early development. |
30 | | - |
31 | | -## Installation |
32 | | -To use the software, in the root directory, run |
33 | | -```bash |
34 | | -pip install -e . |
35 | | -``` |
| 1 | +# Probe Library |
36 | 2 |
|
37 | | -To develop the code, run |
38 | | -```bash |
39 | | -pip install -e . --group dev |
40 | | -``` |
41 | | -Note: --group flag is available only in pip versions >=25.1 |
| 3 | +This readme describes specifications for describing **probes**. These are 3D objects that do not change physical shape during an experiment and have locations along the probe whose position inside the brain are of interest, these might be electrode contacts or |
| 4 | + |
| 5 | +The individual folders in this repository are used to generate the probes in [Pinpoint](https://github.com/virtualBrainLab/pinpoint). |
| 6 | + |
| 7 | +## Probe |
| 8 | + |
| 9 | +A probe is a 3D object with one or more shanks each of which have sites on them. |
| 10 | + |
| 11 | +File | Description |
| 12 | +---|--- |
| 13 | +metadata.json | probe metadata, in JSON format |
| 14 | +model.obj | 3D model of the probe shanks and any attached silicon, the tip of the reference shank is at the origin |
| 15 | +hardware/your_hardware.obj | (optional) 3D model of additional hardware attached to the probe, the origin of the hardware model should be at the tip of the reference shank |
| 16 | +site_map.csv | coordinates of electrode surface relative to the tip and selection layers |
| 17 | +scripts/ | (optional) If you used any scripts to generate your probe 3D model or site_map, please include them here for reproducibility |
| 18 | + |
| 19 | +### metadata.json |
| 20 | + |
| 21 | +Field | Type | Example | Description |
| 22 | +---|---|---|--- |
| 23 | +name | string | Neuropixels 1.0 | Full name of the probe |
| 24 | +type | int | 1 | Unique ID that can identify this probe, this must be different from all other probes in the library |
| 25 | +producer | string | "imec" | Company or insitutition producing the probe |
| 26 | +sites | int | 960 | Number of channels on the probe |
| 27 | +shanks | int | 1 | Number of physical shanks |
| 28 | +references | string | "https://www.nature.com/articles/nature24636" | Reference papers about the probe |
| 29 | +spec | string | "https://www.neuropixels.org/_files/ugd/328966_c5e4d31e8a974962b5eb8ec975408c9f.pdf" | Specifications for the probe |
| 30 | + |
| 31 | +Example for Neuropixels 1.0: |
42 | 32 |
|
43 | | -Alternatively, if using `uv`, run |
44 | | -```bash |
45 | | -uv sync |
46 | 33 | ``` |
| 34 | +{ |
| 35 | + "name":"Neuropixels 1.0", |
| 36 | + "type":"1" |
| 37 | + "producer":"imec", |
| 38 | + "sites":"960", |
| 39 | + "shanks":"1", |
| 40 | + "references":"https://www.nature.com/articles/nature24636", |
| 41 | + "spec":"https://www.neuropixels.org/_files/ugd/328966_c5e4d31e8a974962b5eb8ec975408c9f.pdf" |
| 42 | +} |
| 43 | +``` |
| 44 | + |
| 45 | +### model.obj |
| 46 | + |
| 47 | +3D model of the probe with the surface of the tip at the origin. The probe model should be at "rest" according to the Pinpoint convention. In Unity this means that the .obj file is rotated such that the shanks are pointing along the +Z axis, while the site surface points along the +Y axis. On multi-shank probes the reference shank should be at the origin (i.e. additional shanks should be offset in the -X direction). |
| 48 | + |
| 49 | +In Blender this convention corresponds to the shanks pointing along the -Y axis, the site surface pointing along the +Z axis, and additional shanks should be offset in the +X direction. |
| 50 | + |
| 51 | +#### hardware.obj |
| 52 | + |
| 53 | +Additional 3D model files can be included. For example, you may want a 3D model for the circuit boards that are often attached to the actual probe shanks, or for the parts that connect the probe to a micro-manipulator. These additional hardware models will be *fixed* to the probe when displayed in Pinpoint, they cannot be animated or moved inside the program (as of v1.1). |
| 54 | + |
| 55 | +Each .obj file included in the hardware folder will be available as a separate optional 3D model to display and check collisions against. Please group 3D models that are always attached together into a single file. |
| 56 | + |
| 57 | +### site_map.csv |
| 58 | + |
| 59 | +The site map defines the locations of electrode contacts or other points of interest on the probe shanks. In Pinpoint these are the anatomical locations visible on the site maps and can be rendered on the 3D model as well. The first seven columns define the site positions and size relative to the origin (tip) of the probe. The remaining columns define layer options for controlling which sites are actually displayed. |
| 60 | + |
| 61 | +Fields: index, x, y, z, w, h, d, default, layer1, layer2, ... |
| 62 | + |
| 63 | +Example for Neuropixels 1.0: |
| 64 | + |
| 65 | +| index | x | y | z | w | h | d | default | all | bank0 | double_length | |
| 66 | +|-----------|-----|-----|---|----|----|----|---------|-----|-------|---------------| |
| 67 | +| 0 | -14 | 200 | 0 | 12 | 12 | 24 | 1 | 1 | 1 | 0 | |
| 68 | +| 1 | 18 | 200 | 0 | 12 | 12 | 24 | 1 | 1 | 1 | 1 | |
| 69 | +| 2 | -30 | 220 | 0 | 12 | 12 | 24 | 1 | 1 | 1 | 0 | |
| 70 | +| 3 | 2 | 220 | 0 | 12 | 12 | 24 | 1 | 1 | 1 | 1 | |
| 71 | + |
| 72 | +# Contributing |
| 73 | + |
| 74 | +You can contribute your own probe models to the library and have them included in Pinpoint. Pinpoint is built every 1-2 weeks, if you need to put a 3D model temporarily into the Pinpoint scene you should use the Pinpoint API. To make a new contribution: |
| 75 | + |
| 76 | + 1. Fork the respository |
| 77 | + 2. Copy an existing probe folder |
| 78 | + 3. Modify the folder to match your new probe |
| 79 | + 4. Submit a pull request, your probe metadata and site_map files will run against our automated tests to validate their format. Note that no tests are run on 3D model files. |
| 80 | + 5. Once your pull requested is merged, your probe files will automatically be included in future builds of Pinpoint |
0 commit comments