Struct Metadata

pub struct Metadata { /* private fields */ }

Represents the metadata from PLINK .fam and .bim files.

Construct with Metadata::builder or Metadata::new.

Example

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

use ndarray as nd;
use bed_reader::{Bed, WriteOptions, 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 = temp_testdir::TempDir::default();
let output_file = temp_out.join("random.bed");
WriteOptions::builder(output_file)
    .metadata(&metadata)
    .missing_value(-1)
    .write(&val)?;

Implementations

impl Metadata

pub fn builder() -> MetadataBuilder

Create a Metadata using a builder.

Example

Create metadata. Create a random file with the metadata.

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

let metadata = Metadata::builder()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build()?;
let mut rng = StdRng::seed_from_u64(0);
let val = nd::Array::random_using((3, 4), Uniform::from(-1..3), &mut rng);
let temp_out = temp_testdir::TempDir::default();
let output_file = temp_out.join("random.bed");
WriteOptions::builder(output_file)
    .metadata(&metadata)
    .missing_value(-1)
    .write(&val)?;

pub fn new() -> Metadata

Create an empty Metadata.

See Metadata::builder()

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

Optional family id of each of individual (sample)

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

Optional individual id of each of individual (sample)

Example:

use ndarray as nd;
use bed_reader::Metadata;
let metadata = Metadata::builder().iid(["i1", "i2", "i3"]).build()?;
println!("{0:?}", metadata.iid()); // Outputs optional ndarray Some(["i1", "i2", "i3"]...)
println!("{0:?}", metadata.sid()); // Outputs None

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

Optional father id of each of individual (sample)

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

Optional mother id of each of individual (sample)

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

Optional sex each of individual (sample)

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

Optional phenotype for each individual (seldom used)

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

Optional chromosome of each SNP (variant)

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

Optional SNP id of each SNP (variant)

Example:

use ndarray as nd;
use bed_reader::Metadata;
let metadata = Metadata::builder().iid(["i1", "i2", "i3"]).build()?;
println!("{0:?}", metadata.iid()); // Outputs optional ndarray Some(["i1", "i2", "i3"]...)
println!("{0:?}", metadata.sid()); // Outputs None

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

Optional centimorgan position of each SNP (variant)

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

Optional base-pair position of each SNP (variant)

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

Optional first allele of each SNP (variant)

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

Optional second allele of each SNP (variant)

pub fn read_fam<AnyPath0>( &self, path: AnyPath0, skip_set: &HashSet<MetadataFields>, ) -> Result<(Metadata, usize), Box<BedErrorPlus>>

where AnyPath0: AsRef<Path>,

Create a new Metadata by filling in empty fields with a .fam file.

Example

Read .fam and .bim information into a Metadata. Do not skip any fields.

use ndarray as nd;
use std::collections::HashSet;
use bed_reader::{Metadata, MetadataFields, sample_file};

let skip_set = HashSet::<MetadataFields>::new();
let metadata_empty = Metadata::new();
let (metadata_fam, iid_count) =
    metadata_empty.read_fam(sample_file("small.fam")?, &skip_set)?;
let (metadata_bim, sid_count) =
    metadata_fam.read_bim(sample_file("small.bim")?, &skip_set)?;
assert_eq!(iid_count, 3);
assert_eq!(sid_count, 4);
println!("{0:?}", metadata_fam.iid()); // Outputs optional ndarray Some(["iid1", "iid2", "iid3"]...)
println!("{0:?}", metadata_bim.sid()); // Outputs optional ndarray Some(["sid1", "sid2", "sid3", "sid4"]...)
println!("{0:?}", metadata_bim.chromosome()); // Outputs optional ndarray Some(["1", "1", "5", "Y"]...)

pub async fn read_fam_cloud( &self, cloud_file: &CloudFile, skip_set: &HashSet<MetadataFields>, ) -> Result<(Metadata, usize), Box<BedErrorPlus>>

Create a new Metadata by filling in empty fields with a .fam file in the cloud.

Example

Read .fam and .bim information into a Metadata. Do not skip any fields.

use ndarray as nd;
use std::collections::HashSet;
use bed_reader::{Metadata, MetadataFields, sample_url, CloudFile};

let skip_set = HashSet::<MetadataFields>::new();
let fam_cloud_file = CloudFile::new(sample_url("small.fam")?)?;
let bim_cloud_file = CloudFile::new(sample_url("small.bim")?)?;
let metadata_empty = Metadata::new();
let (metadata_fam, iid_count) =
    metadata_empty.read_fam_cloud(&fam_cloud_file, &skip_set).await?;
let (metadata_bim, sid_count) =
    metadata_fam.read_bim_cloud(&bim_cloud_file, &skip_set).await?;
assert_eq!(iid_count, 3);
assert_eq!(sid_count, 4);
println!("{0:?}", metadata_fam.iid()); // Outputs optional ndarray Some(["iid1", "iid2", "iid3"]...)
println!("{0:?}", metadata_bim.sid()); // Outputs optional ndarray Some(["sid1", "sid2", "sid3", "sid4"]...)
println!("{0:?}", metadata_bim.chromosome()); // Outputs optional ndarray Some(["1", "1", "5", "Y"]...)

pub fn read_bim<AnyPath0>( &self, path: AnyPath0, skip_set: &HashSet<MetadataFields>, ) -> Result<(Metadata, usize), Box<BedErrorPlus>>

where AnyPath0: AsRef<Path>,

Create a new Metadata by filling in empty fields with a .bim file.

Example

Read .fam and .bim information into a Metadata. Do not skip any fields.

use ndarray as nd;
use std::collections::HashSet;
use bed_reader::{Metadata, MetadataFields, sample_file};

let skip_set = HashSet::<MetadataFields>::new();
let metadata_empty = Metadata::new();
let (metadata_fam, iid_count) =
    metadata_empty.read_fam(sample_file("small.fam")?, &skip_set)?;
let (metadata_bim, sid_count) =
    metadata_fam.read_bim(sample_file("small.bim")?, &skip_set)?;
assert_eq!(iid_count, 3);
assert_eq!(sid_count, 4);
println!("{0:?}", metadata_bim.iid()); // Outputs optional ndarray Some(["iid1", "iid2", "iid3"]...)
println!("{0:?}", metadata_bim.sid()); // Outputs optional ndarray Some(["sid1", "sid2", "sid3", "sid4"]...)
println!("{0:?}", metadata_bim.chromosome()); // Outputs optional ndarray Some(["1", "1", "5", "Y"]...)

pub async fn read_bim_cloud( &self, cloud_file: &CloudFile, skip_set: &HashSet<MetadataFields>, ) -> Result<(Metadata, usize), Box<BedErrorPlus>>

Create a new Metadata by filling in empty fields with a .bim file in the cloud.

Example

Read .fam and .bim information into a Metadata. Do not skip any fields.

use ndarray as nd;
use std::collections::HashSet;
use bed_reader::{Metadata, MetadataFields, sample_url, CloudFile};

let skip_set = HashSet::<MetadataFields>::new();
let fam_cloud_file = CloudFile::new(sample_url("small.fam")?)?;
let bim_cloud_file = CloudFile::new(sample_url("small.bim")?)?;
let metadata_empty = Metadata::new();
let (metadata_fam, iid_count) =
    metadata_empty.read_fam_cloud(&fam_cloud_file, &skip_set).await?;
let (metadata_bim, sid_count) =
    metadata_fam.read_bim_cloud(&bim_cloud_file, &skip_set).await?;
assert_eq!(iid_count, 3);
assert_eq!(sid_count, 4);
println!("{0:?}", metadata_fam.iid()); // Outputs optional ndarray Some(["iid1", "iid2", "iid3"]...)
println!("{0:?}", metadata_bim.sid()); // Outputs optional ndarray Some(["sid1", "sid2", "sid3", "sid4"]...)
println!("{0:?}", metadata_bim.chromosome()); // Outputs optional ndarray Some(["1", "1", "5", "Y"]...)

pub fn write_fam<AnyPath0>( &self, path: AnyPath0, ) -> Result<(), Box<BedErrorPlus>>

where AnyPath0: AsRef<Path>,

Write the metadata related to individuals/samples to a .fam file.

If any of the .fam metadata is not present, the function will return an error.

Example

Create metadata with iid and sid arrays, then fill in the other fields with default arrays, finally write the .fam information to a file.

 use ndarray as nd;
 use std::collections::HashSet;
 use bed_reader::Metadata;

 let metadata0 = Metadata::builder()
     .iid(["i1", "i2", "i3"])
     .sid(["s1", "s2", "s3", "s4"])
     .build()?;
 let metadata_filled = metadata0.fill(3, 4)?;
 let temp_out = temp_testdir::TempDir::default();
 let output_file = temp_out.join("no_bed.fam");
 metadata_filled.write_fam(output_file)?;

pub fn write_bim<AnyPath0>( &self, path: AnyPath0, ) -> Result<(), Box<BedErrorPlus>>

where AnyPath0: AsRef<Path>,

Write the metadata related to SNPs/variants to a .bim file.

If any of the .bim metadata is not present, the function will return an error.

Example

Create metadata with iid and sid arrays, then fill in the other fields with default arrays, finally write the .bim information to a file.

 use ndarray as nd;
 use std::collections::HashSet;
 use bed_reader::Metadata;

 let metadata0 = Metadata::builder()
     .iid(["i1", "i2", "i3"])
     .sid(["s1", "s2", "s3", "s4"])
     .build()?;
 let metadata_filled = metadata0.fill(3, 4)?;
 let temp_out = temp_testdir::TempDir::default();
 let output_file = temp_out.join("no_bed.bim");
 metadata_filled.write_bim(output_file)?;

pub fn fill( &self, iid_count: usize, sid_count: usize, ) -> Result<Metadata, Box<BedErrorPlus>>

Create a new Metadata by filling in empty fields with default values.

Example

use ndarray as nd;
use std::collections::HashSet;
use bed_reader::{Metadata, MetadataFields};

let metadata0 = Metadata::builder()
    .iid(["i1", "i2", "i3"])
    .sid(["s1", "s2", "s3", "s4"])
    .build()?;
let metadata_filled = metadata0.fill(3, 4)?;

println!("{0:?}", metadata_filled.iid()); // Outputs optional ndarray Some(["i1", "i2", "i3"]...)
println!("{0:?}", metadata_filled.sid()); // Outputs optional ndarray Some(["s1", "s2", "s3", "s4"]...)
println!("{0:?}", metadata_filled.chromosome()); // Outputs optional ndarray Some(["0", "0", "0", "0"]...)

Trait Implementations

impl Clone for Metadata

fn clone(&self) -> Metadata

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Metadata

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

Formats the value using the given formatter.

impl Default for Metadata

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for Metadata

fn eq(&self, other: &Metadata) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Metadata