Struct bed_reader::ReadOptions

source · [−]
pub struct ReadOptions<TVal: BedVal> { /* private fields */ }
Expand description

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

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]
    ],
);

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]]);

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]]);

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]]);

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]]);

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]]);

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Should always be Self

The inverse inclusion map: attempts to construct self from the equivalent element of its superset. Read more

Checks if self is actually part of its subset T (and can be converted to it).

Use with care! Same as self.to_subset but without any property checks. Always succeeds.

The inclusion map: converts self to the equivalent element of its superset.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.