Skip to main content
`Ctrl`+`K`

# Labeled square matrix format (`skbio.io.format.lsmat`)

The labeled square matrix file format (`lsmat`) stores numeric square matrix data relating a set of objects along each axis. The format also stores identifiers (i.e., unique labels) for the objects. The matrix data and identifiers are stored in delimited text format (e.g., TSV or CSV). This format supports storing a variety of data types including dissimilarity/distance matrices, similarity matrices and amino acid substitution matrices.

## Format Support

Has Sniffer: Yes

Reader | Writer | Object Class
--- | --- | ---
Yes | Yes | `skbio.stats.distance.DissimilarityMatrix`
Yes | Yes | `skbio.stats.distance.DistanceMatrix`

## Format Specification

The labeled square matrix and object identifiers are stored as delimited text. The first line of the file is the header, which must start with the delimiter, followed by the IDs for all objects in the matrix. Each of the following lines must contain an object’s ID, followed by a numeric (float or integer) vector relating the object to all other objects in the matrix. The order of objects is determined by the IDs in the header.

For example, assume we have a 2x2 distance matrix with IDs `'a'` and `'b'`. When serialized in this format, the distance matrix might look like:

    <del>a<del>b
    a<del>0.0<del>1.0
    b<del>1.0<del>0.0

where `<del>` is the delimiter between elements.

Lines containing only whitespace may occur anywhere throughout the file and are ignored. Lines starting with `#` are treated as comments and are ignored. Comments may only occur before the header.

IDs will have any leading/trailing whitespace removed when they are parsed.

Note

This file format is most useful for storing small matrices, or when it is desirable to represent the matrix in a human-readable format, or easily import the file into another program that supports delimited text (e.g., a spreadsheet program). If efficiency is a concern, this format may not be the most appropriate choice.

## Format Parameters

The only supported format parameter is `delimiter`, which defaults to the tab character (`'\t'`). `delimiter` is used to separate elements in the file format. Examples include tab (`'\t'`) for TSV format and comma (`','`) for CSV format. `delimiter` can be specified as a keyword argument when reading from or writing to a file.

A special `delimiter` is `None`, which represents a whitespace of arbitrary length. This value is useful for reading a fixed-width text file. However, it cannot be automatically determined, nor can it be specified when writing to a file.