Struct bed_reader::WriteOptionsBuilder

pub struct WriteOptionsBuilder<TVal> where
    TVal: BedVal,  { /* private fields */ }

Builder for WriteOptions.

Implementations

impl<TVal> WriteOptionsBuilder<TVal> where
    TVal: BedVal, 

pub fn write<S: Data<Elem = TVal>>(
    &mut self,
    val: &ArrayBase<S, Ix2>
) -> Result<(), BedErrorPlus>

Creates a new WriteOptions with the options given and then writes a .bed (and .fam and .bim) file.

See WriteOptions for details and examples.

pub fn fid<I: IntoIterator<Item = T>, T: AsRef<str>>(self, fid: I) -> Self

Set the family id (fid) values for each individual (sample).

Defaults to zeros.

See WriteOptions for examples.

pub fn iid<I: IntoIterator<Item = T>, T: AsRef<str>>(self, iid: I) -> Self

Set the individual id (iid) values for each individual (sample).

Defaults to “iid1”, “iid2”, …

See WriteOptions for examples.

pub fn father<I: IntoIterator<Item = T>, T: AsRef<str>>(self, father: I) -> Self

Set the father id values for each individual (sample).

Defaults to zeros.

See WriteOptions for examples.

pub fn mother<I: IntoIterator<Item = T>, T: AsRef<str>>(self, mother: I) -> Self

Set the mother id values for each individual (sample).

Defaults to zeros.

See WriteOptions for examples.

pub fn sex<I: IntoIterator<Item = i32>>(self, sex: I) -> Self

Set the sex for each individual (sample).

0 is unknown (default), 1 is male, 2 is female

pub fn pheno<I: IntoIterator<Item = T>, T: AsRef<str>>(self, pheno: I) -> Self

Set a phenotype for each individual (sample). Seldom used.

Defaults to zeros.

See WriteOptions for examples.

pub fn chromosome<I: IntoIterator<Item = T>, T: AsRef<str>>(
    self,
    chromosome: I
) -> Self

Set the chromosome for each SNP (variant).

Defaults to zeros.

pub fn sid<I: IntoIterator<Item = T>, T: AsRef<str>>(self, sid: I) -> Self

Set the SNP id (sid) for each SNP (variant).

Defaults to “sid1”, “sid2”, …

See WriteOptions for examples.

pub fn cm_position<I: IntoIterator<Item = f32>>(self, cm_position: I) -> Self

Set the centimorgan position for each SNP (variant).

Defaults to zeros.

pub fn bp_position<I: IntoIterator<Item = i32>>(self, bp_position: I) -> Self

Set the base-pair position for each SNP (variant).

Defaults to zeros.

See WriteOptions for examples.

pub fn allele_1<I: IntoIterator<Item = T>, T: AsRef<str>>(
    self,
    allele_1: I
) -> Self

Set the first allele for each SNP (variant).

Defaults to “A1”, A1“ …

See WriteOptions for examples.

pub fn allele_2<I: IntoIterator<Item = T>, T: AsRef<str>>(
    self,
    allele_2: I
) -> Self

Set the second allele for each SNP (variant).

Defaults to “A2”, A2“ …

See WriteOptions for examples.

pub fn metadata(self, metadata: &Metadata) -> Self

Merge metadata from a Metadata.

If a field is set in both Metadata’s, it will be overridden.

Example

Extract metadata from a file. Create a random file with the same metadata.

use ndarray as nd;
use bed_reader::{Bed, WriteOptions, tmp_path, sample_bed_file};
use ndarray_rand::{rand::prelude::StdRng, rand::SeedableRng, rand_distr::Uniform, RandomExt};

let mut bed = Bed::new(sample_bed_file("small.bed")?)?;
let metadata = bed.metadata()?;
let shape = bed.dim()?;

let mut rng = StdRng::seed_from_u64(0);
let val = nd::Array::random_using(shape, Uniform::from(-1..3), &mut rng);

let temp_out = tmp_path()?;
let output_file = temp_out.join("random.bed");
WriteOptions::builder(output_file)
    .metadata(&metadata)
    .missing_value(-1)
    .write(&val)?;

pub fn fam_path<P: AsRef<Path>>(self, path: P) -> Self

Set the path to the .fam file.

If not set, the .fam file will be assumed to have the same name as the .bed file, but with the extension .fam.

Example:

Write .bed, .fam, and .bim files with non-standard names.

use ndarray as nd;
use bed_reader::{WriteOptions,tmp_path};
let output_folder = tmp_path()?;
let output_file = output_folder.join("small.deb");
let val = nd::array![[1, 0, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]];
WriteOptions::builder(output_file)
    .fam_path(output_folder.join("small.maf"))
    .bim_path(output_folder.join("small.mib"))
    .write(&val)?;

pub fn bim_path<P: AsRef<Path>>(self, path: P) -> Self

Set the path to the .bim file.

If not set, the .bim file will be assumed to have the same name as the .bed file, but with the extension .bim.

Example:

Write .bed, .fam, and .bim files with non-standard names.

use ndarray as nd;
use bed_reader::{WriteOptions,tmp_path};
let output_folder = tmp_path()?;
let output_file = output_folder.join("small.deb");
let val = nd::array![[1, 0, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]];
WriteOptions::builder(output_file)
    .fam_path(output_folder.join("small.maf"))
    .bim_path(output_folder.join("small.mib"))
    .write(&val)?;

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

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

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

Example

Extract metadata from a file. Create a random file with the same metadata.

use ndarray as nd;
use bed_reader::{Bed, WriteOptions, tmp_path, sample_bed_file};
use ndarray_rand::{rand::prelude::StdRng, rand::SeedableRng, rand_distr::Uniform, RandomExt};

let mut bed = Bed::new(sample_bed_file("small.bed")?)?;
let metadata = bed.metadata()?;
let shape = bed.dim()?;

let mut rng = StdRng::seed_from_u64(0);
let val = nd::Array::random_using(shape, Uniform::from(-1..3), &mut rng);

let temp_out = tmp_path()?;
let output_file = temp_out.join("random.bed");
WriteOptions::builder(output_file)
    .metadata(&metadata)
    .missing_value(-1)
    .write(&val)?;

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.

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

Count the number allele 2.

Also see is_a1_counted and count_a1.

pub fn is_a1_counted(&mut self, is_a1_counted: 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, num_threads: usize) -> &mut Self

Number of threads to use (defaults to all processors)

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

Example:

Write using only one thread.

use ndarray as nd;
use bed_reader::{WriteOptions, tmp_path};
let output_folder = tmp_path()?;
let output_file = output_folder.join("small.bed");
let val = nd::array![[1, 0, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]];
WriteOptions::builder(output_file)
    .num_threads(1)
    .write(&val)?;

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

Skip writing .fam file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions, tmp_path};
let output_folder = tmp_path()?;
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .i8()
    .skip_fam()
    .skip_bim()
    .build(3, 4)?;
assert!(write_options.skip_fam());
assert!(write_options.skip_bim());

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

Skip writing .bim file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions, tmp_path};
let output_folder = tmp_path()?;
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .i8()
    .skip_fam()
    .skip_bim()
    .build(3, 4)?;
assert!(write_options.skip_fam());
assert!(write_options.skip_bim());

pub fn build(
    &self,
    iid_count: usize,
    sid_count: usize
) -> Result<WriteOptions<TVal>, BedErrorPlus>

Creates a new WriteOptions with the options given.

Also see WriteOptionsBuilder::write, which creates a WriteOptions and writes to file in one step.

Example

Create a new WriteOptions with some given values and some default values. Then use it to write a .bed file.

use ndarray as nd;
use bed_reader::{WriteOptions, tmp_path, Bed};

let output_folder = tmp_path()?;
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .f64()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build(3, 4)?;
println!("{0:?}", write_options.fid()); // Outputs ndarray ["0", "0", "0"]
println!("{0:?}", write_options.iid()); // Outputs ndarray ["i1", "i2", "i3"]

let 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]
];
Bed::write_with_options(&val, &write_options)?;

impl WriteOptionsBuilder<i8>

pub fn i8(self) -> Self

The input ndarray will be i8.

impl WriteOptionsBuilder<f32>

pub fn f32(self) -> Self

The input ndarray will be f32.

impl WriteOptionsBuilder<f64>

pub fn f64(self) -> Self

The input ndarray will be f64.

Trait Implementations

impl<TVal: Clone> Clone for WriteOptionsBuilder<TVal> where
    TVal: BedVal, 

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<TVal: Clone> Default for WriteOptionsBuilder<TVal> where
    TVal: BedVal, 

fn default() -> Self

Returns the “default value” for a type.