diff --git a/README.md b/README.md index d9a6ffa7..09a9d58e 100644 --- a/README.md +++ b/README.md @@ -34,19 +34,74 @@ Simply download the repository - follow the specific Matlab or Python explanatio ### pypet2bids -Use pip: +Use pip to install this library directly from PyPI: [![asciicast](https://asciinema.org/a/TZJg5BglDMFM2fEEX9dSpnJEy.svg)](https://asciinema.org/a/TZJg5BglDMFM2fEEX9dSpnJEy) -For advance users clone this repository and run from the python source under the `PET2BIDS/pypet2bids` folder. If you -wish to build and install via pip locally we recommend you do so using [poetry](https://python-poetry.org/) build or -using the make commands below. +If you wish to install directly from this repository see the instructions below to either build +a packaged version of `pypet2bids` or how to run the code from source. + +
+Build Package Locally and Install with PIP + +We use [poetry](https://python-poetry.org/) to build this package, no other build methods are supported, +further we encourage the use of [GNU make](https://www.gnu.org/software/make/) and a bash-like shell to simplify the +build process. + +After installing poetry, you can build and install this package to your local version of Python with the following +commands (keep in mind the commands below are executed in a bash-like shell): + +```bash +cd PET2BIDS +cp -R metadata/ pypet2bids/pypet2bids/metadata +cp pypet2bids/pyproject.toml pypet2bids/pypet2bids/pyproject.toml +cd pypet2bids && poetry lock && poetry build +pip install dist/pypet2bids-X.X.X-py3-none-any.whl +``` + +Why is all the above required? Well, because this is a monorepo and we just have to work around that sometimes. + + +[!NOTE] +Make and the additional scripts contained in the `scripts/` directory are for the convenience of +non-windows users. + +If you have GNU make installed and are using a bash or something bash-like in you your terminal of choice, run the +following: ```bash cd PET2BIDS make installpoetry buildpackage installpackage ``` +
+ +
+Run Directly From Source + +Lastly, if one wishes run pypet2bids directly from the source code in this repository or to help contribute to the python portion of this project or any of the documentation they can do so via the following options: + +```bash +cd PET2BIDS/pypet2bids +poetry install +``` + +Or they can install the dependencies only using pip: + +```bash +cd PET2BIDS/pypet2bids +pip install . +``` + +After either poetry or pip installation of dependencies modules can be executed as follows: + +```bash +cd PET2BIDS/pypet2bids +python dcm2niix4pet.py --help +``` + +
+ **Note:** *We recommend using dcm2niix v1.0.20220720 or newer; we rely on metadata included in these later releases. It's best to collect releases from the [rorden lab/dcm2niix/releases](https://github.com/rordenlab/dcm2niix/releases) page. We have diff --git a/docs/installation.rst b/docs/installation.rst index 0e3a4e50..21e96932 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,4 +1,4 @@ -.. _installation +.. _installation: Installation ============ @@ -6,7 +6,8 @@ Installation Matlab ------ -In short, add the contents of the `matlab` folder to your matlab path with `addpath`: +Clone the repo at https://github.com/openneuropet/PET2BIDS.git and the contents of the `matlab` folder to your matlab +path with `addpath`: .. code-block:: @@ -23,7 +24,7 @@ Python ------ The python version of PET2BIDS (from herein referenced by it's library name *pypet2bids*) can be installed -via pip for Python versions >3.7.1,<3.10 +via pip for Python versions >3.7.1,=<3.11 .. code-block:: @@ -35,6 +36,9 @@ via pip for Python versions >3.7.1,<3.10 +If you wish to contribute, are unable to install from PyPi, or simply wish to run pypet2bids from source, continue +reading the `Additional Install Notes`_ section below. + Additional Install Notes ======================== @@ -75,13 +79,45 @@ all arguments in although this is also possible). You can find templates of such Python ------ -pypet2bids can be run from source by cloning the source code at our Github_. +If you are unable to install this library from PyPi you can clone this repository to build and install the package +as distributed on PyPi yourself with poetry. + +We use `poetry `_ to build this package, no other build methods are supported, +further we encourage the use of `GNU make `_ and a bash-like shell to simplify the +build process. + +After installing poetry, you can build and install this package to your local version of Python with the following +commands (keep in mind the commands below are executed in a bash-like shell): + +.. code-block:: + + cd PET2BIDS + cp -R metadata/ pypet2bids/pypet2bids/metadata + cp pypet2bids/pyproject.toml pypet2bids/pypet2bids/pyproject.toml + cd pypet2bids && poetry lock && poetry build + pip install dist/pypet2bids-X.X.X-py3-none-any.whl + +.. note:: + + Make and the additional scripts contained in the `scripts/` directory are for the convenience of + non-windows users. + +If you have GNU make installed and are using a bash or something bash-like in you your terminal of choice, run the +following: + +.. code-block:: + + cd PET2BIDS + make installpoetry buildpackage installpackage .. _Github: https://github.com/openneuropet/PET2BIDS + +pypet2bids can be run from source by cloning the source code at our Github_. + .. code-block:: - git clone git@github.com:openneuropet/PET2BIDS.git + git clone https://github.com/openneuropet/PET2BIDS and then installing it's dependencies via pip: @@ -90,13 +126,20 @@ and then installing it's dependencies via pip: cd PET2BIDS/pypet2bids pip install . -Or with `Poetry `_: +or installing them with `Poetry `_: .. code-block:: cd PET2BIDS/pypet2bids poetry install +After either poetry or pip installation of dependencies modules can be executed as follows: + +.. code-block:: + + cd PET2BIDS/pypet2bids + python dcm2niix4pet.py --help + **Windows Only** It's important that python be on your windows path; when installing Python be sure to select **Add Python 3.XXX** @@ -133,5 +176,3 @@ Or using the *dcm2niix4pet* tool itself to set up the configuration: .. code-block:: dcm2niix4pet --set-dcm2niix-path \path\to\dcm2niix.exe - ------------------------------------------------------------------------------------------------------------------------- diff --git a/docs/usage.rst b/docs/usage.rst index 3d86f434..b0260c90 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -10,7 +10,7 @@ Matlab BIDS requires nifti files and json. While json can be writen be hand, this is more convenient to populate them as one reads data. One issue is that some information is not encoded in ecat/dicom headers and thus needs to be created -overwise. +otherwise. diff --git a/pypet2bids/pypet2bids/convert_pmod_to_blood.py b/pypet2bids/pypet2bids/convert_pmod_to_blood.py index ecda62ed..82e6596b 100644 --- a/pypet2bids/pypet2bids/convert_pmod_to_blood.py +++ b/pypet2bids/pypet2bids/convert_pmod_to_blood.py @@ -9,6 +9,7 @@ | *Authors: Anthony Galassi* | *Copyright: OpenNeuroPET team* """ + import json import logging import textwrap @@ -110,10 +111,11 @@ def cli(): :param json: create a json sidecar/data-dictionary file along with output tsv's, default is set to True :param engine: engine used to read excel files, ignore this option as it will most likely be deprecated in the future :param kwargs: additional key pair arguments one wishes to include, such as extra entries for plasma or blood PET BIDS - fields that aren't in PMOD blood files + fields that aren't in PMOD blood files :param show-examples: shows an example of how to run this module as well as the outputs :return: collected arguments :rtype: argparse.namespace + """ parser = argparse.ArgumentParser(formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument( diff --git a/pypet2bids/pypet2bids/helper_functions.py b/pypet2bids/pypet2bids/helper_functions.py index 719d86aa..53bfd4a6 100644 --- a/pypet2bids/pypet2bids/helper_functions.py +++ b/pypet2bids/pypet2bids/helper_functions.py @@ -579,9 +579,9 @@ def get_coordinates_containing( If you are confident in your input data you would most likely call this method this way: >>> coordinates = get_coordinates_containing( - >>> 'sub-NDAR1', - >>> pandas.DataFrame({'subject_id': ['sub-NDAR1', 'sub-NDAR2'], 'some_values': [1, 2]}), - >>> single=True) + >>> 'sub-NDAR1', + >>> pandas.DataFrame({'subject_id': ['sub-NDAR1', 'sub-NDAR2'], 'some_values': [1, 2]}), + >>> single=True) >>> coordinates >>> (0, 1) @@ -589,14 +589,15 @@ def get_coordinates_containing( :type containing: string, integer, or float :param dataframe: A pandas dataframe read in from a spreadsheet :type dataframe: pandas.datafarame - :param exact: Boolean proscribing an exact match to containing; default is to locate a string or value that holds the - input containing + :param exact: Boolean proscribing an exact match to containing; default is to locate a string or value that holds + the input containing :type exact: bool :param single: return only the first co-ordinate, use only if the string/contains your searching for is unique and - you have high confidence in your data + you have high confidence in your data :type single: bool :return: A co-ordinate in the form of (row, column) or a list containing a set of co-ordinates [(row, column), ...] :rtype: tuple or list of tuples + """ percent_tolerance = 0.001 diff --git a/pypet2bids/pypet2bids/metadata_spreadsheet_example_reader.py b/pypet2bids/pypet2bids/metadata_spreadsheet_example_reader.py index d298c355..6d2e1f98 100644 --- a/pypet2bids/pypet2bids/metadata_spreadsheet_example_reader.py +++ b/pypet2bids/pypet2bids/metadata_spreadsheet_example_reader.py @@ -1,15 +1,9 @@ -import pandas -import warnings -import pathlib -from typing import Union from os.path import join -import json try: from helper_functions import * except ModuleNotFoundError: from pypet2bids.helper_functions import * -#from pypet2bids.helper_functions import open_meta_data, flatten_series parent_dir = pathlib.Path(__file__).parent.resolve() project_dir = parent_dir.parent @@ -18,7 +12,6 @@ permalink_pet_metadata_json = "https://github.com/openneuropet/PET2BIDS/blob/76d95cf65fa8a14f55a4405df3fdec705e2147cf/metadata/PET_metadata.json" """ -This function does? :format: :param: @@ -29,6 +22,7 @@ Copyright Open NeuroPET team """ + def translate_metadata(metadata_dataframe, image_path=NotImplemented): """ This method exists as an example/template for an individual to customize and use on their own PET metadata contained diff --git a/pypet2bids/pypet2bids/multiple_spreadsheets.py b/pypet2bids/pypet2bids/multiple_spreadsheets.py index 129198b7..47ba75a8 100644 --- a/pypet2bids/pypet2bids/multiple_spreadsheets.py +++ b/pypet2bids/pypet2bids/multiple_spreadsheets.py @@ -16,21 +16,21 @@ def read_multi_subject_spreadsheets( specific data is supplied via the second argument. :param general_metadata_spreadsheet: path to a metadata spreadsheet containing bids fields as columns - with values below + with values below :type general_metadata_spreadsheet: file path :param multiple_subject_spreadsheet: path to multi subject spreadsheet containing a subject id, participant id, - subject, or participant column consisting of paths to subject folders/files. + subject, or participant column consisting of paths to subject folders/files. :type multiple_subject_spreadsheet: file path :param kwargs: additional key pair arguments to pass on, these get applied generally - just like the first spreadsheet. e.g. TimeZero=12:12:12, SpecificRadioactivity=3 + just like the first spreadsheet. e.g. TimeZero=12:12:12, SpecificRadioactivity=3 :type kwargs: string or dict :return: dictionary of subject data extracted from each spreadsheet along with any additional - kwargs supplied + kwargs supplied :rtype: dict Anthony Galassi - ----------------------------- Copyright Open NeuroPET team + """ required_fields = load_pet_bids_requirements_json() diff --git a/pypet2bids/pypet2bids/read_ecat.py b/pypet2bids/pypet2bids/read_ecat.py index 42bdff1a..b40f8cb6 100644 --- a/pypet2bids/pypet2bids/read_ecat.py +++ b/pypet2bids/pypet2bids/read_ecat.py @@ -1,5 +1,5 @@ """ -This module contains methods used to read ecat files (*.v), the primary method pulled/imported from this module +This module contains methods used to read ecat files (\*.v), the primary method pulled/imported from this module is read_ecat which returns the contents of a singular ecat file divided into three parts: - main header @@ -11,6 +11,7 @@ :Authors: Anthony Galassi :Copyright: Open NeuroPET team + """ import json import os.path @@ -239,9 +240,10 @@ def read_ecat(ecat_file: str, calibrated: bool = False, collect_pixel_data: bool :param ecat_file: path to an ecat file, does not handle compression currently :param calibrated: if True, will scale the raw imaging data by the SCALE_FACTOR in the subheader and :param collect_pixel_data: By default collects the entire ecat, can be passed false to only return headers - CALIBRATION_FACTOR in the main header + CALIBRATION_FACTOR in the main header :return: main_header, a list of subheaders for each frame, the imagining data from the subheaders + """ if ".gz" in ecat_file: ecat_file = decompress(ecat_file) diff --git a/pypet2bids/pypet2bids/sidecar.py b/pypet2bids/pypet2bids/sidecar.py index bc5806e9..9a9ed263 100644 --- a/pypet2bids/pypet2bids/sidecar.py +++ b/pypet2bids/pypet2bids/sidecar.py @@ -1,14 +1,15 @@ """ This is a lazy way to avoid opening a json, simply import this file to collect your BIDS sidecar templates instead. This -is not a function or a `true` module. It's just two python dictionaries with keys and empty value pairs. +is not a function or a true module. This is just two python dictionaries with keys and empty value pairs. :param sidecar_template_full: a dictionary containing every field specified in the BIDS standard for PET imaging data :param sidecar_template_short: a dictionary containing only the required fields in the BIDS standard for PET imaging data :return: sidecar_template_full, sidecar_template_short -|*Anthony Galassi* -|*Copyright OpenNeuroPET team* +*Anthony Galassi* +*Copyright OpenNeuroPET team* + """ diff --git a/pypet2bids/pyproject.toml b/pypet2bids/pyproject.toml index 8d4c758e..5f4a4188 100644 --- a/pypet2bids/pyproject.toml +++ b/pypet2bids/pyproject.toml @@ -18,7 +18,6 @@ python-dateutil = "^2.8.2" python-dotenv = "^0.19.1" scipy = "^1.7.1" six = "^1.16.0" -pytest = ">=6.2.5, <8.0.0" pydicom = "^2.2.2" openpyxl = "^3.0.9" xlrd = "^2.0.1" @@ -31,6 +30,7 @@ toml = ">=0.10.2" [tool.poetry.dev-dependencies] +pytest = ">=6.2.5, <8.0.0" sphinx = "<=4.5.0" sphinx-rtd-theme = "^1.0.0" sphinxcontrib-matlabdomain = "^0.13.0"