Struct WriteOptions

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

Represents options for writing genotype data and metadata to a PLINK .bed file.

Construct with WriteOptions::builder.

Implementations

impl<TVal> WriteOptions<TVal>

where TVal: BedVal,

pub fn builder<AnyPath0>(path: AnyPath0) -> WriteOptionsBuilder<TVal>

where AnyPath0: AsRef<Path>,

Write values to a file in PLINK .bed format. Supports metadata and options.

Also see Bed::write, which does not support metadata or options.

The options, listed here, can specify the:

• items of metadata, for example the individual ids or the SNP ids
• a non-default path for the .fam and/or .bim files
• a non-default value that represents missing data
• whether the first allele is counted (default) or the second
• number of threads to use for writing
• a Metadata

Examples

In this example, all metadata is given one item at a time.

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

let output_folder = temp_testdir::TempDir::default();
let output_file = output_folder.join("small.bed");
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]
];
WriteOptions::builder(output_file)
    .fid(["fid1", "fid1", "fid2"])
    .iid(["iid1", "iid2", "iid3"])
    .father(["iid23", "iid23", "iid22"])
    .mother(["iid34", "iid34", "iid33"])
    .sex([1, 2, 0])
    .pheno(["red", "red", "blue"])
    .chromosome(["1", "1", "5", "Y"])
    .sid(["sid1", "sid2", "sid3", "sid4"])
    .cm_position([100.4, 2000.5, 4000.7, 7000.9])
    .bp_position([1, 100, 1000, 1004])
    .allele_1(["A", "T", "A", "T"])
    .allele_2(["A", "C", "C", "G"])
    .write(&val)?;

Here, no metadata is given, so default values are assigned. If we then read the new file and list the chromosome property, it is an array of zeros, the default chromosome value.

let output_file2 = output_folder.join("small2.bed");
let val = nd::array![[1, 0, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]];

WriteOptions::builder(&output_file2).write(&val)?;

let mut bed2 = Bed::new(&output_file2)?;
println!("{:?}", bed2.chromosome()?); // Outputs ndarray ["0", "0", "0", "0"]

pub fn fid(&self) -> &Array1<String>

Family id of each of individual (sample). Defaults to “0”’s

Example

use ndarray as nd;
use bed_reader::{WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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"]

pub fn iid(&self) -> &Array1<String>

Individual id of each of individual (sample). Defaults to “iid1”, “iid2” …

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.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)?;

pub fn father(&self) -> &Array1<String>

Father id of each of individual (sample). Defaults to “0”’s

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.father()); // Outputs ndarray ["0", "0", "0"]

pub fn mother(&self) -> &Array1<String>

Mother id of each of individual (sample). Defaults to “0”’s

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.mother()); // Outputs ndarray ["0", "0", "0"]

pub fn sex(&self) -> &Array1<i32>

Sex of each of individual (sample). Defaults to 0’s

0 is unknown, 1 is male, 2 is female

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.sex()); // Outputs ndarray [0, 0, 0]

pub fn pheno(&self) -> &Array1<String>

Phenotype of each of individual (sample). Seldom used. Defaults to 0’s

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.pheno()); // Outputs ndarray ["0", "0", "0"]

pub fn chromosome(&self) -> &Array1<String>

Chromosome of each of SNP (variant). Defaults to “0”’s

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.chromosome()); // Outputs ndarray ["0", "0", "0", "0"]

pub fn sid(&self) -> &Array1<String>

SNP id of each of SNP (variant). Defaults to “sid1”, “sid2”, …

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.sid()); // Outputs ndarray ["s1", "s2", "s3", "s4"]

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

pub fn cm_position(&self) -> &Array1<f32>

Centimorgan position of each SNP (variant). Defaults to 0.0’s.

Example

use ndarray as nd;
use bed_reader::WriteOptions;
let output_folder = temp_testdir::TempDir::default();
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.cm_position()); // Outputs ndarray [0.0, 0.0, 0.0, 0.0]

pub fn bp_position(&self) -> &Array1<i32>

Base-pair position of each SNP (variant). Defaults to 0’s.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.bp_position()); // Outputs ndarray [0, 0, 0, 0]

pub fn allele_1(&self) -> &Array1<String>

First allele of each SNP (variant). Defaults to “A1”

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.allele_1()); // Outputs ndarray ["A1", "A1", "A1", "A1"]
println!("{0:?}", write_options.allele_2()); // Outputs ndarray ["A2", "A2", "A2", "A2"]

pub fn allele_2(&self) -> &Array1<String>

Second allele of each SNP (variant). Defaults to “A2”

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.allele_1()); // Outputs ndarray ["A1", "A1", "A1", "A1"]
println!("{0:?}", write_options.allele_2()); // Outputs ndarray ["A2", "A2", "A2", "A2"]

pub fn metadata(&self) -> Metadata

Metadata for this WriteOptions, for example, the individual (sample) Ids.

This returns a struct with 12 fields. Each field is a ndarray. The struct will always be new, but the 12 ndarrays will be shared with this WriteOptions.

If the needed, default values will be used.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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)?;

let metadata = write_options.metadata();
println!("{0:?}", metadata.iid()); // Outputs optional ndarray Some(["i1", "i2", "i3"])

pub fn iid_count(&self) -> usize

The number of individuals (samples)

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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)?;

assert_eq!(write_options.iid_count(), 3);
assert_eq!(write_options.sid_count(), 4);

pub fn sid_count(&self) -> usize

The number of SNPs (variants)

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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)?;

assert_eq!(write_options.iid_count(), 3);
assert_eq!(write_options.sid_count(), 4);

pub fn dim(&self) -> (usize, usize)

Number of individuals (samples) and SNPs (variants)

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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)?;

assert_eq!(write_options.dim(), (3, 4));

pub fn path(&self) -> &PathBuf

Path to .bed file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.path()); // Outputs "...small.bed"
println!("{0:?}", write_options.fam_path()); // Outputs "...small.fam"
println!("{0:?}", write_options.bim_path()); // Outputs "...small.bim"

pub fn fam_path(&self) -> &PathBuf

Path to .fam file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.path()); // Outputs "...small.bed"
println!("{0:?}", write_options.fam_path()); // Outputs "...small.fam"
println!("{0:?}", write_options.bim_path()); // Outputs "...small.bim"

pub fn bim_path(&self) -> &PathBuf

Path to .bim file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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.path()); // Outputs "...small.bed"
println!("{0:?}", write_options.fam_path()); // Outputs "...small.fam"
println!("{0:?}", write_options.bim_path()); // Outputs "...small.bim"

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, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .i8()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build(3, 4)?;

assert!(write_options.is_a1_counted());

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, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .i8()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build(3, 4)?;

assert!(write_options.num_threads().is_none());

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, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .i8()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build(3, 4)?;

assert!(write_options.missing_value() == -127);

pub fn skip_fam(&self) -> bool

If skipping writing .fam file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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(&self) -> bool

If skipping writing .bim file.

Example

use ndarray as nd;
use bed_reader::{Bed, WriteOptions};
let output_folder = temp_testdir::TempDir::default();
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());

Trait Implementations

impl<TVal> Clone for WriteOptions<TVal>

where TVal: BedVal + Clone,

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<TVal> Debug for WriteOptions<TVal>

where TVal: BedVal + Debug,

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

Formats the value using the given formatter.