bed-reader
==========
[
](https://github.com/fastlmm/bed-reader)
[
](https://crates.io/crates/bed-reader)
[
](https://docs.rs/bed-reader)
[
](https://github.com/fastlmm/bed-reader/actions?query=branch%3Amaster)
Read and write the PLINK BED format, simply and efficiently.
Highlights
----------
* Fast and multi-threaded
* Supports many indexing methods. Slice data by individuals (samples) and/or SNPs (variants).
* The Python-facing APIs for this library is used by [PySnpTools](https://github.com/fastlmm/PySnpTools), [FaST-LMM](https://github.com/fastlmm/FaST-LMM), and [PyStatGen](https://github.com/pystatgen).
* Supports [PLINK 1.9](https://www.cog-genomics.org/plink2/formats).
* Read data locally or from the cloud, efficiently and directly.
Install
-------
**Full version**: Can read local and cloud files
```bash
cargo add bed-reader
```
**Minimal version**: Can read local files, only
```bash
cargo add bed-reader --no-default-features
```
Examples
--------
Read all genotype data from a .bed file.
```rust
use ndarray as nd;
use bed_reader::{Bed, ReadOptions, assert_eq_nan, sample_bed_file};
let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().f64().read(&mut bed)?;
assert_eq_nan(
&val,
&nd::array![
[1.0, 0.0, f64::NAN, 0.0],
[2.0, 0.0, f64::NAN, 2.0],
[0.0, 1.0, 2.0, 0.0]
],
);
# use bed_reader::BedErrorPlus; // '#' needed for doctest
# Ok::<(), Box>(())
```
Read every second individual (samples) and SNPs (variants) 20 to 30.
```rust
use ndarray::s;
let file_name = sample_bed_file("some_missing.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder()
.iid_index(s![..;2])
.sid_index(20..30)
.f64()
.read(&mut bed)?;
assert!(val.dim() == (50, 10));
# use bed_reader::{Bed, ReadOptions, BedErrorPlus, assert_eq_nan, sample_bed_file}; // '#' needed for doctest
# Ok::<(), Box>(())
```
List the first 5 individual (sample) ids, the first 5 SNP (variant) ids,
and every unique chromosome. Then, read every genomic value in chromosome 5.
```rust
# use ndarray::s; // '#' needed for doctest
# use bed_reader::{Bed, ReadOptions, assert_eq_nan, sample_bed_file};
# let file_name = sample_bed_file("some_missing.bed")?;
use std::collections::HashSet;
let mut bed = Bed::new(file_name)?;
println!("{:?}", bed.iid()?.slice(s![..5])); // Outputs ndarray: ["iid_0", "iid_1", "iid_2", "iid_3", "iid_4"]
println!("{:?}", bed.sid()?.slice(s![..5])); // Outputs ndarray: ["sid_0", "sid_1", "sid_2", "sid_3", "sid_4"]
println!("{:?}", bed.chromosome()?.iter().collect::>());
// Outputs: {"12", "10", "4", "8", "19", "21", "9", "15", "6", "16", "13", "7", "17", "18", "1", "22", "11", "2", "20", "3", "5", "14"}
let val = ReadOptions::builder()
.sid_index(bed.chromosome()?.map(|elem| elem == "5"))
.f64()
.read(&mut bed)?;
assert!(val.dim() == (100, 6));
# use bed_reader::BedErrorPlus; // '#' needed for doctest
# Ok::<(), Box>(())
```
From the cloud: open a file and read data for one SNP (variant)
at index position 2. (See ["Cloud URLs and `CloudFile` Examples"](supplemental_document_cloud_urls/index.html)
for details specifying a file in the cloud.)
```rust
use ndarray as nd;
use bed_reader::{assert_eq_nan, BedCloud, ReadOptions};
# #[cfg(feature = "tokio")] Runtime::new().unwrap().block_on(async { // '#' needed for doc test
let url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed";
let mut bed_cloud = BedCloud::new(url).await?;
let val = ReadOptions::builder().sid_index(2).f64().read_cloud(&mut bed_cloud).await?;
assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);
# Ok::<(), Box>(()) }).unwrap();
# #[cfg(feature = "tokio")] use {tokio::runtime::Runtime, bed_reader::BedErrorPlus};
```
Project Links
-----
* [**Installation**](https://crates.io/crates/bed-reader)
* [**Documentation**](https://docs.rs/bed-reader/)
* [**Questions via email**](mailto://fastlmm-dev@python.org)
* [**Source code**](https://github.com/fastlmm/bed-reader)
* [**Discussion**](https://github.com/fastlmm/bed-reader/discussions/)
* [**Bug Reports**](https://github.com/fastlmm/bed-reader/issues)
* [**Project Website**](https://fastlmm.github.io/)
* [**Change Log**](https://github.com/fastlmm/bed-reader/blob/master/CHANGELOG.md)