Merge pull request #61 from adolgert/docs/pretend-reading

Docs/pretend reading

.gitignore

@@ -24,10 +24,16 @@ deps/src/
 docs/build/
 docs/site/
 # Literate.jl creates chunk files.
-docs/src/literate
+docs/src/commonrandom.md
+docs/src/constant_birth.md
 docs/src/distributions.md
+docs/src/gsmp.md
+docs/src/hierarchical.md
+docs/src/literate
 docs/src/mainloop.md
-docs/src/constant_birth.md
+docs/src/memory.md
+docs/src/reliability.md
+docs/src/shifting.md
 docs/src/sir.md
 
 # File generated by Pkg, the package manager, based on a corresponding Project.toml

docs/make.jl

@@ -20,7 +20,10 @@ adliterate = [
         ("constant_birth.jl", "constant_birth"),
         ("sir.jl", "sir"),
         ("commonrandom.jl", "commonrandom"),
-        ("reliability.jl", "reliability")
+        ("reliability.jl", "reliability"),
+        ("memory.jl", "memory"),
+        ("gsmp.jl", "gsmp"),
+        ("hierarchical.jl", "hierarchical")
     ]
 literate_subdir = joinpath(example_base, "literate")
 isdir(literate_subdir) || mkdir(literate_subdir)
@@ -37,7 +40,7 @@ for (source, target) in adliterate
         rm("$(ftarget).md", force=true)
     end
     if !isfile("$(ftarget).md") || mtime(fsource) > mtime("$(ftarget).md")
-        println("Literate of $source to $target")
+        @info "Literate of $source to $target"
         Literate.markdown(
             fsource,
             example_base,
@@ -48,7 +51,10 @@ for (source, target) in adliterate
         ischunk = Regex("$(target)-[0-9]+.(png|svg|pdf)")
         chunks = [fn for fn in readdir(example_base) if match(ischunk, fn) !== nothing]
         for chunk in chunks
-            mv(joinpath(example_base, chunk), joinpath(example_base, "literate", chunk))
+            chunk_source = joinpath(example_base, chunk)
+            chunk_target = joinpath(example_base, "literate", chunk)
+            @info "Moving $chunk_source to $chunk_target"
+            mv(chunk_source, chunk_target)
         end
     end
 end
@@ -72,13 +78,13 @@ makedocs(;
             "distributions.md"
         ],
         "Manual" => [
-            "Structure" => "objects.md",
-            "commonrandom.md",
-            "background.md",
             "distrib.md",
-            "Develop" => "develop.md",
+            "background.md",
+            "GSMP" => "gsmp.md",
             "samplers.md",
-            "Vector Addition Systems" => "vas.md",
+            "hierarchical.md",
+            "memory.md",
+            "commonrandom.md",
         ],
         "Examples" => [
             "Birth-death Process" => "constant_birth.md",

docs/src/background.md

@@ -1,4 +1,4 @@
-# Background
+# Markov Processes
 
 This addresses two main points, how to specify a model for the library
 using distributions defined by hazards and why such a specification,
@@ -18,8 +18,8 @@ measles.
 It frequently happens that random samples of the real valued variables
 such as $\bf{X}$ are actually analyzed on a discrete scale. For example
 Stocks' data on latent periods of measles in
-`latent_period`{.interpreted-text role="ref"} is based on daily visits
-by patients.
+`latent_period` is based on daily visits
+by patients [Stocks:1931].
 
 The (cumulative) distribution of $\bf{X}$ is defined as
 
@@ -36,7 +36,7 @@ f_{X}(k) & =  \mathcal{P}[X=k] \\
 \end{aligned}
 ```
 
-For Stocks' data in `latent_period`{.interpreted-text role="ref"}, the
+For Stocks' data in `latent_period`, the
 density at day $k$ should be interpreted as the probability of the
 appearance of symptoms since the previous visit on day $k-1$.
 
@@ -53,7 +53,7 @@ h_{X}(k) & =  \mathcal{P}[X=k\; |\; k-1<X] \\
 ```
 
 In the case of Stocks' data, the hazards shown in
-`latent_period_hazard`{.interpreted-text role="ref"} would correspond to
+`latent_period_hazard` would correspond to
 the probability of symptoms appearing at day $k$ given that the patient
 had not displayed symptoms at any previous visit. As time goes on,
 patients who have already developed symptoms effectively reduce the pool
@@ -177,7 +177,7 @@ a new stochastic process, $\bf{Z}$, from $\bf{Y}$ by the rule
 $Z_{t} = s_k$ in the time interval $t_n \le t
 < t_{n+1}$ given $Y_{n} = (s_k, t_n)$ . In other words, $\bf{Z}_{t}$ is
 a piecewise constant version of $\bf{Y}$ as shown in
-`piecewise_Z`{.interpreted-text role="ref"}
+`piecewise_Z`.
 
 ![Figure 4. **Realization of a continuous time stochastic process and
 associated Markov chain.**](assets/piecewise_Z.svg)
@@ -280,6 +280,10 @@ waiting time, we won't end up needing to relation $\pi_{ij}(\tau)$ to
 $\Pi_{ij}(\tau)$ when finding trajectories or computing hazards, so the
 more complicated relationship won't be a problem.
 
+## References
+
+[Stocks:1931]	P. Stocks, “[Incubation period of measles](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2313639/),” British Medical Journal 1(3655): p. 157.
+
 ## Acknowledgement
 
 This section comes was created by the Analytical Framework for Infectious Disease Dynamics (AFIDD) group at Cornell University in conjunction with the USDA Agricultural Research Service. This work was supported by the Science & Technology Directorate, Department of Homeland Security via interagency agreement no. HSHQDC-10-X-00138.

docs/src/commonrandom.jl

@@ -4,7 +4,7 @@
 
 # If you set up the same model and run it with different initial random number generator (RNG) states, then it will create a set of trajectories. Fleck sees these as a sequence of clock events and times of those events. You are usually interested in some summary outcomes of a simulation, such as the total time to a goal or the number of events. This summary outcome is a predictable function of the trajectories. We often want to ask how the goal function depends on simulation parameters, and that can be difficult to determine because each trajectory gives an individual value, and the set of trajectories gives an estimate that can have wide variance.
 
-# What we want is a variance reduction technique. Common random numbers (CRN) are a variance reduction technique that enables you to use fewer simulation runs to compare the effect of different simulation parameters on the outcome. There are several other variance reduction techniques, such as antithetic variates and importance sampling, but let's look at common random numbers in Fleck.
+# What we want is a [variance reduction](https://en.wikipedia.org/wiki/Variance_reduction) technique. Common random numbers (CRN) are a variance reduction technique that enables you to use fewer simulation runs to compare the effect of different simulation parameters on the outcome. There are several other variance reduction techniques, such as antithetic variates and importance sampling, but let's look at common random numbers in Fleck.
 
 # If you estimate a value with $n$ independent trajectories, then the bias of the estimate is proportional to $1/\sqrt{n}$ in most cases. If you want to distinguish the effect of changing a parameter, then the estimate must be precise enough that you can see the difference. It is common to use millions of trajectories. On the other hand, CRN means that you can produce $n=100$ trajectories, with significant bias in the estimate, and still see the effect of changing a parameter.