Struct Table 

pub struct Table { /* private fields */ }

A small, owned, rectangular table-like data set.

External guarantees: row order is preserved; column order is preserved; column names are stable after loading. Operations return new owned Table values; no borrowed view lifetimes appear in normal use.

Implementations

impl Table

pub fn from_csv_str(input: &str) -> Result<Table, MattenDataError>

Parse a Table from a CSV string.

The first row is the header. Empty input, empty or duplicate header names, and ragged rows are reported as MattenDataError (never a panic).

use matten_data::Table;
let table = Table::from_csv_str("a,b\n1,2\n3,4").unwrap();
assert_eq!(table.row_count(), 2);
assert_eq!(table.column_names(), &["a".to_string(), "b".to_string()]);

Examples found in repository

examples/data_00_quickstart.rs (line 28)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small table with one text column and one missing numeric cell.
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])? // keep only the numeric columns
        .fill_missing(0.0)? // the missing south/cost becomes 0.0, explicitly
        .try_numeric()? // strict, explicit conversion to f64
        .to_tensor()?; // a normal [rows, columns] Tensor

    println!("shape: {:?}", tensor.shape());
    println!("data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_00_quickstart: OK");
    Ok(())
}

examples/csv_to_tensor.rs (line 27)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small, messy table: a text column and one missing numeric cell.
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,,7
east,120,55,6";

    let table = Table::from_csv_str(csv)?;

    // Inspect what we have before converting anything.
    println!("{}", table.schema_summary());

    // Select only the numeric columns we want, fill the one missing cost with 0,
    // convert explicitly, and produce a [rows, columns] f64 tensor.
    let tensor = table
        .select_columns(["sales", "cost", "quantity"])?
        .fill_missing(0.0)?
        .try_numeric()?
        .to_tensor()?;

    println!("tensor shape: {:?}", tensor.shape());
    println!("tensor data : {:?}", tensor.as_slice());

    // 3 rows x 3 columns; the missing south/cost became 0.0.
    assert_eq!(tensor.shape(), &[3, 3]);
    assert_eq!(
        tensor.as_slice(),
        &[100.0, 40.0, 5.0, 150.0, 0.0, 7.0, 120.0, 55.0, 6.0]
    );
    println!("csv_to_tensor: OK");
    Ok(())
}

examples/data_02_select_columns.rs (line 23)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,45,7";

    let table = Table::from_csv_str(csv)?;

    // Ask for a subset in a deliberately different order than the CSV.
    let reordered = table.select_columns(["quantity", "sales"])?;
    println!("selected names: {:?}", reordered.column_names());

    // The output order is exactly what was requested.
    assert_eq!(
        reordered.column_names(),
        &["quantity".to_string(), "sales".to_string()]
    );
    assert_eq!(reordered.column_count(), 2);
    assert_eq!(reordered.row_count(), 2);

    // Asking for a column that does not exist is a structured error.
    match table.select_columns(["sales", "profit"]) {
        Err(MattenDataError::MissingColumn { name }) => {
            println!("missing column reported: {name}");
            assert_eq!(name, "profit");
        }
        other => panic!("expected MissingColumn, got {other:?}"),
    }

    println!("data_02_select_columns: OK");
    Ok(())
}

examples/data_04_to_tensor.rs (line 26)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,45
east,120,55";

    let tensor: Tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])?
        .try_numeric()?
        .to_tensor()?;

    // [rows, columns] = [3, 2].
    assert_eq!(tensor.shape(), &[3, 2]);

    // Row-major: [north.sales, north.cost, south.sales, south.cost, ...].
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 45.0, 120.0, 55.0]);

    // It is a plain Tensor, so core `matten` operations apply. Mean over axis 0
    // (down the rows) gives the per-column mean: [mean(sales), mean(cost)].
    let column_means = tensor.mean_axis(0);
    println!("shape        : {:?}", tensor.shape());
    println!("column means : {:?}", column_means.as_slice());

    assert_eq!(column_means.shape(), &[2]);
    assert_eq!(
        column_means.as_slice(),
        &[(100.0 + 150.0 + 120.0) / 3.0, (40.0 + 45.0 + 55.0) / 3.0]
    );

    println!("data_04_to_tensor: OK");
    Ok(())
}

examples/data_03_missing_values.rs (line 24)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let table = Table::from_csv_str(csv)?;
    let numeric_cols = table.select_columns(["sales", "cost"])?;

    // Converting with a missing cell still present is rejected — no silent zero.
    match numeric_cols.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value blocked conversion: column={column}, csv_line={row}");
            assert_eq!(column, "cost");
            assert_eq!(row, 3); // header is line 1, so the south row is line 3
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    // Decide explicitly what a missing cost means here, then convert.
    let tensor = numeric_cols.fill_missing(0.0)?.try_numeric()?.to_tensor()?;

    println!("filled shape: {:?}", tensor.shape());
    println!("filled data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    // Only the missing south/cost was filled; the other cells are untouched.
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_03_missing_values: OK");
    Ok(())
}

examples/data_01_schema_summary.rs (line 25)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost,active
north,100,40.5,true
south,150,,true
east,120,55.0,false";

    let table = Table::from_csv_str(csv)?;

    // Top-level shape of the table.
    println!("rows    : {}", table.row_count());
    println!("columns : {}", table.column_count());
    println!("names   : {:?}", table.column_names());

    // A printable, one-glance summary (Table: R rows x C columns, then a line
    // per column with its inferred kind and missing count).
    let summary = table.schema_summary();
    print!("{summary}");

    // The same information, per column, if you want to act on it in code.
    println!("--- per-column ---");
    for col in summary.column_summaries() {
        println!(
            "{:<8} kind={:<7} missing={}",
            col.name, col.kind, col.missing
        );
    }

    // The "cost" column has exactly one missing cell (south).
    let cost = summary
        .column_summaries()
        .iter()
        .find(|c| c.name == "cost")
        .expect("cost column exists");
    assert_eq!(cost.missing, 1);
    assert_eq!(table.row_count(), 3);
    assert_eq!(table.column_count(), 4);

    println!("data_01_schema_summary: OK");
    Ok(())
}

Additional examples can be found in:

• examples/data_05_errors.rs

pub fn from_csv_path<P: AsRef<Path>>(path: P) -> Result<Table, MattenDataError>

Parse a Table from a CSV file at path.

I/O failures (for example a missing file) are reported as MattenDataError::Io with the path and underlying error preserved.

impl Table

pub fn row_count(&self) -> usize

Number of data rows.

Examples found in repository

examples/data_02_select_columns.rs (line 35)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,45,7";

    let table = Table::from_csv_str(csv)?;

    // Ask for a subset in a deliberately different order than the CSV.
    let reordered = table.select_columns(["quantity", "sales"])?;
    println!("selected names: {:?}", reordered.column_names());

    // The output order is exactly what was requested.
    assert_eq!(
        reordered.column_names(),
        &["quantity".to_string(), "sales".to_string()]
    );
    assert_eq!(reordered.column_count(), 2);
    assert_eq!(reordered.row_count(), 2);

    // Asking for a column that does not exist is a structured error.
    match table.select_columns(["sales", "profit"]) {
        Err(MattenDataError::MissingColumn { name }) => {
            println!("missing column reported: {name}");
            assert_eq!(name, "profit");
        }
        other => panic!("expected MissingColumn, got {other:?}"),
    }

    println!("data_02_select_columns: OK");
    Ok(())
}

examples/data_01_schema_summary.rs (line 28)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost,active
north,100,40.5,true
south,150,,true
east,120,55.0,false";

    let table = Table::from_csv_str(csv)?;

    // Top-level shape of the table.
    println!("rows    : {}", table.row_count());
    println!("columns : {}", table.column_count());
    println!("names   : {:?}", table.column_names());

    // A printable, one-glance summary (Table: R rows x C columns, then a line
    // per column with its inferred kind and missing count).
    let summary = table.schema_summary();
    print!("{summary}");

    // The same information, per column, if you want to act on it in code.
    println!("--- per-column ---");
    for col in summary.column_summaries() {
        println!(
            "{:<8} kind={:<7} missing={}",
            col.name, col.kind, col.missing
        );
    }

    // The "cost" column has exactly one missing cell (south).
    let cost = summary
        .column_summaries()
        .iter()
        .find(|c| c.name == "cost")
        .expect("cost column exists");
    assert_eq!(cost.missing, 1);
    assert_eq!(table.row_count(), 3);
    assert_eq!(table.column_count(), 4);

    println!("data_01_schema_summary: OK");
    Ok(())
}

pub fn column_count(&self) -> usize

Number of columns.

Examples found in repository

examples/data_02_select_columns.rs (line 34)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,45,7";

    let table = Table::from_csv_str(csv)?;

    // Ask for a subset in a deliberately different order than the CSV.
    let reordered = table.select_columns(["quantity", "sales"])?;
    println!("selected names: {:?}", reordered.column_names());

    // The output order is exactly what was requested.
    assert_eq!(
        reordered.column_names(),
        &["quantity".to_string(), "sales".to_string()]
    );
    assert_eq!(reordered.column_count(), 2);
    assert_eq!(reordered.row_count(), 2);

    // Asking for a column that does not exist is a structured error.
    match table.select_columns(["sales", "profit"]) {
        Err(MattenDataError::MissingColumn { name }) => {
            println!("missing column reported: {name}");
            assert_eq!(name, "profit");
        }
        other => panic!("expected MissingColumn, got {other:?}"),
    }

    println!("data_02_select_columns: OK");
    Ok(())
}

examples/data_01_schema_summary.rs (line 29)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost,active
north,100,40.5,true
south,150,,true
east,120,55.0,false";

    let table = Table::from_csv_str(csv)?;

    // Top-level shape of the table.
    println!("rows    : {}", table.row_count());
    println!("columns : {}", table.column_count());
    println!("names   : {:?}", table.column_names());

    // A printable, one-glance summary (Table: R rows x C columns, then a line
    // per column with its inferred kind and missing count).
    let summary = table.schema_summary();
    print!("{summary}");

    // The same information, per column, if you want to act on it in code.
    println!("--- per-column ---");
    for col in summary.column_summaries() {
        println!(
            "{:<8} kind={:<7} missing={}",
            col.name, col.kind, col.missing
        );
    }

    // The "cost" column has exactly one missing cell (south).
    let cost = summary
        .column_summaries()
        .iter()
        .find(|c| c.name == "cost")
        .expect("cost column exists");
    assert_eq!(cost.missing, 1);
    assert_eq!(table.row_count(), 3);
    assert_eq!(table.column_count(), 4);

    println!("data_01_schema_summary: OK");
    Ok(())
}

pub fn column_names(&self) -> &[String]

Column names, in column order.

Examples found in repository

examples/data_02_select_columns.rs (line 27)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,45,7";

    let table = Table::from_csv_str(csv)?;

    // Ask for a subset in a deliberately different order than the CSV.
    let reordered = table.select_columns(["quantity", "sales"])?;
    println!("selected names: {:?}", reordered.column_names());

    // The output order is exactly what was requested.
    assert_eq!(
        reordered.column_names(),
        &["quantity".to_string(), "sales".to_string()]
    );
    assert_eq!(reordered.column_count(), 2);
    assert_eq!(reordered.row_count(), 2);

    // Asking for a column that does not exist is a structured error.
    match table.select_columns(["sales", "profit"]) {
        Err(MattenDataError::MissingColumn { name }) => {
            println!("missing column reported: {name}");
            assert_eq!(name, "profit");
        }
        other => panic!("expected MissingColumn, got {other:?}"),
    }

    println!("data_02_select_columns: OK");
    Ok(())
}

examples/data_01_schema_summary.rs (line 30)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost,active
north,100,40.5,true
south,150,,true
east,120,55.0,false";

    let table = Table::from_csv_str(csv)?;

    // Top-level shape of the table.
    println!("rows    : {}", table.row_count());
    println!("columns : {}", table.column_count());
    println!("names   : {:?}", table.column_names());

    // A printable, one-glance summary (Table: R rows x C columns, then a line
    // per column with its inferred kind and missing count).
    let summary = table.schema_summary();
    print!("{summary}");

    // The same information, per column, if you want to act on it in code.
    println!("--- per-column ---");
    for col in summary.column_summaries() {
        println!(
            "{:<8} kind={:<7} missing={}",
            col.name, col.kind, col.missing
        );
    }

    // The "cost" column has exactly one missing cell (south).
    let cost = summary
        .column_summaries()
        .iter()
        .find(|c| c.name == "cost")
        .expect("cost column exists");
    assert_eq!(cost.missing, 1);
    assert_eq!(table.row_count(), 3);
    assert_eq!(table.column_count(), 4);

    println!("data_01_schema_summary: OK");
    Ok(())
}

pub fn schema_summary(&self) -> SchemaSummary

A small, displayable schema summary (row/column counts, per-column missing counts and inferred kinds). Does not perform expensive analysis.

Examples found in repository

examples/csv_to_tensor.rs (line 30)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small, messy table: a text column and one missing numeric cell.
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,,7
east,120,55,6";

    let table = Table::from_csv_str(csv)?;

    // Inspect what we have before converting anything.
    println!("{}", table.schema_summary());

    // Select only the numeric columns we want, fill the one missing cost with 0,
    // convert explicitly, and produce a [rows, columns] f64 tensor.
    let tensor = table
        .select_columns(["sales", "cost", "quantity"])?
        .fill_missing(0.0)?
        .try_numeric()?
        .to_tensor()?;

    println!("tensor shape: {:?}", tensor.shape());
    println!("tensor data : {:?}", tensor.as_slice());

    // 3 rows x 3 columns; the missing south/cost became 0.0.
    assert_eq!(tensor.shape(), &[3, 3]);
    assert_eq!(
        tensor.as_slice(),
        &[100.0, 40.0, 5.0, 150.0, 0.0, 7.0, 120.0, 55.0, 6.0]
    );
    println!("csv_to_tensor: OK");
    Ok(())
}

examples/data_01_schema_summary.rs (line 34)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost,active
north,100,40.5,true
south,150,,true
east,120,55.0,false";

    let table = Table::from_csv_str(csv)?;

    // Top-level shape of the table.
    println!("rows    : {}", table.row_count());
    println!("columns : {}", table.column_count());
    println!("names   : {:?}", table.column_names());

    // A printable, one-glance summary (Table: R rows x C columns, then a line
    // per column with its inferred kind and missing count).
    let summary = table.schema_summary();
    print!("{summary}");

    // The same information, per column, if you want to act on it in code.
    println!("--- per-column ---");
    for col in summary.column_summaries() {
        println!(
            "{:<8} kind={:<7} missing={}",
            col.name, col.kind, col.missing
        );
    }

    // The "cost" column has exactly one missing cell (south).
    let cost = summary
        .column_summaries()
        .iter()
        .find(|c| c.name == "cost")
        .expect("cost column exists");
    assert_eq!(cost.missing, 1);
    assert_eq!(table.row_count(), 3);
    assert_eq!(table.column_count(), 4);

    println!("data_01_schema_summary: OK");
    Ok(())
}

pub fn select_columns<I, S>(&self, columns: I) -> Result<Table, MattenDataError>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Select columns by name, returning a new Table.

Behavior (RFC-034 §5.3): preserves the requested column order; errors with MattenDataError::MissingColumn if a requested column does not exist; rejects duplicate selections with MattenDataError::DuplicateSelection; an empty selection is MattenDataError::EmptySelection.

Examples found in repository

examples/data_00_quickstart.rs (line 29)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small table with one text column and one missing numeric cell.
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])? // keep only the numeric columns
        .fill_missing(0.0)? // the missing south/cost becomes 0.0, explicitly
        .try_numeric()? // strict, explicit conversion to f64
        .to_tensor()?; // a normal [rows, columns] Tensor

    println!("shape: {:?}", tensor.shape());
    println!("data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_00_quickstart: OK");
    Ok(())
}

examples/csv_to_tensor.rs (line 35)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small, messy table: a text column and one missing numeric cell.
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,,7
east,120,55,6";

    let table = Table::from_csv_str(csv)?;

    // Inspect what we have before converting anything.
    println!("{}", table.schema_summary());

    // Select only the numeric columns we want, fill the one missing cost with 0,
    // convert explicitly, and produce a [rows, columns] f64 tensor.
    let tensor = table
        .select_columns(["sales", "cost", "quantity"])?
        .fill_missing(0.0)?
        .try_numeric()?
        .to_tensor()?;

    println!("tensor shape: {:?}", tensor.shape());
    println!("tensor data : {:?}", tensor.as_slice());

    // 3 rows x 3 columns; the missing south/cost became 0.0.
    assert_eq!(tensor.shape(), &[3, 3]);
    assert_eq!(
        tensor.as_slice(),
        &[100.0, 40.0, 5.0, 150.0, 0.0, 7.0, 120.0, 55.0, 6.0]
    );
    println!("csv_to_tensor: OK");
    Ok(())
}

examples/data_02_select_columns.rs (line 26)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,45,7";

    let table = Table::from_csv_str(csv)?;

    // Ask for a subset in a deliberately different order than the CSV.
    let reordered = table.select_columns(["quantity", "sales"])?;
    println!("selected names: {:?}", reordered.column_names());

    // The output order is exactly what was requested.
    assert_eq!(
        reordered.column_names(),
        &["quantity".to_string(), "sales".to_string()]
    );
    assert_eq!(reordered.column_count(), 2);
    assert_eq!(reordered.row_count(), 2);

    // Asking for a column that does not exist is a structured error.
    match table.select_columns(["sales", "profit"]) {
        Err(MattenDataError::MissingColumn { name }) => {
            println!("missing column reported: {name}");
            assert_eq!(name, "profit");
        }
        other => panic!("expected MissingColumn, got {other:?}"),
    }

    println!("data_02_select_columns: OK");
    Ok(())
}

examples/data_04_to_tensor.rs (line 27)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,45
east,120,55";

    let tensor: Tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])?
        .try_numeric()?
        .to_tensor()?;

    // [rows, columns] = [3, 2].
    assert_eq!(tensor.shape(), &[3, 2]);

    // Row-major: [north.sales, north.cost, south.sales, south.cost, ...].
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 45.0, 120.0, 55.0]);

    // It is a plain Tensor, so core `matten` operations apply. Mean over axis 0
    // (down the rows) gives the per-column mean: [mean(sales), mean(cost)].
    let column_means = tensor.mean_axis(0);
    println!("shape        : {:?}", tensor.shape());
    println!("column means : {:?}", column_means.as_slice());

    assert_eq!(column_means.shape(), &[2]);
    assert_eq!(
        column_means.as_slice(),
        &[(100.0 + 150.0 + 120.0) / 3.0, (40.0 + 45.0 + 55.0) / 3.0]
    );

    println!("data_04_to_tensor: OK");
    Ok(())
}

examples/data_03_missing_values.rs (line 25)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let table = Table::from_csv_str(csv)?;
    let numeric_cols = table.select_columns(["sales", "cost"])?;

    // Converting with a missing cell still present is rejected — no silent zero.
    match numeric_cols.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value blocked conversion: column={column}, csv_line={row}");
            assert_eq!(column, "cost");
            assert_eq!(row, 3); // header is line 1, so the south row is line 3
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    // Decide explicitly what a missing cost means here, then convert.
    let tensor = numeric_cols.fill_missing(0.0)?.try_numeric()?.to_tensor()?;

    println!("filled shape: {:?}", tensor.shape());
    println!("filled data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    // Only the missing south/cost was filled; the other cells are untouched.
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_03_missing_values: OK");
    Ok(())
}

examples/data_05_errors.rs (line 47)

fn main() {
    // 1. Duplicate header column.
    match Table::from_csv_str("sales,sales\n1,2") {
        Err(MattenDataError::DuplicateColumn { name }) => {
            println!("duplicate header : {name}");
            assert_eq!(name, "sales");
        }
        other => panic!("expected DuplicateColumn, got {other:?}"),
    }

    // 2. Ragged row: the second data row (CSV line 3) has too few cells.
    match Table::from_csv_str("a,b,c\n1,2,3\n4,5") {
        Err(MattenDataError::RaggedRow {
            row,
            expected,
            actual,
        }) => {
            println!("ragged row       : line {row}, expected {expected}, got {actual}");
            assert_eq!((row, expected, actual), (3, 3, 2));
        }
        other => panic!("expected RaggedRow, got {other:?}"),
    }

    // 3. Non-numeric value during conversion.
    let with_text = Table::from_csv_str("label,value\nok,10\nbad,oops")
        .expect("parses fine; the text only fails at numeric conversion");
    match with_text
        .select_columns(["value"])
        .and_then(|t| t.try_numeric())
    {
        Err(MattenDataError::NonNumericValue { column, row, value }) => {
            println!("non-numeric value: column={column}, line={row}, value={value:?}");
            assert_eq!((column.as_str(), row, value.as_str()), ("value", 3, "oops"));
        }
        other => panic!("expected NonNumericValue, got {other:?}"),
    }

    // 4. Missing value during conversion (fill it first to proceed).
    let with_missing =
        Table::from_csv_str("a,b\n1,2\n3,").expect("missing cell is allowed in a Table");
    match with_missing.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value    : column={column}, line={row}");
            assert_eq!((column.as_str(), row), ("b", 3));
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    println!("data_05_errors: OK");
}

pub fn fill_missing( &self, value: impl Into<CellValue>, ) -> Result<Table, MattenDataError>

Fill every missing cell with value, returning a new Table.

Missing values are never silently turned into zero; filling is always explicit (RFC-035 §6). Non-missing cells and the shape are unchanged.

Examples found in repository

examples/data_00_quickstart.rs (line 30)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small table with one text column and one missing numeric cell.
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])? // keep only the numeric columns
        .fill_missing(0.0)? // the missing south/cost becomes 0.0, explicitly
        .try_numeric()? // strict, explicit conversion to f64
        .to_tensor()?; // a normal [rows, columns] Tensor

    println!("shape: {:?}", tensor.shape());
    println!("data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_00_quickstart: OK");
    Ok(())
}

examples/csv_to_tensor.rs (line 36)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small, messy table: a text column and one missing numeric cell.
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,,7
east,120,55,6";

    let table = Table::from_csv_str(csv)?;

    // Inspect what we have before converting anything.
    println!("{}", table.schema_summary());

    // Select only the numeric columns we want, fill the one missing cost with 0,
    // convert explicitly, and produce a [rows, columns] f64 tensor.
    let tensor = table
        .select_columns(["sales", "cost", "quantity"])?
        .fill_missing(0.0)?
        .try_numeric()?
        .to_tensor()?;

    println!("tensor shape: {:?}", tensor.shape());
    println!("tensor data : {:?}", tensor.as_slice());

    // 3 rows x 3 columns; the missing south/cost became 0.0.
    assert_eq!(tensor.shape(), &[3, 3]);
    assert_eq!(
        tensor.as_slice(),
        &[100.0, 40.0, 5.0, 150.0, 0.0, 7.0, 120.0, 55.0, 6.0]
    );
    println!("csv_to_tensor: OK");
    Ok(())
}

examples/data_03_missing_values.rs (line 38)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let table = Table::from_csv_str(csv)?;
    let numeric_cols = table.select_columns(["sales", "cost"])?;

    // Converting with a missing cell still present is rejected — no silent zero.
    match numeric_cols.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value blocked conversion: column={column}, csv_line={row}");
            assert_eq!(column, "cost");
            assert_eq!(row, 3); // header is line 1, so the south row is line 3
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    // Decide explicitly what a missing cost means here, then convert.
    let tensor = numeric_cols.fill_missing(0.0)?.try_numeric()?.to_tensor()?;

    println!("filled shape: {:?}", tensor.shape());
    println!("filled data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    // Only the missing south/cost was filled; the other cells are untouched.
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_03_missing_values: OK");
    Ok(())
}

pub fn try_numeric(&self) -> Result<NumericTable, MattenDataError>

Convert the table to an explicit numeric table (RFC-035 §7).

Strict conversion: Int/Float become f64; Bool and Text are rejected (MattenDataError::NonNumericValue); a remaining Missing cell is rejected (MattenDataError::MissingValue). Text is never parsed as a number by default.

Examples found in repository

examples/data_00_quickstart.rs (line 31)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small table with one text column and one missing numeric cell.
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])? // keep only the numeric columns
        .fill_missing(0.0)? // the missing south/cost becomes 0.0, explicitly
        .try_numeric()? // strict, explicit conversion to f64
        .to_tensor()?; // a normal [rows, columns] Tensor

    println!("shape: {:?}", tensor.shape());
    println!("data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_00_quickstart: OK");
    Ok(())
}

examples/csv_to_tensor.rs (line 37)

fn main() -> Result<(), matten_data::MattenDataError> {
    // A small, messy table: a text column and one missing numeric cell.
    let csv = "\
region,sales,cost,quantity
north,100,40,5
south,150,,7
east,120,55,6";

    let table = Table::from_csv_str(csv)?;

    // Inspect what we have before converting anything.
    println!("{}", table.schema_summary());

    // Select only the numeric columns we want, fill the one missing cost with 0,
    // convert explicitly, and produce a [rows, columns] f64 tensor.
    let tensor = table
        .select_columns(["sales", "cost", "quantity"])?
        .fill_missing(0.0)?
        .try_numeric()?
        .to_tensor()?;

    println!("tensor shape: {:?}", tensor.shape());
    println!("tensor data : {:?}", tensor.as_slice());

    // 3 rows x 3 columns; the missing south/cost became 0.0.
    assert_eq!(tensor.shape(), &[3, 3]);
    assert_eq!(
        tensor.as_slice(),
        &[100.0, 40.0, 5.0, 150.0, 0.0, 7.0, 120.0, 55.0, 6.0]
    );
    println!("csv_to_tensor: OK");
    Ok(())
}

examples/data_04_to_tensor.rs (line 28)

fn main() -> Result<(), matten_data::MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,45
east,120,55";

    let tensor: Tensor = Table::from_csv_str(csv)?
        .select_columns(["sales", "cost"])?
        .try_numeric()?
        .to_tensor()?;

    // [rows, columns] = [3, 2].
    assert_eq!(tensor.shape(), &[3, 2]);

    // Row-major: [north.sales, north.cost, south.sales, south.cost, ...].
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 45.0, 120.0, 55.0]);

    // It is a plain Tensor, so core `matten` operations apply. Mean over axis 0
    // (down the rows) gives the per-column mean: [mean(sales), mean(cost)].
    let column_means = tensor.mean_axis(0);
    println!("shape        : {:?}", tensor.shape());
    println!("column means : {:?}", column_means.as_slice());

    assert_eq!(column_means.shape(), &[2]);
    assert_eq!(
        column_means.as_slice(),
        &[(100.0 + 150.0 + 120.0) / 3.0, (40.0 + 45.0 + 55.0) / 3.0]
    );

    println!("data_04_to_tensor: OK");
    Ok(())
}

examples/data_03_missing_values.rs (line 28)

fn main() -> Result<(), MattenDataError> {
    let csv = "\
region,sales,cost
north,100,40
south,150,
east,120,55";

    let table = Table::from_csv_str(csv)?;
    let numeric_cols = table.select_columns(["sales", "cost"])?;

    // Converting with a missing cell still present is rejected — no silent zero.
    match numeric_cols.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value blocked conversion: column={column}, csv_line={row}");
            assert_eq!(column, "cost");
            assert_eq!(row, 3); // header is line 1, so the south row is line 3
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    // Decide explicitly what a missing cost means here, then convert.
    let tensor = numeric_cols.fill_missing(0.0)?.try_numeric()?.to_tensor()?;

    println!("filled shape: {:?}", tensor.shape());
    println!("filled data : {:?}", tensor.as_slice());

    assert_eq!(tensor.shape(), &[3, 2]);
    // Only the missing south/cost was filled; the other cells are untouched.
    assert_eq!(tensor.as_slice(), &[100.0, 40.0, 150.0, 0.0, 120.0, 55.0]);

    println!("data_03_missing_values: OK");
    Ok(())
}

examples/data_05_errors.rs (line 48)

fn main() {
    // 1. Duplicate header column.
    match Table::from_csv_str("sales,sales\n1,2") {
        Err(MattenDataError::DuplicateColumn { name }) => {
            println!("duplicate header : {name}");
            assert_eq!(name, "sales");
        }
        other => panic!("expected DuplicateColumn, got {other:?}"),
    }

    // 2. Ragged row: the second data row (CSV line 3) has too few cells.
    match Table::from_csv_str("a,b,c\n1,2,3\n4,5") {
        Err(MattenDataError::RaggedRow {
            row,
            expected,
            actual,
        }) => {
            println!("ragged row       : line {row}, expected {expected}, got {actual}");
            assert_eq!((row, expected, actual), (3, 3, 2));
        }
        other => panic!("expected RaggedRow, got {other:?}"),
    }

    // 3. Non-numeric value during conversion.
    let with_text = Table::from_csv_str("label,value\nok,10\nbad,oops")
        .expect("parses fine; the text only fails at numeric conversion");
    match with_text
        .select_columns(["value"])
        .and_then(|t| t.try_numeric())
    {
        Err(MattenDataError::NonNumericValue { column, row, value }) => {
            println!("non-numeric value: column={column}, line={row}, value={value:?}");
            assert_eq!((column.as_str(), row, value.as_str()), ("value", 3, "oops"));
        }
        other => panic!("expected NonNumericValue, got {other:?}"),
    }

    // 4. Missing value during conversion (fill it first to proceed).
    let with_missing =
        Table::from_csv_str("a,b\n1,2\n3,").expect("missing cell is allowed in a Table");
    match with_missing.try_numeric() {
        Err(MattenDataError::MissingValue { column, row }) => {
            println!("missing value    : column={column}, line={row}");
            assert_eq!((column.as_str(), row), ("b", 3));
        }
        other => panic!("expected MissingValue, got {other:?}"),
    }

    println!("data_05_errors: OK");
}

Trait Implementations

impl Clone for Table

fn clone(&self) -> Table

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Table

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.