Merge pull request #214 from smoia/int/setup

Remove bioread form required dependencies, ease extra modules installation

.requires.yml

@@ -1,6 +1,7 @@
 version: 1.0
 requirements:
   - requirements.txt
+  - setup.cfg
   - setup.py
   - tox.ini
   - path: /requirements.txt

.travis.yml

@@ -43,11 +43,14 @@ before_install:
 
 install:
     if [ "${INSTALL_TYPE}" == "setup" ]; then
+      pip install "bioread>=1.0.5";
       python setup.py install;
     elif [ "${INSTALL_TYPE}" == "sdist" ]; then
+      pip install "bioread>=1.0.5";
       python setup.py sdist;
       pip install dist/*.tar.gz;
     elif [ "${INSTALL_TYPE}" == "wheel" ]; then
+      pip install "bioread>=1.0.5";
       python setup.py bdist_wheel;
       pip install dist/*.whl;
     else

README.md

@@ -23,7 +23,7 @@ It was born for AcqKnowledge files (BIOPAC), and at the moment it supports
 (ADInstruments).
 It doesn't support physiological files recorded with the MRI, as you can find a software for it [here](https://github.com/tarrlab/physio2bids).
 
-If you use ``phy2bids`` in your work, please cite it with the zenodo DOI as:
+If you use ``phys2bids`` in your work, please cite it with the zenodo DOI as:
 
 >The phys2bids contributors, Daniel Alcalá, Apoorva Ayyagari, Molly Bright, César Caballero-Gaudes, Vicente Ferrer Gallardo, Soichi Hayashi, Ross Markello, Stefano Moia, Rachael Stickland, Eneko Uruñuela, & Kristina Zvolanek (2020, February 6). physiopy/phys2bids: BIDS formatting of physiological recordings v1.3.0-beta (Version v1.3.0-beta). Zenodo. http://doi.org/10.5281/zenodo.3653153
 

docs/contributing.rst

@@ -9,28 +9,53 @@ First of all: thank you!
 Contributions can be made in different ways, not only code!
 As we follow the `all-contributors`_ specification, any contribution will be recognised accordingly.
 
-The first thing you might want to do, is having a look at the `contributor guide <contributorfile.html>`_ page as well as the `code of conduct <conduct.html>`_.
+The first thing you might want to do, is to have a look at the `contributor guide <contributorfile.html>`_ page as well as the `code of conduct <conduct.html>`_.
 
-The second thing is to install ``phys2bids`` as a developer.
-This will let you run the program with the latest modification, without requiring to re-install it every time.
+The second thing is to check you have ``git`` and ``pip`` installed in your system.
+
+The third thing is to install ``phys2bids`` as a developer.
+This will let you run the program with the latest modification, without requiring you to re-install it every time.
 
 .. _`all-contributors`: https://github.com/all-contributors/all-contributors
 
+.. note::
+    The following instructions are provided assuming that python 3 is **not** your default version of python.
+    If it is, you might need to use ``pip`` instead of ``pip3``, although some OSs do adopt ``pip3`` anyway.
+    If you want to check, type ``python --version`` in a terminal.
+
 
 Linux and mac developer installation
 ------------------------------------
 
-Be sure to have git installed, then open a terminal and use the command::
-``git clone https://github.com/physiopy/phys2bids.git``
+Be sure to have ``git`` and ``pip`` installed, then open a terminal and run::
+
+	git clone https://github.com/physiopy/phys2bids.git
+
+Basic installation
+^^^^^^^^^^^^^^^^^^
+
+If you use python frequently, or you are a python developer, chances are that all the necessary dependencies
+are already installed in your system.
+
+Move into the ``phys2bids`` folder and execute the command::
+
+	pip3 install -e .
+
+Full developer installation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Move in the ``phy2bids`` folder and execute the command::
-``pip3 install -e .``
+If it's your first experience as a python developer, or you just want to be sure that you have everything you need
+to collaborate with us, you can install ``phys2bids`` with all the other packages that we frequently use during development in one step!
 
-If python 3 is already your default, you might use instead::
-``pip install -e .``
+Move into the ``phys2bids`` folder and execute the command::
 
-User testing
-------------
+	pip3 install -e .[all]
 
-Coming soon.
+This will install:
 
+	- ``phys2bids`` as an editable package, which means that you can modify the program and run it without having to reinstall it every time!
+	- All the ``phys2bids`` dependencies.
+	- All the **interface** modules, that deal with the interfaces for all the file formats.
+	- All the **style** modules, such as ``flake8``, to help you linter the code!
+	- All the **documentation** modules, like ``sphinx``, so that you can build the docs locally before submitting them.
+	- All the **test** modules, like ``pytest``, in order for you to test your code locally before committing it!

docs/heuristic.rst

@@ -10,7 +10,7 @@ Anatomy of a heuristic file
 ---------------------------
 
 Let's have a look under the hood of the heuristic files used in the `tutorial <howto.html>`_.
-It's the file ``heur_tutorial.py`` in ``phys2bids/phy2bids/heuristics/``:
+It's the file ``heur_tutorial.py`` in ``phys2bids/phys2bids/heuristics/``:
 
 .. _heuristicfile:
 

docs/howto.rst

@@ -17,7 +17,12 @@ Setup
 
 In order to follow the tutorial, you need a very quick setup: download or clone the `github repository <https://github.com/physiopy/phys2bids>`_ and install either the latest stable or development release as described `here <installation.html#install-with-pip>`_.
 
-**Note**: for the tutorial, we will assume the repository was downloaded in ``/home/arthurdent/git``. Let's get there right now:
+.. warning::
+    Before starting to use ``phys2bids``, check that you have installed all the extra modules that you need, depending on the files you will work with.
+
+    For instance, if you are planning to process AcqKnowledge files, install the interface dependencies as described `here <installation.html#>`_.
+
+For the tutorial, we will assume the repository was downloaded in ``/home/arthurdent/git``. Let's get there right now:
 
 .. code-block:: shell
 
@@ -32,7 +37,8 @@ The file can be found in ``phys2bids/phys2bids/tests/data/tutorial_file.txt``. T
    :linenos:
    :lines: 1-15
 
-**Note**: time is not a "real" channel recorded by LabChart or AcqKnowledge. For this reason, ``phys2bids`` treats it as a hidden channel, always in position 0. Channel 1 will be classed as the first channel recorded in either software.
+.. note::
+    time is not a "real" channel recorded by LabChart or AcqKnowledge. For this reason, ``phys2bids`` treats it as a hidden channel, always in position 0. Channel 1 will be classed as the first channel recorded in either software.
 
 Using the -info option
 ######################
@@ -53,7 +59,7 @@ However, we’ll use one more argument to have a sneak peak into the content of
 
     phys2bids -in tutorial_file.txt -info
 
-This ``-info`` argument means ``phy2bids`` does not process the file, but only outputs information it reads from the file, by printing to the terminal and outputting a png plot of the data in the current directory:
+This ``-info`` argument means ``phys2bids`` does not process the file, but only outputs information it reads from the file, by printing to the terminal and outputting a png plot of the data in the current directory:
 
 .. code-block:: shell
 
@@ -203,8 +209,8 @@ If for some reason ``-ntp`` and the number of timepoints found by ``phys2bids``
 3. The file doesn't have all the trigger pulses you expect because the recording started later than the MRI recording (e.g. by mistake).
 
 .. note::
-    ``phys2bids`` was created to deal with little sampling errors - such as distracted researchers that started sampling a bit too late than expected. For this reason, if it finds less trigger pulses than the amount specified, it will assume that the missing ones are at the beginning and anticipate the starting time consequently. 
-    
+    ``phys2bids`` was created to deal with little sampling errors - such as distracted researchers that started sampling a bit too late than expected. For this reason, if it finds less trigger pulses than the amount specified, it will assume that the missing ones are at the beginning and anticipate the starting time consequently.
+
 
 Let's go through an example where the number of timepoints automatically found is not correct. For that, will we use tutorial_file_v2.txt (in the same location as tutorial_file.txt):
 
@@ -251,7 +257,7 @@ There is one trigger that ``phys2bids`` couldn't find automatically. We can work
 
 By looking at this figure, we can work out that we need a smaller threshold in order to include the first time point. This can be implemented with the ``-thr`` argument:
 
-..  code-block:: shell
+.. code-block:: shell
 
     phys2bids -in tutorial_file_v2.txt -indir /home/arthurdent/git/phys2bids/phys2bids/tests/data/ -chtrig 1 -ntp 158 -tr 1.2 -thr 1.04 -outdir /home/arthurdent/physio_v2
 
@@ -296,7 +302,7 @@ As there might not be a link between the physiological file and the subject (and
 
 The output will look very similar to our previous calls, when we did not use the ``-heur``, ``-sub`` and ``-ses`` arguments. However, there is one extra line in command line output:
 
-..  code-block:: shell
+.. code-block:: shell
 
     INFO:phys2bids.phys2bids:Preparing BIDS output using /home/arthurdent/git/phys2bids/phys2bids/heuristics/heur_tutorial.py
 

docs/index.rst

@@ -39,7 +39,7 @@ Any suggestion/bug report is welcome! Feel free to open an issue.
 Citing ``phys2bids``
 --------------------
 
-If you use ``phy2bids``, please cite it using the Zenodo DOI as:
+If you use ``phys2bids``, please cite it using the Zenodo DOI as:
 
     The phys2bids contributors, Daniel Alcalá, Apoorva Ayyagari, Molly Bright, César Caballero-Gaudes, Vicente Ferrer Gallardo, Soichi Hayashi, Ross Markello, Stefano Moia, Rachael Stickland, Eneko Uruñuela, & Kristina Zvolanek (2020, February 6). physiopy/phys2bids: BIDS formatting of physiological recordings v1.3.0-beta (Version v1.3.0-beta). Zenodo. http://doi.org/10.5281/zenodo.3653153
 

docs/installation.rst

@@ -12,54 +12,80 @@ Requirements
 - ``numpy >= 1.9.3``
 - ``matplotlib >= 3.1.1``
 
-Depending on the processed files, it might require the **manual installation** of other modules.
+Depending on the processed files, it might require the **manual installation** of extra modules.
 At the moment, those modules are:
 
-- `bioread`_, for AcqKnowledge (``.acq``) files.
+- |bioread|_, for AcqKnowledge (``.acq``) files.
 
-.. _`bioread`: https://github.com/uwmadison-chm/bioread
+.. _bioread: https://github.com/uwmadison-chm/bioread
+
+.. |bioread| replace:: ``bioread``
 
 Linux and mac installation
 --------------------------
 
 Install with ``pip``
 ^^^^^^^^^^^^^^^^^^^^
 
-Pipy has the latest stable version of ``phys2bids`` as a package. Just run
-``pip3 install phys2bids`` or ``pip install phys2bids`` if your default python is python3.
+.. note::
+    The following instructions are provided assuming that python 3 is **not** your default version of python.
+    If it is, you might need to use ``pip`` instead of ``pip3``, although some OSs do adopt ``pip3`` anyway.
+    If you want to check, type ``python --version`` in a terminal.
+
+Install ``phys2bids`` alone
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pypi has the latest stable release of ``phys2bids`` as a package. Just run::
+
+    pip3 install phys2bids
 
 If you want the latest development version of the program, download the package from `github <https://github.com/physiopy/phys2bids>`_ and uncompress it.
 Alternatively, if you have ``git``, use the command::
 
     git clone https://github.com/physiopy/phys2bids.git
 
-Open a terminal in the ``phy2bids`` folder and execute the command::
+Open a terminal in the ``phys2bids`` folder and execute the command::
 
     pip3 install .
 
-If python 3 is already your default, you might use instead::
+Install extra modules
+~~~~~~~~~~~~~~~~~~~~~
+
+If you are planning to use file formats other than plain ``txt``, you need to install extra modules to have the right interface.
+Extra modules installation can be done with the syntax::
 
-    pip install .
+    pip3 install <package>[<extra>]
 
-If you need to install other libraries, you can call again ``pip``::
+Where ``<package>>`` is either ``phys2bids`` or ``.``, depending on whether you want to use ``pip`` or ``git`` for the installation, and ``<extra>`` is one of the following:
+
+    - ``acq``: if you plan to use native AcqKnowledge files (``.acq`` extension)
+    - ``interfaces``: for all the interfaces above.
+
+For instance, if you plan to install ``phys2bids`` and use all the interfaces, run::
+
+    pip3 install phys2bids[interfaces]
+
+.. note::
+    If you "missed" or skipped this trick when you installed ``phys2bids`` the first time, don't worry!
+    You can do it any time - this will update ``phys2bids`` and install all the extra modules you want. 
 
-    pip3 install bioread
 
 Install without ``pip``
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-Download the package from github and uncompress it.
-Alternatively, if you have ``git``, use the command::
+Download the latest package release from `github <https://github.com/physiopy/phys2bids>`_ and uncompress it.
+Alternatively, if you have ``git`` installed, use the command::
 
     git clone https://github.com/physiopy/phys2bids.git
 
-Open a terminal in the phy2bids folder and execute the command::
+Open a terminal in the ``phys2bids`` folder and execute the command::
 
     python3 setup.py
 
-If python 3 is already your default, you might use instead::
+You might still need to install extra dependencies listed at the beginning of the page.
 
-    python setup.py
+.. note::
+    If python 3 is already your default, you might use ``python`` rather than ``python3``
 
 Check your installation!
 ^^^^^^^^^^^^^^^^^^^^^^^^

phys2bids/phys2bids.py

@@ -170,7 +170,7 @@ def use_heuristic(heur_file, sub, ses, filename, outdir, record_label=''):
     if not bids_keys['task']:
         LGR.warning(f'The heuristic {heur_file} could not deal with'
                     f'{Path(filename).stem}')
-        raise KeyError(f'No "task" attribute found')
+        raise KeyError('No "task" attribute found')
 
     # Compose name by looping in the bids_keys dictionary
     # and adding nonempty keys
@@ -341,8 +341,8 @@ def phys2bids(filename, info=False, indir='.', outdir='.', heur_file=None,
     if heur_file and sub:
         LGR.info(f'Preparing BIDS output using {heur_file}')
     elif heur_file and not sub:
-        LGR.warning(f'While "-heur" was specified, option "-sub" was not.\n'
-                    f'Skipping BIDS formatting.')
+        LGR.warning('While "-heur" was specified, option "-sub" was not.\n'
+                    'Skipping BIDS formatting.')
 
     # Preparing output parameters: name and folder.
     for uniq_freq in uniq_freq_list:

phys2bids/physio_obj.py

@@ -339,7 +339,7 @@ def print_info(self, filename):
         for ch in range(1, self.ch_amount):
             info = info + (f'{ch:02d}. {self.ch_name[ch]};'
                            f' sampled at {self.freq[ch]} Hz\n')
-        info = info + f'------------------------------------------------\n'
+        info = info + '------------------------------------------------\n'
 
         LGR.info(info)
 

requirements.txt

@@ -1,3 +1,2 @@
-bioread>=1.0.4
 numpy>=1.9.3
 matplotlib>=3.1.1

setup.cfg

@@ -22,7 +22,6 @@ provides =
 [options]
 python_requires = >=3.6.1
 install_requires =
-    bioread >=1.0.4
     numpy >=1.9.3
     matplotlib >=3.1.1
 tests_require =
@@ -33,15 +32,22 @@ packages = find:
 include_package_data = True
 
 [options.extras_require]
+acq = 
+    bioread >=1.0.5
 doc =
     sphinx >=2.0
     sphinx-argparse
     sphinx_rtd_theme
 style =
     flake8 >=3.7
+    flake8-docstrings >=1.5
 test =
+    pytest >=5.3
     pytest-cov
+interfaces = 
+    %(acq)s
 all =
+    %(interfaces)s
     %(doc)s
     %(style)s
     %(test)s