README.md in distribution-0.7.3 vs README.md in distribution-0.8.0
- old
+ new
@@ -1,80 +1,103 @@
# [Distribution](https://github.com/sciruby/distribution)
[](https://travis-ci.org/SciRuby/distribution)
[](https://codeclimate.com/github/SciRuby/distribution)
+Distribution is a gem with several probabilistic distributions. Pure Ruby is used by default, C (GSL) or Java extensions are used if available. Some facts:
+
+- Very fast ruby 1.9.3+ implementation, with improved method to calculate factorials and other common functions.
+- All methods tested on several ranges. See `spec/`.
+- Code for normal, Student's t and chi square is lifted from the [statistics2 gem](https://rubygems.org/gems/statistics2). Originally at [this site](http://blade.nagaokaut.ac.jp/~sinara/ruby/math/statistics2).
+- The code for some functions and RNGs was lifted from Julia's [Rmath-julia](https://github.com/JuliaLang/Rmath-julia), a patched version of R's standalone math library.
+
+The following table lists the available distributions and the methods available for each one. If a field is marked with an *x*, that distribution doesn't have that method implemented.
+
+| Distribution | PDF | CDF | Quantile | RNG | Mean | Mode | Variance | Skewness | Kurtosis | Entropy |
+| :--------------- | :-: | :-: | :------: | :-: | :--: | :--: | :------: | :------: | :------: | :-----: |
+| Uniform | | | | | x | x | x | x | x | x |
+| Normal | | | | | x | x | x | x | x | x |
+| Lognormal | | | x | x | x | x | x | x | x | x |
+| Bivariate Normal | | | x | x | x | x | x | x | x | x |
+| Exponential | | | | | x | x | x | x | x | x |
+| Logistic | | | | | x | x | x | x | x | x |
+| Student's T | | | | x | x | x | x | x | x | x |
+| Chi Square | | | | | x | x | x | x | x | x |
+| Fisher-Snedecor | | | | x | x | x | x | x | x | x |
+| Beta | | | | x | x | x | x | x | x | x |
+| Gamma | | | x | x | x | x | x | x | x | x |
+| Weibull | | | | x | x | x | x | x | x | x |
+| Binomial | | | | x | x | x | x | x | x | x |
+| Poisson | | | | | x | x | x | x | x | x |
+| Hypergeometric | | | | x | x | x | x | x | x | x |
+
## Installation
```
$ gem install distribution
```
-If you have GSL installed and want to speed things up, install `rb-gsl`:
+You can install GSL for better performance:
+* For Mac OS X: `brew install gsl`
+* For Ubuntu / Debian: `sudo apt-get install libgsl0-dev`
+
+After successfully installing the library:
+
```bash
$ gem install rb-gsl
```
-## Description
+## Examples
-Statistical Distributions library. Includes Normal univariate and bivariate, T, F, Chi Square, Binomial, Hypergeometric, Exponential, Poisson, Beta, LogNormal and Gamma.
+You can find automatically generated documentation on [RubyDoc](http://www.rubydoc.info/github/sciruby/distribution/master).
-Uses Ruby by default and C (statistics2/GSL) or Java extensions where available.
-
-Includes code from statistics2 on Normal, T, F and Chi Square ruby code [http://blade.nagaokaut.ac.jp/~sinara/ruby/math/statistics2]
-
-## Synopsis
-
-* Returns Gaussian PDF for x
-
```
-pdf=Distribution::Normal.pdf(x)
-```
+# Returns Gaussian PDF for x.
+pdf = Distribution::Normal.pdf(x)
-* Returns Gaussian CDF for x
+# Returns Gaussian CDF for x.
+cdf = Distribution::Normal.cdf(x)
-```
-cdf=Distribution::Normal.cdf(x)
-```
+# Returns inverse CDF (or p-value) for x.
+pv = Distribution::Normal.p_value(x)
-* Returns inverse CDF (or p-value) for x
+# API.
-```
-pv=Distribution::Normal.p_value(x)
-```
+# You would normally use the following
+p = Distribution::T.cdf(x)
-## Developers
+# to get the cumulative probability of `x`. However, you can also:
+include Distribution::Shorthand
+tdist_cdf(x)
```
-$ git clone https://github.com/SciRuby/distribution.git
-```
-If you want to provide a new distribution, run `lib/distribution`:
+## API Structure
+```ruby
+Distribution::<name>.(cdf|pdf|p_value|rng)
```
-$ distribution --new your_distribution
-```
-This should create the main distribution file, the directory with Ruby and GSL engines and specs on the spec/ directory.
-
-## API Structure
-
- Distribution::<name>.(cdf|pdf|p_value|rng)
-
On discrete distributions, exact Ruby implementations of pdf, cdf and p_value could be provided, using
+
```
Distribution::<name>.exact_(cdf|pdf|p_value)
```
+
module Distribution::Shorthand provides (you guess?) shortands method to call all methods
+
```
<Distribution shortname>_(cdf|pdf|p|r)
```
+
On discrete distributions, exact cdf, pdf and p_value are
+
```
<Distribution shortname>_(ecdf|epdf|ep)
```
+
Shortnames for distributions:
* Normal: norm
* Bivariate Normal: bnor
* T: tdist
@@ -85,28 +108,48 @@
* Exponential: expo
* Poisson: pois
* Beta: beta
* Gamma: gamma
* LogNormal: lognormal
+ * Uniform: unif
-### API Structure Example
+## Roadmap
-```
- Distribution::T.cdf
-```
+This gem wasn't updated for a long time before I started working on it, so there are a lot of work to do. The first priority is cleaning the interface and removing cruft whenever possible. After that, I want to implement more distributions and make sure that each one has a RNG.
-could be called after including Distribution::Shorthand
+### Short-term
-```
- tdist_cdf
-```
+- Define a minimal interface for continuous and discrete distributions (e.g. mean, variance, mode, skewness, kurtosis, pdf, cdf, quantile, cquantile).
+- Implement `Distribution::Uniform` with the default Ruby `Random`.
+- Clean up the implementation of normal distribution. Implement the necessary functions.
+- The same for Student's t, chi square, Fisher-Snedecor, beta, gamma, lognormal, logistic.
+- The same for discrete distributions: binomial, hypergeometric, bernoulli (still missing), etc.
-## Features
+### Medium-term
-* Very fast ruby 1.8.7/1.9.+ implementation, with improved method to calculate factorials and others common functions
-* All methods tested on several ranges. See spec/
+- Implement [DSFMT](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/) for the uniform random generator.
+- Cauchy distribution.
+### Long-term
+
+- Implementing everything in the distributions x functions table above.
+
## Issues
* On JRuby and Rubinius, BivariateNormal returns incorrect pdf
For current issues see the [issue tracker pages](https://github.com/sciruby/distribution/issues).
+
+## OMG! I want to help!
+
+Everyone is welcome to help! Please, test these distributions with your own use
+cases and give a shout on the issue tracker if you find a problem or something
+is strange or hard to use. Documentation pull requests are totally welcome.
+More generally, any ideas or suggestions are welcome -- even by private e-mail.
+
+If you want to provide a new distribution, run `lib/distribution`:
+
+```
+$ distribution --new your_distribution
+```
+
+This should create the main distribution file, the directory with Ruby and GSL engines and specs on the spec/ directory.