Setting session label and renaming subjects

The plugin lets you set session label in a several ways. You can also modify subject labels. The popover under Subject & session rules button probably requires some explanation.

images/subject_session_rules.png

Regular expressions

To rename subjects and set session labels you will use regular expressions (sequences of characters which define a pattern). In most cases, they will be will be very simple, such as (pre|post) (one of the two words, either pre or post) or _([a-z]*)$ (a set of lowercase letters between an underscore and the end of a string). Should you require a more complex pattern, you can use the tables 1 - 3 in Apple documentation for reference.

Here are some examples of elements you may use to build regular expressions:

• ^ - the beginning of a string
• $ - the end of a string
• [A-D] - the set of letters between A and D
• [BDIS] - a set of letters: B, D, I, S
• a|b - letter a or b
• [a-z]* - letters from the set between a and z occurring zero or more times
• [a-z]+ - letters from the set between a and z occurring one or more times
• subject-01 - literally the string subject-01
• subject-[0-9]+ - the string subject- followed by one or more digits
• (...) - use brackets to create a capture group, which may be referenced later by using $1 (first capture group), $2 (second capture group) and so on.

Use cases

Default behaviour

If you don't use the Subject & sessions rules button, the subject name from DICOM file (with non-alphanumeric characters stripped) will be used as the subject label. The dataset will be created without sessions.

Renaming subjects without creating sessions.

If you simply wish to rename subjects, you can leave the Session label field empty and follow the instructions in the Defining patterns in subject names and using them section below.

Creating session labels from series names.

Instead of coding session using subject name, you might use sequence names for that purpose (while keeping subject name consistent across sessions). If that's the case, you should add ses_<session_label> to at least one sequence name. In this case you should tick the look for _ses-label in DICOM series names checkbox.

Doing so will make the plugin search all sequence names from a given DICOM-study until it finds a match for the _ses-([a-zA-Z0-9]*) pattern. This will assign the session label to the whole study (such behaviour is aimed to mimic heudiconv defaults). If the pattern can't be found, the session label is set to unknown.

One thing to note - using Scout sequence for this purpose might not work, as Horos (?) groups them under Localizers name (and technically the plugin checks the name of a DicomDeries Horos object rather than the ProtocolName DICOM field).

You may still rename subjects - see the description and examples below.

Creating a fixed session label.

If you want to create a fixed session label (this may happen if you want to export one session at a time and manually merge those sessions into one dataset), you should specify a pattern for subject name (this could be as simple as .*) and enter the desired session label verbatim.

Using dicom subject name to create both subject and series label

This is the primary use case. See the section below for explanations.

Defining patterns in subject names and using them

The Subject and session rules popover has three fields: Pattern, Subject label and Session label.

images/sub_ses_rules.png

To use the functionality, you should enter the following:

• Pattern - the regular expression that will be matched against each subject name.
• Subject label - template for subject label. You may use $1, $2, etc. to reference capture groups from the regular expression above.
• Session label - template for session label. You may use $1, $2, etc. to reference capture groups from the regular expression above.

Technically speaking, the plugin uses the [NSRegularExpression replacementStringForResult:match inString:subjectName offset:0 template:template] method to generate both subject and session label. You have to supply both the regular expression producing match and the template.

The examples below should make it clearer.

Examples

Example 1: session name in last letter, discard part of the name

• Subject names: mystudy-01-a, mystudy-01-b, mystudy-01-c, mystudy-02-a, …
  • session labels are a, b and c
  • subject labels are 01, 02, etc
• Pattern: mystudy-([0-9]+)-([abc])$
  • first capture group contains at least one digit
  • second capture group contains one of the letters [abc]
  • the capture groups are separated by a dash and before them there is mystudy-
• subject label: $1
  • this means: take contents of the first capture group
• session label: $2
  • this means: take contents of the second capture group

Example 2: a bit more complex pattern

• Subject names: Chr_W20R_Pilot, Chr_W20G_Pilot, Chr_W20B_Pilot, Chr_P03R_Pilot, …
  • subject labels are W20 and P03 (in general: one letter, W or P, followed by a number)
  • session labels are R, G, B (like colours)
  • both Chr_ and _Pilot parts were used to distinguish the study from other studies, but now they can be discarded
• Pattern: Chr_([WP][0-9]+)([RGB])
  • first capture group contains one of the letters [WP] followed by one or more digits
  • second capture group contains one of the letters [RGB]
  • the capture groups are preceded by Chr-
• subject label: $1
  • this means: take contents of the first capture group
• session label: $2
  • this means: take contents of the second capture group

Example 3: all subjects from the same session (but we want to keep the session level in the structure)

• Subject names: mystudy-01, mystudy-02, …
  • subject labels are 01, 02, etc.
  • session label is first (we are planning to acquire session named second and extend our dataset later)
  • we used mystudy to distinguish the study from other studies, but now this part can be discarded
• Pattern: ([0-9]+)
  • the first and only capture group contains one or more digits
• subject label: $1
  • this means: take contents of the first capture group
• session label: first
  • this means: literally, first

Example 4: a slightly twisted case

• Subject names: group-exp-sub-01-ses-pre, group-exp-sub-01-ses-post, group-con-sub-01-ses-pre, group-con-sub-01-ses-post, group-exp-sub-02-ses-pre, …
  • session labels are pre and post
  • subject labels are myexp01, mycon01, myexp02, etc (exp / con and the number are already in the name, but for some reason we want to append my)
  • luckily, we were consistent with naming patterns
• Pattern: group-(exp|con)-sub-([0-9]+)-ses-(pre|post)
  • first capture group contains either exp or con
  • second capture group contains one or more digits
  • third capture group contains either pre or post
  • there capture groups are separated by strings with a fixed content
• subject label: my$1$2
  • this means: concatenate my and the contents of first and second capture groups
• session label: $3
  • this means: take contents of the third capture group