Skip to content

TSV files

A Tab-Separate Values (TSV) file is a text file where tab characters (\t) separate fields that are in the file. It is structured as a table, with each column representing a field of interest, and each row representing a single datapoint.

Python

In Python, the easiest way to work with TSV files is to use the Pandas library. This provides a high-level structure to organize, manipulate, clean, and visualize tabular data. You can install pandas with the following command:

pip install pandas

MATLAB / Octave

Since MATLAB R2013b, there is a readtable function that can load TSV files, and a writetable function to write them.

For Octave, the writetable function is not implemented in older version of Octave (e.g 4.2.2) and the table function differs from its MATLAB counterpart, so it may be easier to rely on bids-matlab functions (bids.util.tsvwrite and bids.util.tsvread) to help you work with those files.

R

Reading and writing tab separated files comes natively in R, no need for extra packages.

Reading a .tsv file

In this example, we assume the .tsv includes column names (headers), and explicitly set column separator (delimiter) to tab ('\t').

import pandas as pd
data = pd.read_csv("file.tsv", sep="\t", headers=True)

table_content = readtable('file.tsv', ...
                          'FileType', 'text', ...
                          'Delimiter', '\t', ...
                          'TreatAsEmpty', {'N/A','n/a'});

The example below uses the bids-matlab library.

table_content = bids.util.tsvread('file.tsv');

In this example, we assume the .tsv includes column names (headers), and explicitly set column separator (delimiter) to tab ('\t')

data = read.table('file.tsv', header=TRUE, sep='\t')

Excel, LibreOffice Calc and similar software to work with tables should have no problem opening TSV files.

Writing a .tsv file

import pandas as pd

participants = pd.DataFrame(
    {
        "participant_id": ["sub-01", "sub-02"],
        "age": [20, 30],
        "sex": ["m", "f"],
    }
)
participants.to_csv("participants.tsv")

participant_id = ['sub-01'; 'sub-02'];
age = [20; 30]';
sex = ['m'; 'f'];
participants = table(participant_id, age, sex);

writetable(participants, ...
           'participants.tsv', ...
           'FileType', 'text', ...
           'Delimiter', '\t');

The example below uses the bids-matlab library.

participants = struct(...
    'participant_id', ['sub-01', 'sub-02'];
    'age', [20, 30]';
    'sex', ['m', 'f']
    );

bids.util.tsvwrite('participants.tsv', participants);

When writing files, column and row names are always saved, we remove row names and quotes from the output explicitly by setting them to FALSE.

participant_id <- c('sub-01', 'sub-02');
age <- c(20, 30);
sex <- c('m', 'f');
participants <- data.frame(participant_id, age, sex)
write.table(participants,
            file='participants.tsv',
            sep='\t',
            row.names = FALSE,
            quote = FALSE)