juaml/junifer
Watch
3
0
Fork
You've already forked junifer
 0
Code Issues 14 Pull requests 2 Packages Activity Actions

docs: improve documentation #30

Merged
synchon merged 6 commits from update/readme into dev 2022-09-09 16:02:07 +00:00
Conversation 2 Commits 6 Files changed 5 +274 -69
5 changed files with 274 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

54
README.md
View file

@ -1,5 +1,18 @@
# python-library-mockup # junifer - JUelich NeuroImaging FEature extractoR
JUelich NeuroImaging FEature extractoR
![PyPI](https://img.shields.io/pypi/v/junifer?style=flat-square)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/junifer?style=flat-square)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/junifer?style=flat-square)
![GitHub](https://img.shields.io/github/license/juaml/junifer?style=flat-square)
[![codecov](https://codecov.io/gh/juaml/junifer/branch/main/graph/badge.svg?token=5H21JuZXMw)](https://codecov.io/gh/juaml/junifer)
## About
junifer is a data handling and feature extraction library targeted towards neuroimaging data specifically functional MRI data.
It is curently being developed and maintained at the [Applied Machine Learning](https://www.fz-juelich.de/en/inm/inm-7/research-groups/applied-machine-learning-aml) group at [Forschungszentrum Juelich](https://www.fz-juelich.de/en), Germany. Although the library is designed for people working at [Institute of Neuroscience and Medicine - Brain and Behaviour (INM-7)](https://www.fz-juelich.de/en/inm/inm-7), it is designed to be as modular as possible thus enabling others to extend it easily.
The documentation is available at [https://juaml.github.io/junifer](https://juaml.github.io/junifer/main/index.html).
## Repository Organization ## Repository Organization
@ -15,6 +28,39 @@ JUelich NeuroImaging FEature extractoR
* `preprocess`: Preprocessing module. * `preprocess`: Preprocessing module.
* `storage`: Storage module. * `storage`: Storage module.
* `utils`: Utilities module (e.g. logging) * `utils`: Utilities module (e.g. logging)
## Installation
Use `pip` to install from PyPI like so:
```
pip install junifer
```
## Citation
If you use junifer in a scientific publication, we would appreciate if you cite our work. Currently, we do not have a publication, so feel free to use the project [URL](https://juaml.github.io/junifer).
## Contribution
Contributions are welcome and greatly appreciated. Please read the [guidelines](https://juaml.github.io/junifer/main/contributing.html) to get started.
## License
junifer is released under the AGPL v3 license:
julearn, FZJuelich AML neuroimaging feature extraction library.
Copyright (C) 2022, authors of junifer.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.

187
docs/contribution.rst Normal file
View file

@ -0,0 +1,187 @@
.. include:: links.inc
Contributing to junifer
=======================
Setting up the local development environment
--------------------------------------------
1. Fork the https://github.com/juaml/junifer repository on GitHub. If you
have never done this before, `follow the official guide
<https://guides.github.com/activities/forking/>`_.
2. Clone your fork locally as described in the same guide.
3. Install your local copy into a Python virtual environment. You can `read
this guide to learn more
<https://realpython.com/python-virtual-environments-a-primer/>`_ about them
and how to create one.
.. code-block:: console
pip install -e ".[dev]"
4. Create a branch for local development using the ``dev`` branch as a
starting point. Use ``fix``, ``refactor``, or ``feat`` as a prefix.
.. code-block:: console
git checkout dev
git checkout -b <prefix>/<name-of-your-branch>
Now you can make your changes locally.
5. When making changes locally, it is helpful to ``git commit`` your work
regularly. On one hand to save your work and on the other hand, the smaller
the steps, the easier it is to review your work later. Please use `semantic
commit messages
<http://karma-runner.github.io/2.0/dev/git-commit-msg.html>`_.
.. code-block:: console
git add .
git commit -m "<prefix>: <summary of changes>"
6. When you're done making changes, check that your changes pass our test suite.
This is all included with ``tox``.
.. code-block:: console
tox
You can also run all ``tox`` tests in parallel. As of ``tox 3.7``, you can run::
.. code-block:: console
tox --parallel
7. Push your branch to GitHub.
.. code-block:: console
git push origin <prefix>/<name-of-your-branch>
8. Open the link displayed in the message when pushing your new branch in order
to submit a pull request. Please follow the template presented to you in the
web interface to complete your pull request.
GitHub Pull Request guidelines
------------------------------
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests in the respective ``tests`` directory.
Except in rare circumstances, code coverage must not decrease (as reported
by codecov which runs automatically when you submit your pull request).
2. If the pull request adds functionality, the docs should be
updated. Consider creating a Python file that demonstrates the usage in
``examples`` directory.
3. The pull request should also include a short one-liner of your contribution
in `docs/changes/latest.inc`. If it's your first contribution, also add
yourself to `docs/changes/contributors.inc`.
4. The pull request will be tested against several Python versions.
5. Someone from the core team will review your work and guide you to a successful
contribution.
Running unit tests
------------------
junifer uses `pytest <http://docs.pytest.org/en/latest/>`_ for its
unit-tests and new features should in general always come with new
tests that make sure that the code runs as intended.
To run all tests::
.. code-block:: console
tox -e test
Adding and building documentation
---------------------------------
Building the documentation requires some extra packages and can be installed by::
.. code-block:: console
pip install -e ".[docs]"
To build the docs::
.. code-block:: bash
cd docs
make html
To view the documentation, open `docs/_build/html/index.html`.
In case you remove some files or change their filenames, you can run into
errors when using ``make html``. In this situation you can use ``make clean``
to clean up the already build files and then re-run ``make html``.
Writing Examples
----------------
Examples are run and displayed in HTML format using `sphinx gallery`_. To add an
example, just create a ``.py`` file that starts either with ``plot_`` or ``run_``,
dependending on whether the example generates a figure or not.
The first lines of the example should be a python block comment with a title,
a description of the example an the following include directive to be able to
use the links.
The format used for text is reST. Check the `sphinx reST reference`_ for more
details.
Example of the first lines:
.. code-block:: python
"""
Simple Binary Classification
============================
This example uses the 'iris' dataset and performs a simple binary
classification using a Support Vector Machine classifier.
.. include:: ../../links.inc
"""
The rest of the script will be executed as normal Python code. In order to
render the output and embed formatted text within the code, you need to add
a 79 ``#`` (a full line) at the point in which you want to render and add text.
Each line of text shall be preceded with ``#``. The code that is not
commented will be executed.
The following example will create 3 texts and render the output between the
texts.
.. code-block:: python
###############################################################################
# Imports needed for the example
from seaborn import load_dataset
from julearn import run_cross_validation
from julearn.utils import configure_logging
###############################################################################
df_iris = load_dataset('iris')
###############################################################################
# The dataset has three kind of species. We will keep two to perform a binary
# classification.
df_iris = df_iris[df_iris['species'].isin(['versicolor', 'virginica'])]
Finally, when the example is done, you can run as a normal Python script.
To generate the HTML, just build the docs:
.. code-block:: bash
cd docs
make html

14
docs/index.rst
View file

@ -1,8 +1,17 @@
.. include:: links.inc .. include:: links.inc
Welcome to the documentation! Welcome to junifer's documentation!
============================= ===================================
junifer (JUelich NeuroImaging FEature extractoR) is a data handling and feature
extraction library targeted towards neuroimaging data specifically functional
MRI data.
It is curently being developed and maintained at the Applied Machine Learning
(`AML`_) group at Forschungszentrum Juelich, Germany. Although the library is
designed for people working at Institute of Neuroscience and Medicine - Brain
and Behaviour (`INM-7`_), it is designed to be as modular as possible thus
enabling others to extend it easily.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
@ -12,6 +21,7 @@ Welcome to the documentation!
data data
api api
auto_examples/index.rst auto_examples/index.rst
contribution
maintaining maintaining
whats_new whats_new

86
docs/installation.rst
View file

@ -1,91 +1,53 @@
.. include:: links.inc .. include:: links.inc
Installing Installing junifer
========== ==================
Requirements Requirements
^^^^^^^^^^^^ ^^^^^^^^^^^^
junifer requires the following packages: junifer is compatible with `Python`_ >= 3.8 and requires the following packages:
Running the examples requires: * click>=8.1.3,<8.2
* numpy>=1.22,<1.23
* datalad>=0.15.4,<0.18
* pandas>=1.4.0,<1.5
* nibabel>=3.2.0,<4.1
* nilearn>=0.9.0,<1.0
* sqlalchemy>=1.4.27,<= 1.5.0
* pyyaml>=5.1.2,<7.0
Depending on the installation method, this packages might be installed Depending on the installation method, these packages might be installed automatically.
automatically.
Installing Installation
^^^^^^^^^^ ^^^^^^^^^^^^
There are different ways to install junifer: Depending on your use-case, junifer can be installed differently.
* Install the :ref:`install_latest_release`. This is the most suitable approach * Install the :ref:`install_latest_release`. This is the most suitable approach
for most end users. for end users.
* Install the :ref:`install_latest_development`. This version will have the * Install from :ref:`install_development_git`. This is mostly suitable approach
latest features. However, it is still under development and not yet for developers.
officially released. Some features might still change before the next stable
release.
* Install from :ref:`install_development_git`. This is mostly suitable for
developers that want to have the latest version and yet edit the code.
Either way, we strongly recommend using virtual environments: Either way, we strongly recommend using `virtual environments <https://realpython.com/python-virtual-environments-a-primer>`_.
* `venv`_
* `conda env`_
.. _install_latest_release: .. _install_latest_release:
Latest release Stable release
-------------- --------------
We have packaged junifer and published it in PyPi, so you can just install it Use `pip` to install julearn from PyPI, like so:
with `pip`.
.. code-block:: bash .. code-block:: bash
pip install -U junifer pip install -U junifer
.. _install_latest_development:
Latest Development Version
--------------------------
First, make sure that you have all the dependencies installed:
Then, install junifer from TestPypi
.. code-block:: bash
pip install -U junifer --pre
.. _install_development_git: .. _install_development_git:
Local git repository (for developers) Local Git repository
------------------------------------- --------------------
First, make sure that you have all the dependencies installed:
Then, clone `junifer Github`_ repository in a folder of your choice: Follow the `detailed contribution guidelines <contribution.rst>`_.
.. code-block:: bash
git clone https://github.com/juaml/junifer.git
Install development mode requirements:
.. code-block:: bash
cd junifer
pip install -r dev-requirements.txt
Finally, install in development mode:
.. code-block:: bash
python setup.py develop
.. note:: Every time that you run ``setup.py develop``, the version is going to
be automatically set based on the git history. Nevertheless, this change
should not be committed (changes to ``_version.py``). Running ``git stash``
at this point will forget the local changes to ``_version.py``.

2
docs/links.inc
View file

@ -30,4 +30,4 @@
.. _`setuptools_scm`: https://github.com/pypa/setuptools_scm/ .. _`setuptools_scm`: https://github.com/pypa/setuptools_scm/
.. _`sphinx gallery`: https://sphinx-gallery.github.io/stable/index.html .. _`sphinx gallery`: https://sphinx-gallery.github.io/stable/index.html
.. _`sphinx RST reference`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#inline-markup .. _`sphinx reST reference`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#inline-markup