pypet2bids

pypet2bids.ecat_cli module

Simple command line tool to extract header and pixel information from ecat files and convert ecat to nifti.

Authors: Anthony Galassi
Copyright OpenNeuroPET team
pypet2bids.ecat_cli.cli()

Builds an argparse.ArgumentParser() object to access the methods available in the Ecat class in pypet2bids.ecat.ECAT

Parameters

  • ecat (path) – original ecat image to inspect or convert

  • --affine – display the affine matrix of the ecat

  • --convert (flag) – fattempt to convert the ecat file into a nifti defaults to False if flag isn’t present

  • --dump (flag) – dump the main header of the ecat file

  • --json (flag) – output the entire header, subheaders, and affine matrix to stdout as jsan

  • --nifti (path) – Name of the output nifti file

  • --subheader (flag) – display just the subheaders to the stdout

  • --sidecar (flag) – output a bids formatted sidecar with the nifti, defalts to True

  • --kwargs (strings, nargs) – include additional key/pair arguments to append to a sidecar file post conversion to nifti

  • --scannerparams – a parameter.txt file to extract scanner specific kwargs/args/BIDS fields from; constant per scanner

  • --directory_table – collect directory table from ECAT, useful for poking around the ecat file bytewise by frame

  • --show-examples (flag) – shows verbose example usage of this cli

  • --metadata-path (path) – path to a spreadsheet containing PET metadata

Returns

argparse.ArgumentParser.args for later use in executing conversions or ECAT methods

pypet2bids.ecat_cli.main()

Executes cli() and then uses Ecat class to convert or extract information from an Ecat file

Returns

N/A

pypet2bids.ecat_cli.update_json_with_ecat_value_cli()

Updates a json sidecar with values extracted from an ecat file, optionally additional values can be included via the -k –additional-arguments flag and/or a metadata spreadsheet can be supplied via the –metadata-path flag. Command can be accessed after installation via upadatepetjsonfromecat

pypet2bids.dcm2niix4pet module

This module acts as a simple wrapper around dcm2niix, it takes all of the same arguments as dcm2niix but does a little bit of extra work to conform the output nifti and json from dcm2niix to the PET BIDS specification. Additionally, but optionally, this module can collect blood or physiological data/metadata from spreadsheet files if the path of that spreadsheet file as well as a python module/script written to interpret it are provided in addition to relevant dcm2niix commands.

For more details see the CLI portion of this module or the documentation for the main class Dcm2niix4PET

Authors: Anthony Galassi
Copyright OpenNeuroPET team
class pypet2bids.dcm2niix4pet.Dcm2niix4PET(image_folder, destination_path=None, metadata_path=None, metadata_translation_script=None, additional_arguments={}, file_format='%p_%i_%t_%s', silent=False, tempdir_location=None)

Bases: object

check_for_dcm2niix()

Just checks for dcm2niix using the system shell, returns 0 if dcm2niix is present.

Returns

status code of the command dcm2niix -h

static check_posix()
convert()
extract_dicom_headers(depth=1)

Opening up files till a dicom is located, then extracting any header information to be used during and after the conversion process. This includes patient/subject id, as well any additional frame or metadata that’s required for conversion.

Parameters

depth – the number of dicoms to collect per folder, defaults to 1 as it assumes a single sessions worth of dicoms is included per folder.

Returns

dicom header information to self.subject_id and/or self.dicom_header_data

extract_metadata()

Opens up a metadata file and reads it into a pandas dataframe :return: a pd dataframe object

load_spread_sheet_data()
match_dicom_header_to_file(destination_path=None)

Matches a dicom header to a nifti or json file produced by dcm2niix, this is run after dcm2niix converts the input dicoms into nifti’s and json’s.

Parameters

destination_path – the path dcm2niix generated files are placed at, collected during class instantiation

Returns

a dictionary of headers matched to nifti and json file names

open_meta_data(extension)

Opens a text metadata file with the pandas method most appropriate for doing so based on the metadata file’s extension. :param extension: The extension of the file :return: a pandas dataframe representation of the spreadsheet/metadatafile

post_dcm2niix()
run_dcm2niix()

This runs dcm2niix and uses the other methods within this class to supplement the sidecar json’s produced as dcm2niix output.

Returns

the path to the output of dcm2niix and the modified sidecar jsons

pypet2bids.dcm2niix4pet.cli()

Collects arguments used to initiate a Dcm2niix4PET class, collects the following arguments from the user.

Parameters

  • folder – folder containing imaging data, no flag required

  • --metadata-path (-m,) – path to PET metadata spreadsheet

  • --translation-script-path (-t,) – path to script used to extract information from metadata spreadsheet

  • --destination-path (-d,) – path to place outputfiles post conversion from dicom to nifti + json

Returns

arguments collected from argument parser

pypet2bids.dcm2niix4pet.collect_date_time_from_file_name(file_name)

Collects the date and time from a nifti or a json produced by dcm2niix when dcm2niix is run with the options %p_%i_%t_%s. This datetime us used to match a dicom header object to the resultant file. E.G. if there are missing BIDS fields in the json produced by dcm2niix it’s hopeful that the dicom header may contain the missing info. :param file_name: name of the file to extract the date time info from, this should be a json ouput file from dcm2niix :return: a date and time object

pypet2bids.dcm2niix4pet.dicom_datetime_to_dcm2niix_time(dicom=None, date='', time='')

Dcm2niix provides the option of outputing the scan data and time into the .nii and .json filename at the time of conversion if ‘%t’ is provided following the ‘-f’ flag. The result is the addition of a date time string of the format. This function similarly generates the same datetime string from a dicom header.

Parameters

  • dicom – pydicom.dataset.FileDataset object or a path to a dicom

  • date – a given date, used in conjunction with time to supply a date time

  • time – a given time, used in conjunction with date

Returns

a datetime string that corresponds to the converted filenames from dcm2niix when used with the -f %t flag

pypet2bids.dcm2niix4pet.main()

Executes cli() and uses Dcm2niix4PET class to convert a folder containing dicoms into nifti + json.

Returns

None

pypet2bids.ecat module

This module contains the Ecat class which uses collections of other functions in this library to read native ECAT files and write them out to Nifti files.

Anthony Galassi
Copyright Open NeuroPET team
class pypet2bids.ecat.Ecat(ecat_file, nifti_file=None, decompress=True, collect_pixel_data=True, metadata_path=None, kwargs={})

Bases: object

This class reads an ecat file -> extracts header, subheader, and image matrices for viewing in stdout. Additionally, this class can be used to convert an ECAT7.X image into a nifti image.

convert()

Convert ecat to nifti :return: None

extract_affine()

Extract affine matrix from ecat

json_out()

Dumps entire ecat header and header info into stdout formatted as json.

Returns

None

make_nifti(output_path=None)

Outputs a nifti from the read in ECAT file. :param output_path: Optional path to output file to, if not supplied saves nifti in same directory as ECAT :param output_path: Optional path to output file to, if not supplied saves nifti in same directory as ECAT :type output_path: :return: the output path the nifti was written to, used later for placing metadata/sidecar files :rtype:

populate_sidecar(**kwargs)

Creates a side-car dictionary with any bids relevant information extracted from the ecat.

Parameters

kwargs – Populates sidecar file with relevant PET information, additional information that is not in the ECAT file can be supplied as a dictionary argument via kwargs.

Returns

None

prune_sidecar()

Eliminate unpopulated fields in sidecar while leaving in mandatory fields even if they are unpopulated.

Returns

a list of removed fields from the sidecar file

show_affine()

Display affine to stdout :return: affine matrix row by row.

show_directory_table()

Prints the directory table for the ECAT file to stdout.

Returns

None

show_header()

Display header to stdout in key: value format.

Returns

None

show_sidecar(output_path=None)

Write sidecar file to a json or display to stdout if no filepath is supplied :param output_path: path to output a json file :return: None

show_subheaders()

Displays subheaders to stdout.

Returns

None

update_pet_json(pet_json_path)

given a json file (or a path ending in .json) update or create a PET json file with information collected from an ecat file. :param pet_json: a path to a json file :type pet_json: str or pathlib.Path :return: None

write_out_blood_files(new_file_name_with_entities=None, destination_folder=None)
pypet2bids.ecat.parse_this_date(date_like_object) → str

Uses the dateutil.parser module to extract a date from a variety of differently formatted date strings

Parameters

date_like_object – something that resembles a timestamp or a date time, could be integer, float, or string.

Returns

an hour minute second datetime string.

pypet2bids.ecat2nii module

Contains class ecat2ii, used to write ecat information out to a nifti file, depends on nibabel and pypet2bids.read_ecat.read_ecat().

Authors: Anthony Galassi
Copyright OpenNeuroPET team
pypet2bids.ecat2nii.ecat2nii(ecat_main_header=None, ecat_subheaders=None, ecat_pixel_data=None, ecat_file=None, nifti_file: str = '', sif_out=False, affine=None, save_binary=False, **kwargs)

Converts an ECAT file into a nifti and a sidecar json, used in conjunction with pypet2bids.read_ecat.read_ecat()

Parameters

  • ecat_main_header – the main header of an ECAT file

  • ecat_subheaders – the subheaders for each frame of the ECAT file

  • ecat_pixel_data – the imaging/pixel data from the ECAT file

  • ecat_file – the path to the ECAT file, required and used to create .nii and .json output files

  • nifti_file – the desired output path of the nifti file

  • sif_out – outputs a .sif file containing the images pixel data

  • affine – a user supplied affine, this is gathered from the ECAT if not supplied.

  • save_binary – dumps a pickled ECAT object, you probably shouldn’t be using this.

  • kwargs – additional key value pairs that one wishes to add to the sidecar json accompanying a converted ECAT nii image

Returns

a nibabel nifti object if one wishes to muddle with the object in python and not in a .nii file

pypet2bids.helper_functions module

This module contains a collection of general functions used across this library, that is to say if a method ends up here it is because it is useful in more than one context.

Some of the modules in this library that depend on this module are:

Authors: Anthony Galassi
Copyright OpenNeuroPET team
class pypet2bids.helper_functions.CustomFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

Bases: logging.Formatter

Custom debugger courtesy of Sergey Pleshakov on stack overflow see https://stackoverflow.com/a/56944256

FORMATS = {10: '\x1b[38;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 20: '\x1b[38;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 30: '\x1b[33;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 40: '\x1b[31;20m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m', 50: '\x1b[31;1m%(asctime)s - %(name)s - %(levelname)s - %(message)s (%(filename)s:%(lineno)d)\x1b[0m'}
bold_red = '\x1b[31;1m'
format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

grey = '\x1b[38;20m'
red = '\x1b[31;20m'
reset = '\x1b[0m'
yellow = '\x1b[33;20m'
class pypet2bids.helper_functions.ParseKwargs(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)

Bases: argparse.Action

Class that is used to extract key pair arguments passed to an argparse.ArgumentParser object via the command line. Accepts key value pairs in the form of ‘key=value’ and then passes these arguments onto the arg parser as kwargs. This class is used during the construction of the ArgumentParser class via the add_argument method. e.g.:

ArgumentParser.add_argument(’–kwargs’, ‘-k’, nargs=’*’, action=helper_functions.ParseKwargs, default={})

pypet2bids.helper_functions.ad_hoc_checks(metadata: dict, modify_input=False, items_that_should_be_checked=None)

Check to run on PET BIDS metadata to evaluate whether input is acceptable or not, this function will most likely be refactored to use the schema instead of relying on hardcoded checks as listed in items_that_should_be_checked :param metadata: :type metadata: :param modify_input: :type modify_input: :param items_that_should_be_checked: items to check, hardcoded at the moment, but can accept a dict as input :type items_that_should_be_checked: dict :return: :rtype:

pypet2bids.helper_functions.check_pet2bids_config(variable: str = 'DCM2NIIX_PATH')

Checks the config file at users home /.pet2bidsconfig for the variable passed in, defaults to checking for DCM2NIIX_PATH. However, we can use it for anything we like, including setting paths to other useful files or “pet2bids” specific variables we’d like to access globally, or set as unchanging defaults.

Parameters

variable (string) – a string variable name to check for in the config file

Returns

the value of the variable if it exists in the config file

Return type

str

pypet2bids.helper_functions.check_units(entity_key: str, entity_value: str, accepted_units: Union[list, str])

Given an entity’s name, value, and an accepted range of values (accepted units), check whether those units are valid/in accepted units. Raises warning and returns False if units in entity value don’t intersect with any entry in accepted_units

Parameters

  • entity_key (str) – key/name of the entity

  • entity_value (str) – units value; some sort of SI unit(s) see (GBq, g, etc)

  • accepted_units (str or list) – a range of accepted units for the BIDS entity

Returns

Whether the units in entity value ar allowed or not

Return type

bool

pypet2bids.helper_functions.collect_bids_part(bids_part: str, path_like: Union[str, pathlib.Path]) → str

Regex is hard, this finds a bids key if it’s present in path or pathlink string

>>> bids_like_path = '/home/users/user/bids_data/sub-NDAR123/ses-firstsession'
>>> subject_id = collect_bids_part('sub', bids_like_path)
>>> subject_id
>>> "sub-NDAR123"
Parameters

  • bids_part (string) – the bids part to find in the path e.g. subject id, session id, recording, etc etc

  • path_like (string or pathlib.Path object, we don't descriminate) – a pathlike input, this is strictly for parsing file paths or file like strings

Returns

the collected bids part

Return type

string

pypet2bids.helper_functions.collect_spreadsheets(folder_path: pathlib.Path)
pypet2bids.helper_functions.compress(file_like_object, output_path: str = None)

Compresses a file using gzip.

Parameters

  • file_like_object – a file path to an uncompressed file

  • output_path – an output path to compress the file to, if omitted simply appends .gz to file_like_object path

Returns

output_path on successful completion of compression

pypet2bids.helper_functions.decompress(file_like_object, output_path: str = None)

Decompresses a gzip file.

Parameters

  • file_like_object – a compressed gzip file

  • output_path – optional output path, if not supplied this function simply trims ‘.gz’ off of the input file and writes to that amended path

Returns

output_path on successful decompression

pypet2bids.helper_functions.drop_row(dataframe: pandas.core.frame.DataFrame, index: int)
pypet2bids.helper_functions.expand_path(path_like: str) → str

Expands relative ~ paths to full paths

Parameters

path_like (string) – path like string

Returns

full path string

Return type

string

pypet2bids.helper_functions.flatten_series(series)

This function retrieves either a list or a single value from a pandas series object thus converting a complex data type to a simple datatype or list of simple types. If the length of the series is one or less this returns that single value, else this object returns all values within the series that are not Null/nan in the form of a list :param series: input series of type pandas.Series object, typically extracted as a column/row from a pandas.Dataframe object :return: a simplified single value or list of values

pypet2bids.helper_functions.get_coordinates_containing(containing: Union[str, int, float], dataframe: pandas.core.frame.DataFrame, exact: bool = False, single=False) → Union[list, tuple]

Collects the co-ordinates (row and column) containing an input value, that value could be a string, integer, or float. When searching for integers or floats it is most likely best to use set the exact argument to True; the same goes for finding the exact match of a string. This method is primarily meant to find the row corresponding to a subject ID, e.g.

if your dataframe is given as

subject_id some_values more_values sub-NDAR1 1 2 sub-NDAR2 3 3

And you provided the arguments: containing=’sub-NDAR’, exact=False you would return a set of the following co-ordinates

[(0, ‘subject_id’), (1, ‘subject_id’)]

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)
>>> coordinates
>>> (0, 1)
Parameters

  • containing (string, integer, or float) – value you wish to search a dataframe for

  • dataframe (pandas.datafarame) – A pandas dataframe read in from a spreadsheet

  • exact (bool) – Boolean proscribing an exact match to containing; default is to locate a string or value that holds the input containing

  • single (bool) – 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

Returns

A co-ordinate in the form of (row, column) or a list containing a set of co-ordinates [(row, column), …]

Return type

tuple or list of tuples

pypet2bids.helper_functions.get_recon_method(ReconstructionMethodString: str) → dict

Given the reconstruction method from a dicom header this function does its best to determine the name of the reconstruction, the number of iterations used in the reconstruction, and the number of subsets in the reconstruction.

Parameters

ReconstructionMethodString –

Returns

dictionary containing PET BIDS fields ReconMethodName, ReconMethodParameterUnits, ReconMethodParameterLabels, and ReconMethodParameterValues

pypet2bids.helper_functions.get_version()

Gets the version of this software from the toml file :return: version number from pyproject.toml

pypet2bids.helper_functions.hash_fields(**fields)
pypet2bids.helper_functions.import_and_write_out_module(module: str, destination: str)

Writes an imported module file to a destination :param module: an imported python module :param destination: the destination to write the source/script of the module to file

Returns

the destination path of the copied module file if successful

pypet2bids.helper_functions.is_numeric(check_this_object: str) → bool
pypet2bids.helper_functions.load_pet_bids_requirements_json(pet_bids_req_json: Union[str, pathlib.Path] = '/home/docs/checkouts/readthedocs.org/user_builds/pet2bids/checkouts/latest/pypet2bids/pypet2bids/metadata/PET_metadata.json') → dict
pypet2bids.helper_functions.load_vars_from_config(path_to_config: str)

Loads values from a .env file given a path to said .env file.

Parameters

path_to_config – path to .env file

Returns

a dictionary containing the values stored in .env

pypet2bids.helper_functions.logger(name)
pypet2bids.helper_functions.modify_config_file(var: str, value: Union[pathlib.Path, str])

Given a variable name and a value updates the config file with those inputs. Namely used (on Windows, but not limited to) to point to a dcm2niix executable (dcm2niix.exe) file as we don’t assume dcm2niix is in the path. :param var: variable name :type var: str :param value: variable value, most often a path to another file :type value: Union[pathlib.Path, str] :return: None :rtype: None

pypet2bids.helper_functions.open_meta_data(metadata_path: Union[str, pathlib.Path], separator=None) → pandas.core.frame.DataFrame

Opens a text metadata file with the pandas method most appropriate for doing so based on the metadata file’s extension. :param metadata_path: Path or pathlike object/string to a spreadsheet file :type metadata_path: Path or str :param separator: Optional seperator argument, used to try and parse tricky spreadsheets. e.g. ‘,’ ‘ ‘, ‘ ‘ :type separator: str :return: a pandas dataframe representation of the spreadsheet/metadatafile

pypet2bids.helper_functions.replace_nones(dictionary)
pypet2bids.helper_functions.sanitize_bad_path(bad_path: Union[str, pathlib.Path]) → Union[str, pathlib.Path]
pypet2bids.helper_functions.single_spreadsheet_reader(path_to_spreadsheet: Union[str, pathlib.Path], pet2bids_metadata_json: Union[str, pathlib.Path] = '/home/docs/checkouts/readthedocs.org/user_builds/pet2bids/checkouts/latest/pypet2bids/pypet2bids/metadata/PET_metadata.json', dicom_metadata={}, **kwargs) → dict
pypet2bids.helper_functions.transform_row_to_dict(row: Union[int, str, pandas.core.series.Series], dataframe: pandas.core.frame.DataFrame = None) → dict

Parses a row of a dataframe (or a series from a dataframe) into a dictionary, special care is taken to transform array like data contained in a single cell to a list of numbers or strings. :param row: either the row index as an integer or a pandas.Series object :type row: int, pandas.Series :param dataframe: Provided if only an int is given to this method, will be queried at the row by the given integer :type dataframe: pandas.DataFrame :return: a dictionary corresponding a row from a (most likely multi-subject input sheet) spreadsheet :rtype: dict

pypet2bids.helper_functions.translate_metadata(metadata_path, metadata_translation_script_path, **kwargs)
pypet2bids.helper_functions.very_tolerant_literal_eval(value)

Evaluates a string or string like input into a python datatype. Provides a lazy way to extract True from ‘true’, None from ‘none’, [0] from ‘[0’], etc. etc. :param value: the value you wish to convert to a python type :type value: string like, could be anything that can be evaluated as valid python :return: the value converted into a python object :rtype: depends on what ast.literal_eval determines the object to be

pypet2bids.helper_functions.write_out_module(module: str = 'pypet2bids.metadata_spreadsheet_example_reader')

pypet2bids.read_ecat 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

  • subheaders

  • pixel data

The other functions primarily operate bitwise, so it’s best not to use them outside of this module, unless you are a glutton or twisted in that sort of way.

Authors

Anthony Galassi

Copyright

Open NeuroPET team

pypet2bids.read_ecat.collect_specific_bytes(bytes_object: bytes, start_position: int = 0, width: int = 0)

Collects specific bytes within a bytes object.

Parameters

  • bytes_object – an opened bytes object

  • start_position – the position to start to read at

  • width – how far to read from the start position

  • relative_to – position relative to 0 -> start of file/object, 1 -> current position of seek head, 2 -> end of file/object

Returns

the bytes starting at position

pypet2bids.read_ecat.filter_bytes(unfiltered: bytes, struct_fmt: str)

Cleans up byte strings and bytes types into python int, float, string, and list data types, additionally struct.unpack returns a tuple object even if only a single value is available, this function determines when to return a single value or a list of values based on the contents of the unfiltered object.

Parameters

  • unfiltered – a raw bytes type object

  • struct_fmt – the c struct type of the object

Returns

a cleaned python int, float, string, or list

pypet2bids.read_ecat.get_buffer_size(data_type: str, variable_name: str)

Determine the byte width of a variable as defined in the ecat_headers.json such that Fill(6) will return 6

Parameters

  • data_type –

  • variable_name –

Returns

the number of bytes to expand a buffer to

pypet2bids.read_ecat.get_directory_data(byte_block: bytes, ecat_file: str, return_raw: bool = False)

Collects the directory data within an ECAT file. The directory data refers to the 512 byte table that describes the byte location of each frame, subheader, number of frames, and additional directory tables within the file.

Parameters

  • byte_block – A block of file bytes to convert into a 2 dimensional numpy array.

  • ecat_file – the path to the ecat file

  • return_raw – return the directory tables as extracted, if left False this will return the directory tables combined into a single table. The single table is all that is needed in order to read information in from an ECAT.

Returns

Individual tables corresponding to up to 31 frames each or a combined directory table consisting of no more columns than than are number of frames in the image/PET scan.

pypet2bids.read_ecat.get_ecat_bytes(path_to_ecat: str)

Opens an ecat file and reads the entry file into memory to return a bytes object not terribly memory efficient for large or parallel reading of ecat files.

Parameters

path_to_ecat – path to an ecat file, however will literally open any file an read it in as bytes.

Returns

a bytes object

pypet2bids.read_ecat.get_header_data(header_data_map: dict, ecat_file: str = '', byte_offset: int = 0, clean=True)

ECAT header data is contained in json files translated from ECAT documentation provided via the Turku PET Inst. For machine and human readability the original Siemens PDF/Scanned ECAT file documentation has been rewritten into json to provide easy access to byte position, byte width, variable name, and byte data type. Json’s including this header information are sub-divided into ECAT versions with sub-dictionaries corresponding to each imaging type as mentioned in the original ECAT spec.

Parameters

  • header_data_map – schema for reading in header data, this is stored in dictionary that is read in from a json file.

  • ecat_file – path to an ecat file, file is opened and byte blocks containing header data are then extracted, read, and cleaned into python float, int, or list data types

  • byte_offset – off set from the head of the file to read from

  • clean – Whether to remove byte padding or not, if not provided strings will include padding w/ x bytes and lists/arrays of data will be returned as tuples instead of lists. Uncleaned data will be of format b’’.

Returns

a dictionary with variable names of header fields as keys and cleaned/uncleaned header fields as values

pypet2bids.read_ecat.read_bytes(path_to_bytes: str, byte_start: int, byte_stop: int = - 1)

Open a file at path to bytes and reads in the information byte by byte.

Parameters

  • path_to_bytes – Path to file to read

  • byte_start – Position to place the seek head at before reading bytes

  • byte_stop – Position to stop reading bytes at

Returns

the bytes located at the position sought when invoking this function.

pypet2bids.read_ecat.read_ecat(ecat_file: str, calibrated: bool = False, collect_pixel_data: bool = True)

Reads in an ecat file and collects the main header data, subheader data, and imagining data.

Parameters

  • ecat_file – path to an ecat file, does not handle compression currently

  • calibrated – if True, will scale the raw imaging data by the SCALE_FACTOR in the subheader and

  • collect_pixel_data – By default collects the entire ecat, can be passed false to only return headers CALIBRATION_FACTOR in the main header

Returns

main_header, a list of subheaders for each frame, the imagining data from the subheaders

pypet2bids.sidecar module

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. This is just two python dictionaries with keys and empty value pairs.

Parameters

  • sidecar_template_full: a dict containing every PET BIDS field

  • sidecar_template_short: a dict containing only required PET BIDS fields

Returns sidecar_template_full, sidecar_template_short

Anthony Galassi Copyright OpenNeuroPET team

pypet2bids.convert_pmod_to_blood module

This module converts PMOD blood files (extension .bld) into BIDS compliant tsv and json files. It contains a class PmodToBlood and a cli that uses that class to interface with the user. This module currently exists solely to convert PMOD blood files and is not incorporated within any of the other conversion tools in PET2BIDS.

The command line arguments are details below, for more information about how this module works see the documentation for PmodToBlood.

Authors: Anthony Galassi
Copyright: OpenNeuroPET team
class pypet2bids.convert_pmod_to_blood.PmodToBlood(whole_blood_activity: pathlib.Path, parent_fraction: pathlib.Path = PosixPath('.'), plasma_activity: pathlib.Path = PosixPath('.'), output_path: pathlib.Path = None, output_json: bool = False, engine='', **kwargs)

Bases: object

Converts PMOD blood files to PET BIDS compliant tsv’s and json _blood.* files

Parameters

  • whole_blood_activity (pathlib.Path) – path to a PMOD whole blood activity file

  • parent_fraction (pathlib.Path) – path to a PMOD metabolite parent blood file

  • output_path (pathlib.Path) – path to write output tsv and jsons to, defaults to parent folder of whole blood input file

  • output_json (bool) – boolean specifying whether to output a json sidecar for the blood files, default is false

  • engine (str) – soon to be deprecated, determines what engine is used in pandas.read_excel

  • kwargs (dict) – additional plasma/blood/radioactivity key/pair BIDS arguments, not required but if provided used during logic phase and written to sidecar json

ask_recording_type(recording: str)

Prompt user about data collection to determine how data was collected for each measure. e.g. auto-sampled, manually drawn, or a combination of the two.

Parameters

recording – the name of the recording

Type

str

Returns

None

Return type

None

check_for_interpolated_data()
check_fraction_is_fraction()
check_time_info()

Checks for time units, and time information between .bld files, number of rows and the values in the time index must be the same across each input .bld file. Additionally, renames time column to ‘time’ instead of what it’s defined as in the pmod file. Does some more checks and scaling of plasma data, de-duplication etc.

static load_pmod_file(pmod_blood_file: pathlib.Path, engine='')

Loads a pmod .bld blood file in with pandas.

Parameters

  • pmod_blood_file (pathlib.Path) – path to pmod blood file

  • engine (str) – python engine used to read excel sheet with pandas.read_excel,

Returns

contents of .bld file

Return type

pandas.DataFrame

scale_time_rename_columns()

Scales time info if it’s not in seconds and renames dataframe column to ‘time’ instead of given column name in .bld file. Renames radioactivity column to BIDS compliant column name if it’s in units Bq/cc or Bq/mL.

write_out_jsons()

Writes out sidecar json to correspond to _blood.tsv files

Returns

None

Return type

None

write_out_tsvs()

Writes out blood data to tsv files corresponding to autosampled or manually sampled versions (dependent on user input)

Returns

None

Return type

None

pypet2bids.convert_pmod_to_blood.cli()

Command line interface used to collect arguments for PmodToBlood class, note parameters defined below apply to the invocation at the command line not the method cli itself which takes no argument in Python.

Parameters

  • whole-blood-path – path to a PMOD .bld file containing the whole blood activity of a subject/run/scan

  • parent-fraction-path – path to a PMOD .bld file containing the parent fraction of a subject/run/scan

  • plasma-activity-path – path to a PMOD .bld file containing the plasma activity of a subject/run/scan

  • output-path – the desired output path for the converted tsv and json files, if the path contains BIDS subject id’s and session id’s these will be extracted from the path and inserted into the filenames of the resultant tsv and json files.

  • json – create a json sidecar/data-dictionary file along with output tsv’s, default is set to True

  • engine – engine used to read excel files, ignore this option as it will most likely be deprecated in the future

  • 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

  • show-examples – shows an example of how to run this module as well as the outputs

Returns

collected arguments

Return type

argparse.namespace

pypet2bids.convert_pmod_to_blood.main()

Executes the PmodToBlood class using argparse

Returns

None

pypet2bids.convert_pmod_to_blood.type_cast_cli_input(kwarg_arg)

This method sanitizes collects inputs from the cli and casts them as native python data types.

Parameters

kwarg_arg (str) – a kwarg argument parsed from the command line, literal string

Returns

kwarg argument evaluated to python datatype

Return type

dict, list, str, int, float, bool

pypet2bids.multiple_spreadsheets module

pypet2bids.multiple_spreadsheets.cli()

Instantiates a command line interface with which allows reading and writing of 2 spreadsheets following the format specified in PET2BIDS/spreadsheet_conversion/many_subjects_sheet :return: a dictionary version of the subject sidecar json’s that get written out :rtype: dict

pypet2bids.multiple_spreadsheets.read_multi_subject_spreadsheets(general_metadata_spreadsheet: pathlib.Path, multiple_subject_spreadsheet: pathlib.Path, **kwargs) → dict

Reads in two spreadsheets as formatted in PET2BIDS/spreadsheet_conversion/many_subject_sheets, generic (scanner or subject independent data is supplied via the first argument and subject specific data is supplied via the second argument.

Parameters

  • general_metadata_spreadsheet (file path) – path to a metadata spreadsheet containing bids fields as columns with values below

  • multiple_subject_spreadsheet (file path) – path to multi subject spreadsheet containing a subject id, participant id, subject, or participant column consisting of paths to subject folders/files.

  • kwargs (string or dict) – additional key pair arguments to pass on, these get applied generally just like the first spreadsheet. e.g. TimeZero=12:12:12, SpecificRadioactivity=3

Returns

dictionary of subject data extracted from each spreadsheet along with any additional kwargs supplied

Return type

dict

Anthony Galassi Copyright Open NeuroPET team

pypet2bids.multiple_spreadsheets.write_multi_subject_spreadsheets(subjects: dict, output_path: Union[str, pathlib.Path], create_bids_tree: bool = False) → None

Writes out a dictionary of subjects to a series of json files, if files exist updates them with new values obtained from spreadsheets.

Parameters

  • subjects (dict) – subject dictionary with subject id as primary keys and all bids fields as values

  • output_path (str or pathlib.Path object) – path to write out files to, very much required

  • create_bids_tree (bool) – boolean flag to create a bids tree, function will do it’s best to create subject folders and session folders along w/ pet modality folder if this option is specified. Works on existing bids trees so long as session and subject id can be parsed from multi subject input sheet.

Returns

None

Return type

None

pypet2bids.update_pet_json module

pypet2bids.update_json_pet_file.check_json(path_to_json, items_to_check=None, silent=False, spreadsheet_metadata={}, mandatory=True, recommended=True, logger_name='pypet2bids', **additional_arguments)

This method opens a json and checks to see if a set of mandatory values is present within that json, optionally it also checks for recommended key value pairs. If fields are not present a warning is raised to the user.

Parameters

  • spreadsheet_metadata –

  • path_to_json – path to a json file e.g. a BIDS sidecar file created after running dcm2niix

  • items_to_check – a dictionary with items to check for within that json. If None is supplied defaults to the PET_metadata.json contained in this repository

  • silent – Raises warnings or errors to stdout if this flag is set to True

Returns

dictionary of items existence and value state, if key is True/False there exists/(does not exist) a corresponding entry in the json the same can be said of value

pypet2bids.update_json_pet_file.check_meta_radio_inputs(kwargs: dict, logger='pypet2bids') → dict

Routine to check input consistency, possibly generate new ones from PET BIDS metadata - this only makes sense if you respect the input units as indicated

e.g. arguments in are provided via the following params (key/value pairs)

  • ‘InjectedRadioctivity’,81.24

  • ‘SpecificRadioactivity’,1.3019e+04

Units are transformed as follows:

InjectedRadioactivity: in MBq InjectedMass: in ug SpecificRadioactivity: in Bq/g or MBq/ug MolarActivity: in GBq/umol MolecularWeight: in g/mol

Parameters

kwargs (dict) – metadata key pair’s to examine

Returns

fitted/massaged metadata, return type is an update on input kwargs

Return type

dict

pypet2bids.update_json_pet_file.get_metadata_from_spreadsheet(metadata_path: Union[str, pathlib.Path], image_folder, image_header_dict={}, **additional_arguments) → dict

Extracts metadata from a spreadsheet and returns a dictionary of metadata organized under three main keys: nifti_json, blood_json, and blood_tsv

Parameters

  • metadata_path ([str, pathlib.Path]) – path to a spreadsheet

  • image_folder ([str, pathlib.Path]) – path to image folder

  • image_header_dict (dict) – dictionary of image header values

  • additional_arguments (dict) – additional arguments to pass on, typically user sourced key value pairs

Returns

dictionary of metadata

Return type

dict

pypet2bids.update_json_pet_file.get_radionuclide(pydicom_dicom)

Gets the radionuclide if given a pydicom_object if pydicom_object.RadiopharmaceuticalInformationSequence[0].RadionuclideCodeSequence exists

Parameters

pydicom_dicom – dicom object collected by pydicom.dcmread(“dicom_file.img”)

Returns

Labeled Radionuclide e.g. 11Carbon, 18Flourine

pypet2bids.update_json_pet_file.update_json_cli()

Updates a json file with user supplied values or values from a spreadsheet. This command can be accessed after conversion via updatepetjson if so required.

pypet2bids.update_json_pet_file.update_json_with_dicom_value(path_to_json, missing_values, dicom_header, dicom2bids_json=None, silent=True, **additional_arguments)

We go through all the missing values or keys that we find in the sidecar json and attempt to extract those missing entities from the dicom source. This function relies on many heuristics a.k.a. many unique conditionals and simply is what it is, hate the game not the player.

Parameters

  • path_to_json – path to the sidecar json to check

  • missing_values – dictionary output from check_json indicating missing fields and/or values

  • dicom_header – the dicom or dicoms that may contain information not picked up by dcm2niix

  • dicom2bids_json – a json file that maps dicom header entities to their corresponding BIDS entities

Returns

a dictionary of sucessfully updated (written to the json file) fields and values

pypet2bids.update_json_pet_file.update_json_with_dicom_value_cli()

Command line interface for update_json_with_dicom_value, updates a PET json with values from a dicom header, optionally can update with values from a spreadsheet or via values passed in as additional arguments with the -k –additional_arguments flag. This command be accessed after installation of pypet2bids via updatepetjsonfromdicom.

Module contents