Some default parameter annotations in API are confusing

Help scanpy
1

Hey everyone,

I have been getting into the scverse lately to analyze some single cell data. When looking at the documentation online, I often was confused when parameters had None as their default parameter, even though the type hint said bool or similar. In these cases I usually then went into the source code to see how you handle the None default. One example is sc.tl.leiden which has directed=None as default which is later set to False if it is None.

Is there a systematic reason for why you chose to have these default arguments?

Especially as a new user I either have to trust that you will do some meaningful decisions downstream, or I have to really dig into the code to get exactly what each of these parameters eventually defaults to if I don’t specify them.

Would be grateful for any clarification and thanks for the great ecosystem!

2

Hey @MSHelm, welcome to scverse!

Without looking at the specific functions, I would say None is a meaningful default in Python that allows one to distinguish whether a value has been provided by the user. E.g. when using directed=False, there will be no way to know, in the body of that function, if False came from the user or merely from the default value set for that optional argument.

I hope that perspective helps!

3

On a different note, this is ideally clarified in the docstring. Feel free to submit pull requests if you feel like some defaults are still underspecified.