#testing #hypothesis #io #t-test #z-test #chi-squared #pearson

hyte

A hypothesis testing library crate for Z, T, and Pearson's Chi-squared tests

2 releases

0.1.1 Jan 9, 2024
0.1.0 Jan 9, 2024

#6 in #hypothesis

MIT license

55KB
770 lines

Hyte 🦀

MIT License Version example workflow

Hyte is a Hypothesis testing library crate for Rust with support for Z, T, and Pearson's Chi-squared tests.

Documentation 📃 | crates.io 📦 | Source 🌿

Installation

Include the following in your Cargo.toml file.

[dependencies]
hyte = "0.1.0"

Quickstart

The following are collapsible contents, each containing snippets to help you get started.

Performing Z-tests

1-sample Z-test

You can perform a 1-sample Z-test using z::test, a function that takes in the following arguments:

  • data: Vec<Number>
  • expected_mean: Number
  • tail: Tails::LOWER, Tails::UPPER, or Tails::BOTH
  • print_output: bool

where Number is a generic that accepts integers and floats. Here is an example of a how you can perform a lower-tailed 1-sample Z-test:

use hyte::z;
use hyte::utils::Tails;
 
fn main() {
    let data = vec![1, 2, 3, 4, 5];
    let results = z::test(data, 3.5, Tails::LOWER, true).unwrap();
}

Should you need to perform upper-tailed or 2-sided Z-tests, simply pass the Tails::UPPER or Tails::BOTH variants to tail.

1-sample Z-test given numerical summaries

You can alternatively perform Z-tests using the z::test_dataless function which takes in numerical summaries including observed mean, sample size, and population standard deviation, all in replacement of data. The z::test_dataless function takes the following arguments:

  • observed_mean: Number
  • expected_mean: Number
  • sample_size: u32
  • pop_sd: Number
  • tail: Tails::LOWER, Tails::UPPER, or Tails::BOTH
  • print_output: bool

Here is an example:

use hyte::z;
use hyte::utils::Tails;

fn main() {
    let results = z::test_dataless(1.2, 1.0, 30, 0.5, Tails::LOWER, true).unwrap();
}
Performing T-tests

1-sample T-test

You can perform a 1-sample T-test using t::test, a function that takes in the following arguments:

  • data: Vec<Number>
  • expected_mean: Number
  • tail: Tails::LOWER, Tails::UPPER, or Tails::BOTH
  • print_output: bool

where Number is a generic that accepts integers and floats. Here is an example of a how you can perform a lower-tailed 1-sample T-test:

use hyte::t;
use hyte::utils::Tails;

fn main() {
    let data = vec![2.5, 2.9, 3.1, 2.6, 2.7, 2.8, 3.0, 3.2];
    let results = t::test(data, 3, Tails::LOWER, true).unwrap();
}

1-sample T-test given numerical summaries

You can alternatively perform T-tests using the t::test_dataless function which takes in numerical summaries including observed mean, sample size, and population standard deviation, all in replacement of data. The t::test_dataless function takes the following arguments:

  • observed_mean: Number
  • expected_mean: Number
  • sample_size: u32
  • pop_sd: Number
  • tail: Tails::LOWER, Tails::UPPER, or Tails::BOTH
  • print_output: bool

Here is an example:

use hyte::t;
use hyte::utils::Tails;

fn main() {
    let results = t::test_dataless(1.2, 1.0, 30, 0.5, Tails::LOWER, true).unwrap();
}

2-sample T-test

Hyte provides the t::test_two_samples function for performing a 2-sample T-test. It takes in the following arguments:

  • data1: Vec<Number>
  • data2: Vec<Number>
  • print_output: bool

Here's an example:

use hyte::t;

fn main() {
    let group1 = vec![20, 22, 19, 20, 21, 20, 19, 21, 22, 18];
    let group2 = vec![22, 24, 23, 24, 25, 23, 24, 23, 22, 24];
    let results = t::test_two_samples(group1, group2, true).unwrap();
}
Performing Pearson's Chi-squared tests

The chisquare module only contains one funtion chisquare::test which can be used to perform both Pearson's Chi-squared test of independence and goodness of fit. It takes on the following arguments:

  • test_type: &str
  • observed_matrix: Matrix<Number>
  • gof_probabilities: Option<Vec<f64>>
  • print_output: bool

where Matrix<Number> is an enum with two variants: Matrix::TwoDimensional(Vec<Vec<Number>>) and Matrix::OneDimensional(Vec<Number>).

Test of independence

To perform a test of independence, you must pass in:

  • "toi" to test_type
  • Option::None variant to gof_probabilities
  • Matrix::TwoDimensional(Vec<Vec<Number>>) to observed_matrix

Here's an example:

use hyte::chisquare;
use hyte::utils::Matrix;

fn main() {
    let observed_frequencies = Matrix::TwoDimensional(vec![vec![762, 327, 468], 
                                                           vec![484, 239, 477]]);
    let results = chisquare::test(
        "toi", 
        observed_frequencies, 
        None, 
        true
    ).unwrap();
}

Goodness Of Fit

To perform a goodness of fit test, you must pass in:

  • "gof" to test_type
  • Option::Some(f64) variant to gof_probabilities
  • Matrix::OneDimensional(Vec<Number>) to observed_matrix

Here's an example:

use hyte::chisquare;
use hyte::utils::Matrix;

fn main() {
    let results = chisquare::test(
        "gof",
        Matrix::OneDimensional(vec![30, 40, 30]),
        Some(vec![0.25, 0.5, 0.25]),
        true
    ).unwrap();
}
Concluding a test

Concluding with a custom significance level using conclude

Every instance of a test result such as ZResult, TResult, and ChiSquareResult have a method conclude which returns a Conclusion variant (one of Reject or DoNotReject). The conclude method takes in two parameters:

  • significance_level: f64
  • print_output: bool
use hyte::z;
use hyte::utils::Tails;

fn main() {
    let results = z::test(vec![1, 2, 3, 4, 5], 3.5, Tails::LOWER, true).unwrap();
    let conclusion = results.conclude(0.1, true);
}

conclude checks if the p-value assigned to self.p exceeds the significance level. If self.p < significance_level, then conclude will return the Reject variant. Otherwise, it will return the DoNotReject variant.

Concluding conventionally with conclude_by_convention

conclude_by_convention is an alternative to conclude. It assumes a significance level of 0.05, which is widely regarded as an appropriate default in statistics.

use hyte::z;
use hyte::utils::Tails;

fn main() {
    let results = z::test(vec![1, 2, 3, 4, 5], 3.5, Tails::LOWER, true).unwrap();
    let conclusion = results.conclude_by_convention(true);
}

Getting help

The documentation for this crate can be found at docs.rs/hyte. Alternatively, you can print a short manual to the standard output by calling the help function.

use hyte::help;

fn main() {
    help();
}

Dependencies

~6.5MB
~123K SLoC