From 1d7ea7bfe98bf5c6ce90b4c5956a830f07718cf5 Mon Sep 17 00:00:00 2001 From: Christian Goldammer Date: Sat, 7 Mar 2015 08:51:41 -0600 Subject: [PATCH 1/3] Added 'getting started' to documentation --- doc/source/index.rst | 1 + doc/source/starting.rst | 112 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) create mode 100644 doc/source/starting.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 4e23a0a69..9980f8731 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -14,6 +14,7 @@ The *Distributions* package provides a large collection of probabilistic distrib .. toctree:: :maxdepth: 2 + starting.rst types.rst univariate.rst truncate.rst diff --git a/doc/source/starting.rst b/doc/source/starting.rst new file mode 100644 index 000000000..b91aad5b1 --- /dev/null +++ b/doc/source/starting.rst @@ -0,0 +1,112 @@ +Getting Started +=============== + +Installation +----------- +The Distributions package is available through the Julia package system by running ``Pkg.add("Distributions")``. Throughout, we assume that you have installed the package. + +Starting With a Normal Distribution +----------- + +We start by drawing :math:`100` observations from a standard-normal random variable. After setting up the environment through + +.. code-block:: julia + + julia> using Distributions + julia> srand(123) # Setting the seed + +We first create a ``normal`` distribution and then obtain samples using ``rand``: + +.. code-block:: julia + + julia> normal = Normal() + Normal(μ=0.0, σ=1.0) + + julia> x = rand(normal, 100) + 100-element Array{Float64,1}: + 0.376264 + -0.405272 + ... + +You can easily obtain a pdf, cdf, percentile, and many other functions for a distribution. For instance, the median (50th percentile) and the 95th percentile for the standard-normal distribution are + +.. code-block:: julia + + julia> quantile(Normal(), [0.5, 0.95]) + 2-element Array{Float64,1}: + 0.0 + 1.64485 + +The normal distribution is parameterized by a mean (location) and standard deviation (scale). To draw random samples from a normal distribution with mean 1 and standard deviation 2: + +.. code-block:: julia + + julia> rand(Normal(1, 2), 100) + +Using Other Distributions +----------- + +The package contains a large number of additional distributions of four main types: + +* ``Univariate`` +* ``Truncated`` +* ``Multivariate`` +* ``Matrixvariate`` + +The ``Univariate`` random variables split further into ``Discrete`` and ``Continuous``. + +For instance, you can define the following distributions (among many others): + +.. code-block:: julia + + julia> Binomial(p) # Discrete univariate + julia> Cauchy(u, b) # Continuous univariate + julia> TruncatedNormal(Normal(mu, sigma), l, u) # Truncated + julia> Multinomial(n, p) # Multivariate + julia> Wishart(nu, S) # Matrix-variate + +To find out which parameters are appropriate for a given distribution ``D``, you can use ``names(D)``: + +.. code-block:: julia + + julia> names(Cauchy) + 2-element Array{Symbol,1}: + :μ + :β + +This tells you that a Cauchy distribution is initialized with location ``μ`` and scale ``β``. + +Estimate the Parameters +------------------ + +It is often useful to approximate an empirical distribution with a theoretical distribution. As an example, we can use the array ``x`` we created above and ask which normal distribution best describes it: + +.. code-block:: julia + + julia> fit(Normal, x) + Normal(μ=0.036692077201688635, σ=1.1228280164716382) + +Since ``x`` is a random draw from ``Normal``, it's easy to check that the fitted values are sensible. Indeed, the estimates :math:`[0.04, 1.12]` are close to the true values of :math:`[0.0, 1.0]` that we used to generate ``x``. + +Create Mixture Models +------------------ + +Creating mixture models is simple. For instance, you can create a mixture of three normal variables with prior probabilities :math:`0.2, 0.5, 0.3` as follows: + +.. code-block:: julia + + julia> m = MixtureModel(Normal[ + Normal(-2.0, 1.2), + Normal(0.0, 1.0), + Normal(3.0, 2.5)], [0.2, 0.5, 0.3]) + +A mixture model can be accessed using a smaller set of functions than the pre-defined distributions. While a pdf is defined: + +.. code-block:: julia + + julia> pdf(m, 2) + 0.07144494659237469 + +a quantile is not defined. + +This package does not provide facilities for estimating mixture models. One can resort to other packages, *e.g.* *MixtureModels.jl*, for this purpose. \ No newline at end of file From 067b689d2cab30f3dce8e517b7c7381d35faa621 Mon Sep 17 00:00:00 2001 From: Christian Goldammer Date: Sat, 7 Mar 2015 18:12:55 -0600 Subject: [PATCH 2/3] Incorporated comments on pull request and edited further --- doc/source/starting.rst | 55 ++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 36 deletions(-) diff --git a/doc/source/starting.rst b/doc/source/starting.rst index b91aad5b1..ea0928015 100644 --- a/doc/source/starting.rst +++ b/doc/source/starting.rst @@ -8,27 +8,29 @@ The Distributions package is available through the Julia package system by runni Starting With a Normal Distribution ----------- -We start by drawing :math:`100` observations from a standard-normal random variable. After setting up the environment through +We start by drawing :math:`100` observations from a standard-normal random variable. + +The first step is to set up the environment: .. code-block:: julia julia> using Distributions julia> srand(123) # Setting the seed -We first create a ``normal`` distribution and then obtain samples using ``rand``: +Then, we create a standard-normal distribution ``d`` and obtain samples using ``rand``: .. code-block:: julia - julia> normal = Normal() + julia> d = Normal() Normal(μ=0.0, σ=1.0) - julia> x = rand(normal, 100) + julia> x = rand(d, 100) 100-element Array{Float64,1}: 0.376264 -0.405272 ... -You can easily obtain a pdf, cdf, percentile, and many other functions for a distribution. For instance, the median (50th percentile) and the 95th percentile for the standard-normal distribution are +You can easily obtain the pdf, cdf, percentile, and many other functions for a distribution. For instance, the median (50th percentile) and the 95th percentile for the standard-normal distribution are given by: .. code-block:: julia @@ -37,7 +39,7 @@ You can easily obtain a pdf, cdf, percentile, and many other functions for a dis 0.0 1.64485 -The normal distribution is parameterized by a mean (location) and standard deviation (scale). To draw random samples from a normal distribution with mean 1 and standard deviation 2: +The normal distribution is parameterized by its mean and standard deviation. To draw random samples from a normal distribution with mean 1 and standard deviation 2, you write: .. code-block:: julia @@ -46,14 +48,13 @@ The normal distribution is parameterized by a mean (location) and standard devia Using Other Distributions ----------- -The package contains a large number of additional distributions of four main types: +The package contains a large number of additional distributions of three main types: * ``Univariate`` -* ``Truncated`` * ``Multivariate`` * ``Matrixvariate`` -The ``Univariate`` random variables split further into ``Discrete`` and ``Continuous``. +Each type splits further into ``Discrete`` and ``Continuous``. For instance, you can define the following distributions (among many others): @@ -61,9 +62,14 @@ For instance, you can define the following distributions (among many others): julia> Binomial(p) # Discrete univariate julia> Cauchy(u, b) # Continuous univariate - julia> TruncatedNormal(Normal(mu, sigma), l, u) # Truncated - julia> Multinomial(n, p) # Multivariate - julia> Wishart(nu, S) # Matrix-variate + julia> Multinomial(n, p) # Discrete multivariate + julia> Wishart(nu, S) # Continuous matrix-variate + +In addition, you can create truncated distributions from univariate distributions: + +.. code-block:: julia + + julia> Truncated(Normal(mu, sigma), l, u) To find out which parameters are appropriate for a given distribution ``D``, you can use ``names(D)``: @@ -86,27 +92,4 @@ It is often useful to approximate an empirical distribution with a theoretical d julia> fit(Normal, x) Normal(μ=0.036692077201688635, σ=1.1228280164716382) -Since ``x`` is a random draw from ``Normal``, it's easy to check that the fitted values are sensible. Indeed, the estimates :math:`[0.04, 1.12]` are close to the true values of :math:`[0.0, 1.0]` that we used to generate ``x``. - -Create Mixture Models ------------------- - -Creating mixture models is simple. For instance, you can create a mixture of three normal variables with prior probabilities :math:`0.2, 0.5, 0.3` as follows: - -.. code-block:: julia - - julia> m = MixtureModel(Normal[ - Normal(-2.0, 1.2), - Normal(0.0, 1.0), - Normal(3.0, 2.5)], [0.2, 0.5, 0.3]) - -A mixture model can be accessed using a smaller set of functions than the pre-defined distributions. While a pdf is defined: - -.. code-block:: julia - - julia> pdf(m, 2) - 0.07144494659237469 - -a quantile is not defined. - -This package does not provide facilities for estimating mixture models. One can resort to other packages, *e.g.* *MixtureModels.jl*, for this purpose. \ No newline at end of file +Since ``x`` is a random draw from ``Normal``, it's easy to check that the fitted values are sensible. Indeed, the estimates :math:`[0.04, 1.12]` are close to the true values of :math:`[0.0, 1.0]` that we used to generate ``x``. \ No newline at end of file From 93bb1bf1e81f82ad3238ba1d7efb0c2ff31afcc4 Mon Sep 17 00:00:00 2001 From: Christian Goldammer Date: Sun, 8 Mar 2015 10:39:45 -0500 Subject: [PATCH 3/3] Removed :math for showing numbers in text --- doc/source/starting.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/starting.rst b/doc/source/starting.rst index ea0928015..99f5a5d93 100644 --- a/doc/source/starting.rst +++ b/doc/source/starting.rst @@ -8,7 +8,7 @@ The Distributions package is available through the Julia package system by runni Starting With a Normal Distribution ----------- -We start by drawing :math:`100` observations from a standard-normal random variable. +We start by drawing 100 observations from a standard-normal random variable. The first step is to set up the environment: @@ -92,4 +92,4 @@ It is often useful to approximate an empirical distribution with a theoretical d julia> fit(Normal, x) Normal(μ=0.036692077201688635, σ=1.1228280164716382) -Since ``x`` is a random draw from ``Normal``, it's easy to check that the fitted values are sensible. Indeed, the estimates :math:`[0.04, 1.12]` are close to the true values of :math:`[0.0, 1.0]` that we used to generate ``x``. \ No newline at end of file +Since ``x`` is a random draw from ``Normal``, it's easy to check that the fitted values are sensible. Indeed, the estimates [0.04, 1.12] are close to the true values of [0.0, 1.0] that we used to generate ``x``. \ No newline at end of file