# Session acquisition information files

Session information files hold the key information about a subject's session. Single session files are generated automatically during `dicom2nii` QuNex command; they can then be concatenated and adjusted to list all subjects in a study. Most commonly named and referred to as `session.txt`, single session files are the key source of information for running preprocessing and analyses in QuNex. The name is not fixed, but can be changed, which allows storage of multiple parallel files. For example, during initial processing and importing of data, `session.txt` files are created. When they are adjusted to be used with the HCP pipeline, they are by default renamed to `session_<pipeline>.txt` (see [Session pipeline information files](../Overview/file_session_pipeline_txt)).

Information in session information files are provided in `key:value` pairs or `key:value1:value2:value3` sequences. The most common fields are:

* `session` — the identification information for this session (or subject), this is the value that will define the session folder name
* `subject` — the subject code
* `dicom` — the location of the session's dicom files (usually the `<session_id>/dicom` folder)
* `raw_data` — the folder with non-preprocessed files as converted from dicom format (usually the `<session_id>/nii` folder)
* `data` — the folder with standard volume preprocessed files (usually `<session_id>/4dfp` folder)
* `hcp` — the folder with data preprocessed using the HCP pipeline (usually `<session_id>/hcp` folder)

Besides these, any additional `key:value` pairs can be specified to store other information and might be referenced by the code. Preprocessing code, for instance, supports filtering by arbitrary combination of `key:value` pairs. Some keys can have specific functionality in the determination of preprocessing parameters and need to be provided in a specific format. These are:

* `institution` – provides information about the institution where the data was acquired
* `device` - provides information about the specific device used that has to take the form: `<manufacturer>|<model name>|<serial number>`

In addition, `key:value` pairs can define session specific processing parameters. In this case, the name of the parameter to be set has to be preceded by an underscore, e.g., `_hcp_brainsize: 170`.

Next follows the information about individual sequences / images. Each starts with the sequence number and should correspond to the dicom subfolder of that image and the nifti image number for the raw nifti images once converted from dicom using `dicom2niix`. Next is the specific information about the sequence. When generated automatically, the first information will be the sequence name read from the dicom file. In later processing this information should be extended by adding standard descriptors recognized by QuNex (see [Session pipeline information files](../Overview/file_session_pipeline_txt)).

Any number of additional values can be further specified. Separated by colon, these can provide image specific information to be used instead of the study general parameters. This information should be listed as `<key>(<value>)` pairs. The keys currently in use by QuNex are:

* `phenc` – Phase Encoding direction (used for BOLD, SE and DWI images), specified as AP/PA/LR/RL values
* `UnwarpDir` – Unwarp direction (used for T1w and T2w images)
* `EchoSpacing` - Echo Spacing (used for DWI, BOLD, and SE images; note that it has to be provided in ms for DWI images and in s for BOLD and Spin-Echo images)
* `DwellTime` – Dwell Time in seconds
* `se` - The spin echo pair to use for distortion correction (integer)
* `filename` – The exact (unique) filename of the sequence file
* `TR` – Time of repetition
* `PEDirection` - The phase encoding direction of the image specified as i/i-/j/j-/k/k- values

## Example

Here is a full example of session's information:

``` bash
id: <session_id>                                                 # Identification for this session
subject: <subject_id>                                            # Overall Subject ID
dicom: /<path_to_sessions_folder>/<session_id>/dicom             # Location of source DICOM images
raw_data: /<path_to_sessions_folder>/<session_id>/nii            # Location of source NIfTI images
data: /<path_to_sessions_folder>/<session_id>/4dfp               # Location of images processed using WashU NIL images
hpc: /<path_to_sessions_folder>/<session_id>/hpc                 # Location of images and data used for HCP preprocessing

age: 21                                                          # Demographic information
handedness: right
gender: male
group: control

institution: MR Imaging Center New Amsterdam
device: Siemens|Prisma_fit|123456

_hcp_brain_size: 150

01: Survey                                                       # Imaging data corresponding to source NIfTI image 1
02: T1w 0.7mm N2 : se(1): DwellTime(0.0000459): UnwarpDir(z)     # Imaging data corresponding to source NIfTI image 2 ...
03: T2w 0.7mm N2 : se(1): DwellTime(0.0000066): UnwarpDir(z)
04: Survey
05: C-BOLD 3mm 48 2.5s FS-P   : se(1): phenc(AP): EchoSpacing(0.0006146)
06: C-BOLD 3mm 48 2.5s FS-A   : se(1): phenc(PA): EchoSpacing(0.0006146)
07: BOLD 3mm 48 2.5s          : se(1): TR(2.5): phenc(PA): EchoSpacing(0.0006029): filename(rest_PA)
08: BOLD 3mm 48 2.5s          : se(1): TR(2.5): phenc(PA): EchoSpacing(0.0006029): filename(task1_PA)
09: BOLD 3mm 48 2.5s          : se(1): TR(2.5): phenc(PA): EchoSpacing(0.0006029): filename(task2_PA)
10: dMRI_dir98_AP             : TR(3.23): PEDirection(j-): EchoSpacing(0.000689998)
11: dMRI_dir98_PA             : TR(3.23): PEDirection(j ): EchoSpacing(0.000689998)
12: dMRI_dir99_AP             : TR(3.23): PEDirection(j-): EchoSpacing(0.000689998)
13: dMRI_dir99_PA             : TR(3.23): PEDirection(j ): EchoSpacing(0.000689998)
```

Note that any line starting with a "#" is considered a comment and is ignored by the QuNex session information parser. See [Preparing the study folder and importing data](../UsageDocs/PreparingStudy) for automatic generation of session information files during data import, and the *Mapping data to HCP folder structure* section of the [Running HCP pipeline](../UsageDocs/HCPPreprocessing) page for information on how to automatize adding HCP descriptors.