use rayon::prelude::*;
use crate::{CompositionError, LabeledMatrix, Result};
#[derive(Clone, Debug, PartialEq)]
pub struct GramMatrix {
rows: Vec<String>,
columns: Vec<String>,
values: Vec<f64>,
}
impl GramMatrix {
#[must_use]
pub fn rows(&self) -> &[String] {
&self.rows
}
#[must_use]
pub fn columns(&self) -> &[String] {
&self.columns
}
#[must_use]
pub fn values(&self) -> &[f64] {
&self.values
}
}
pub fn closure(matrix: &LabeledMatrix) -> Result<LabeledMatrix> {
let rows: Result<Vec<Vec<f64>>> = matrix
.rows()
.zip(matrix.samples())
.map(|(row, sample)| close_row(row, sample, matrix.components()))
.collect();
matrix.same_shape(rows?.into_iter().flatten().collect())
}
pub fn perturb(
matrix: &LabeledMatrix,
operand: &LabeledMatrix,
inverse: bool,
) -> Result<LabeledMatrix> {
let component_order = matrix.component_order_for(operand)?;
let row_order = if operand.sample_count() == 1 {
vec![0; matrix.sample_count()]
} else {
matrix.sample_order_for(operand)?
};
let width = matrix.component_count();
let operand_rows: Result<Vec<Vec<f64>>> = operand
.rows()
.zip(operand.samples())
.map(|(row, sample)| close_row(row, sample, operand.components()))
.collect();
let operand_rows = operand_rows?;
let values: Result<Vec<Vec<f64>>> = matrix
.rows()
.zip(matrix.samples())
.enumerate()
.map(|(row_index, (row, sample))| {
let closed = close_row(row, sample, matrix.components())?;
let operand = &operand_rows[row_order[row_index]];
let mut logs = Vec::with_capacity(width);
for (index, value) in closed.iter().copied().enumerate() {
let other = operand[component_order[index]];
if value == 0.0 || other == 0.0 {
return Err(invalid_component(
matrix,
row_index,
index,
value.min(other),
"strictly positive for perturbation",
));
}
logs.push(value.ln() + if inverse { -other.ln() } else { other.ln() });
}
softmax(&logs, sample, matrix.components())
})
.collect();
matrix.same_shape(values?.into_iter().flatten().collect())
}
pub fn power(matrix: &LabeledMatrix, exponent: f64) -> Result<LabeledMatrix> {
if !exponent.is_finite() {
return Err(CompositionError::NonFiniteScalar(exponent));
}
let values: Result<Vec<Vec<f64>>> = matrix
.rows()
.zip(matrix.samples())
.enumerate()
.map(|(row_index, (row, sample))| {
validate_nonnegative(matrix, row_index, row)?;
if exponent == 0.0 {
return Ok(vec![1.0 / row.len() as f64; row.len()]);
}
if exponent < 0.0
&& let Some(index) = row.iter().position(|&value| value == 0.0)
{
return Err(invalid_component(
matrix,
row_index,
index,
0.0,
"strictly positive for a negative power",
));
}
let logs: Vec<f64> = row
.iter()
.map(|&value| {
if value == 0.0 {
f64::NEG_INFINITY
} else {
exponent * value.ln()
}
})
.collect();
softmax(&logs, sample, matrix.components())
})
.collect();
matrix.same_shape(values?.into_iter().flatten().collect())
}
pub fn centralize(matrix: &LabeledMatrix) -> Result<LabeledMatrix> {
let closed = closure(matrix)?;
let width = matrix.component_count();
let mut center = vec![0.0; width];
for (row_index, row) in closed.rows().enumerate() {
validate_positive(&closed, row_index, row)?;
for (sum, &value) in center.iter_mut().zip(row) {
*sum += value.ln();
}
}
for value in &mut center {
*value /= matrix.sample_count() as f64;
}
let values: Result<Vec<Vec<f64>>> = closed
.rows()
.zip(closed.samples())
.map(|(row, sample)| {
let logs: Vec<f64> = row
.iter()
.zip(¢er)
.map(|(&value, ¢er)| value.ln() - center)
.collect();
softmax(&logs, sample, closed.components())
})
.collect();
matrix.same_shape(values?.into_iter().flatten().collect())
}
pub fn inner(left: &LabeledMatrix, right: &LabeledMatrix) -> Result<GramMatrix> {
inner_with_limit(left, right, crate::DEFAULT_MAX_DENSE_CELLS)
}
pub fn inner_with_limit(
left: &LabeledMatrix,
right: &LabeledMatrix,
maximum_cells: usize,
) -> Result<GramMatrix> {
let mut values = crate::limits::dense_vec(
"Aitchison inner-product matrix",
left.sample_count(),
right.sample_count(),
maximum_cells,
0.0,
)?;
let component_order = left.component_order_for(right)?;
let left_clr = crate::clr(left)?;
let right_clr = crate::clr(right)?;
let width = left.component_count();
let right_rows: Vec<&[f64]> = right_clr.rows().collect();
values
.par_chunks_mut(right.sample_count())
.zip(left_clr.values().par_chunks(width))
.for_each(|(output, left_row)| {
for (slot, right_row) in output.iter_mut().zip(&right_rows) {
*slot = left_row
.iter()
.enumerate()
.map(|(index, &value)| value * right_row[component_order[index]])
.sum();
}
});
Ok(GramMatrix {
rows: left.samples().to_vec(),
columns: right.samples().to_vec(),
values,
})
}
pub(crate) fn close_row(row: &[f64], sample: &str, components: &[String]) -> Result<Vec<f64>> {
let mut maximum = 0.0_f64;
for (index, &value) in row.iter().enumerate() {
if !value.is_finite() {
return Err(CompositionError::NonFinite {
sample: sample.to_owned(),
component: components[index].clone(),
value,
});
}
if value < 0.0 {
return Err(CompositionError::InvalidComponent {
sample: sample.to_owned(),
component: components[index].clone(),
value,
requirement: "non-negative",
});
}
maximum = maximum.max(value);
}
if maximum == 0.0 {
return Err(CompositionError::EmptyComposition(sample.to_owned()));
}
let scaled_sum: f64 = row.iter().map(|&value| value / maximum).sum();
Ok(row
.iter()
.map(|&value| (value / maximum) / scaled_sum)
.collect())
}
pub(crate) fn validate_positive(
matrix: &LabeledMatrix,
row_index: usize,
row: &[f64],
) -> Result<()> {
validate_nonnegative(matrix, row_index, row)?;
if let Some(index) = row.iter().position(|&value| value == 0.0) {
return Err(invalid_component(
matrix,
row_index,
index,
0.0,
"strictly positive",
));
}
Ok(())
}
pub(crate) fn validate_nonnegative(
matrix: &LabeledMatrix,
row_index: usize,
row: &[f64],
) -> Result<()> {
for (index, &value) in row.iter().enumerate() {
if !value.is_finite() {
return Err(CompositionError::NonFinite {
sample: matrix.samples()[row_index].clone(),
component: matrix.components()[index].clone(),
value,
});
}
if value < 0.0 {
return Err(invalid_component(
matrix,
row_index,
index,
value,
"non-negative",
));
}
}
if !row.iter().any(|&value| value > 0.0) {
return Err(CompositionError::EmptyComposition(
matrix.samples()[row_index].clone(),
));
}
Ok(())
}
pub(crate) fn softmax(
coordinates: &[f64],
sample: &str,
components: &[String],
) -> Result<Vec<f64>> {
for (index, &value) in coordinates.iter().enumerate() {
if value.is_nan() || value == f64::INFINITY {
return Err(CompositionError::NonFiniteCoordinate {
sample: sample.to_owned(),
component: components[index].clone(),
});
}
}
let maximum = coordinates
.iter()
.copied()
.fold(f64::NEG_INFINITY, f64::max);
if maximum == f64::NEG_INFINITY {
return Err(CompositionError::EmptyComposition(sample.to_owned()));
}
let mut output: Vec<f64> = coordinates
.iter()
.map(|&value| (value - maximum).exp())
.collect();
let sum: f64 = output.iter().sum();
for value in &mut output {
*value /= sum;
}
Ok(output)
}
fn invalid_component(
matrix: &LabeledMatrix,
row: usize,
component: usize,
value: f64,
requirement: &'static str,
) -> CompositionError {
CompositionError::InvalidComponent {
sample: matrix.samples()[row].clone(),
component: matrix.components()[component].clone(),
value,
requirement,
}
}
#[cfg(test)]
mod tests {
use super::*;
fn matrix(values: &[f64]) -> LabeledMatrix {
LabeledMatrix::new(
vec!["s1".into(), "s2".into()],
vec!["a".into(), "b".into(), "c".into()],
values.to_vec(),
)
.unwrap()
}
#[test]
fn closure_is_stable_at_extreme_scale() {
let result = closure(&matrix(&[f64::MAX, f64::MAX, 0.0, 1e-300, 2e-300, 3e-300])).unwrap();
assert_eq!(&result.values()[..3], &[0.5, 0.5, 0.0]);
assert!((result.values()[3] - 1.0 / 6.0).abs() < 1e-15);
assert!((result.values()[5] - 0.5).abs() < 1e-15);
}
#[test]
fn perturb_aligns_components_and_samples() {
let input = matrix(&[1.0, 2.0, 7.0, 2.0, 3.0, 5.0]);
let operand = LabeledMatrix::new(
vec!["broadcast".into()],
vec!["c".into(), "a".into(), "b".into()],
vec![2.0, 3.0, 1.0],
)
.unwrap();
let forward = perturb(&input, &operand, false).unwrap();
let back = perturb(&forward, &operand, true).unwrap();
let closed = closure(&input).unwrap();
for (&actual, &expected) in back.values().iter().zip(closed.values()) {
assert!((actual - expected).abs() < 1e-12);
}
}
#[test]
fn zero_power_is_uniform() {
let result = power(&matrix(&[0.0, 2.0, 3.0, 1.0, 2.0, 3.0]), 0.0).unwrap();
assert!(
result
.values()
.iter()
.all(|&value| (value - 1.0 / 3.0).abs() < 1e-15)
);
}
#[test]
fn centralize_matches_skbio_example() {
let table = LabeledMatrix::new(
vec!["s1".into(), "s2".into()],
vec!["a".into(), "b".into(), "c".into(), "d".into()],
vec![0.1, 0.3, 0.4, 0.2, 0.2, 0.2, 0.2, 0.4],
)
.unwrap();
let expected = [
0.17445763, 0.30216948, 0.34891526, 0.17445763, 0.32495488, 0.18761279, 0.16247744,
0.32495488,
];
for (&actual, expected) in centralize(&table).unwrap().values().iter().zip(expected) {
assert!((actual - expected).abs() < 1e-7);
}
}
#[test]
fn inner_is_clr_dot_product() {
let left = LabeledMatrix::new(
vec!["x".into()],
vec!["a".into(), "b".into(), "c".into(), "d".into()],
vec![0.1, 0.3, 0.4, 0.2],
)
.unwrap();
let right = LabeledMatrix::new(
vec!["y".into()],
vec!["d".into(), "c".into(), "b".into(), "a".into()],
vec![0.2, 0.2, 0.4, 0.2],
)
.unwrap();
assert!((inner(&left, &right).unwrap().values()[0] - 0.210785247375243).abs() < 1e-12);
}
#[test]
fn inner_limit_fails_before_computation() {
let input = matrix(&[1.0, 2.0, 3.0, 2.0, 3.0, 4.0]);
assert!(matches!(
inner_with_limit(&input, &input, 3),
Err(CompositionError::DenseMatrixTooLarge { .. })
));
}
}