[ENH][REF] Cortex

[jgranley]

This is finally it! Adds support for simulation of cortical prostheses. Visual field maps, models, implants, 3D models, MRI/neuropythy, its all here.

Overview of changes

This includes all PR's for the cortex branch. It may be easier to review the individual PR's.

Implants

• Orion [ENH] Add Orion implant and Test #524
• Cortivis [ENH] Add Cortivis implant #525, [ENH] Update to match 2023 Cortivis electrode numbering #561, [REF] Cortivis Electrode Numbering #560
• ICVP [ENH] Add ICVP Cortical Implant + Test #542
• Neuralink (EllipsoidElectrode, NeuralinkThread, LinearEdgeThread, Neuralink) [ENH] Neuropythy, Neuralink, 3D models #597
• EnsembleImplant [ENH] Add Ensemble implant #537 [ENH] Add methods to initialize an EnsembleImplant from a list of coordinates #601

Topography

• Restructured Grid2D, build(), and grid.vfmap. All attributes can be accessed through (e.q. model.grid.v1.x, model.grid['v1'].x), regions can be anything, determined by the visual field map. Supports 3D coordinates ([ENH][REF] Modified Grid2D and VisualFieldMap to support multiple visual areas #509, [ENH] Neuropythy, Neuralink, 3D models #597)

• retinotopy renamed to vfmap. New VisualFieldMap inheritance structure.from_dva and to_dva. ([REF][DOC] Retinotopy -> vfmap, doc updates #594, [ENH] Unmark dva_to_v2 and dva_to_v3 as abstract #555)

• Polimeni visual field mapping ([ENH] Add Polimeni visual field mapping #531, [REF] Default values for Polimeni mapping #567, [ENH] Add plot for Polimeni Mapping #535)

• Neuropythy MRI based visual field mapping ([ENH] Neuropythy, Neuralink, 3D models #597)

• Helper functions (Neuralink.from_neuropythy) to place neuralinks at locations in cortex corresponding to VF locations, automatically inserted perpendicular to cortical surface.

Models

• models.cortex module, with CortexSpatial (abstract) and ScoreboardModel (but for cortex) ([ENH] Add base CortexSpatial model #536, [ENH] Add Cortex ScoreboardModel, updates to PolimeniMap #533, [BUG][MNT] Package organization for cortex submodules #581, [BUG] Cortex model plotting fails if model isn't built #566)
• Updated plotting to support cortex ([FIX] Fix Implants, Grid Plotting #552, [FIX] Plotting with unbuilt model #570)
• Dynaphos (from Grinten/Lozano/Stevenick et al) ([ENH] Add Grinten / Stevenick / Lozano model (Dynaphos) #547, [ENH][FIX][DOC] Add Dynaphos activation threshold #593, [FIX] Fix Dynaphos model phosphene size at amplitude 0 #592)

Misc

• Bump to python 3.11 ([MNT] Bump to Py311 #596)
• Package restructuring ([REF] Add topography, implants.cortex, and models.cortex submodules #518, [MNT] Update package setup for cortex packages #579, [FIX][MNT] Fix cortex packages not importing as expected #584)
• Docs, including Dynaphos example, updated retinotopy example, cortex basic concepts, and cortical implant gallery ([DOC] Add Dynaphos to example gallery #590, [DOC] Improve Cortex Docs #588, [REF][DOC] Retinotopy -> vfmap, doc updates #594, [DOC] Fix sphinx issues and merge Luke's examples #587, [DOC] Fix incorrect implant mention in Dynaphos docs #598, [DOC] Add EnsembleImplant to cortex docs #600 )
• Weird bugs ([DOC][FIX] Fix docs, remove calls to slow _fast_math cython functions #586, [FIX] Y axis treatment in retinotopy, visual field, and Grid2D. Fix AxonMapModel OD location #578)
• New pytest --runslow option and github action for slow tests (e.g. neuropythy download) so they don't run every time pytest is ran.

Open questions / sharp bits

• How to handle models that cannot separate temporal and spatial components (Dynaphos does this and thus extends BaseModel).
• Consistent model naming (Dynaphos has 3 first authors, Dynaphos was chosen to match their code base)
• Another ScoreboardModel in models.cortex. Does 2 separate ones (one for cortex and one for retina) make sense?
• vfmap instead of retinotopy? Neuropythy for example uses retinotopy everywhere.

Open TODO's

I will likely make issues for these but I think we should go ahead and merge now.

• Doc example for Neuropythy and Neuralink, add to cortex intro.
• Add from_neuropythy for ensemble implant to support placing one or more e.g. cortivis or icvp across the 3D cortex perpendicular to surface, like it does for neuralink

Type of Change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[jgranley]

@mbeyeler We can go over things in a meeting next week too if that is helpful!

[jgranley]

Reminder to self / whoever merges: remember to rebase and merge instead of squash and merge, so that the individual PR's / commits are not lost.