README

image izef_math_libgsl_histogram_math_libgsl_histogram_0_0_2_examples_2dhistogram_svg not found

NAME

Math::Libgsl::Histogram - An interface to libgsl, the Gnu Scientific Library - Histograms

SYNOPSIS

use Math::Libgsl::Histogram;

my $h = Math::Libgsl::Histogram.new(3).set-ranges(0, 10, 100, 1000);
say $h.find(18);
$h.scanf('file.dat');
say "max: { $h.max-val } in bin { $h.max-bin }";
say "mean: { $h.mean } standard deviation: { $h.sigma }";

use Math::Libgsl::Histogram2D;

my $h = Math::Libgsl::Histogram2D.new(10, 10)
        .set-uniform(0, 1, 0, 1)
        .accumulate(.3, .3, 1)
        .accumulate(.8, .1, 5)
        .accumulate(.7, .9, .5);
say "Number of bins: x = { $h.nx }, y = { $h.ny }"; # output: Number of bins: x = 10, y = 10
say "bin (0, 0) = { $h.get(0, 0) }";                # output: bin (7, 9) = 0.5

DESCRIPTION

Math::Libgsl::Histogram is an interface to the Histogram functions of libgsl, the Gnu Scientific Library.

This module exports four classes:

Math::Libgsl::Histogram
Math::Libgsl::Histogram::PDF
Math::Libgsl::Histogram2D
Math::Libgsl::Histogram2D::PDF

Histogram manages one-dimensional histograms, Histogram2D manages two-dimensional histograms, Histogram::PDF uses the 1D histogram as a probability function, same goes for the Histogram2D::PDF.

Math::Libgsl::Histogram

new(UInt $size!)

new(UInt :$size!)

The constructor accepts one simple or named argument: the histogram size, or number of bins.

set-ranges(_@ranges where _.elems == self.bins + 1 --> Math::Libgsl::Histogram)

This method sets the ranges of the histogram using the @array. This method returns self, to allow method chaining.

set-uniform(Num() xmax where * > $xmin --> Math::Libgsl::Histogram)

This method sets the ranges of the histogram to cover the range from xmax uniformly. This method returns self, to allow method chaining.

increment(Num() $x --> Math::Libgsl::Histogram)

This method updates the histogram by adding one (1.0) to the bin whose range contains the coordinate $x. This method returns self, to allow method chaining.

accumulate(Num() weight --> Math::Libgsl::Histogram)

This method updates the histogram by increasing the value of the appropriate bin by the floating-point number $weight. This method returns self, to allow method chaining.

get(Int $i --> Num)

This method returns the content of the i-th bin of the histogram.

get-range(Int $i --> List)

This method finds the upper and lower range limits of the i-th bin of the histogram and returns them as a two-value list.

max(--> Num)

min(--> Num)

bins(--> UInt)

These methods return the maximum upper and minimum lower range limits and the number of bins of the histogram.

reset()

This method resets all the bins in the histogram to zero.

find(Num() $x --> UInt)

This method returns the index of the bin which covers the coordinate $x in the histogram.

copy(Math::Libgsl::Histogram src.bins == self.bins } --> Math::Libgsl::Histogram)

This method copies the histogram $src into the current object. This method returns self, to allow method chaining.

clone(--> Math::Libgsl::Histogram)

This method returns a newly created histogram which is an exact copy of the current histogram.

max-val(--> Num)

This method returns the maximum value contained in the histogram bins.

max-bin(--> UInt)

This method returns the index of the bin containing the maximum value.

min-val(--> Num)

This method returns the minimum value contained in the histogram bins.

min-bin(--> UInt)

This method returns the index of the bin containing the minimum value.

mean(--> Num)

This method returns the mean of the histogrammed variable, where the histogram is regarded as a probability distribution.

sigma(--> Num)

This method returns the standard deviation of the histogrammed variable, where the histogram is regarded as a probability distribution.

sum(--> Num)

This method returns the sum of all bin values.

equal(Math::Libgsl::Histogram $h2 --> Bool)

This method returns True if the all of the individual bin ranges of the two histograms are identical, and False otherwise.

add(Math::Libgsl::Histogram $h2 --> Math::Libgsl::Histogram)

This method adds the contents of the bins in histogram h2 to the corresponding bins of the current histogram. The two histograms must have the same number of bins and the same ranges. This method returns self, to allow method chaining.

sub(Math::Libgsl::Histogram $h2 --> Math::Libgsl::Histogram)

This method subtracts the contents of the bins in histogram h2 from the corresponding bins of the current histogram. The two histograms must have the same number of bins and the same ranges. This method returns self, to allow method chaining.

mul(Math::Libgsl::Histogram $h2 --> Math::Libgsl::Histogram)

This method multiplies the contents of the bins in histogram h2 by the corresponding bins of the current histogram. The two histograms must have the same number of bins and the same ranges. This method returns self, to allow method chaining.

div(Math::Libgsl::Histogram $h2 --> Math::Libgsl::Histogram)

This method divides the contents of the bins in histogram h2 by the corresponding bins of the current histogram. The two histograms must have the same number of bins and the same ranges. This method returns self, to allow method chaining.

scale(Num() $scale --> Math::Libgsl::Histogram)

This method multiplies the contents of the bins of the current histogram by $scale. This method returns self, to allow method chaining.

shift(Num() $offset --> Math::Libgsl::Histogram)

This method shifts the contents of the bins of the current histogram by $offset. This method returns self, to allow method chaining.

write(Str $filename --> Math::Libgsl::Histogram)

This method writes the ranges and bins of the current histogram to a file in binary format. This method returns self, to allow method chaining.

read(Str $filename --> Math::Libgsl::Histogram)

This method reads the ranges and bins of the current histogram from a file in binary format. This method returns self, to allow method chaining.

printf(Str range-format, Str $bin-format --> Math::Libgsl::Histogram)

This function writes the ranges and bins of the current histogram line-by-line to a file using the format specifiers bin-format. This method returns self, to allow method chaining.

scanf(Str $filename --> Math::Libgsl::Histogram)

This function reads formatted data from a file. The histogram must be preallocated with the correct length since the C library function uses the size of the current object to determine how many numbers to read. This method returns self, to allow method chaining.

Math::Libgsl::Histogram::PDF

new(UInt h!)

new(UInt :h!)

The constructor accepts two simple or named arguments: the probability distribution function size, or number of bins, and the histogram. The histogram must not contain negative values, because a probability distribution cannot contain negative values.

sample(Num() $r --> Num)

This method uses $r, a uniform random number between zero and one, to compute a single random sample from the probability distribution object.

Math::Libgsl::Histogram2D

new(UInt ny!)

new(UInt :ny!)

The constructor accepts two simple or named arguments: the number of bins in the x direction ny.

set-ranges(:@xranges where _.elems == self.nx + 1, :@yranges where _.elems == self.ny + 1 --> Math::Libgsl::Histogram2D)

This method sets the ranges of the current histogram using the arrays @xrange and @yrange. This method returns self, to allow method chaining.

set-uniform(Num() xmax where _ > ymin, Num() ymin --> Math::Libgsl::Histogram2D)

This method sets the ranges of the histogram to cover the ranges xmax and ymax uniformly. This method returns self, to allow method chaining.

increment(Num() y --> Math::Libgsl::Histogram2D)

This method updates the histogram by adding one (1.0) to the bin whose x and y ranges contain the coordinates (y). This method returns self, to allow method chaining.

accumulate(Num() y, Num() $weight --> Math::Libgsl::Histogram2D)

This method updates the histogram by increasing the value of the appropriate bin by the floating-point number $weight. This method returns self, to allow method chaining.

get(Int j --> Num)

This method returns the content of the (i, j)-th bin of the histogram.

get-xrange(Int $i --> List)

get-yrange(Int $i --> List)

This method finds the upper and lower range limits of the i-th and j-th bin in the x and y directions of the histogram and returns them as a two-value list.

xmax(--> Num)

xmin(--> Num)

nx(--> UInt)

ymax(--> Num)

ymin(--> Num)

ny(--> UInt)

These methods return the maximum upper and minimum lower range limits and the number of bins of the histogram.

reset()

This method resets all the bins in the histogram to zero.

find(Num() y --> List)

This method returns the index of the bin which covers the coordinate (y) in the histogram.

copy(Math::Libgsl::Histogram2D src.nx == self.nx && $src.ny == self.ny } --> Math::Libgsl::Histogram2D)

This method copies the histogram $src into the current object. This method returns self, to allow method chaining.

clone(--> Math::Libgsl::Histogram2D)

This method returns a newly created histogram which is an exact copy of the current histogram.

max-val(--> Num)

This method returns the maximum value contained in the histogram bins.

max-bin(--> List)

This method returns the indexes of the bin containing the maximum value.

min-val(--> Num)

This method returns the minimum value contained in the histogram bins.

min-bin(--> List)

This method returns the indexes of the bin containing the minimum value.

xmean(--> Num)

This method returns the mean of the histogrammed x variable, where the histogram is regarded as a probability distribution.

ymean(--> Num)

This method returns the mean of the histogrammed y variable, where the histogram is regarded as a probability distribution.

xsigma(--> Num)

This method returns the standard deviation of the histogrammed x variable, where the histogram is regarded as a probability distribution.

ysigma(--> Num)

This method returns the standard deviation of the histogrammed y variable, where the histogram is regarded as a probability distribution.

cov(--> Num)

This method returns the covariance of the histogrammed x and y variables, where the histogram is regarded as a probability distribution.

sum(--> Num)

This method returns the sum of all bin values.

equal(Math::Libgsl::Histogram2D $h2 --> Bool)

This method returns True if the all of the individual bin ranges of the two histograms are identical, and False otherwise.

add(Math::Libgsl::Histogram2D $h2 --> Math::Libgsl::Histogram2D)

sub(Math::Libgsl::Histogram2D $h2 --> Math::Libgsl::Histogram2D)

mul(Math::Libgsl::Histogram2D $h2 --> Math::Libgsl::Histogram2D)

div(Math::Libgsl::Histogram2D $h2 --> Math::Libgsl::Histogram2D)

scale(Num() $scale --> Math::Libgsl::Histogram2D)

This method multiplies the contents of the bins of the current histogram by $scale. This method returns self, to allow method chaining.

shift(Num() $offset --> Math::Libgsl::Histogram2D)

This method shifts the contents of the bins of the current histogram by $offset. This method returns self, to allow method chaining.

write(Str $filename --> Math::Libgsl::Histogram2D)

This method writes the ranges and bins of the current histogram to a file in binary format. This method returns self, to allow method chaining.

read(Str $filename --> Math::Libgsl::Histogram2D)

This method reads the ranges and bins of the current histogram from a file in binary format. This method returns self, to allow method chaining.

printf(Str range-format, Str $bin-format --> Math::Libgsl::Histogram2D)

This function writes the ranges and bins of the current histogram line-by-line to a file using the format specifiers bin-format. This method returns self, to allow method chaining.

scanf(Str $filename --> Math::Libgsl::Histogram2D)

Math::Libgsl::Histogram2D::PDF

new(UInt ny!, Math::Libgsl::Histogram2D $h!)

new(UInt :ny!, Math::Libgsl::Histogram2D :$h!)

The constructor accepts three simple or named arguments: the probability distribution function x and y number of bins, and the histogram. The histogram must not contain negative values, because a probability distribution cannot contain negative values.

sample(Num() r2 --> List)

This method uses two uniform random numbers between zero and one, r2, to compute a single random sample from the two-dimensional probability distribution.

C Library Documentation

For more details on libgsl see https://www.gnu.org/software/gsl/. The excellent C Library manual is available here https://www.gnu.org/software/gsl/doc/html/index.html, or here https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf in PDF format.

Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

Debian Linux and Ubuntu 20.04

sudo apt install libgsl23 libgsl-dev libgslcblas0

That command will install libgslcblas0 as well, since it's used by the GSL.

Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

Installation

To install it using zef (a module management tool):

$ zef install Math::Libgsl::Histogram

AUTHOR

Fernando Santagata [email protected]

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.