Create tatami matrices from Matrix Market files

Overview

Pretty much as it says on the tin. This provides one-line wrappers around the eminem parser to enable quick creation of tatami matrices from Matrix Market files.

Quick start

The load_matrix_from_file() function will create a tatami::Matrix from a Matrix Market file:

#include "tatami_mtx/tatami_mtx.hpp"
 
tatami_mtx::Options opt;
opt.row = false;
auto mat = tatami_mtx::load_matrix_from_text_file<double, int>("some_matrix.mtx", opt);
 
// If compiled with Gzip support:
auto mat2 = tatami_mtx::load_matrix_from_gzip_file<double, int>("some_matrix.mtx.gz", opt);
 
// If the compression is unknown:
auto mat3 = tatami_mtx::load_matrix_from_some_file<double, int>("some_matrix.mtx.??", opt);

This will return a compressed sparse column matrix for coordinate formats and a column-major dense matrix for array formats. If opt.row = true, row-based matrices are returned instead.

The template arguments control the interface and storage types - for example, the above call will return a tatami::Matrix<double, int> interface The storage types are automatically chosen based on the Matrix Market field (for data) and the size of the matrix (for indices, only relevant for sparse outputs). Users can customize these by passing the desired types directly:

auto mat4 = tatami_mtx::load_matrix_from_text_file<
    true, /* Row-based */
    double, /* Data interface */
    int, /* Index interface */
    int32_t, /* Data storage */
    uint16_t /* Index storage */
>("some_matrix.mtx");

Check out the reference documentation for more details.

Building projects

CMake with FetchContent

If you're using CMake, you just need to add something like this to your CMakeLists.txt:

include(FetchContent)
 
FetchContent_Declare(
  tatami_mtx
  GIT_REPOSITORY https://github.com/tatami-inc/tatami_mtx
  GIT_TAG master # or any version of interest 
)
 
FetchContent_MakeAvailable(tatami_mtx)

Then you can link to tatami_mtx to make the headers available during compilation:

# For executables:
target_link_libraries(myexe tatami_mtx)
 
# For libaries
target_link_libraries(mylib INTERFACE tatami_mtx)

CMake using find_package()

You can install the library by cloning a suitable version of this repository and running the following commands:

mkdir build && cd build
cmake .. -DTATAMI_MTX_TESTS=OFF
cmake --build . --target install

Then you can use find_package() as usual:

find_package(tatami_tatami_mtx CONFIG REQUIRED)
target_link_libraries(mylib INTERFACE tatami::tatami_mtx)

Manual

If you're not using CMake, the simple approach is to just copy the files the include/ subdirectory - either directly or with Git submodules - and include their path during compilation with, e.g., GCC's -I. You'll also need to link to the tatami and eminem libraries (and their dependencies).