Indicate what parameters are optional

[bendichter]

Feature Request

It's not clear to me from the pynwb docs what arguments are required and what arguments are optional.

If I run:

from pynwb import NWBFile
NWBFile()

I get the following error:

TypeError: missing argument 'source', missing argument 'session_description', missing argument 'identifier', missing argument 'session_start_time'

which tells me which arguments are required. If I then run:

from pynwb import NWBFile
from datetime import datetime
NWBFile(source='source', session_description='session_description',
        identifier='identifier', session_start_time=datetime.now())

no error, but what about the other arguments? The docs list many parameters:

source (str) – the source of the data
session_description (str) – a description of the session where this data was generated
identifier (str) – a unique text identifier for the file
session_start_time (datetime or str) – the start time of the recording session
file_create_date (ndarray or list or tuple or Dataset or DataChunkIterator or DataIO or FORMDataset or datetime or str) – the time the file was created and subsequent modifications made
experimenter (str) – name of person who performed experiment
experiment_description (str) – general description of the experiment
session_id (str) – lab-specific ID for the session
institution (str) – institution(s) where experiment is performed
lab (str) – lab where experiment was performed
acquisition (list or tuple) – Raw TimeSeries objects belonging to this NWBFile
stimulus (list or tuple) – Stimulus TimeSeries objects belonging to this NWBFile
stimulus_template (list or tuple) – Stimulus template TimeSeries objects belonging to this NWBFile
epochs (Epochs) – Epoch objects belonging to this NWBFile
epoch_tags (tuple or list or set) – A sorted list of tags used across all epochs
modules (list or tuple) – ProcessingModule objects belonging to this NWBFile
ec_electrodes (ElectrodeTable or Iterable) – the ElectrodeTable that belongs to this NWBFile
ec_electrode_groups (Iterable) – the ElectrodeGroups that belong to this NWBFile
ic_electrodes (list or tuple) – IntracellularElectrodes that belong to this NWBFile
imaging_planes (list or tuple) – ImagingPlanes that belong to this NWBFile
ogen_sites (list or tuple) – OptogeneticStimulusSites that belong to this NWBFile
devices (list or tuple) – Device objects belonging to this NWBFile
subject (Subject) – subject metadata

4 of those are required and the rest are not. As far as I can tell the only way to determine this is by trial and error. The input arguments are obscured by docval, so my standard PyCharm tricks don't work either.

There's a standard way to do this with the various docstring formats (Google, numpy, reStructuredText etc.), but we are using docval, so I don't really know how to handle it. Perhaps we could add the ability to mark arguments as optional, if it does not already exist?

• Have you ensured the feature or change was not already reported ?
• Have you included a brief and descriptive title?
• Have you included a clear description of the problem you are trying to solve?
• Have you included a minimal code snippet that reproduces the issue you are encountering?

[ajtritt]

keyword arguments are optional, positional arguments are required. You can see which arguments are keyword and which are positional by looking at the method signature.

[bendichter]

class pynwb.file.NWBFile(source, session_description, identifier, session_start_time, file_create_date=None, experimenter=None, experiment_description=None, session_id=None, institution=None, lab=None, acquisition=None, stimulus=None, stimulus_template=None, epochs=None, epoch_tags=set(), modules=None, ec_electrodes=None, ec_electrode_groups=None, ic_electrodes=None, imaging_planes=None, ogen_sites=None, devices=None, subject=None)

oh ok I see

[bendichter]

I'm used to having the word "optional" after optional arguments as well e.g. https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.medfilt.html. I think it would be nice to add that so the documentation style is consistent with common python tools

[ajtritt]

If you want to add something "(optional)" to the arguments list in the documentation, you would need to modify pynwb.form.utils.__googledoc

[bendichter]

got it, thanks!