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..99f5a5d93 --- /dev/null +++ b/doc/source/starting.rst @@ -0,0 +1,95 @@ +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 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 + +Then, we create a standard-normal distribution ``d`` and obtain samples using ``rand``: + +.. code-block:: julia + + julia> d = Normal() + Normal(μ=0.0, σ=1.0) + + julia> x = rand(d, 100) + 100-element Array{Float64,1}: + 0.376264 + -0.405272 + ... + +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 + + julia> quantile(Normal(), [0.5, 0.95]) + 2-element Array{Float64,1}: + 0.0 + 1.64485 + +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 + + julia> rand(Normal(1, 2), 100) + +Using Other Distributions +----------- + +The package contains a large number of additional distributions of three main types: + +* ``Univariate`` +* ``Multivariate`` +* ``Matrixvariate`` + +Each type splits 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> 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)``: + +.. 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 [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