Struct ReadOptions

pub struct ReadOptions<TVal: BedVal> { /* private fields */ }

Represents options for reading genotype data from a PLINK .bed file.

Construct with ReadOptions::builder.

See the Table of ReadOptions for a list of the supported options. See the Table of Index Expressions for a list of expressions for selecting individuals (sample) and SNPs (variants).

Implementations

impl<TVal: BedVal> ReadOptions<TVal>

pub fn builder() -> ReadOptionsBuilder<TVal>

Read genotype data. Supports selection and options.

Also see Bed::read (read without options). To fill a preallocated ndarray, see ReadOptionsBuilder::read_and_fill.

See the Table of ReadOptions for a list of the supported options. See the Table of Index Expressions for a list of expressions for selecting individuals (sample) and SNPs (variants).

Errors

See BedError and BedErrorPlus for all possible errors.

Examples

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

// Read all data from a .bed file into an ndarray of f64.
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]
    ],
);

// Read the SNPs indexed by 2.
let val = ReadOptions::builder().sid_index(2).f64().read(&mut bed)?;

assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);

// Read the SNPs indexed by 2, 3, and 4th from last.
let val = ReadOptions::builder()
    .sid_index([2, 3, -4])
    .f64()
    .read(&mut bed)?;

assert_eq_nan(
    &val,
    &nd::array![[f64::NAN, 0.0, 1.0], [f64::NAN, 2.0, 2.0], [2.0, 0.0, 0.0]],
);

//  Read SNPs from 1 (inclusive) to 4 (exclusive).
let val = ReadOptions::builder()
    .sid_index(1..4)
    .f64()
    .read(&mut bed)?;

assert_eq_nan(
    &val,
    &nd::array![[0.0, f64::NAN, 0.0], [0.0, f64::NAN, 2.0], [1.0, 2.0, 0.0]],
);

// Print unique chrom values. Then, read all SNPs in chrom 5.
use std::collections::HashSet;

println!("{:?}", bed.chromosome()?.iter().collect::<HashSet<_>>());
// This outputs: {"1", "5", "Y"}.
let val = ReadOptions::builder()
    .sid_index(bed.chromosome()?.map(|elem| elem == "5"))
    .f64()
    .read(&mut bed)?;

assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);

// Read 1st individual (across all SNPs).
let val = ReadOptions::builder().iid_index(0).f64().read(&mut bed)?;
assert_eq_nan(&val, &nd::array![[1.0, 0.0, f64::NAN, 0.0]]);

// Read every 2nd individual.
use ndarray::s;

let val = ReadOptions::builder()
    .iid_index(s![..;2])
    .f64()
    .read(&mut bed)?;
assert_eq_nan(
    &val,
    &nd::array![[1.0, 0.0, f64::NAN, 0.0], [0.0, 1.0, 2.0, 0.0]],
);

// Read last and 2nd-to-last individuals and the last SNP
let val = ReadOptions::builder()
    .iid_index([-1,-2])
    .sid_index(-1)
    .f64()
    .read(&mut bed)?;

assert_eq_nan(&val, &nd::array![[0.0],[2.0]]);

// The output array can be f32, f64, or i8
let val = ReadOptions::builder().i8().read(&mut bed)?;

assert_eq_nan(
    &val,
    &nd::array![
        [1, 0, -127, 0],
        [2, 0, -127, 2],
        [0, 1, 2, 0]
    ],
);

pub fn missing_value(&self) -> TVal

Value to be used for missing values (defaults to -127 or NaN).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
assert_eq!(read_options.missing_value(), -127);

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

pub fn iid_index(&self) -> &Index

Index of individuals (samples) to read (defaults to all).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
println!("{0:?}", read_options.iid_index()); // Outputs 'All'
println!("{0:?}", read_options.sid_index()); // Outputs 'Vec([2, 3, 0])'

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

pub fn sid_index(&self) -> &Index

Index of SNPs (variants) to read (defaults to all).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
println!("{0:?}", read_options.iid_index()); // Outputs 'All'
println!("{0:?}", read_options.sid_index()); // Outputs 'Vec([2, 3, 0])'

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

pub fn is_f(&self) -> bool

Is the order of the output array Fortran-style (defaults to true).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
assert_eq!(read_options.is_f(), true);

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

pub fn is_a1_counted(&self) -> bool

If allele 1 will be counted (defaults to true).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
assert_eq!(read_options.is_a1_counted(), true);

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

pub fn num_threads(&self) -> Option<usize>

Number of threads to be used (None means set with Environment Variables or use all processors).

Example

use ndarray as nd;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use bed_reader::assert_eq_nan;

let read_options = ReadOptions::builder().sid_index([2, 3, 0]).i8().build()?;
assert_eq!(read_options.num_threads(), None);

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = bed.read_with_options(&read_options)?;
assert_eq_nan(&val, &nd::array![[-127, 0, 1], [-127, 2, 2], [2, 0, 0]]);

Trait Implementations

impl<TVal: Clone + BedVal> Clone for ReadOptions<TVal>

fn clone(&self) -> ReadOptions<TVal>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<TVal: Debug + BedVal> Debug for ReadOptions<TVal>

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

Formats the value using the given formatter.