Struct DataMatrixBuilder

Source

pub struct DataMatrixBuilder { /* private fields */ }

Expand description

A builder for loading labeled matrices from plain text, CSV, or TSV files.

DataMatrixBuilder provides flexible configuration for how files are parsed:

specify which columns contain row labels, column labels, and values,
optionally specify explicit row and column indices (for 5-column formats),
control the separator (space, comma, tab, etc.),
skip header lines,
control whether the matrix should be symmetric.

§Supported formats

Three-column format: row label, column label, value
Five-column format: row label, column label, row index, column index, value
Single-column format: raw values for a square matrix (handled separately); requires labels provided by a user with DataMatrixBuilder::labels().

Lines starting with # are ignored as comments.

§Examples

§Reading a 5-column file (e.g., `five_columns_short.txt`)

# Comment lines are allowed
Alice Bob 0 1 1.5
Bob John 1 2 2.2

use data_matrix::{DataMatrixBuilder, Error};
let matrix = DataMatrixBuilder::new()
    .label_columns(0, 1)    // columns 0 and 1: row and column labels
    .index_columns(2, 3)    // columns 2 and 3: row and column indices
    .data_column(4)         // column 4: value
    .separator(' ')         // whitespace separator
    .symmetric(true)        // make symmetric
    .from_file(input_fname)?;

§Reading a 3-column file (e.g., `three_columns_short.txt`)

# Comment lines are allowed
Alice Bob 1.2
Bob John 2.4

use data_matrix::{DataMatrixBuilder, Error};

let matrix = DataMatrixBuilder::new()
    .label_columns(0, 1)    // columns 0 and 1: row and column labels
    .data_column(2)         // column 2: value
    .separator(' ')         // whitespace separator
    .symmetric(true)        // make symmetric
    .skip_header(false)     // this is the default behaviour
    .from_file(input_fname)?;

§Notes

Columns are indexed starting from 0
field separator must be a single character (with an exception for ' ', see below); if not given, the value will be inferred from the file extension, e.g. '\t' for .tsv
when ' ' (a space) is used a separator, the builder splits by all white spaces, i.e. str.split_whitespace(&self) method is used
.symmetric(true) ensures that if (i,j) is set, (j,i) will also be set automatically.

Implementations§

Source §

impl DataMatrixBuilder

Source

pub fn new() -> Self

Creates just a new builder.

Now use its methods to set up column indexes (e.g. label_columns()), then provide some data (e.g. from_file())

Source

pub fn label_columns(self, row: usize, col: usize) -> Self

Specifies which columns contain the row and column labels.

Column indices are 0-based (i.e., the first column is 0).

§Arguments

row — Column number for row labels.
col — Column number for column labels.

§Example

use data_matrix::DataMatrixBuilder;
let mut builder = DataMatrixBuilder::new();
builder.label_columns(1, 2);

Source

pub fn labels<I, S>(self, labels: I) -> Self
where I: IntoIterator<Item = S>, S: Into<String>,

Provides labels for the case when the input data is a single column.

Source

pub fn data_column(self, val: usize) -> Self

Specifies which column contains the numeric value.

Column index is 0-based.

Source

pub fn index_columns(self, row_idx: usize, col_idx: usize) -> Self

Specifies which columns provide explicit row and column indices.

Column indices are 0-based.

§Arguments

row_idx — Column number for the row index.
col_idx — Column number for the column index.

§Example

use data_matrix::DataMatrixBuilder;
let mut builder = DataMatrixBuilder::new();
builder.index_columns(3, 4);

Source

pub fn separator(self, sep: char) -> Self

Sets the character used to separate fields in the input file.

Common choices: ' ', ',', '\t'.

Source

pub fn skip_header(self, if_header: bool) -> Self

If set to true, the first line of the file should be skipped as a header.

Source

pub fn symmetric(self, if_symmetric: bool) -> Self

Sets whether the matrix should be treated as symmetric.

If enabled, for every entry (row, col, value), the symmetric entry (col, row, value) is automatically added.

Source

pub fn from_data(self, data: &[f64]) -> Result<DataMatrix, Error>

Creates a new DataMatrix from a given 1D vector of data.

This method is devised to turn a 1D column of numbers into a square (usually symmetrix) 2D DataMatrix object. Labels should be provided with labels() method, otherwise they will be automatically generated as "row-{}", i + 1 and col-{}", i + 1 for rows and columns, respectively.

§Examples

Creates a square matrix with automatically generated labels:

use data_matrix::{DataMatrixBuilder, Error};
let data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
let matrix = DataMatrixBuilder::new().from_data(&data).unwrap();
assert_eq!(matrix.ncols(), 3);
assert_eq!(matrix.get(0,0).unwrap(), 1.0);
assert_eq!(matrix.row_label(0), "row-1");

Creates a square symmetric matrix with user-defined labels:

use data_matrix::{DataMatrixBuilder, Error};
let data = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
let labels = ["data-1", "data-2", "data-3"];
let matrix = DataMatrixBuilder::new().labels(labels).from_data(&data).unwrap();
assert_eq!(matrix.ncols(), 3);
assert_eq!(matrix.get(0,0).unwrap(), 1.0);
assert_eq!(matrix.row_label(0), "data-1");