# Compressed Sparse Vector (CSV) Binary Matrix Library

[![Crates.io][crate_badge]][crate_link]
[![MSRV][msrv_badge]][crate_link]
[![Crate Downloads][downloads_badge]][crate_link]
[![Coverage report][coverage_badge]][coverage_link]
[![Pipeline status][pipeline_badge]][pipeline_link]
[![docs.rs][docs_badge]][docs_link]
[![License][license_badge]][licence_link]

🦀 Rust package for binary matrices represented in the Compressed Sparse Vector (CSV) format.

📖 **For more info on this library, check out the [docs.rs docs][docs_link].**

[`CSVBinaryMatrix`](https://docs.rs/csvbinmatrix/latest/csvbinmatrix/matrix/struct.CSVBinaryMatrix.html) is the main structure and maintains the CSV format which is suitable for sparse matrices.

This crate is based on the paper cited in the [References](#references) section.

* [Quick Usage](#quick-usage)
* [Tutorials](#tutorials)
* [Recent Changes](#recent-changes)
* [Contributing](#contributing)
* [License](#license)
* [References](#references)

## Quick Usage

Add the following into your `Cargo.toml` configuration file:

```toml
[dependencies]
    csvbinmatrix = "0.8.0"
```

```rust
# fn quick_usage() -> Result<(), Box<dyn std::error::Error>> {
use csvbinmatrix::prelude::CSVBinaryMatrix;

let matrix = match CSVBinaryMatrix::try_from(&[
    [0, 0, 0],
    [0, 0, 1],
    [0, 1, 1],
    [1, 1, 1],
]) {
    Ok(m) => m,
    Err(e) => panic!("[ERROR] Cannot create the matrix: {e}"),
};

println!("Matrix stats");
println!("------------");
println!(
    "Dimensions: {}x{} ({})",
    matrix.number_of_rows(),
    matrix.number_of_columns(),
    matrix.number_of_cells()
);
println!(
    "Number of ones/zeros: {}/{}",
    matrix.number_of_ones(),
    matrix.number_of_zeros()
);
println!("Density: {:.2}%", matrix.density() * 100.0);
println!("Sparsity: {:.2}%", matrix.sparsity() * 100.0);
println!();

println!("Coordinates of ones");
println!("-------------------");
println!("row\tcolumn");
println!("---\t-------");
for coordinates in matrix.iter_ones_coordinates() {
    println!("{}\t{}", coordinates.row(), coordinates.column());
}
println!();

match matrix.to_file("mymatrix.csvbm") {
    Ok(_) => println!("[INFO] File created"),
    Err(e) => println!("[ERROR] Creating the file fails: {e}"),
}

match CSVBinaryMatrix::try_from_file("mymatrix.csvbm") {
    Ok(m) => {
        println!("[INFO] Read from file");
        assert_eq!(m, matrix)
    }
    Err(e) => println!("[ERROR] Cannot read the file: {e}"),
}
#
#    std::fs::remove_file("mymatrix.csvbm").unwrap_or(());
#    Ok(())
# }
```

## Tutorials

* [Extend a matrix with rows or columns](https://docs.rs/csvbinmatrix/latest/csvbinmatrix/matrix/update/index.html)
* [Write a matrix into a file and initialize a new matrix from a file](https://docs.rs/csvbinmatrix/latest/csvbinmatrix/matrix/io/index.html)
* [Efficiently produce submatrices](https://docs.rs/csvbinmatrix/latest/csvbinmatrix/matrix/ops/index.html)

## Recent Changes

See [`CHANGELOG.md`](https://gitlab.com/vepain/csvbinmatrix-rust/-/blob/main/CHANGELOG.md).

## Contributing

See [`CONTRIBUTING.md`](https://gitlab.com/vepain/csvbinmatrix-rust/-/blob/main/CONTRIBUTING.md).

## License

Dual-licensed to be compatible with the Rust project.

Licensed under the Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0> or the MIT license <http://opensource.org/licenses/MIT>, at your option. This file may not be copied, modified, or distributed except according to those terms.

## References

This package is based on this paper, where the authors' method is adapted for binary matrices:
> Farzaneh, Aiyoub, Hossein Kheırı, et Mehdi Abbaspour Shahmersı. « AN EFFICIENT STORAGE FORMAT FOR LARGE SPARSE MATRICES ». Communications Faculty of Sciences University of Ankara Series A1 Mathematics and Statistics 58, nᵒ 2 (1 août 2009): 1‑10. <https://doi.org/10.1501/Commua1_0000000648>.

<!-- Badges -->

[crate_badge]: https://img.shields.io/crates/v/csvbinmatrix?style=for-the-badge&logo=rust&color=blue "Crate badge"
[crate_link]: https://crates.io/crates/csvbinmatrix "Crate link"
[downloads_badge]: https://img.shields.io/crates/dv/csvbinmatrix.svg?style=for-the-badge&logo=rust "Crate downloads"
[msrv_badge]: https://img.shields.io/crates/msrv/csvbinmatrix?style=for-the-badge&logo=rust "Minimum Supported Rust Version"
[coverage_badge]: https://img.shields.io/gitlab/pipeline-coverage/vepain%2Fcsvbinmatrix-rust?job_name=test_coverage&branch=main&style=for-the-badge&logo=codecov "Coverage badge"
[coverage_link]: https://gitlab.com/vepain/csvbinmatrix-rust/-/commits/main "Coverage link"
[pipeline_badge]: https://img.shields.io/gitlab/pipeline-status/vepain%2Fcsvbinmatrix-rust?branch=main&style=for-the-badge&logo=circleci "Pipeline badge"
[pipeline_link]: https://gitlab.com/vepain/csvbinmatrix-rust/-/commits/main "Pipeline link"
[docs_badge]: https://img.shields.io/docsrs/csvbinmatrix?style=for-the-badge&logo=docsdotrs "docs.rs badge"
[docs_link]: https://docs.rs/csvbinmatrix/latest/csvbinmatrix/ "docs.rs link"
[license_badge]: https://img.shields.io/crates/l/csvbinmatrix.svg?style=for-the-badge&logo=readdotcv "Licence badge"
[licence_link]: https://gitlab.com/vepain/csvbinmatrix-rust "Licence link"