timeseries_to_file.md

Extract Timeseries to File Using Surface Parcels

What is this snippet for?

Simple walkthrough and example code (python) to extract timeseries vectors, from a dense timeseries (dtseries) file, using a parcel set's dlabel file.

Why do we need this?

The most basic of needs for any analyses is a bit different using surface files. Here is an example in the most basic of scenarios. You have a dense timseries file created from the core HCP pipeline (or any offshoot, such as from DCAN lab or using fMRIPrep). Below is how you would:

1. Create a ptseries (parcellated timeseries) file. This is the average value of all vertices within each surface parcel, for all TRs (repetition time).
2. Extract the timeseries vectors from that ptseries file (to a .txt file use in any script), using the 333 cortical surface parcels in the Gordon 333 parcellation set.

Note: This ptseries (parcellated timeseries file) file can be used with other workbench commands, etc.

Code example!

Step I: Create a pstseries (parcellated timeseries file) from the dtseries

# the dtseries file you want to extract
dt_path = <PATH TO>'/your_dense_timeseries_file.dtseries.nii'
# whatever parcel set you want to use
parc_path = <PATH TO>'/Gordon333_Parcels_LR.dlabel.nii' 
# output path to the ptseries you want to create - 
pt_path = <PATH TO>'/your_parcellated_timeseries_file.ptseries.nii'

pt_comm = ' '.join(['wb_command',
                    '-cifti-parcellate',
                    dt_path,
                    parc_path,
                    'COLUMN',
                    pt_path
                    ])
try:
    subprocess.call(pt_comm, shell=True)
except subprocess.CalledProcessError as err:
    print('ERROR:', err)

Step II: Extract timeseries of average vertex values within each parcel to a .txt file.

# output path to the .txt - this will have one vector, per line. 
# NOTE: Each line is a parcel (in the order the dlabel file has them labeled).
# Each vector has one value for each TR of the scan.
tc_path = <PATH TO>'/your_timeseries_text_file.txt'

    tcext_comm = ' '.join(['wb_command',
                           '-cifti-convert',
                           '-to-text',
                           pt_path,
                           tc_path
                           ])
    try:
        subprocess.call(tcext_comm, shell=True)
    except subprocess.CalledProcessError as err:
        print('ERROR:', err)

Example Outputs