datman.scanid module

Manages name conventions and functions to ensure that IDs conform to them.

Note

While multiple ID conventions are supported (Datman, KCNI, BIDS) the datman convention is the ‘base’/default convention used. As a result all conventions get parsed into datman fields and return datman IDs when get_full_subjectid and other similar methods are called. The original ID in its native convention can always be retrieved from ‘orig_id’.

class datman.scanid.BIDSFile(subject, session, suffix, task=None, acq=None, ce=None, dir=None, rec=None, run=None, echo=None, mod=None)

Bases: object

class datman.scanid.DatmanIdentifier(identifier, settings=None)

Bases: datman.scanid.Identifier

Parses a datman-style ID into fields.

The datman convention is detailed here

get_xnat_experiment_id()

get_xnat_subject_id()

pha_pattern = re.compile('^(?P<id>(?P<study>[^_]+)_(?P<site>[^_]+)_(?P<subject>PHA_(?P<type>[A-Z]{3})(?P<num>[0-9]{4,6}))(?P<timepoint>)(?P<session>))$')

pha_re = '(?P<id>(?P<study>[^_]+)_(?P<site>[^_]+)_(?P<subject>PHA_(?P<type>[A-Z]{3})(?P<num>[0-9]{4,6}))(?P<timepoint>)(?P<session>))'

scan_pattern = re.compile('^(?P<id>(?P<study>[^_]+)_(?P<site>[^_]+)_(?P<subject>[^_]+)(?<!PHA)_(?P<timepoint>[^_]+)_(?!MR)(?!SE)(?P<session>[^_]+))$')

scan_re = '(?P<id>(?P<study>[^_]+)_(?P<site>[^_]+)_(?P<subject>[^_]+)(?<!PHA)_(?P<timepoint>[^_]+)_(?!MR)(?!SE)(?P<session>[^_]+))'

property session

class datman.scanid.Identifier

Bases: abc.ABC

get_bids_name()

get_full_subjectid()

get_full_subjectid_with_timepoint()

get_full_subjectid_with_timepoint_session()

abstract get_xnat_experiment_id()

abstract get_xnat_subject_id()

match(identifier)

class datman.scanid.KCNIIdentifier(identifier, settings=None)

Bases: datman.scanid.Identifier

Parses a KCNI style ID into datman-style fields.

The KCNI convention is detailed here.

get_xnat_experiment_id()

get_xnat_subject_id()

pha_pattern = re.compile('^(?P<id>(?P<study>[A-Z]{3}[0-9]{2})_(?P<site>[A-Z]{3})_(?P<pha_type>[A-Z]{3})PHA_(?P<subject>[0-9]{4,6})_(?P<modality>[A-Z]{2,4})(?P<timepoint>)(?P<session>))$')

pha_re = '(?P<id>(?P<study>[A-Z]{3}[0-9]{2})_(?P<site>[A-Z]{3})_(?P<pha_type>[A-Z]{3})PHA_(?P<subject>[0-9]{4,6})_(?P<modality>[A-Z]{2,4})(?P<timepoint>)(?P<session>))'

scan_pattern = re.compile('^(?P<id>(?P<study>[A-Z]{3}[0-9]{2})_(?P<site>[A-Z]{3})_(?P<subject>[A-Z0-9]{4,8})_(?P<timepoint>[0-9]{2})_SE(?P<session>[0-9]{2})_(?P<modality>[A-Z]{2,4}))$')

scan_re = '(?P<id>(?P<study>[A-Z]{3}[0-9]{2})_(?P<site>[A-Z]{3})_(?P<subject>[A-Z0-9]{4,8})_(?P<timepoint>[0-9]{2})_SE(?P<session>[0-9]{2})_(?P<modality>[A-Z]{2,4}))'

datman.scanid.get_field(match, field, settings=None)

Find the value of an ID field, allowing for user specified changes.

Parameters

• match (re.Match) – A match object created from a valid ID

• field (str) – An ID field name. This corresponds to the match groups of valid (supported) ID (e.g. study, site, subject)

• settings (dict, optional) – User settings to specify fields that should be modified and how to modify them. See the settings description in parse() for more info. Defaults to None.

Returns

The value of the field based on the re.Match groups and user

settings.

Return type

str

datman.scanid.get_kcni_identifier(identifier, settings=None)

Get a KCNIIdentifier from a valid string or an identifier.

Parameters

• identifier (string) – A string matching a supported naming convention.

• settings (dict, optional) – A settings dictionary matching the format described in parse(). Defaults to None.

Raises

ParseException – When an ID that doesnt match any supported convention is given or when a valid ID can’t be converted to KCNI format.

Returns

An instance of a KCNI identifier with any field

mappings applied.

Return type

KCNIIdentifier

datman.scanid.get_session_num(ident)

For those times when you always want a numeric session (including for phantoms who are technically always session ‘1’)

datman.scanid.get_subid(current_subid, settings=None)

datman.scanid.is_phantom(identifier)

datman.scanid.is_scanid(identifier)

datman.scanid.is_scanid_with_session(identifier)

datman.scanid.make_filename(ident, tag, series, description, ext=None)

datman.scanid.parse(identifier, settings=None)

Parse a subject ID matching a supported naming convention.

The ‘settings’ flag can be used to exclude any IDs that do not match the specified convention, or to translate certain ID fields to maintain consistency within a single naming convention.

Accepted keys include:

‘IdType’: Restricts parsing to one naming convention (e.g. ‘DATMAN’

or ‘KCNI’)

‘Study’: Allows the ‘study’ field of an ID to be mapped from another

convention’s study code to a datman study code.

‘Site’: Allows the ‘site’ field of an ID to be translated from another

convention’s site code to a datman site code.

Note

All ‘settings’ keys are case-sensitive.

Using the settings from the below example will cause parse to reject any IDs that are not KCNI format, will translate any valid IDs containing ‘DTI01’ to the study code ‘DTI’, and will translate any valid IDs containing the site ‘UTO’ to the site ‘UT1’.

settings = {
    'IdType': 'KCNI',
    'Study': {
        'DTI01': 'DTI'
    },
    'Site': {
        'UTO': 'UT2'
    }
}

Parameters

• identifier (str) – A string that might be a valid subject ID.

• settings (dict, optional) – A dictionary of settings to use when parsing the ID. Defaults to None.

Raises

ParseException – If identifier does not match any supported naming convention.

Returns

An instance of a subclass of Identifier for the

matched naming convention.

Return type

Identifer

datman.scanid.parse_bids_filename(path)

datman.scanid.parse_filename(path)

Parse a datman style file name.

Parameters

path (str) – A file name or full path to parse

Raises

ParseException – If the file name does not match the datman convention.

Returns

A tuple containing:

• ident (DatmanIdentifier): The parsed subject ID portion of

  the path.

• tag (str): The scan tag that identifies the acquisition.

• series (int): The series number.

• description (str): The series description. Should be

  identical to the SeriesDescription field of the dicom headers (aside from some mangling to non-alphanumeric characters).

Return type

(tuple)