WIP: Improved docs

docs/Project.toml

@@ -1,4 +1,10 @@
 [deps]
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DemoCards = "311a05b2-6137-4a5a-b473-18580a3d38b5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 Pluto = "c3e4b0f8-55cb-11ea-2926-15256bba5781"
+ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea"

docs/ddc.bib

@@ -39,15 +39,15 @@ @article{hotz1993
 @incollection{rust_chapter_1994,
 	title = {Chapter 51 Structural estimation of markov decision processes},
         editor = {Robert F. Engle and Daniel L. McFadden},
-        series = {Handbook of Econometrics},
+        booktitle = {Handbook of Econometrics},
 	volume = {4},
 	isbn = {1573-4412},
 	url = {http://www.sciencedirect.com/science/article/B7GX7-4FPWV09-P/2/e9b682c3d248e68bdb50c9fbe88ca778},
 	publisher = {Elsevier},
 	author = {John Rust},
 	year = {1994},
 	pages = {3081--3143}
-
+}
 
 @article{rr1995,
 author={Rust,John and Rothwell,Geoffrey},
@@ -75,3 +75,24 @@ @TECHREPORT{rr1995w
 abstract = {This paper presents a dynamic programming (DP) model of an electric utility's optimal policy for operating a nuclear power plant (NPP). The utility chooses the level of capacity utilization of the NPP as a function of signals about the NPP's current operating state. In each period the utility must determine whether or not to operate the reactor, or shut it down for preventive maintenance or refueling, or to permanently close the plant. Maintenance performed during periodic refueling outages partially ``regenerates'' the NPP, reducing the risk of unplanned forced outages in succeeding periods. Using monthly data on U.S. NPPs in the post-TMI era we estimate parameters of the utility's profit function, the failure processes that lead to unplanned forced outages, and the parameters governing the duration of refueling outages. These parameters imply an endogenous distribution of operating spells and capacity utilization levels that depend on the NPP's age, signals the operator receives about the NPP's current operating state, and the duration since last refueling. The estimates of the DP model reveal that utilities appear responsive to NRC regulation insofar as they impute a very high cost to unplanned and forced outages. Utilities are also highly averse to causing unnecessary wear and tear on their NPP's caused by stop/start operation of their NPP's including planned and unplanned outages. Overall, the DP model yields very accurate predictions of nuclear power generation including the impact of the relatively rare event of NPP decommissionings.},
 url = {http://EconPapers.repec.org/RePEc:wpa:wuwpmi:9502001}
 }
+
+@article{magnac2002,
+ ISSN = {00129682, 14680262},
+ URL = {http://www.jstor.org/stable/2692293},
+ author = {Thierry Magnac and David Thesmar},
+ journal = {Econometrica},
+ number = {2},
+ pages = {801--816},
+ publisher = {[Wiley, Econometric Society]},
+ title = {Identifying Dynamic Discrete Decision Processes},
+ urldate = {2022-12-01},
+ volume = {70},
+ year = {2002}
+}
+
+@misc{schrimpf2011,
+author={Paul Schrimpf},
+year={2011},
+title={Structural Dynamic Models},
+url={https://faculty.arts.ubc.ca/pschrimpf/628/dynamic.pdf}
+}

docs/demos/Rust_&_Rothwell/rr.jl

@@ -0,0 +1,53 @@
+# ---
+# title: Reproducing Rust & Rothwell (1995)
+# date: 2022
+# author: Paul Schrimpf
+# ---
+
+using ZipFile, DataFrames, Downloads, CSV, CategoricalArrays
+
+# # Data 
+# The data for this paper is available from the *Journal of Applied Econometrics* data archive. 
+# It's supplied as a zip archive containing text files. Each text file named nameX.mon contains monthly data from a plant, reactor number X. There's also nukesum.asc with time-variant information about each reactor and plant. 
+#
+# First, we donwload the zip archive.
+dataurl="http://qed.econ.queensu.ca/jae/1995-v10.S/rust-rothwell/rr-data.zip"
+datazip="rr-data.zip"
+if !isfile(datazip)
+    Downloads.download(dataurl, datazip)
+end 
+
+# Now, we read the time invariant information.
+
+nukesum = let 
+    zfr = ZipFile.Reader(datazip) 
+    df = filter(x->x.name=="nukesum.asc",zfr.files)[1] |>
+    x->CSV.File(x, header=false, delim=" ", ignorerepeated=true) |>
+    DataFrame 
+    rename!(df, ["name","firm",
+    "start month","start day","start year",
+    "thermal capacity","nameplate rating",
+    "net power","arch engineer","steam system",
+    "builder","turbine","state"])
+    df
+end
+
+# And the time-varying information.
+
+nuket = let 
+    zfr = ZipFile.Reader(datazip)
+    df = vcat([DataFrame(CSV.File(f, header=false, delim=" ", ignorerepeated=true))
+    for f ∈ zfr.files if occursin(r"\.mon$", f.name)]...)
+    rename!(df, ["name","ID","steam system","year","month",
+    "vintage","age","hours refuel","hours planned outage",
+    "hours forced outage","hours total",
+    "scram in","scram out","number forced outages"])
+    df[!,"steam system"] = recode(df[!,"steam system"], 
+    1=>"Babcock Wilcox",2=>"Combustion", 3=>"GE", 4=>"Westinghouse", 
+    5=>"Other1",6=>"Other2") 
+    df[!,"vintage"] = recode(df[!,"vintage"], 0=>"preTMI", 1=>"postTMI")
+    df
+end;
+
+describe(nuket)
+

docs/make.jl

@@ -1,9 +1,16 @@
 using DynamicDiscreteChoice
-using Documenter, DocumenterCitations
+using Documenter, DocumenterCitations, DemoCards
 
 DocMeta.setdocmeta!(DynamicDiscreteChoice, :DocTestSetup, :(using DynamicDiscreteChoice); recursive=true)
 
 
+# generate demo files
+demopage, postprocess_cb, demo_assets = makedemos("demos") # this is the relative path to docs/
+# if there are generated css assets, pass it to Documenter.HTML
+assets = []
+isnothing(demo_assets) || (push!(assets, demo_assets))
+
+
 bib = CitationBibliography("ddc.bib")
 
 makedocs(bib;
@@ -13,14 +20,20 @@ makedocs(bib;
     sitename="DynamicDiscreteChoice.jl",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://ubcecon567.github.io/DynamicDiscreteChoice.jl",
-        assets=String[],
+        canonical="https://UBCECON567.github.io/DynamicDiscreteChoice.jl",
+        assets=assets,
     ),
     pages=[
         "Home" => "index.md",
+        "Method" => "method.md",
+        "Example" => "rr-example.md",
+        demopage,
     ],
 )
 
+# for democards
+postprocess_cb()
+
 deploydocs(;
     repo="github.com/UBCECON567/DynamicDiscreteChoice.jl",
     devbranch="main",