Add import specific documentation #2168
Conversation
|
Hi Zach. |
|
I think it is fair to add the pros and cons of all views. Needing to memorize a bunch of aliases could be annoying for some users and it is a fair point. :) |
Co-authored-by: Garcia Samuel <[email protected]>
| that you have more aliases to keep track of. | ||
|
|
||
|
|
||
| Flat Import |
There was a problem hiding this comment.
Did anyone favor this option in the issue? I kind of forgot it. Could we have this to the end? I am not sure this is what numpy or pandas do btw. Is that the case? They also have np.linalg in numpy at least.
There was a problem hiding this comment.
That's fair. It was perhaps an oversimplification to explain a point.
numpy does hive some things off like numpy.testing, numpy.linalg, intentionally, but for most beginning users I think they really start with the things open with the import of numpy as np.
Pandas I don't know. I just picked it as a common library people would likely know. I've never had to import a submodule from Pandas. I think for me I would love to give an example that people latch on to. Is there a common package that you think is flat enough to count for this @h-mayorquin ?
There was a problem hiding this comment.
@samuelgarcia , you like this sometimes right?
There was a problem hiding this comment.
Yes, I mean, I think that your mind is on the right place. For user what matters is that: "all the functions that I could use or want will be available without nesting" so si.function1, si.function2, si.function3 will work I think your example is fine from that perspective as it conveys the right idea with a familiar example.
Mine was more a technical caveat by saying that I don't think numpy or pandas are putting ALL their stuff the way that we are doing it:
There was a problem hiding this comment.
Very true! They keep more functions more private. I can change the wording slightly so more technically users are put off, but keep the simplicity of the example. Thanks :)
There was a problem hiding this comment.
I do not understand the question. Do I like this flat import ? yes I use it almost always.
For me the comparison to numpy/pndas is not the best I think.
I would more compare to scipy many modules that could be imported flat.
There was a problem hiding this comment.
@samuelgarcia, I'm off GH for this week, but just to briefly comment on this one. I think this is a "simplification" for tutorial purposes vs being as exact as possible. (Pandas I think is closer than Numpy, though). My problem with using scipy here is that above we say you can import modules, so if we then talk about scipy modules here it will be mixing concepts (even if their flatness is more accurate to the .full flatness). Maybe it is best just to remove the reference to other packages for flat, so not muddy the water because I don't think we will find a perfect example.
Honestly for me I would expect
import spikeinterface as si # import the full package flat
import spikeinterface.core as si # import only core submoduleI think I understand why you did it your way for the purpose of dependency management (keep core light--but correct me if there was another design choice there), but it makes it a little tricker to find parallels with other packages.
tl;dr:
Should I just delete the outside examples?
I'll fix the numba etc this weekend when I'm back on.
There was a problem hiding this comment.
@samuelgarcia
The question was if that somebody was using it. You have answered it already by saying you do. Thanks.
| This import statement will import all of the SpikeInterface modules as one flattened module. | ||
| Note that importing :code:`spikeinterface.full` will take a few extra seconds, because some modules use | ||
| just-in-time :code:`numba` compilation performed at the time of import. | ||
| We recommend this approach for advanced (or lazy) users, since it requires a deeper knowledge of the API. The advantage |
There was a problem hiding this comment.
Is anyone of us using it?
I would recommend the functionality that we are using ourselves as that will be the one that is better tested.
There was a problem hiding this comment.
In the old docs it went
Import core
Import full
no mention of by function.
So I just kept the same general flow and added by function at the bottom. Happy to move unless Sam strong wants it above. He added edits to the full paragraph so he definitely took a peek.
There was a problem hiding this comment.
All right. Makes sense to not make a lot of changes on the same PR. Thanks for explaining yourself.
There was a problem hiding this comment.
Yes. When I teahc spikeinterface with tutorial very often I use this spikeinterface.full so participant do not have to focus on the submodules concept and take spikeinterface a a whole.
There was a problem hiding this comment.
When I teach/show tutorials I use the by module approach
Co-authored-by: Heberto Mayorquin <[email protected]>
for more information, see https://pre-commit.ci
doc/import.rst
Outdated
|
|
||
| .. code-block:: python | ||
|
|
||
| import spikeinterface as si |
There was a problem hiding this comment.
Based on the speed metrics @h-mayorquin supplied why don't we suggest
import spikeinterface.core as si
It has a slight speed advantage directly importing rather than doing without core? And it follows the syntax for all the other submodules?
|
Merci Zach. This is almost OK for me. |
Related to #2046. (But doesn't close it).
This is just a starting pass, so no need to rush to review yet, especially with the webinar coming up :).
I figured before doing a pass at the docs I want to get the import portion squared away. This PR moves import to its own section. Previously it was part of the core module, but if someone wants to look for importing the package it is probably nice for it to have its own searchable tab rather than be buried in one of the modules docs.