Struct net_ensembles::sampling::HeatmapF64

pub struct HeatmapF64<HistWidth, HistHeight> { /* fields omitted */ }

Heatmap

• stores heatmap in row-major order: the rows of the heatmap are contiguous, and the columns are strided
• enables you to quickly create a heatmap
• you can create gnuplot scripts to plot the heatmap
• you can transpose the heatmap
• …

Implementations

impl<HistWidth, HistHeight> HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Clone,
    HistHeight: Clone, 

pub fn transpose(&self) -> HeatmapF64<HistHeight, HistWidth>

Use this to get a “flipped” heatmap

• creates a transposed heatmap
• also look at self.transpose_inplace

impl<HistWidth, HistHeight> HeatmapF64<HistWidth, HistHeight>

pub fn transpose_inplace(self) -> HeatmapF64<HistHeight, HistWidth>

Use this to get a “flipped” heatmap

• transposes the heatmap inplace

pub fn get(&self, x: usize, y: usize) -> Option<f64>

Returns value stored in the heatmap at specified coordinates, or None, if out of Bounds

pub fn get_row(&self, y: usize) -> Option<&[f64]>

row of the heatmap

• None if out of bounds
• otherwise it is a slice of the row at height y

Note

• there is no get_column method, because, due to implementation details, it is way less efficient, and could not be returned as slice

pub unsafe fn get_row_unchecked(&self, y: usize) -> &[f64]

row of the heatmap

• returns reference of Slice of the specifed row of the heatmap without checking for bounds
• Generally not recommended, use with caution! Calling this with out-of-bounds index will result in a panic!

pub unsafe fn get_unchecked(&self, x: usize, y: usize) -> f64

Returns value stored in the heatmap at specified coordinates without performing bound checks. undefined behavior if coordinates are out of bounds

pub fn width(&self) -> usize

returns width of the heatmap

• the width is the same size, as the self.width_projection().bin_count()

pub fn height(&self) -> usize

returns height of the heatmap

• the height is the same size, as the self.height_projection().bin_count()

pub fn width_count_hist(&self) -> &HistWidth

Returns reference to current width Histogram

• statistical information of how often a count hit a specific width

pub fn height_count_hist(&self) -> &HistHeight

Returns reference to current height Histogram

• statistical information of how often a count hit a specific height

pub fn width_hist(&self) -> &HistWidth

Returns reference to current width Histogram

• histogram used to bin in the “width” direction
• all counts are counted here -> this is a projection of the heatmap

pub fn height_hist(&self) -> &HistHeight

Returns reference to current height Histogram

• histogram used to bin in the “height” direction
• all counts are counted here -> this is a projection of the heatmap

impl<HistWidth, HistHeight> HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Histogram,
    HistHeight: Histogram, 

pub fn new(
    width_hist: HistWidth,
    height_hist: HistHeight
) -> HeatmapF64<HistWidth, HistHeight>

Create a new Heatmap

• heatmap will have width width_hist.bin_count() and height height_hist.bin_count()
• histograms will be reset (zeroed) here, so it does not matter, if they were used before and contain Data

pub fn reset(&mut self)

Reset

• resets histograms
• heatmap is reset to contain only 0’s
• miss_count is reset to 0

pub fn combine<OtherHW, OtherHH, F>(
    &mut self,
    other: &HeatmapF64<OtherHW, OtherHH>,
    combine_fn: F
) -> Result<(), HeatmapError> where
    F: Fn(f64, f64) -> f64,
    OtherHW: Histogram,
    OtherHH: Histogram, 

“combine” heatmaps

• heatmaps have to have the same dimensions
• miss counts of other will be added to self
• with and hight histogram counts will be added to self
• self.heatmap will be modified at each index by self.heatmap[i] = combine_fn(self.heatmap[i], other.heatmap[i])

Usecase

• e.g. if you want to add, subtract or multiply two heatmaps

pub fn total(&self) -> usize

counts how often the heatmap was hit

• should be equal to self.heatmap.iter().sum::<usize>() but more efficient
• Note: it calculates this in O(min(self.width, self.height))

pub fn total_misses(&self) -> usize

Counts how often the Heatmap was missed, i.e., you tried to count a value (x,y), which was outside the Heatmap

pub fn heatmap(&self) -> &Vec<f64, Global>

returns heatmap

• each vector entry will contain the number of times, the corresponding bin was hit
• an entry is 0 if it was never hit

Access indices; understanding how the data is mapped

• A specific heatmap location (x,y) corresponds to the index y * self.width() + x
• you can use the heatmap_index function to calculate the index

pub fn normalize_total(&mut self)

Normalizes self

• Afterwards sum over all entrys (within numerical precision) should be 1.0

pub fn normalize_columns(&mut self)

Normalizes self

• Afterwards the sum of each column (fixed x) will be 1.0, if the sum of the row was not 0.0 before If it did not, the column will only consist of 0.0

pub fn heatmap_normalize_rows(&mut self)

Normalizes self

• Afterwards the sum of each row (fixed y) will be 1.0, if the sum of the row was not 0.0 before

impl<HistWidth, HistHeight> HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Histogram,
    HistHeight: Histogram, 

pub fn count<A, B, X, Y>(
    &mut self,
    width_val: A,
    height_val: B,
    val: f64
) -> Result<(usize, usize), HeatmapError> where
    A: Borrow<X>,
    B: Borrow<Y>,
    HistWidth: HistogramVal<X>,
    HistHeight: HistogramVal<Y>, 

update the heatmap

• calculates the coordinate (x, y) of the bin corresponding to the given value pair (width_val, height_val)
• if coordinate is out of bounds, it counts a “miss” and returns the HeatmapError
• otherwise it counts the “hit” (by adding val to the heatmap at the corresponding location) and returns the coordinate (x, y) of the hit

pub fn write_to<W>(&self, data_file: W) -> Result<(), Error> where
    W: Write, 

Write heatmap to file

• writes data of heatmap to file.

file

• lets assume self.width()is 4 and self.height() is 3
• the resulting file could look like

0.1 1.0 0.0 10.0
100.0 0.2 0.3 1.1
2.2 9.3 1.0 0.0

pub fn gnuplot_quick<W, S>(
    &self,
    writer: W,
    gnuplot_output_name: S
) -> Result<(), Error> where
    W: Write,
    S: AsRef<str>, 

Create a gnuplot script to plot your heatmap

• writer: The gnuplot script will be written to this
• gnuplot_output_name: how shall the file, created by executing gnuplot, be called? Ending of file will be set automatically

Note

• This is the same as calling gnuplot with default GnuplotSettings
• The default axis are the bin indices, which, e.g, means they always begin at 0. You have to set the axis via the GnuplotSettings

pub fn gnuplot<W, S, GS>(
    &self,
    gnuplot_writer: W,
    gnuplot_output_name: S,
    settings: GS
) -> Result<(), Error> where
    W: Write,
    S: AsRef<str>,
    GS: Borrow<GnuplotSettings>, 

Create a gnuplot script to plot your heatmap

This function writes a file, that can be plottet via the terminal via gnuplot

gnuplot gnuplot_file

Parameter:

• gnuplot_writer: writer gnuplot script will be written to
• gnuplot_output_name: how shall the file, created by executing gnuplot, be called? Ending of file will be set automatically

Note

• The default axis are the bin indices, which, e.g, means they always begin at 0. You have to set the axis via the GnuplotSettings

Example

use rand_pcg::Pcg64;
use rand::{SeedableRng, distributions::*};
use sampling::*;
use std::fs::File;
use std::io::BufWriter;
 
// first randomly create a heatmap
let h_x = HistUsizeFast::new_inclusive(0, 10).unwrap();
let h_y = HistU8Fast::new_inclusive(0, 10).unwrap();

let mut heatmap = HeatmapU::new(h_x, h_y);
heatmap.count(0, 0).unwrap();
heatmap.count(10, 0).unwrap();

let mut rng = Pcg64::seed_from_u64(27456487);
let x_distr = Uniform::new_inclusive(0, 10_usize);
let y_distr = Uniform::new_inclusive(0, 10_u8);

for _ in 0..100000 {
    let x = x_distr.sample(&mut rng);
    let y = y_distr.sample(&mut rng);
    heatmap.count(x, y).unwrap();
}
 
// create File for gnuplot skript
let file = File::create("heatmap_normalized.gp").unwrap();
let buf = BufWriter::new(file);

// Choose settings for gnuplot
let mut settings = GnuplotSettings::new();
settings.x_axis(GnuplotAxis::new(-5.0, 5.0, 6))
    .y_axis(GnuplotAxis::from_slice(&["a", "b", "c", "d"]))
    .y_label("letter")
    .x_label("number")
    .title("Example");

 
// norm heatmap row wise - this converts HeatmapU to HeatmapfF64
let heatmap = heatmap.into_heatmap_normalized_rows();

// create skript
heatmap.gnuplot(
    buf,
    "heatmap_normalized",
    settings
).unwrap();

Skript can now be plotted with

gnuplot heatmap_normalized.gp

Trait Implementations

impl<HistWidth, HistHeight> Clone for HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Clone,
    HistHeight: Clone, 

pub fn clone(&self) -> HeatmapF64<HistWidth, HistHeight>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<HistWidth, HistHeight> Debug for HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Debug,
    HistHeight: Debug, 

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

Formats the value using the given formatter.

impl<'de, HistWidth, HistHeight> Deserialize<'de> for HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Deserialize<'de>,
    HistHeight: Deserialize<'de>, 

pub fn deserialize<__D>(
    __deserializer: __D
) -> Result<HeatmapF64<HistWidth, HistHeight>, <__D as Deserializer<'de>>::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<HistWidth, HistHeight> From<HeatmapUsize<HistWidth, HistHeight>> for HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Histogram,
    HistHeight: Histogram, 

pub fn from(
    other: HeatmapUsize<HistWidth, HistHeight>
) -> HeatmapF64<HistWidth, HistHeight>

Performs the conversion.

impl<HistWidth, HistHeight> Serialize for HeatmapF64<HistWidth, HistHeight> where
    HistWidth: Serialize,
    HistHeight: Serialize, 

pub fn serialize<__S>(
    &self,
    __serializer: __S
) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.