Crate npy [−] [src]

Serialize and deserialize the NumPy's *.npy binary format.

Overview

NPY is a simple binary data format. It stores the type, shape and endianness information in a header, which is followed by a flat binary data field. This crate offers a simple, mostly type-safe way to read and write *.npy files. Files are handled using iterators, so they don't need to fit in memory.

Only one-dimensional structured arrays are supported at the moment as they map well to Rust structs.

To successfully import an array from NPY using the #[derive(NpyRecord)] mechanism, the target struct must contain:

corresponding number of fields in the same order,
corresponding names of fields,
compatible field types.

Currently, all the primitive numeric types and arrays of up to 16 elements are supported, though they work only with little-endian. To deserialize other types or big-endian values, one must manually implement Serializable. A very common object that (right now) requires a manual impl is a vector, as illustrated in an example.

Examples

More examples can be found in the examples directory.

Let's create a simple *.npy file in Python:

import numpy as np
a = np.array([(1,2.5,4), (2,3.1,5)], dtype=[('a', 'i4'),('b', 'f4'),('c', 'i8')])
np.save('examples/simple.npy', a)

Now, we can load it in Rust:

#[macro_use]
extern crate npy_derive;
extern crate npy;

use std::io::Read;
use npy::NpyData;

#[derive(NpyRecord, Debug)]
struct Array {
    a: i32,
    b: f32,
    c: i64,
}

fn main() {
    let mut buf = vec![];
    std::fs::File::open("examples/simple.npy").unwrap()
        .read_to_end(&mut buf).unwrap();

    let data: NpyData<Array> = NpyData::from_bytes(&buf).unwrap();
    for arr in data {
        println!("{:?}", arr);
    }
}

The output is:

Array { a: 1, b: 2.5, c: 4 }
Array { a: 2, b: 3.1, c: 5 }

Structs

DType	Representation of a Numpy type
NpyData	The data structure representing a deserialized `npy` file.
OutFile	Serialize into a file one row at a time. To serialize an iterator, use the `to_file` function.

Traits

NpyRecord	A trait representing a (de-)serializable data-structure.
Serializable	This trait contains information on how to serialize and deserialize a primitive type.

Functions

to_file

Serialize an iterator over a struct to a NPY file