Contributing

Getting Started

• Start by navigating to https://github.com/neurodata/ndio and forking the project to your own GitHub account.

  git clone https://github.com/neurodata/ndio.git
  

• Download the required packages. This can be done easily with pip:

  pip install -r requirements.txt
  

• Ensure that the test suite passes by running:

  coverage run -m unittest discover
  

Contributing Code

It is highly recommended that you reach out to the development team at [email protected] before beginning on a project, as it may already be under development.

• Check out a new branch on your forked copy of the repo. By convention, we prefix branch names with add- if it's a feature addition, fix- if it's a bug-fix, etc.

  git checkout -b add-json-exports
  

• Make your changes and push to your fork. Then, take out a pull-request against the master branch of the official neurodata/ndio repository. Be sure your code subscribes to our style guide (below)!

Style Guide

We adhere to the Google Style Guide whenever possible, and use the Google docstring styleguide as well. Optional arguments can be 'defaulted' with the syntax: param_name (type: Default): Description.

For instance:

    answer (int: 42): The universal answer to supply to the function

pep8 Compliance

Our pull-request merge process requires that any file with a .py extension in the repository passes pep8 compliance checks. Some argue that this is superfluous, but it's a good way of making sure that our requirements are clear and well-defined. If you think you have a really, really good reason that your pull-request breaks pep8 compliance, then tag a core developer in your PR to discuss further.

Docstring Compliance

We also like docstrings to be present and well-formed in all public-facing functions, classes, and modules. Pull request status checks will fail if docstrings are not well-formed. We use pydocstyle (pip-installable) to verify goodness of documentation, though we have some permitted exceptions in order to improve readability and feasibility of adhering to all required rules. To make sure that your code passes locally before pushing, you can run the checkstyle script from the root of the repository, which will check both pep8-compliance and docstring compliance.

Code Conventions

• Raise exceptions, don't print. Raising exceptions sends output to stderr, which is good — printing goes to stdout. Consider the following script:

  # print_csv.py
  import ndio.remote.neurodata as ND
  import sys
  
  nd = ND()
  
  print ",".join([i for i in nd.get_ramon_ids(sys.argv[1], sys.argv[2])])
  

  This script accepts two command-line arguments and prints out a CSV of token/channel IDs:

  python print_csv.py kasthuri2015_ramon_v1 neurons > out.csv
  

  If you print warnings, you'll ruin the CSV schema!

• Double-quotes unless you need double-quotes inside the quotes. Then, single quotes.

Naming

Because we anticipate users aliasing packages when they're imported instead of importing * from a package, we can use that to our advantage and make our function names shorter. For instance:

import ndio.convert.png as png

png.from_cutout( . . . )

Conventions are as follows:

• Converters or exporters should be titled from_{fmt} or to_{fmt}, and their package predicate should elaborate on the source or target format. For instance, ramon.to_hdf5() quite clearly converts from RAMON to hdf5.
• Filenames come first, then data. (Keeping with common python package tradition.)