Struct Saf 

pub struct Saf<const N: usize> { /* private fields */ }

Joint SAF likelihood matrix for N populations.

Internally, the matrix is represented with each site in continuous memory. That is, the first values are those from the first site of all populations, then comes the next site, and so on. Saf::shape gives the number of values per site per population. This should only be important when operating directly on the underlying storage, e.g. using Saf::as_slice or Saf::as_mut_slice.

Implementations

impl<const N: usize> Saf<N>

pub fn as_mut_slice(&mut self) -> &mut [f32]

Returns a mutable reference to the values of the SAF as a flat slice.

See the Saf documentation for details on the storage order.

pub fn iter_mut(&mut self) -> IterMut<'_, f32>

Returns an iterator over mutable references to all values in the SAF.

See the Saf documentation for details on the storage order.

pub fn iter_blocks(&self, block_size: usize) -> BlockIter<'_, N>

Returns an iterator over blocks of sites in the SAF.

If the number of sites in the SAF is not evenly divided by block_size, the last block will be smaller than the others.

Examples

use winsfs_core::saf1d;
let saf = saf1d![
    [0.0,  0.1,  0.2],
    [0.3,  0.4,  0.5],
    [0.6,  0.7,  0.8],
    [0.9,  0.10, 0.11],
    [0.12, 0.13, 0.14],
];
let mut iter = saf.iter_blocks(2);
assert_eq!(
    iter.next().unwrap(),
    saf1d![[0.0, 0.1, 0.2], [0.3, 0.4, 0.5]].view()
);
assert_eq!(
    iter.next().unwrap(),
    saf1d![[0.6, 0.7, 0.8], [0.9, 0.10, 0.11]].view()
);
assert_eq!(iter.next().unwrap(), saf1d![[0.12, 0.13, 0.14]].view());
assert!(iter.next().is_none());

pub fn iter_sites(&self) -> SiteIter<'_, N>

Returns an iterator over the sites in the SAF.

Examples

use winsfs_core::saf1d;
let saf = saf1d![
    [0.0,  0.1,  0.2],
    [0.3,  0.4,  0.5],
    [0.6,  0.7,  0.8],
];
let mut iter = saf.iter_sites();
assert_eq!(iter.next().unwrap().as_slice(), [0.0,  0.1,  0.2]);
assert_eq!(iter.next().unwrap().as_slice(), [0.3,  0.4,  0.5]);
assert_eq!(iter.next().unwrap().as_slice(), [0.6,  0.7,  0.8]);
assert!(iter.next().is_none());

pub fn new(values: Vec<f32>, shape: [usize; N]) -> Result<Self, ShapeError<N>>

Returns a new SAF.

The number of provided values must be a multiple of the sum of shapes. See the Saf documentation for details on the storage order.

Examples

use winsfs_core::{saf::Saf, saf2d};
let vec = vec![0.0, 0.1, 0.2, 1.0, 1.1, 0.3, 0.4, 0.5, 1.2, 1.3];
let shape = [3, 2];
assert_eq!(
    Saf::new(vec, shape).unwrap(),
    saf2d![
        [0.0,  0.1,  0.2 ; 1.0, 1.1],
        [0.3,  0.4,  0.5 ; 1.2, 1.3],
    ],
);

A ShapeError is thrown if the shape does not fit the number of values:

use winsfs_core::saf::Saf;
let vec = vec![0.0, 0.1, 0.2, 1.0, 1.1, 0.3, 0.4, 0.5, 1.2, 1.3];
let wrong_shape = [4, 2];
assert!(Saf::new(vec, wrong_shape).is_err());

pub fn par_iter_blocks(&self, block_size: usize) -> ParBlockIter<'_, N>

Returns a parallel iterator over the blocks in the SAF.

This is the parallel version of Saf::iter_blocks. If the number of sites in the SAF is not evenly divided by block_size, the last block will be smaller than the others.

Examples

use winsfs_core::{saf::SafView, saf1d};
use rayon::iter::ParallelIterator;
let saf = saf1d![
    [0.0,  0.1,  0.2],
    [0.3,  0.4,  0.5],
    [0.6,  0.7,  0.8],
    [0.9,  0.10, 0.11],
    [0.12, 0.13, 0.14],
];
let blocks: Vec<SafView<1>> = saf.par_iter_blocks(2).collect();
assert_eq!(blocks.len(), 3);
assert_eq!(
    blocks[0],
    saf1d![[0.0, 0.1, 0.2], [0.3, 0.4, 0.5]].view()
);
assert_eq!(
    blocks[1],
    saf1d![[0.6, 0.7, 0.8], [0.9, 0.10, 0.11]].view()
);
assert_eq!(blocks[2], saf1d![[0.12,  0.13,  0.14]].view());

pub fn par_iter_sites(&self) -> ParSiteIter<'_, N>

Returns a parallel iterator over the sites in the SAF.

This is the parallel version of Saf::iter_sites.

Examples

use winsfs_core::saf1d;
use rayon::iter::ParallelIterator;
let saf = saf1d![
    [1.,  1.,  1.],
    [1.,  1.,  1.],
    [1.,  1.,  1.],
];
saf.par_iter_sites().all(|site| site.as_slice() == &[1., 1., 1.]);

pub fn read<R>(readers: [ReaderV3<R>; N]) -> Result<Self>

where R: BufRead + Seek,

Creates a new SAF by reading intersecting sites among SAF readers.

SAF files contain values in log-space. The returned values will be exponentiated to get out of log-space.

Panics

Panics if N == 0.

pub fn read_from_banded<R>(readers: [ReaderV4<R>; N]) -> Result<Self>

where R: BufRead + Seek,

Creates a new SAF by reading intersecting sites among banded SAF readers.

SAF files contain values in log-space. The returned values will be exponentiated to get out of log-space.

Note that this simply fills all non-explicitly represented values in the banded SAF with zeros (after getting out of log-space). Hence, this amounts to in some sense “undoing” the banding.

Panics

Panics if N == 0.

pub fn shuffle<R>(&mut self, rng: &mut R)

where R: Rng,

Shuffles the SAF sitewise according to a random permutation.

pub fn view(&self) -> SafView<'_, N>

Returns a view of the entire SAF.

pub fn as_slice(&self) -> &[f32]

Returns the values of the SAF as a flat slice.

See the Saf documentation for details on the storage order.

pub fn iter(&self) -> Iter<'_, f32>

Returns an iterator over all values in the SAF.

See the Saf documentation for details on the storage order.

pub fn get_site(&self, index: usize) -> SiteView<'_, N>

Returns a single site in the SAF.

pub fn sites(&self) -> usize

Returns the number of sites in the SAF.

pub fn shape(&self) -> [usize; N]

Returns the shape of the SAF.

Trait Implementations

impl<'a, const N: usize> AsSafView<N> for &'a Saf<N>

fn as_saf_view(&self) -> <Self as Lifetime<'_>>::Item

Returns a SAF view of self.

impl<const N: usize> AsSafView<N> for Saf<N>

fn as_saf_view(&self) -> <Self as Lifetime<'_>>::Item

Returns a SAF view of self.

impl<const N: usize> Clone for Saf<N>

fn clone(&self) -> Saf<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<const N: usize> Debug for Saf<N>

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

Formats the value using the given formatter.

impl<'a, const N: usize> IntoBlockIterator<N> for &'a Saf<N>

type Item = SafView<'a, N>

The type of each individual block.

type Iter = BlockIter<'a, N>

The type of iterator.

fn into_block_iter(self, block_size: usize) -> Self::Iter

Convert this type into an iterator over SAF blocks containing block_size sites per block.

impl<'a, const N: usize> IntoParallelBlockIterator<N> for &'a Saf<N>

type Item = SafView<'a, N>

The type of each individual block.

type Iter = ParBlockIter<'a, N>

The type of iterator.

fn into_par_block_iter(self, block_size: usize) -> Self::Iter

Convert this type into a parallel iterator over SAF blocks containing block_size sites per block.

impl<'a, const N: usize> IntoParallelSiteIterator<N> for &'a Saf<N>

type Item = SiteView<'a, N>

The type of each individual site.

type Iter = ParSiteIter<'a, N>

The type of iterator.

fn into_par_site_iter(self) -> Self::Iter

Convert this type into a parallel SAF site iterator.

impl<'a, const N: usize> IntoSiteIterator<N> for &'a Saf<N>

type Item = SiteView<'a, N>

The type of each individual site.

type Iter = SiteIter<'a, N>

The type of iterator.

fn into_site_iter(self) -> Self::Iter

Convert this type into a SAF site iterator.

impl<'a, 'b, const N: usize> Lifetime<'a> for &'b Saf<N>

type Item = SafView<'a, N>

The inner item, the lifetime of which should be tied to Self.

impl<'a, const N: usize> Lifetime<'a> for Saf<N>

type Item = SafView<'a, N>

The inner item, the lifetime of which should be tied to Self.

impl<const N: usize> PartialEq for Saf<N>

fn eq(&self, other: &Saf<N>) -> 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<const N: usize> StructuralPartialEq for Saf<N>