We're building a Python toolkit to support neuroscience. This effort is complementary to others in this space, such as nilearn, nipy, and similar. We are primarily working on new research efforts in processing and understanding functional Magnetic Resonance Imaging (fMRI) data sets.
We provide high performance algorithms, typically implemented in C/C++, along with convenient Python wrapper modules that make these advanced tools available for easy use. These are some of the design goals that contributors should keep in mind:
- We do not intend to duplicate existing functionality, either in the C++ side, or the Python side. For example, we do not provide any tools for parsing Nifti files, even though BrainIAK heavily depends on them. Nibabel already has perfectly good tools for this.
- We try to make the C++ libraries usable outside of Python as well, so that they could be used directly in your C++ project, or accessed from other languages. However this is a secondary goal, our primary goal is to produce a solid, highly usable, very high performance toolkit for Python.
- Every algorithm should be capable of running on a single machine, and if there is an appropriate distributed algorithm, it should also be capable of running at cluster scale. It is understood that the single-machine version of an algorithm will need to work with smaller datasets than the cluster version.
We use GitHub pull requests (PRs) to make improvements to the repository. Please see the GitHub help for collaborating on projects using issues and pull requests for information about how to create your own fork of the project and generate pull requests to submit your code for inclusion in the project.
All pull requests will be automatically tested as described below, so make sure you test them yourself before submitting them:
# optional, but highly recommended: create a virtualenv to isolate tests virtualenv ../brainiak_pr_venv source ../brainiak_pr_venv/bin/activate # install developer dependencies pip3 install -U -r requirements-dev.txt # static analysis ./run-checks.sh # install brainiak in editable mode (required for testing) pip3 install -U -e . # run tests ./run-tests.sh # build documentation cd docs make cd - # optional: remove virtualenv deactivate rm -r ../brainiak_pr_venv
Alternatively, you can run pr-check.sh, which does all of the above and
supports conda in addition to virtualenv.
We primarily use PyCharm (or equivalently, IDEA with Python plugin). You're free to use whatever you like to develop, but bear in mind that if you use the same tools as the rest of the group, more people will be able to help if something goes wrong.
The development requirements are listed in requirements-dev.txt. You can
install them with:
pip3 install -U -r requirements-dev.txt
- Python code should follow the Scikit-learn coding guidelines with the exception that we target Python 3 only.
- Python docstrings should be formatted according to the NumPy docstring standard as implemented by the Sphinx Napoleon extension (see also the Sphinx NumPy example). In particular, note that type annotations must follow PEP 484. Please also read the NumPy documentation guide, but note that we consider Sphinx authoritative.
- C++ code should follow the WebKit code style guidelines.
- All code exposed through public APIs must have documentation that explains what the code does, what its parameters mean, and what its return values can be, at a minimum.
- All code must have repeatable automated unit tests, and most code should have integration tests as well.
- Where possible, transformations and classifiers should be made compatible
with Scikit-learn Pipelines by implementing
fit,transformandfit_transformmethods as described in the Scikit-learn pipeline documentation.
Use
loggingto record debug messages with a logger obtained using:logging.getLogger(__name__)
Use
warningsto show warning messages to users. Do not useprint. See the Python Logging Tutorial for details.
Unit tests are small tests that execute very quickly, seconds or less. They are
the first line of defense against software errors, and you must include some
whenever you add code to BrainIAK. We use a tool called "pytest" to run tests;
please read the Pytest documentation. You should put your tests in a
test_*.py file in the test folder, following the structure of the
brainiak folder. So for example, if you have your code in
brainiak/functional_alignment/srm.py you should have tests in
tests/functional_alignment/test_srm.py.
You must install the package in editable mode using the -e flag of pip3
install before running the tests.
You can run ./run-tests.sh to run all the unit tests, or you can use the
py.test <your-test-file.py> command to run your tests only, at a more
granular level.
Next to the test results, you will also see a code coverage report. New code should have at least 90% coverage.
Note that you can only obtain test coverage data when the package is installed
in editable mode or the test command is called from the test directory. If
the package is installed normally and the test command is called from the
project root directory, the coverage program will fail to report the coverage
of the installed code, because it will look for the code in the current
directory, which is not executed.
Since BrainIAK is primarily published as a Python package, it is largely organized according to the Python Packaging User Guide.
Python code goes in the brainiak package, usually with a subpackage for
each major research initiative. If an algorithm can be implemented in a single
module, place the module directly in the brainiak package, do not create a
subpackage.
Name subpackages and modules using short names describing their functionality,
e.g., tda for the subpackage containing topological data analysis work and
htfa.py for the module implementing hierarchical topographical factor
analysis.