Skip to content
Permalink
Browse files

documenter first pass

  • Loading branch information...
arnavs committed Jul 20, 2018
1 parent 640fe29 commit ac09abe74f00c8ef17314a0560bd1e2e02a723c6
Showing with 280 additions and 45 deletions.
  1. +2 −0 .gitignore
  2. +3 −0 .travis.yml
  3. +6 −30 README.md
  4. +2 −1 REQUIRE
  5. +10 −0 docs/make.jl
  6. +24 −0 docs/mkdocs.yml
  7. +95 −0 docs/src/index.md
  8. +2 −1 src/Expectations.jl
  9. +108 −8 src/iterable.jl
  10. +26 −4 src/types.jl
  11. +2 −1 test/REQUIRE
@@ -1,3 +1,5 @@
*.jl.cov
*.jl.*.cov
*.jl.mem
docs/build/
docs/site/
@@ -33,3 +33,6 @@ after_success:
- julia -e 'cd(Pkg.dir("Expectations")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'
# push coverage results to Codecov
- julia -e 'cd(Pkg.dir("Expectations")); Pkg.add("Coverage"); using Coverage; Codecov.submit(Codecov.process_folder())'
# build documentation
- julia -e 'Pkg.add("Documenter")'
- julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))'
@@ -2,6 +2,8 @@
[![codecov](https://codecov.io/gh/econtoolkit/Expectations.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/econtoolkit/Expectations.jl)
[![Coverage Status](https://coveralls.io/repos/github/econtoolkit/Expectations.jl/badge.svg?branch=master)](https://coveralls.io/github/econtoolkit/Expectations.jl?branch=master)

[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://econtoolkit.github.io/Expectations.jl/stable)
[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://ceontoolkit.github.io/Expectations.jl/latest)

# Expectations

@@ -18,31 +20,20 @@ The underlying distributions are objects from `Distributions.jl` (currently `<:U

### Quadrature Algorithms

We have `QuadratureAlgorithm` for algorithms which pick their own nodes, and
`ExplicitQuadratureAlgorithm` for ones where the user picks. Currently, the only concrete subtypes of
the former are `Gaussian` and `FiniteDiscrete`, and `Trapezoidal` for the latter.
We support different types of Gaussian quadrature (Gauss-Hermite, Gauss-Legendre, Gauss-Laguerre, etc.) based on the distribution, as well as some methods
with user-defined nodes (e.g., trapezoidal integration).

### Expectation Operator

The package produces an expectation operators, `E`, as follows:
The key object is the expectation operator, `E`, which can be used as follows:

```julia
dist = Normal()
E = expectation(dist)
E(x -> x)
E_morenodes = expectation(dist; n = 50) # Be careful, as too many nodes can introduce floating-point errors from miniscule exponents.
```

Expectations fall into a type hierarchy `IterableExpectation{NT, WT} <: IterableExpectation <: Expectation`
Currently, only iterables are supported, and they are parametrized by `weights` and `nodes`.

```julia
h(x) = x^2
dot(weights(E), h.(nodes(E)))
```

Or as a linear operator, either when you give your own nodes (or apply a function `h.(nodes(E))`):
Or as a linear operator on vectors:

```julia
dist = Normal()
@@ -52,18 +43,3 @@ E = expectation(dist, z; kwargs...)
E*h # is equal to dot(h, weights(E))
3E*h # is equal to 3(E*h) and (3E)*h
```

### Mathematical Details

For finite discrete distributions, we simply compute the precise expectation. For
continuous distributions given without nodes, we use some form of Gaussian quadrature
(either Gauss-Legendre, or a distribution-specific form for common distributions). These
distribution-specific algorithms are derived from `FastGaussQuadrature.jl`.

The default for distributions with nodes (and currently the only supported algorithm) is
trapezoidal quadrature.

It is important to ensure that the particular quadrature scheme used is compatible with the
given function, distribution, and support. See the tests for accuracy under some normal and
edge cases.

@@ -2,4 +2,5 @@ julia 0.6+
Distributions
Compat
FastGaussQuadrature
SpecialFunctions
SpecialFunctions
Reexport
@@ -0,0 +1,10 @@
using Documenter, Expectations

# Compile the raw documentation.
makedocs()

# Push the documentation to the server.
deploydocs(
repo = "github.com/econtoolkit/Expectations.jl.git",
julia = "nightly"
)
@@ -0,0 +1,24 @@
site_name: Expectations.jl
repo_url: https://github.com/econtoolkit/Expectations.jl
site_description: A package to help with numerical expectations of random variables and their functions.
site_author: econtoolkit, jlperla, ArnavSood

theme: readthedocs

extra_css:
- assets/Documenter.css

extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS_HTML
- assets/mathjaxhelper.js

markdown_extensions:
- extra
- tables
- fenced_code
- mdx_math

docs_dir: 'build'

pages:
- Home: index.md
@@ -0,0 +1,95 @@
# Expectations.jl Documentation
```@contents
```

## Overview

The goal of this package is to provide an intuitive and mathematically sound interface for taking expectations of random variables
and their higher-order functions (i.e., if ``X \sim N(0, 1)``, what is ``\mathbb{E}[\sin(X)]``?).

The underlying random variables are assumed to be distributions from [`Distributions.jl`](https://github.com/juliastats/distributions.jl). Currently,
only univariate distributions are supported.

## Installation

To install, run:

```@repl
Pkg.add("Expectations")
```

Currently, Julia 0.6 and Julia 0.7 are supported.

## The Expectation Operator

The key object in this package is an **expectation operator**, or an object `<: Expectation`. These include all objects capable of being called on
a function; e.g. that support a method `function (e::Expectation)(f::Function)`. You can create these as following:

```@example
dist = Normal();
E = expectation(dist)
```

You can also choose and algorithms and default parameters (see below for list):

```@example
E = expectation(dist, Gaussian; n = 30)
```

These objects can then be applied to functions:

```@example
E(x -> x)
E(x -> x^2)
```

### IterableExpectation

The only concrete subtype of `Expectation` currently supported is `IterableExpectation{NT, WT}`. These are expectations for which we have a
discrete vector of quadrature nodes and weights, either defined by user fiat, or set algorithmically. These support some additional behavior:

```@example
nodeList = nodes(E)
vals = map(x -> sin(x)^2, nodeList)
E * vals
(2E) * vals
```

The above behavior, in some sense, puts the "operator" in "expectation operator"; that is, it allows it to move elements of a vector space around,
and to be scalar-multiplied.


## Supported Distributions, Algorithms, Keywords, and Defaults

Here is a list of currently supported distributions, along with keyword arguments and their defaults.

| Distribution Name | Algorithm (Julia Type) | Keywords and Defaults | Restrictions |
| ----------------- | -------------- | --------------------- | ------------ |
| Discrete Univariate | FiniteDiscrete <: QuadratureAlgorithm | N/A | Support must be finite. |
| Continuous Univariate | Gauss-Legendre (Gaussian <: QuadratureAlgorithm) | n = 500 | Support must be a compact interval ``[a, b]``. |
| Normal <: Continuous Univariate | Gauss-Hermite (...) | n = 30 | Parameters must be finite. |
| LogNormal <: ... | Gauss-Hermite (...) | n = 30 | ... |
| Beta <: ... | Gauss-Jacobi (...) | n = 32 | ... |
| Exponential <: ... | Gauss-Laguerre (...) | n = 32 | ... |
| Gamma <: ... | Gauss-Laguerre (...) | n = 32 | ... |
| Univariate | Trapezoidal <: ExplicitQuadratureAlgorithm | N/A | All nodes must be inside distribution's support. |

## Mathematical Details and References

The specific quadrature algorithms come from the [`FastGaussQuadrature.jl`](https://github.com/ajt60gaibb/FastGaussQuadrature.jl) library, which is maintained by [Alex Townsend](https://github.com/ajt60gaibb) of Cornell University. Much of the quadrature code came from the [`DistQuads.jl`](https://github.com/pkofod/DistQuads.jl) library, which is maintained by [Patrick K. Mogensen](https://github.com/pkofod) at the University of Copenhagen.

:warning: It is important to be aware of the deficiencies of numerical quadrature schemes. For example, it is recommended to be careful when using these methods for the following classes of functions and situations:

* Discontinuous or nondifferentiable functions (even if the function is a.e.-differentiable)
* Periodic/oscillatory functions with a high frequency
* Extremely large numbers of quadrature nodes, which may lead to vanishingly small weights.

## Contact

If you would like to get in touch, please do one of the following:

* Issue requests: Open an issue on the [package repository](https://github.com/econtoolkit/Expectations.jl) with the tag `feature request`.
* Bugs: Same as above, but with the tag `bug`.
* Pull Request: We are always open to new functionality. If you have a feature you'd like to add (say, a new distribution or algorithm), once you prepare a PR with the feature and some tests, open it in the usual way.
* Other: You can reach out to Jesse Perla at `jesse.perla@ubc.ca` and Arnav Sood at `arnav.sood@ubc.ca`.
* Citation: If this package was helpful in your research work, you may consider citing the package in whatever method is appropriate for your field.
@@ -3,9 +3,10 @@
module Expectations

# Load external dependencies.
using Distributions, Compat, FastGaussQuadrature
using Compat, FastGaussQuadrature
using Compat.LinearAlgebra
using SpecialFunctions
@reexport using Distributions

# Load internal files.
include("types.jl"),

0 comments on commit ac09abe

Please sign in to comment.
You can’t perform that action at this time.