Struct Spectrum

pub struct Spectrum<S: State> { /* private fields */ }

A site spectrum.

The spectrum may either be over frequencies (Sfs) or counts (Scs).

Implementations

impl<S: State> Spectrum<S>

pub fn dimensions(&self) -> usize

Returns the number of dimensions of the spectrum.

pub fn elements(&self) -> usize

Returns the number of elements in the spectrum.

pub fn fold(&self) -> Folded<S>

Returns a folded spectrum.

pub fn inner(&self) -> &Array<f64>

Returns the underlying array.

pub fn into_normalized(self) -> Sfs

Returns a normalized frequency spectrum, consuming self.

pub fn iter_frequencies(&self) -> FrequenciesIter<'_>

Returns an iterator over the allele frequencies of the elements in the spectrum in row-major order.

Note that this is not an iterator over frequencies in the sense of a frequency spectrum, but in the sense of allele frequencies corresponding to indices in a spectrum.

pub fn king(&self) -> Result<f64, StatisticError>

Returns the King statistic.

See Manichaikul (2010) and Waples (2019) for details.

Errors

If the spectrum is not a 3x3 2-dimensional spectrum.

pub fn marginalize(&self, axes: &[Axis]) -> Result<Self, MarginalizationError>

Returns a spectrum with the provided axes marginalized out.

Errors

If the provided axes contain duplicates, or if any of them are out of bounds.

pub fn normalize(&mut self)

Normalizes the spectrum to frequencies in-place.

See also Spectrum::into_normalized to normalize and convert to an Sfs at the type-level.

pub fn pi(&self) -> Result<f64, StatisticError>

Returns the average number of pairwise differences, also known as π.

Errors

If the spectrum is not a 1-dimensional spectrum.

pub fn pi_xy(&self) -> Result<f64, StatisticError>

Returns the average number of pairwise differences between two populations, also known as πₓᵧ or Dₓᵧ.

See Nei and Li (1987).

Errors

If the spectrum is not a 1-dimensional spectrum.

pub fn project<T>(&self, project_to: T) -> Result<Self, ProjectionError>

where T: Into<Shape>,

Returns a spectrum projected down to a shape.

The projection is based on hypergeometric down-sampling. See Marth (2004) and Gutenkunst (2009) for details. Note that projecting a spectrum after creation may cause problems; prefer projecting site-wise during creation where possible.

Errors

Errors if the projected shape is not valid for the provided spectrum.

pub fn r0(&self) -> Result<f64, StatisticError>

Returns the R0 statistic.

See Waples (2019) for details.

Errors

If the spectrum is not a 3x3 2-dimensional spectrum.

pub fn r1(&self) -> Result<f64, StatisticError>

Returns the R0 statistic.

See Waples (2019) for details.

Errors

If the spectrum is not a 3x3 2-dimensional spectrum.

pub fn shape(&self) -> &Shape

Returns the shape of the spectrum.

pub fn sum(&self) -> f64

Returns the sum of elements in the spectrum.

pub fn theta_watterson(&self) -> Result<f64, StatisticError>

Returns Watterson’s estimator of the mutation-scaled effective population size θ.

Errors

If the spectrum is not a 1-dimensional spectrum.

impl Spectrum<Counts>

pub fn d_fu_li(&self) -> Result<f64, StatisticError>

Returns Fu and Li’s D difference statistic.

See Fu and Li (1993).

Errors

If the spectrum is not a 1-dimensional spectrum.

pub fn d_tajima(&self) -> Result<f64, StatisticError>

Returns Tajima’s D difference statistic.

See Tajima (1989).

Errors

If the spectrum is not a 1-dimensional spectrum.

pub fn from_range<S>(range: Range<usize>, shape: S) -> Result<Self, ShapeError>

where S: Into<Shape>,

Creates a new spectrum from a range and a shape.

This is mainly intended for testing and illustration.

Errors

If the number of items in the range does not match the provided shape.

pub fn from_vec<T>(vec: T) -> Self

where T: Into<Vec<f64>>,

Creates a new one-dimensional spectrum from a vector.

pub fn from_zeros<S>(shape: S) -> Self

where S: Into<Shape>,

Creates a new spectrum filled with zeros to a shape.

pub fn inner_mut(&mut self) -> &mut Array<f64>

Returns a mutable reference to the underlying array.

pub fn new<D, S>(data: D, shape: S) -> Result<Self, ShapeError>

where D: Into<Vec<f64>>, S: Into<Shape>,

Creates a new spectrum from data in row-major order and a shape.

Errors

If the number of items in the data does not match the provided shape.

pub fn segregating_sites(&self) -> f64

Returns the number of sites segregating in any population in the spectrum.

impl Spectrum<Frequencies>

pub fn f2(&self) -> Result<f64, StatisticError>

Returns the f₂ statistic.

See Reich (2009) and Peter (2016) for details.

Errors

If the spectrum is not a 2-dimensional spectrum.

pub fn f3(&self) -> Result<f64, StatisticError>

Returns the f₃(A; B, C)-statistic, where A, B, C is in the order of the populations in the spectrum.

Note that f₃ may also be calculated as a linear combination of f₂, which is often going to be more efficient and flexible.

See Reich (2009) and Peter (2016) for details.

Errors

If the spectrum is not a 3-dimensional spectrum.

pub fn f4(&self) -> Result<f64, StatisticError>

Returns the f₄(A, B; C, D)-statistic, where A, B, C is in the order of the populations in the spectrum.

Note that f₄ may also be calculated as a linear combination of f₂, which is often going to be more efficient and flexible.

See Reich (2009) and Peter (2016) for details.

Errors

If the spectrum is not a 4-dimensional spectrum.

pub fn fst(&self) -> Result<f64, StatisticError>

Returns Hudson’s estimator of Fst.

See Bhatia (2013) for details. (This uses a “ratio of estimates” as recommended there.)

Errors

If the spectrum is not a 2-dimensional spectrum.

Trait Implementations

impl<S: State> Clone for Spectrum<S>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<S: State> Debug for Spectrum<S>

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

Formats the value using the given formatter.

impl<I, S: State> Index<I> for Spectrum<S>

where I: AsRef<[usize]>,

type Output = f64

The returned type after indexing.

fn index(&self, index: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<I, S: State> IndexMut<I> for Spectrum<S>

where I: AsRef<[usize]>,

fn index_mut(&mut self, index: I) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<S: PartialEq + State> PartialEq for Spectrum<S>

fn eq(&self, other: &Spectrum<S>) -> 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<S: State> StructuralPartialEq for Spectrum<S>