Struct ReadOptionsBuilder

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

Builder for ReadOptions.

Implementations

impl<TVal: BedVal + Clone> ReadOptionsBuilder<TVal>

pub fn missing_value(&mut self, value: TVal) -> &mut Self

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

pub fn iid_index<VALUE: Into<Index>>(&mut self, value: VALUE) -> &mut Self

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

pub fn sid_index<VALUE: Into<Index>>(&mut self, value: VALUE) -> &mut Self

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

pub fn is_f(&mut self, value: bool) -> &mut Self

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.

pub fn is_a1_counted(&mut self, value: bool) -> &mut Self

Sets if allele 1 is counted. Default is true.

Also see count_a1 and count_a2.

pub fn num_threads(&mut self, value: usize) -> &mut Self

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

pub fn max_concurrent_requests(&mut self, value: usize) -> &mut Self

Maximum number of concurrent async requests (defaults to 10) – Used by BedCloud.

In this example, we read using only request at a time.

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

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().max_concurrent_requests(1).i8().read_cloud(&mut bed_cloud).await?;

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

pub fn max_chunk_bytes(&mut self, value: usize) -> &mut Self

Maximum chunk size of async requests (defaults to 8_000_000 bytes) – Used by BedCloud.

In this example, we read using only 1_000_000 bytes per request.

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

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().max_chunk_bytes(1_000_000).i8().read_cloud(&mut bed_cloud).await?;

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

pub fn build(&self) -> Result<ReadOptions<TVal>, Box<BedErrorPlus>>

Builds a new ReadOptions.

Errors

If a required field has not been initialized.

impl<TVal: BedVal> ReadOptionsBuilder<TVal>

pub fn read(&self, bed: &mut Bed) -> Result<Array2<TVal>, Box<BedErrorPlus>>

See ReadOptions::builder for details and examples.

pub async fn read_cloud( &self, bed_cloud: &mut BedCloud, ) -> Result<Array2<TVal>, Box<BedErrorPlus>>

Read genotype data from the cloud.

Also see BedCloud::read_with_options.

Errors

See BedError and BedErrorPlus for all possible errors.

Example

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

// Read the SNPs indexed by 2.
let url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed";
let mut bed_cloud = BedCloud::new(&url).await?;
let mut val = ReadOptions::builder()
    .sid_index(2)
    .read_cloud(&mut bed_cloud).await?;

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

pub fn read_and_fill( &self, bed: &mut Bed, val: &mut ArrayViewMut2<'_, TVal>, ) -> Result<(), Box<BedErrorPlus>>

Read genotype data 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]]);

pub async fn read_and_fill_cloud( &self, bed_cloud: &mut BedCloud, val: &mut ArrayViewMut2<'_, TVal>, ) -> Result<(), Box<BedErrorPlus>>

Read genotype data from the cloud into a preallocated array.

Also see BedCloud::read_and_fill and BedCloud::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::{BedCloud, ReadOptions};
use bed_reader::assert_eq_nan;

// Read the SNPs indexed by 2.
let url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed";
let mut bed_cloud = BedCloud::new(&url).await?;
let mut val = nd::Array2::<f64>::default((3, 1));
ReadOptions::builder()
    .sid_index(2)
    .read_and_fill_cloud(&mut bed_cloud, &mut val.view_mut()).await?;

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

pub fn f(&mut self) -> &mut Self

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

Also called “column-major order” Wikipedia.

Also see is_f and c.

pub fn c(&mut self) -> &mut Self

Order of the output array, C (default)

Also called “row-major order” Wikipedia.

Also see is_f and f.

pub fn count_a1(&mut self) -> &mut Self

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

pub fn count_a2(&mut self) -> &mut Self

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

impl ReadOptionsBuilder<i8>

pub fn i8(&mut self) -> &mut Self

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

impl ReadOptionsBuilder<f32>

pub fn f32(&mut self) -> &mut Self

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

impl ReadOptionsBuilder<f64>

pub fn f64(&mut self) -> &mut Self

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

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<TVal: BedVal + Clone> Default for ReadOptionsBuilder<TVal>

fn default() -> Self

Returns the “default value” for a type.