documentation of MEDiCINe

[bendichter]

The MEDiCINe has been implemented in the estimate_motion function, and the argument is available in the low-level API, but I do not see an explanation of this method anywhere in the docs, nor a link to the corresponding paper.

[alejoe91]

Thanks @bendichter

@chrishalcrow is currently refactoring the motion functions in the preprocessing module and also adding a high-level estimate_motion function there that accepts presets. We should add medicine as a preset and add docs and refs there

[chrishalcrow]

Hey @bendichter PR #3905 added medicine to the motion correction presets. This was added before the newest release, so will work in version 102.3 and above. Uou can use it by running something like

import spikeinterface.full as si
motion = si.compute_motion(recording=recording, preset="medicine")

and take a look at the results. Then make an interpolated recording using

interpolated_recording = si.interpolate_motion(recording=recording, motion=motion)

and medicine is included in the docs here: https://spikeinterface.readthedocs.io/en/stable/how_to/handle_drift.html

Hoping to add some more docs after some further preprocessing refactoring that is happening before the next release :)

[brian-arnold]

Thank you for integrating medicine! Posting here in case it's useful to others, but is it possible to use medicine in the separate estimate_motion function from spikeinterface.sortingcomponents.motion in 0.102.3? I've modularized our pipeline to separate spike detection/localization from actual motion estimation/correction in order to explore various approaches without recomputing features, so I'm using estimate_motion instead of the compute_motion function mentioned above, which appears to be a wrapper that includes feature detection.

When I try to use medicine with estimate_motion, I get the error message below that appears to be due to the output_dir argument to medicine, which at first glance doesn't appear to be exposed for passing from spikeinterface to medicine? Am I missing something simple? Thanks for any advice!!

2025-05-21 23:14:42,904 - medicine.logger - INFO - Creating output_dir None
Traceback (most recent call last):
  File "/lab/users/barnold/enigma_repos/spike-sorting/src/ephys/runners/runner_spike_sorting.py", line 161, in estimate_correct_motion
    motion_object = motion.estimation_correction.estimate_motion(rec,
  File "/lab/users/barnold/enigma_repos/spike-sorting/src/ephys/motion/estimation_correction.py", line 51, in estimate_motion
    est_motion_out = motion.estimate_motion(
  File "/opt/venv/lib/python3.10/site-packages/spikeinterface/sortingcomponents/motion/motion_estimation.py", line 111, in estimate_motion
    motion = method_class.run(
  File "/opt/venv/lib/python3.10/site-packages/spikeinterface/sortingcomponents/motion/medicine.py", line 75, in run
    trainer, time_bins, depth_bins, pred_motion = run_medicine(
  File "/opt/venv/lib/python3.10/site-packages/medicine/run.py", line 77, in run_medicine
    output_dir = Path(output_dir)
  File "/usr/lib/python3.10/pathlib.py", line 960, in __new__
    self = cls._from_parts(args)
  File "/usr/lib/python3.10/pathlib.py", line 594, in _from_parts
    drv, root, parts = self._parse_args(args)
  File "/usr/lib/python3.10/pathlib.py", line 578, in _parse_args
    a = os.fspath(a)
TypeError: expected str, bytes or os.PathLike object, not NoneType
Error occurred: expected str, bytes or os.PathLike object, not NoneType

Brian

[samuelgarcia]

@brian-arnold : If I remember correctly the output_dir was not needed anymore in latest version of medicine (I made a patch for it) so maybe only updating it should be OK. But maybe this is not working anymore.

Not sure we have the correct ref in the doc yet.

[brian-arnold]

Thanks so much @samuelgarcia for your reply! I was previously using medicine 1.5 and an upgrade to 1.6 fixed my issue. Thanks!

[alejoe91]

This is documented now, let's close :)

[bendichter]

@alejoe91 can you point me to where this is documented? For example, is there any explanation of when you might use medicine vs other algorithms? Is the paper referenced anywhere?

Also, this sentence appears twice:

Correcting for drift is easy! You just need to run a single function. We will try this function with some presets.

[alejoe91]

Let's reopen this @bendichter

I thought that we had more refs on the how to page, but we don't (not even for dredge).

We have docs in the classes, e.g. for dredge, but still not for medicine. I guess this is because the wrapper was made way before the paper/preprint were out.

[zm711]

I added dredge + medicine to our citation page. (+ a couple others) so I think that covers this issue. I'm curious what you mean by

any explanation of when you might use medicine vs other algorithms?

At least in my opinion the point of SI is to provide a hook for users to pick different algorithms, but that it is the users responsibility to choose which algos to use by reading the docs. What type of a doc would you want for this?

Also, this sentence appears twice:

Correcting for drift is easy! You just need to run a single function. We will try this function with some presets.

Fixed this one in #4057. Thanks for finding that.

Once those two PRs are merged I think we have hit the actionable parts of this issue. But maybe we want more discussion of whether we want documentation of when to use motion correction algos?

[bendichter]

@zm711 thanks for addressing this. I was thinking something roughly analogous to this tSNE page on scikit-learn.

[zm711]

That would be super cool. I don't know if any of us have the bandwidth for that style of doc. Could be a cool hackathon/doc sprint idea in the future for the next even. I'll close this issue as we've hit the limit of what we can do at the moment. But definitely propose this idea again when we have dedicated brain time to make a chart like this (I can imagine a more SpikeForest like comparison -- or the KS paper that showed different drift types and how the sorters performed compared to KS4).