Struct PopulationMatrix 

pub struct PopulationMatrix { /* private fields */ }

This struct represents the likelihood of different lifestages of an organism to survive, grow, and reproduce to the next lifestage (or stay in the same lifestage) by storing decimal (f64) values in a matrix (a vector of vectors, denoted Vec<Vec<f64>>). Each sub-vector (row) represents a lifestage, and each item (column) represents the yearly proportion of individuals recruited to that lifestage. The first row typically represents newborns, seedlings, etc.

Examples

Index [1][1] is the number of lifestage 1 individuals that were in lifestage 1 the previous year.

Index [1][2] is the number of lifestage 1 indidviduals that were in lifestage 2 the year before.

Indeg [2][1] is the number of lifestage 2 individuals who were lifetage 1 individuals the previous year.

…etc…

An example matrix could look like this: [0][0][0.1][0.2] [0.6][0][0][0] [0][0.8][0][0] [0][0][0.8][0.94]

Implementations

impl PopulationMatrix

pub fn build(input: Vec<Vec<f64>>) -> Result<PopulationMatrix, &'static str>

This function builds a Population Matrix from a square vector of vectors (Vec<Vec>), ensuring that it contains a consistent number of lifestages across all inputted Lifestage Survival Vectors and in the number of inputted Lifestage Survival Vectors. If these conditions are not met, it will return an error message.

pub fn get_lifestage_count(&self) -> u8

Returns the number of listages represented in the Population Matrix, useful for calculations requiring matching numbers of lifestages.

pub fn get_matrix(&self) -> &Vec<Vec<f64>>

Returns the full matrix of matrices stored in the Population Matrix.

pub fn project_vector( &self, vector: &PopulationVector, ) -> Result<PopulationVector, &'static str>

Given an input of a PopulationMatrix and a PopulationVector with the same number of items in their matrix and vector values respectively, the function will return a PopulationMatrix. ##Use This function takes a population matrix (formatted as a PopulationMatrix struct) and a population vector (formatted as a PopulationVector struct) as an imput, calculating the sum of the components of each column of the vector within the population matrix and muliplying it by the value of the population vector at the same index. This is essentially a column-wise matrix-vector product. It then returns a new PopulationVector.

This can be visually thought of as such:

[ 40] [0 , 0 , 0.1 ] [ 10] [ 20] x [0.6, 0.8, 0 ] = [ 40] [100] [0 , 0.8, 0.95] [111]

This calculation is common in Population Variability Analysis (PVA) wherein each row (LifeStageSurvivalVector) represents the probability of recruitment into that life stage over the course of a year. By multiplying a matrix of these probabilities by a vector containing the current population, a researcher can estimate the following year’s population.

Errors

This function will return an Err(‘static str’) if the number of rows or items within rows in the matrix is not equal to the number of items in the population vector.

Although this is theoretically impossible, the program could also panic if it recieves an out-of-bounds index request for the population vector. However, the function checks for this earlier in order to return a useful error code and prevent other mistakes, so should never occur.

Examples

use ecolysis_core::populations::population_level_simulation::{PopulationMatrix, PopulationVector}; // import relevant structs
let popvector = PopulationVector::new(vec![150.0, 200.0, 33.0]); // create a population vector type
let popmatrix = PopulationMatrix::build(vec![
vec![0.25, 0.001, 0.75],
vec![0.3, 0.4346, 0.002],
vec![0.98, 0.66, 0.161]
]).unwrap(); // create a Population Matrix type
let new_popvector = popmatrix.project_vector(&popvector); // project the vector by the matrix
println!("{:?}", new_popvector.unwrap().get_vector()); // print results