Struct Bed 

pub struct Bed { /* private fields */ }

Represents a PLINK .bed file that is open for reading genotype data and metadata.

Construct with Bed::new or Bed::builder.

For reading cloud files, see BedCloud.

Example

Open a file for reading. Then, read the individual (sample) ids and all the genotype data.

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)?;
println!("{:?}", bed.iid()?); // Outputs ndarray ["iid1", "iid2", "iid3"]
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]
    ],
);

Implementations

impl Bed

pub fn builder<AnyPath0>(path: AnyPath0) -> BedBuilder

where AnyPath0: AsRef<Path>,

Attempts to open a local PLINK .bed file for reading. Supports options.

Also see Bed::new, which does not support options. For reading from the cloud, see BedCloud.

The options, listed here, can:

• set the path of the .fam and/or .bim file
• override some metadata, for example, replace the individual ids.
• set the number of individuals (samples) or SNPs (variants)
• control checking the validity of the .bed file’s header
• skip reading selected metadata

Note that this method is a lazy about holding files, so unlike std::fs::File::open(&path), it will not necessarily lock the file(s).

Errors

By default, this method will return an error if the file is missing or its header is ill-formed. It will also return an error if the options contradict each other. See BedError and BedErrorPlus for all possible errors.

Examples

List individual (sample) iid and SNP (variant) sid, then read the whole file.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::builder(file_name).build()?;
println!("{:?}", bed.iid()?); // Outputs ndarray ["iid1", "iid2", "iid3"]
println!("{:?}", bed.sid()?); // Outputs ndarray ["snp1", "snp2", "snp3", "snp4"]
let val = bed.read::<f64>()?;

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

Replace iid.

let mut bed = Bed::builder(file_name)
   .iid(["sample1", "sample2", "sample3"])
   .build()?;
println!("{:?}", bed.iid()?); // Outputs ndarray ["sample1", "sample2", "sample3"]

Give the number of individuals (samples) and SNPs (variants) so that the .fam and .bim files need never be opened.

let mut bed = Bed::builder(file_name).iid_count(3).sid_count(4).build()?;
let val = bed.read::<f64>()?;

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

Mark some properties as “don’t read or offer”.

let mut bed = Bed::builder(file_name)
    .skip_father()
    .skip_mother()
    .skip_sex()
    .skip_pheno()
    .skip_allele_1()
    .skip_allele_2()
    .build()?;
println!("{:?}", bed.iid()?); // Outputs ndarray ["iid1", "iid2", "iid3"]
bed.allele_2().expect_err("Can't be read");

pub fn new<AnyPath0>(path: AnyPath0) -> Result<Self, Box<BedErrorPlus>>

where AnyPath0: AsRef<Path>,

Attempts to open a local PLINK .bed file for reading. Does not support options.

Also see Bed::builder, which does support options. For reading from the cloud, see BedCloud.

Note that this method is a lazy about holding files, so unlike std::fs::File::open(&path), it will not necessarily lock the file(s).

Errors

By default, this method will return an error if the file is missing or its header is ill-formed. See BedError and BedErrorPlus for all possible errors.

Examples

List individual (sample) iid and SNP (variant) sid, then read the whole file.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
println!("{:?}", bed.iid()?); // Outputs ndarray: ["iid1", "iid2", "iid3"]
println!("{:?}", bed.sid()?); // Outputs ndarray: ["sid1", "sid2", "sid3", "sid4"]
let val = bed.read::<f64>()?;

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

Open the file and read data for one SNP (variant) at index position 2.

let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().sid_index(2).f64().read(&mut bed)?;

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

pub fn iid_count(&mut self) -> Result<usize, Box<BedErrorPlus>>

Number of individuals (samples)

If this number is needed, it will be found by opening the .fam file and quickly counting the number of lines. Once found, the number will be remembered. The file read can be avoided by setting the number with BedBuilder::iid_count or, for example, BedBuilder::iid.

Example:

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

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

assert!(iid_count == 3);

pub fn sid_count(&mut self) -> Result<usize, Box<BedErrorPlus>>

Number of SNPs (variants)

If this number is needed, it will be found by opening the .bim file and quickly counting the number of lines. Once found, the number will be remembered. The file read can be avoided by setting the number with BedBuilder::sid_count or, for example, BedBuilder::sid.

Example:

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

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

assert!(sid_count == 4);

pub fn dim(&mut self) -> Result<(usize, usize), Box<BedErrorPlus>>

Number of individuals (samples) and SNPs (variants)

If these numbers aren’t known, they will be found by opening the .fam and .bim files and quickly counting the number of lines. Once found, the numbers will be remembered. The file read can be avoided by setting the number with BedBuilder::iid_count and BedBuilder::sid_count.

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 dim = bed.dim()?;

assert!(dim == (3,4));

pub fn fid(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Family id of each of individual (sample)

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::fid.

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 fid = bed.fid()?;
println!("{fid:?}"); // Outputs ndarray ["fid1", "fid1", "fid2"]

pub fn iid(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Individual id of each of individual (sample)

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::iid.

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 iid = bed.iid()?;    ///
println!("{iid:?}"); // Outputs ndarray ["iid1", "iid2", "iid3"]

pub fn father(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Father id of each of individual (sample)

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::father.

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 father = bed.father()?;
println!("{father:?}"); // Outputs ndarray ["iid23", "iid23", "iid22"]

pub fn mother(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Mother id of each of individual (sample)

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::mother.

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 mother = bed.mother()?;
println!("{mother:?}"); // Outputs ndarray ["iid34", "iid34", "iid33"]

pub fn sex(&mut self) -> Result<&Array1<i32>, Box<BedErrorPlus>>

Sex each of individual (sample)

0 is unknown, 1 is male, 2 is female

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::sex.

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 sex = bed.sex()?;
println!("{sex:?}"); // Outputs ndarray [1, 2, 0]

pub fn pheno(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

A phenotype for each individual (seldom used)

If this ndarray is needed, it will be found by reading the .fam file. Once found, this ndarray and other information in the .fam file will be remembered. The file read can be avoided by setting the array with BedBuilder::pheno.

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 pheno = bed.pheno()?;
println!("{pheno:?}"); // Outputs ndarray ["red", "red", "blue"]

pub fn chromosome(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Chromosome of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::chromosome.

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 chromosome = bed.chromosome()?;
println!("{chromosome:?}"); // Outputs ndarray ["1", "1", "5", "Y"]

pub fn sid(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

SNP id of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::sid.

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 sid = bed.sid()?;
println!("{sid:?}"); // Outputs ndarray "sid1", "sid2", "sid3", "sid4"]

pub fn cm_position(&mut self) -> Result<&Array1<f32>, Box<BedErrorPlus>>

Centimorgan position of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::cm_position.

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 cm_position = bed.cm_position()?;
println!("{cm_position:?}"); // Outputs ndarray [100.4, 2000.5, 4000.7, 7000.9]

pub fn bp_position(&mut self) -> Result<&Array1<i32>, Box<BedErrorPlus>>

Base-pair position of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::bp_position.

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 bp_position = bed.bp_position()?;
println!("{bp_position:?}"); // Outputs ndarray [1, 100, 1000, 1004]

pub fn allele_1(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

First allele of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::allele_1.

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 allele_1 = bed.allele_1()?;
println!("{allele_1:?}"); // Outputs ndarray ["A", "T", "A", "T"]

pub fn allele_2(&mut self) -> Result<&Array1<String>, Box<BedErrorPlus>>

Second allele of each SNP (variant)

If this ndarray is needed, it will be found by reading the .bim file. Once found, this ndarray and other information in the .bim file will be remembered. The file read can be avoided by setting the array with BedBuilder::allele_2.

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 allele_2 = bed.allele_2()?;
println!("{allele_2:?}"); // Outputs ndarray ["A", "C", "C", "G"]

pub fn metadata(&mut self) -> Result<Metadata, Box<BedErrorPlus>>

Metadata for this dataset, 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 Bed.

If the needed, the metadata will be read from the .fam and/or .bim files.

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

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let metadata = bed.metadata()?;
println!("{0:?}", metadata.iid()); // Outputs Some(["iid1", "iid2", "iid3"] ...)
println!("{0:?}", metadata.sid()); // Outputs Some(["sid1", "sid2", "sid3", "sid4"] ...)

pub fn path(&self) -> &Path

Return the path of the .bed file.

pub fn fam_path(&mut self) -> PathBuf

Return the path of the .fam file.

pub fn bim_path(&mut self) -> PathBuf

Return the path of the .bim file.

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

Read genotype data.

Also see ReadOptions::builder which supports selection and options.

Errors

See BedError and BedErrorPlus for all possible errors.

Examples

Read all data in a .bed file.

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 = bed.read::<f64>()?;

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

// Your output array can be f32, f64, or i8
let val = bed.read::<i8>()?;
assert_eq_nan(
    &val,
    &nd::array![
        [1, 0, -127, 0],
        [2, 0, -127, 2],
        [0, 1, 2, 0]
    ],
);

pub fn read_and_fill_with_options<TVal: BedVal>( &mut self, val: &mut ArrayViewMut2<'_, TVal>, read_options: &ReadOptions<TVal>, ) -> Result<(), Box<BedErrorPlus>>

Read genotype data with options, into a preallocated array.

Also see ReadOptionsBuilder::read_and_fill.

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 read_options = ReadOptions::builder().sid_index(2).build()?;
let mut val = nd::Array2::<f64>::default((3, 1));
bed.read_and_fill_with_options(&mut val.view_mut(), &read_options)?;

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

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

Read all genotype data into a preallocated array.

Also see ReadOptions::builder.

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;

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let mut val = nd::Array2::<i8>::default(bed.dim()?);
bed.read_and_fill(&mut val.view_mut())?;

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

pub fn read_with_options<TVal: BedVal>( &mut self, read_options: &ReadOptions<TVal>, ) -> Result<Array2<TVal>, Box<BedErrorPlus>>

Read genotype data with options.

Also see ReadOptions::builder.

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 read_options = ReadOptions::builder().sid_index(2).f64().build()?;
let val = bed.read_with_options(&read_options)?;

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

pub fn write<S: Data<Elem = TVal>, TVal: BedVal>( val: &ArrayBase<S, Ix2>, path: &Path, ) -> Result<(), Box<BedErrorPlus>>

Write genotype data with default metadata.

Also see WriteOptions::builder, which supports metadata and options.

Errors

See BedError and BedErrorPlus for all possible errors.

Example

In this example, write genotype data using default metadata.

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, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]];
Bed::write(&val, &output_file)?;

// If we then read the new file and list the chromosome property,
// it is an array of zeros, the default chromosome value.
let mut bed2 = Bed::new(&output_file)?;
println!("{:?}", bed2.chromosome()?); // Outputs ndarray ["0", "0", "0", "0"]

pub fn write_with_options<S, TVal>( val: &ArrayBase<S, Ix2>, write_options: &WriteOptions<TVal>, ) -> Result<(), Box<BedErrorPlus>>

where S: Data<Elem = TVal>, TVal: BedVal,

Given an 2D array of genotype data and a WriteOptions, write to a .bed file.

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

Example

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

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

let output_folder = temp_testdir::TempDir::default();
let output_file = output_folder.join("small.bed");
let write_options = WriteOptions::builder(output_file)
    .iid(["iid1", "iid2", "iid3"])
    .sid(["sid1", "sid2", "sid3", "sid4"])
    .build(3,4)?;

Bed::write_with_options(&val, &write_options)?;

Trait Implementations

impl Clone for Bed

fn clone(&self) -> Bed

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Bed

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

Formats the value using the given formatter.