pypet2bids package
Submodules
pypet2bids.ecat_cli module
Simple command line tool to extract header and pixel information from ecat files and convert ecat to nifti.
- 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
- 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.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
- class pypet2bids.dcm2niix4pet.Dcm2niix4PET(image_folder, destination_path=None, metadata_path=None, metadata_translation_script=None, additional_arguments=None, file_format='%p_%i_%t_%s', silent=False)
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_for_pet2bids_config()
- 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.check_json(path_to_json, items_to_check=None, silent=False, **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
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.dcm2niix4pet.check_meta_radio_inputs(kwargs: dict) dict
Executes very specific PET logic, author does not recall everything it does. :param kwargs: metadata key pair’s to examine :type kwargs: dict :return: fitted/massaged metadata corresponding to logic steps below, return type is an update on input kwargs :rtype: dict
- 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.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.dcm2niix4pet.main()
Executes cli() and uses Dcm2niix4PET class to convert a folder containing dicoms into nifti + json.
- Returns
None
- pypet2bids.dcm2niix4pet.update_json_with_dicom_value(path_to_json, missing_values, dicom_header, dicom2bids_json=None, **additional_arguments)
We go through all of 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.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.
- class pypet2bids.ecat.Ecat(ecat_file, nifti_file=None, decompress=True, collect_pixel_data=True)
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.
- 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
- 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()
.
- 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:
pyet2bids.read_ecat()
- class pypet2bids.helper_functions.CustomFormatter(fmt=None, datefmt=None, style='%', validate=True)
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 objet 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_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: Optional[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: Optional[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 – 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 :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
- 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.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.log()
- 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.set_dcm2niix_path(dc2niix_path: pathlib.Path)
Given a path (or a string it thinks might be a path), updates the config file to point to a dcm2niix.exe file. Used on windows via dcm2niix command line :param dc2niix_path: path to dcm2niix executable :type dc2niix_path: path :return: None :rtype: None
- 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: Optional[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. It’s 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
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.
- class pypet2bids.convert_pmod_to_blood.PmodToBlood(whole_blood_activity: pathlib.Path, parent_fraction: pathlib.Path = PosixPath('.'), plasma_activity: pathlib.Path = PosixPath('.'), output_path: Optional[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 :param show-examples: shows an example of how to run this module as well as the outputs :return: collected arguments :rtype: 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 – path to a metadata spreadsheet containing bids fields as columns
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. :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 :type kwargs: string or dict :return: dictionary of subject data extracted from each spreadsheet along with any additional kwargs supplied :rtype: dict
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