TSV (.tsv)

Background & Context

    • MIME type: text/tab-separated-values
    • TSV tabular data format.
    • Stores records of numerical and textual information as lines, using tab characters to separate fields.
    • TSV is an acronym for Tab-Separated Values.
    • Plain text format.
    • Similar to CSV.

Import & Export

  • Import["file.tsv"] returns a list of lists containing strings and numbers, representing the rows and columns stored in the file.
  • Import["file.tsv",elem] imports the specified element from a TSV file.
  • Import["file.tsv",{elem,sub1,…}] imports subelements, specifically useful for partial data import.
  • The import format can be specified with Import["file","TSV"] or Import["file",{"TSV",elem,…}].
  • Export["file.tsv",expr] creates a TSV file from expr.
  • Supported expressions expr include:
  • {v1,v2,…}a single column of data
    {{v11,v12,…},{v21,v22,…},…}lists of rows of data
    arrayan array such as SparseArray, QuantityArray, etc.
    tseriesa TimeSeries, EventSeries or a TemporalData object
    Dataset[…]a dataset
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Rules"list of rules for all available elements
    "Summary"summary of the file
  • Data representation elements:
  • "Data"two-dimensional array
    "Grid"table data as a Grid object
    "RawData"two-dimensional array of strings
    "Dataset"table data as a Dataset
  • Import and Export use the "Data" element by default.
  • For partial data import, any data representation element elem can take row and column specifications in the form {elem, rows, cols}, where rows and cols can be any of the following:
  • nnth row or column
    -ncounts from the end
    n;;mfrom n through m
    n;;m;;sfrom n through m with steps of s
    {n1,n2,…}specific rows or columns ni
  • Metadata elements:
  • "Dimensions"a list of number of rows and maximum number of columns
    "MaxColumnCount"maximum number of columns
    "RowCount"number of rows

Options

  • Import and Export options:
  • "EmptyField"""how to represent empty fields
    "TextDelimiters""\""character used to delimit non-numeric fields
  • Data fields containing commas and line separators are typically wrapped in double-quote characters. By default, Export uses double-quote characters as delimiters. Specify a different character using "TextDelimiters".
  • Double-quote characters delimiting text fields are not imported by default.
  • Import options:
  • CharacterEncoding"UTF8ISOLatin1"raw character encoding used in the file
    "CurrencyTokens"{{"$", "£", "¥", "€"}, {"c", "¢", "p", "F"}}currency units to be skipped when importing numerical values
    "DateStringFormat"Nonedate format, given as a DateString specification
    "FillRows"Automaticwhether to fill rows to the max column length
    "HeaderLines"0number of lines to assume as headers
    "IgnoreEmptyLines"Falsewhether to ignore empty lines
    "NumberPoint""."decimal point string
    "Numeric"Automaticwhether to import data fields as numbers if possible
    "SkipLines"0number of lines to skip at the beginning of the file
  • By default, Import attempts to interpret the data as "UTF8" encoded text. If any sequence of bytes stored in the file cannot be represented in "UTF8", Import uses "ISOLatin1" instead.
  • With CharacterEncoding -> Automatic, Import will attempt to infer the character encoding of the file.
  • Possible settings for "HeaderLines" and "SkipLines" are:
  • nn rows to skip or to use as Dataset headers
    {rows,cols}rows and columns to skip or to use as headers
  • Import converts table entries formatted as specified by "DateStringFormat" to a DateObject.
  • Export options:
  • AlignmentNonehow data is aligned within table columns
    CharacterEncoding"UTF8"raw character encoding used in the file
    "FillRows"Falsewhether to fill rows to the max column length
    "TableHeadings"Noneheadings for table columns and rows
  • Possible settings for Alignment are None, Left, Center, and Right.
  • "TableHeadings" can be set to the following values:
  • Noneno labels
    Automaticgives successive integer labels for columns and rows
    {"col1","col2",…}list of column labels
    {rhead,chead}specifies separate labels for the rows and columns
  • Export encodes line separator characters using the convention of the computer system on which the Wolfram Language is being run.

Examples

open allclose all

Basic Examples  (3)

Import a TSV file:

Import a TSV file as a Dataset with headers:

Export an array of expressions to TSV:

Scope  (4)

Export a Dataset:

Use Values to remove headers from a dataset:

Use the "HeaderLines" option to import table headers:

Export a TimeSeries:

Export an EventSeries:

Export a QuantityArray:

Import Elements  (17)

"Data"  (6)

Import a TSV file as a 2D list of values:

This is also the default element:

Import a single row of a TSV file:

Import some specific rows of a TSV file:

Import the first 3 rows of a TSV file:

Import a single row and column from a TSV file:

Import a single column from a TSV file:

"Dataset"  (3)

Import a TSV file as a Dataset:

Use "HeaderLines" to use the first row as column headers:

Use "SkipLines" to only import the data of interest:

"Dimensions"  (1)

Get the dimensions from a TSV file:

If all rows in the file do not have the same number of columns, the maximum number of columns is used:

"Grid"  (1)

Import TSV data as a Grid:

"MaxColumnCount"  (1)

Get the maximum number of columns from a TSV file:

"RawData"  (3)

Import TSV data as raw strings:

Compare to "Data":

By default for "RawData", "Numeric"->False is used:

Use "Numeric"->True:

By default for "RawData", "FillRows"->True is used:

Use "FillRows"->False:

"RowCount"  (1)

Get the number of rows a TSV file:

"Summary"  (1)

Summary of a TSV file:

Import Options  (10)

CharacterEncoding  (1)

The character encoding can be set to any value from $CharacterEncodings:

"CurrencyTokens"  (1)

Currency tokens are automatically skipped:

Use "CurrencyTokens"->None to include all currency tokens:

"DateStringFormat"  (1)

Convert dates to a DateObject using the date format specified:

By default, no conversion is happening:

"EmptyField"  (1)

Specify a default value for empty fields in TSV data:

"FillRows"  (1)

For the "Data" element, row lengths are automatically preserved:

Pad rows:

For the "RawData" element, a full array is imported by default:

"HeaderLines"  (1)

By default, no row or column is assumed to be a header line:

Specify column headers:

Specify row headers:

Specify row and column headers:

"IgnoreEmptyLines"  (1)

Use "IgnoreEmptyLines" to remove lines with no data from the imported data:

"Numeric"  (1)

Use "Numeric"->True to interpret numbers:

By default, everything imports as strings:

"SkipLines"  (1)

TSV files may include a comment line:

Skip the comment line:

Skip the comment line, and use the next line as a Dataset header:

"TextDelimiters"  (1)

The default text delimiter is a double quote:

A different character can be used as the text delimiter:

Export Options  (7)

Alignment  (1)

By default, no additional characters are added for any alignment:

Left-align column values:

Center-align column values:

CharacterEncoding  (1)

The character encoding can be set to any value from $CharacterEncodings:

"EmptyField"  (1)

By default, empty elements are exported as empty strings:

Specify a different value for empty elements:

"FillRows"  (1)

By default, a full array is exported:

Use "FillRows"->False to preserve row lengths:

"TableHeadings"  (1)

Export data using custom column headers:

Export data using custom column and row headers:

Export data using successive integer labels for columns and rows:

"TextDelimiters"  (2)

The default text delimiter for non-numeric elements is a double quote:

Specify a different delimiter character:

Use "TextDelimiters"->"" to disable any text delimiters:

By default, numeric elements do not get any delimiter characters:

Applications  (1)

Export a list of European countries and their populations to a TSV file:

Import the data back and convert to expressions:

Possible Issues  (5)

Some TSV data generated from older versions of the Wolfram Language may have incorrectly delimited text fields and will not import as expected in Version 11.2:

Using "TextDelimiters""" will give the previously expected result:

By default, a full array is exported using a double-quote for "TextDelimiters":

Use "TextDelimiters""" and "FillRows"False to export TSV data similar to versions prior to 11.2:

Entries of the format "nnnDnnn" or "nnnEnnn" are interpreted as numbers with scientific notation:

Use the "Numeric" option to override this interpretation:

The top-left corner of data is lost when importing a Dataset with row and column headers:

Dataset may look different depending on the dimensions of the data: