Struct bed_reader::ReadOptionsBuilder

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

Builder for ReadOptions.

Implementations

Value to use for missing values (defaults to -127 or NaN)

-127 is the default for i8 and NaN is the default for f32 and f64.

In this example, the missing value is set to -1:

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().missing_value(-1).i8().read(&mut bed)?;

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

Select which individual (sample) values to read – Defaults to all.

Can select with a signed number, various lists of signed numbers, ranges, and various lists of booleans.

See the Table of Index Expressions for a list of the supported index expressions.

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

let file_name = sample_bed_file("some_missing.bed")?;
let mut bed = Bed::new(file_name)?;

// Read the individual at index position 3

let val = ReadOptions::builder()
    .iid_index(3)
    .f64()
    .read(&mut bed)?;
assert!(val.dim() == (1, 100));

// Read the individuals at index positions 0, 5, and 1st-from-last.

let val = ReadOptions::builder()
    .iid_index([0, 5, -1])
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (3, 100));

// Read the individuals at index positions 20 (inclusive) to 30 (exclusive).

let val = ReadOptions::builder()
    .iid_index(20..30)
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (10, 100));

// Read the individuals at every 2nd index position.

let val = ReadOptions::builder()
    .iid_index(s![..;2])
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (50, 100));

// Read chromosome 5 of the female individuals.

let female = bed.sex()?.map(|elem| *elem == 2);
let chrom_5 = bed.chromosome()?.map(|elem| elem == "5");
let val = ReadOptions::builder()
    .iid_index(female)
    .sid_index(chrom_5)
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (50, 6));

Select which SNPs (variant) values to read – Defaults to all.

Can select with a signed number, various lists of signed numbers, ranges, and various lists of booleans.

See the Table of Index Expressions for a list of the supported index expressions.

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

let file_name = sample_bed_file("some_missing.bed")?;
let mut bed = Bed::new(file_name)?;

// Read the SNP at index position 3

let val = ReadOptions::builder()
    .sid_index(3)
    .f64()
    .read(&mut bed)?;
assert!(val.dim() == (100, 1));

// Read the SNPs at index positions 0, 5, and 1st-from-last.

let val = ReadOptions::builder()
    .sid_index([0, 5, -1])
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (100, 3));

// Read the SNPs at index positions 20 (inclusive) to 30 (exclusive).

let val = ReadOptions::builder()
    .sid_index(20..30)
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (100, 10));

// Read the SNPs at every 2nd index position.

let val = ReadOptions::builder()
    .sid_index(s![..;2])
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (100, 50));

// Read chromosome 5 of the female individuals.

let female = bed.sex()?.map(|elem| *elem == 2);
let chrom_5 = bed.chromosome()?.map(|elem| elem == "5");
let val = ReadOptions::builder()
    .iid_index(female)
    .sid_index(chrom_5)
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (50, 6));

Sets if the order of the output array is Fortran-style – Default is true.

“Fortran order” is also called “column-major order” Wikipedia.

Also see f and c.

Sets if allele 1 is counted. Default is true.

Also see count_a1 and count_a2.

Number of threads to use (defaults to all processors)

Can also be set with an environment variable. See Environment Variables.

In this example, we read using only one thread.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().num_threads(1).i8().read(&mut bed)?;

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

Builds a new ReadOptions.

Errors

If a required field has not been initialized.

See ReadOptions::builder for details and examples.

Read genotype data with options, into a preallocated array.

Also see Bed::read_and_fill and Bed::read_and_fill_with_options.

Note that options ReadOptions::f, ReadOptions::c, and ReadOptions::is_f are ignored. Instead, the order of the preallocated array is used.

Errors

See BedError and BedErrorPlus for all possible errors.

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

// Read the SNPs indexed by 2.
let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let mut val = nd::Array2::<f64>::default((3, 1));
ReadOptions::builder()
    .sid_index(2)
    .read_and_fill(&mut bed, &mut val.view_mut())?;

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

Order of the output array, Fortran-style (default)

Also called “column-major order” Wikipedia.

Also see is_f and c.

Order of the output array, C (default)

Also called “row-major order” Wikipedia.

Also see is_f and f.

Count the number allele 1 (default and PLINK standard).

Also see is_a1_counted and count_a2.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().count_a1().i8().read(&mut bed)?;

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

Count the number allele 2.

Also see is_a1_counted and count_a1.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().count_a2().i8().read(&mut bed)?;

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

Output an ndarray of i8.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
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]
    ],
);

Output an ndarray of f32.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().f32().read(&mut bed)?;

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

Output an ndarray of f64.

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

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

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Returns the “default value” for a type. 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.