# FreeBSD Manual Pages

```Math::SymbolicX::StatiUsersContributed:PerloDicX::Statistics::Distributions(3)

NAME
Math::SymbolicX::Statistics::Distributions - Statistical	Distributions

SYNOPSIS
use Math::SymbolicX::Statistics::Distributions	':all';

#####################################################
# The following demonstrates the procedural interface

# (included in	:all)
use Math::SymbolicX::Statistics::Distributions	':functions';

\$dist = normal_distribution('mean', 'rmsd');
print \$dist->value(mean => 5, rmsd => 2, x => 1);

# similar:
\$dist = gauss_distribution('mean', 'rmsd'); # same as normal_distribution
\$dist = bivariate_normal_distribution(	'mean1', 'rmsd1',
'mean2', 'rmsd2',
'correlation	  );

# plug	in any expression: (y*2	will be	mean, z^3 root mean square deviation)
\$dist = normal_distribution('y*2', 'z^3');
print \$dist->value(x => 0.5, y	=> 3, z	=> 0.2);

# To generate the error function: (mean = 0; rmsd = 1)
\$dist = normal_distribution(0,	1);
print \$dist->value(x => 1);

#########################################################
# The following demonstrates the parser/grammar interface
# We'll do the	exact same as above with the other interface.

# (included in	:all)
use Math::SymbolicX::Statistics::Distributions	':grammar';
use Math::Symbolic qw/parse_from_string/;

\$dist = parse_from_string('normal()');
print \$dist->value(mean => 5, rmsd => 2, x => 1);

# similar:
\$dist = parse_from_string('gauss(mean,	rmsd)'); # same	as normal()
\$dist = parse_from_string( 'bivariate_normal(mean1, rmsd1,'
.'mean2, rmsd2,'
.'correlation  )' );

# plug	in any expression: (y*2	will be	mean, z^3 root mean square deviation)
\$dist = parse_from_string('normal(y*2,	z^3)');
print \$dist->value(x => 0.5, y	=> 3, z	=> 0.2);

# To generate the error function: (mean = 0; rmsd = 1)
\$dist = parse_from_string('normal(0, 1)');
print \$dist->value(x => 1);

# same	works for the keywords 'boltzmann', 'bose', 'fermi'

DESCRIPTION
distributions. For that,	it uses	the Math::Symbolic module which	gives
the user	an opportunity to manufacture distributions to his liking.

The module can be used in two styles: It	has a procedural interface
which is	demonstrated in	the first half of the synopsis.	But it also
features	a wholly different interface: It can modify the	Math::Symbolic
parser so that you can use the distributions right inside strings that
will be parsed as Math::Symbolic	trees. This is demonstrated for	very
simple cases in the second half of the synopsis.

All arguments in	both interface styles are optional.  Whichever
expression is used instead of, for examle 'mean', is plugged into the
formula for the distribution as a Math::Symbolic	tree.  Details on
argument	handling are explained below.

Please see the section on Export	for details on how to choose the
interface style you want	to use.

The arguments for the grammar-interface version of the module follow
the same	concept	as for the function interface which is described in
Distributions in	detail.	The only significant difference	is that	the
arguments must all be strings to	be parsed as Math::Symbolic trees.
There is	one exception: If the string 'undef' is	passed as one argument
to the function,	that string is converted to a real undef, but
nevermind and see below.

Export
By default, the module does not export any functions and	does not
modify the Math::Symbolic parser. You have to explicitly	request	that
does so using the usual Exporter	semantics.

If using	the module without parameters ("use
Math:SymbolicX::Statistics::Distributions;"), you can access the
distributions via the fully qualified subroutine	names such as
"Math::SymbolicX::Statistics::Distributions::normal_distribution()".
But that	would be annoying, no?

You can choose to export	any of the distribution	functions (see below)
by specifying one or more function names:

use Math::SymbolicX::Statistics::Distributions	qw/gauss_distribution/;
# then:
\$dist = gauss_distribution(...);

You can also import all of them by using	the ':functions' tag:

use Math::SymbolicX::Statistics::Distributions	qw/:functions/;
...

Alternatively, you can choose to	modify the Math::Symbolic parser by
using any of the	following keywords in the same way we used the
function	names above.

normal_grammar
gauss_grammar
bivariate_normal_grammar
cauchy_grammar
boltzmann_grammar
bose_grammar
fermi_grammar

To add all the keywords ("normal()", "gauss()", "bivariate_normal()",
"cauchy()", "boltzmann()", "bose()", and	"fermi()" to the grammar, you

Finally,	the module supports the	exporter tag ":all" to both export all
functions and add all keywords to the parser.

Distributions
The following is	a list of distributions	that can be generated using
this module.

Normal (Gauss) Distribution
Normal	(or Gauss) distributions are availlable	through	the functions
"normal_distribution" or "gauss_distribution" which are equivalent.
The functions return the Math::Symbolic representation	of a gauss
distribution.

The gauss distribution	has three parameters: The mean "mu", the root
mean square deviation "sigma" and the variable	"x".

The functions take two	optional arguments: The	Math::Symbolic trees
(or strings) to be plugged into the formula for 1) "mu" and 2)
"sigma".

If any	argument is undefined or omitted, the corresponding variable
will remain unchanged.

The variable "x" always remains in the	formula.

details.

Bivariate Normal	Distribution
Bivariate normal distributions	are availlable through the function
"bivariate_normal_distribution".  The function	returns	the
Math::Symbolic	representation of a bivariate normal distribution.

The bivariate normal distribution has seven parameters: The mean
"mu1" of the first variable, the root mean square deviation "sigma1"
of the	first variable,	the mean "mu2" of the second variable, the
root mean square deviation "sigma2" of	the second variable, the first
variable "x1",	the second variable "x2", and the correlation of the
first and second variables, "sigma12".

The function takes five optional arguments: The Math::Symbolic	trees
(or strings) to be plugged into the formula for 1) "mu1", 2)
"sigma1", 3) "mu1", 4)	"sigma1", and 5) "sigma12".

If any	argument is undefined or omitted, the corresponding variable
will remain unchanged.

The variables "x1" and	"x2" always remain in the formula.

details.

Cauchy Distribution
Cauchy	distributions are availlable through the function
"cauchy_distribution".	 The function returns the Math::Symbolic
representation	of a cauchy distribution.

The cauchy distribution has three parameters: The median "m", the
full width at half maximum "lambda" of	the curve, and the variable
"x".

The function takes two	optional arguments: The	Math::Symbolic trees
(or strings) to be plugged into the formula for 1) "m"	and 2)
"lambda".

If any	argument is undefined or omitted, the corresponding variable
will remain unchanged.

The variable "x" always remains in the	formula.

details.

Boltzmann Distribution
Boltzmann distributions are availlable	through	the function
"boltzmann_distribution".  The	function returns the Math::Symbolic
representation	of a Boltzmann distribution.

The Boltzmann distribution has	four parameters: The energy "E", the
weighting factor "gs" that describes the number of states at energy
"E", the temperature "T", and the chemical potential "mu".

The function takes fouroptional arguments: The	Math::Symbolic trees
(or strings) to be plugged into the formula for 1) "E", 2) "gs", 3)
"T", and 4) "mu"

If any	argument is undefined or omitted, the corresponding variable
will remain unchanged.

The formula used is: "N = gs *	e^(-(E-mu)/(k_B*T))".

details. Boltzmann's constant "k_B" is	used as	"1.3807	* 10^-23 J/K".

Fermi Distribution
Fermi distributions are availlable through the	function
"fermi_distribution".	The function returns the Math::Symbolic
representation	of a Fermi distribution.

The Fermi distribution	has four parameters: The energy	"E", the
weighting factor "gs" that describes the number of states at energy
"E", the temperature "T", and the chemical potential "mu".

The function takes fouroptional arguments: The	Math::Symbolic trees
(or strings) to be plugged into the formula for 1) "E", 2) "gs", 3)
"T", and 4) "mu"

If any	argument is undefined or omitted, the corresponding variable
will remain unchanged.

The formula used is: "N = gs /	( e^((E-mu)/(k_B*T)) + 1)".

details. Boltzmann's constant "k_B" is	used as	"1.3807	* 10^-23 J/K".

Have a look at Math::Symbolic, Math::Symbolic::Parser,
Math::SymbolicX::ParserExtensionFactory and all associated modules.

New versions of this module can be found	on http://steffen-mueller.net
or CPAN.

Details on several distributions	implemented in the code	can be found
on the MathWorld	site:

Eric W. Weisstein. "Normal Distribution." From MathWorld	-- A Wolfram
Web Resource. http://mathworld.wolfram.com/NormalDistribution.html

Eric W. Weisstein. "Bivariate Normal Distribution." From	MathWorld -- A
Wolfram Web Resource.
http://mathworld.wolfram.com/BivariateNormalDistribution.html

Eric W. Weisstein. "Cauchy Distribution." From MathWorld	-- A Wolfram
Web Resource. http://mathworld.wolfram.com/CauchyDistribution.html

The Boltzmann, Bose, and	Fermi distributions are	discussed in detail in
N.W. Ashcroft, N.D. Mermin. "Solid State	Physics". Brooks/Cole, 1976

AUTHOR
Steffen Mueller,	<symbolic-module at steffen-mueller dot	net>