Struct stats_ci::comparison::Paired

pub struct Paired<T: Float> { /* private fields */ }

Structure to collect statistics on two paired samples.

Paired observations are when each measurement in the first sample is paired with a measurement in the second sample. For instance, when measuring the performance of two algorithms, the same input data is used for both algorithms to yield a pair of related observations.

When observations cannot naturally be paired, the samples must be compared using unpaired observations (see Unpaired). Typically, unpaired observations require noticeably more observations to achieve the same statistical significance.

Examples

The example below considers the zinc concentration in water samples from a river. Each sample is taken at the same location, but one at the bottom of the river and the other at the surface. Thus, those measurements are paired (bottom and surface). See https://online.stat.psu.edu/stat500/lesson/7/7.3/7.3.2 for details on this example.

// Zinc concentration in water samples from a river
let data_bottom_water = [
    0.430, 0.266, 0.567, 0.531, 0.707, 0.716, 0.651, 0.589, 0.469, 0.723,
];
let data_surface_water = [
    0.415, 0.238, 0.390, 0.410, 0.605, 0.609, 0.632, 0.523, 0.411, 0.612,
];

let mut stats = comparison::Paired::default();
stats.extend(data_bottom_water, data_surface_water).unwrap();
let ci = stats.ci_mean(Confidence::new_two_sided(0.95)).unwrap();

References

• R. Jain, The Art of Computer Systems Performance Analysis, Wiley, 1991.
• Wikipedia article on paired difference test
• PennState. Stat 500. Lesson 7: Comparing Two Population Parameters. Online

Implementations

impl<T: Float> Paired<T>

pub fn append_pair(&mut self, data_a: T, data_b: T) -> CIResult<()>

Add a pair of observations to the two samples.

Arguments

• data_a - the observation for the first sample
• data_b - the observation for the second sample

Errors

• CIError::FloatConversionError - if the conversion to T fails

Examples

let mut stats = comparison::Paired::default();
stats.append_pair(1., 2.)?;

pub fn extend_tuple<I>(&mut self, iter: I) -> CIResult<()>where I: IntoIterator<Item = (T, T)>,

Append multiple pairs of observations to the two samples.

Arguments

• iter - an iterable collection of tuples to add to the data

Errors

• CIError::FloatConversionError - if the conversion to T fails

Examples

let mut stats = comparison::Paired::default();
stats.extend_tuple([(1., 2.), (3., 4.)])?;

pub fn extend<I1, I2>(&mut self, data_a: I1, data_b: I2) -> CIResult<()>where I1: IntoIterator<Item = T>, I2: IntoIterator<Item = T>,

Append multiple observations to the two samples.

Arguments

• data_a - an iterable collection of observations for the first sample
• data_b - an iterable collection of observations for the second sample

Errors

• CIError::DifferentSampleSizes - if the two iterables have different lengths
• CIError::FloatConversionError - if the conversion to T fails

Examples

let mut stats = comparison::Paired::default();
stats.extend([1., 3.], [2., 4.])?;

pub fn sample_mean(&self) -> T

Return the sample mean of the difference between the two samples.

Examples

let data_a = [1., 2., 3.];
let data_b = [4., 5., 6.];
let mut stats = comparison::Paired::default();
stats.extend(data_a, data_b)?;
let mean = stats.sample_mean();
assert_eq!(mean, -3.);

pub fn sample_sem(&self) -> T

Return the standard error of the difference between the two samples.

Examples

let data_a = [1., 2., 3.];
let data_b = [4., 5., 6.];
let mut stats = comparison::Paired::default();
stats.extend(data_a, data_b)?;
let sem = stats.sample_sem();
assert_eq!(sem, 0.);

pub fn sample_count(&self) -> usize

Return the number of sample pairs.

Examples

let data_a = [1., 2., 3.];
let data_b = [4., 5., 6.];
let mut stats = comparison::Paired::default();
stats.extend(data_a, data_b)?;
let count = stats.sample_count();
assert_eq!(count, 3);

pub fn ci_mean(&self, confidence: Confidence) -> CIResult<Interval<T>>

Return the confidence interval of the difference between the means of the two samples.

Arguments

• confidence - the confidence level

Returns

The confidence interval of the difference as a result.

Notes

If the interval includes zero, the difference is not significant. If the interval is strictly positive (resp. negative), the mean of the first sample is significantly greater (resp. smaller) than the mean of the second sample.

Examples

let data_a = [1., 2., 3.];
let data_b = [4., 5., 6.];
let mut stats = comparison::Paired::default();
stats.extend(data_a, data_b)?;
let confidence = Confidence::new_two_sided(0.95);
let ci = stats.ci_mean(confidence)?;
assert_eq!(ci, Interval::new(-3., -3.)?);

pub fn ci( confidence: Confidence, data_a: &[T], data_b: &[T] ) -> CIResult<Interval<T>>

Compute the confidence interval of the difference between the means of the two samples.

Arguments

• confidence - the confidence level
• data_a - the first sample
• data_b - the second sample

Returns

The confidence interval of the difference as a result.

Errors

• CIError::DifferentSampleSizes - if the two samples do not have the same length

Notes

If the interval includes zero, the difference is not significant. If the interval is strictly positive (resp. negative), the mean of the first sample is significantly greater (resp. smaller) than the mean of the second sample.

This function provides a simple interface to obtain the confidence interval with a single call, when the samples are known a priori and there is no need to include additional observations, obtain the confidence intervals for other levels or access the sample statistics. For more refined use cases, it is recommended to use Paired::ci_mean instead.

References

• R. Jain, The Art of Computer Systems Performance Analysis, Wiley, 1991.
• Wikipedia article on paired difference test
• PennState. Stat 500. Lesson 7: Comparing Two Population Parameters. Online

Examples

let data_a = [1., 2., 3.];
let data_b = [4., 5., 6.];
let confidence = Confidence::new_two_sided(0.95);
let ci = comparison::Paired::ci(confidence, &data_a, &data_b)?;

Trait Implementations

impl<F: Float> Add<Paired<F>> for Paired<F>

type Output = Paired<F>

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<F: Float> AddAssign<Paired<F>> for Paired<F>

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl<T: Clone + Float> Clone for Paired<T>

fn clone(&self) -> Paired<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug + Float> Debug for Paired<T>

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

Formats the value using the given formatter.

impl<T: Float> Default for Paired<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: PartialEq + Float> PartialEq<Paired<T>> for Paired<T>

fn eq(&self, other: &Paired<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T: Float> StructuralPartialEq for Paired<T>