[FEATURE]: Spike2py alias and comments

[joannadiong]

Hi there, thanks for a neat package -- it makes importing data from Spike2 much more streamlined. I had some comments that seem more suited as a Discussion instead of as an Issue, so Feature seemed the best fit.

Spike2py alias The Tutorial recommends importing spike2py using the alias sp, however scipy is often imported as sp. I can imagine some users might want to use scipy functions after having imported data using spike2py, which would create conflicts. What do you think about importing spike2py using a different alias, e.g. s2p, as a recommendation?

Demo data file location In the Tutorial, when practicing loading the pickle file, I could not work out where demo tutorial.mat file is located to supply the file path of the pickle file to run the code. If the intention is for users to test storing and loading the files at this point, could the docs advise where the tutorial.mat file is stored?

Hyperlinks to functions In the How To Guides, at the list of signal processing steps, the docs said clicking on the names takes users to the full documentation but the names are not hyperlinked. I'm not sure if they should be hyperlinked, or whether the docs refers to clicking on function names in an IDE. Could this be clarified?

Thanks for your consideration.

[MartinHeroux]

Thanks for the input.

spike2py alias. Good suggestion. Happy to to implement it, or to have you make the change and make a pull request.

Demo data file location. I made the conscious decision to not have the matlab data file be part of the package. As can be seen in demo.py, the file is located in an Amazon s3-bucket. This approach was recommended by @bbelderbos and leads to a clean package (no random data file).

The introductory tutorial is meant to show the basics to users and have them follow along with the commands (not be adventurous and look around for the data files and the pickled files!). Having said that, I can see that the tutorial breaks down at step 5 because of the issue you raise. There is a solution to the problem, and if you feel like tackling it that would be great (if not I will get to it in a bit).

The answer to your question is in the tutorial: "The file was saved in the directory listed in tutorial.info.path_save_trial. This path defaults to a directory called data created in the directory from where we imported our tutorial dataset."

On my system, I get the following:

So the file obtained from the s3-bucket is stored in my /tmp/ folder. Based on what is said in the tutorial, that is also where the .pkl file will be located if you run tutorial.save(). Can you think of a way to change tutorial = sp.trial.load(file='/home/martin/Desktop/data/tutorial.pkl') so that it will run on anyone's computer?

Consequently the tutorial should be updated slightly to reflect this change. This will definitely make it simpler and more useful to beginners, so thank you for taking the time to go through the tutorial!

Hyperlinks to functions. Thanks for pointing this out. This is a Sphinx issue (which I am no expert at). I will leave this Feature request open for a bit to see if anyone (possibly you) wants to have a look at solving this. If not I will look into it in the new years.

[joannadiong]

Thanks for the feedback, and clues!

spike2py alias. Cool, I'll set up a PR.

Demo data file location. I thought the below might work, but it generated an error saying the PKL file isn't there. Any pointers?

>>>import spike2py as s2p
>>>from pathlib import Path

>>>tutorial = s2p.demo.tutorial_data()
>>>tutorial.save()

# load saved file
>>>tutorial = s2p.trial.load(file=tutorial.info.path_save_trial / 'tutorial.pkl')
Traceback (most recent call last):
  File "<input>", line 1, in <module>
  File "/home/joanna/Dropbox/Sketchbook/python/spike2py/spike2py/trial.py", line 182, in load
    with open(file, "rb") as trial_file:
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/data/tutorial.pkl'

Hyperlinks to functions. In the How To Guides, I was playing around with :meth: instead of :func: and realised that the HTML files in my local directory does hyperlink to the function documentation, but the How To Guides page through GitHub does not. Do hyperlinks on your local HTML files work too?

Not sure, but the .gitignore also seems to be ignoring a .docs/build instead of docs/build

No rush. Thanks for considering.

[MartinHeroux]

Thanks for looking into these issues.

Demo data file location

You are almost there. If you have a look in the folder where the data is saved (/tmp/data/ in this case), you will see that there is a file called motor_units.pkl. This is because spike2py uses the name found in .info.name as the file name.

So in your code above, rather than have 'tutorial.pkl', you can use the the name in tutorial.info.name. Hopefully that is enough to get it working for you. After that, it would be great if you can revise the docs a little so that your change is implemented and the documentation is clearer regarding this point.

Make sure you sync your fork with origin for you make these changes as I have made a few attempts to solve the issue with sphinx and readthedocs (unsuccessfully!)

Hyperlinks to functions

I am a bit stumped here. I get the hyper links on my local version of the docs, and also the documentation in the reference sections. But on readthedocs the links don't work AND the actual reference documents are not there (maybe that is why the links don't work because there is nothing there). I thought I fixed this by increasing the tree-depth to 3, but it only fixed my local version not the one up on readthedocs.

I will continue to look into this issue and report back. If you find a solution, I would be grateful if you could let me know!

[joannadiong]

Thanks for the pointers!

Demo data file location

The code below works but seems less elegant because it requires the user to import Path. That might suffice just for the tutorial, since in practice we'll be importing data from elsewhere. But please revise if there are better solutions.

>>>from pathlib import Path
>>>tutorial = s2p.trial.load(file=Path('.' /
                       tutorial.info.path_save_trial /
                       tutorial.info.name).with_suffix('.pkl'))

Tutorial text also revised slightly. I'll open a PR.

Hyperlinks to functions

Same here. Please keep the Issue open a while longer. I'll look around and feedback if I find anything relevant.

Thanks again.