Add documentation

junyuan-chen · junyuan-chen · commit ba6af0cdd1cb · 2022-03-02T20:30:26.000-08:00
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -0,0 +1,21 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs -e "using Pkg; lib = joinpath(@__DIR__, \""lib\""); paths = joinpath.(lib, readdir(lib)); foreach(x->Pkg.develop(PackageSpec(path=x)), paths); Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()"
+      - name: Build and deploy
+        run: julia --project=docs docs/make.jl
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.SSH_KEY }}
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,7 +2,10 @@
 DiffinDiffs = "1c15b2bf-cfaa-4a64-9ed6-b84bdd745e5c"
 DiffinDiffsBase = "7fc23ce2-6e83-4e3c-822f-a79085ccb3e8"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 InteractionWeightedDIDs = "4fda0319-85a0-4a01-849e-821b918731ee"
+StatsProcedures = "d2f4e7c0-4966-47f3-9552-d63f8a71a436"
+Vcov = "ec2bfdc2-55df-4fc9-b9ae-4958c2cf2486"
 
 [compat]
 Documenter = "0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,12 +1,19 @@
 using Documenter
 using DiffinDiffs
+using DocumenterCitations
+using StatsProcedures
+using Vcov
 
-makedocs(
+bib = CitationBibliography(joinpath(@__DIR__, "../paper/paper.bib"), sorting=:nyt)
+
+makedocs(bib,
     modules = [DiffinDiffsBase, InteractionWeightedDIDs],
     format = Documenter.HTML(
+        assets = ["assets/favicon.ico"],
         canonical = "https://JuliaDiffinDiffs.github.io/DiffinDiffs.jl/stable/",
         prettyurls = get(ENV, "CI", nothing) == "true",
-        collapselevel = 1
+        collapselevel = 2,
+        ansicolor = true
     ),
     sitename = "DiffinDiffs.jl",
     authors = "Junyuan Chen",
@@ -18,13 +25,24 @@ makedocs(
         "Library" => [
             "Treatment Types" => "lib/treatments.md",
             "Parallel Types" => "lib/parallels.md",
-            "Treatment Terms" => "lib/terms.md",
+            "Formula Terms" => "lib/terms.md",
+            "Estimators" => "lib/estimators.md",
+            "Inference" => "lib/inference.md",
+            "Procedures" => "lib/procedures.md",
+            "Results" => "lib/results.md",
+            "Tables" => "lib/tables.md",
+            "Panel Operations" => "lib/panel.md",
+            "ScaledArrays" => "lib/ScaledArrays.md",
+            "StatsProcedures" => "lib/StatsProcedures.md",
             "Miscellanea" => "lib/miscellanea.md"
         ],
         "About" => [
+            "References" => "about/references.md",
+            "License" => "about/license.md"
         ]
     ],
-    workdir = joinpath(@__DIR__, "..")
+    workdir = joinpath(@__DIR__, ".."),
+    doctest = false
 )
 
 deploydocs(
diff --git a/docs/src/about/license.md b/docs/src/about/license.md
@@ -0,0 +1,5 @@
+# License
+
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+is licensed under the
+[MIT license](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl/blob/master/LICENSE.md).
diff --git a/docs/src/about/references.md b/docs/src/about/references.md
@@ -0,0 +1,4 @@
+# References
+
+```@bibliography
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -0,0 +1,47 @@
+# DiffinDiffs.jl
+
+Welcome to the documentation site for DiffinDiffs.jl!
+
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+is a suite of Julia packages for difference-in-differences (DID).
+The goal of its development is to promote applications of
+the latest advances in econometric methodology related to DID in academic research
+while leveraging the performance and composability of the Julia language.
+
+## Why DiffinDiffs.jl?
+
+- **Fast:** Handle datasets of multiple gigabytes with ease
+- **Transparent:** Completely open source and natively written in Julia
+- **Extensible:** Unified interface with modular package organization
+
+## Package Organization
+
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+reexports types, functions and macros defined in
+component packages that are separately registered.
+The package itself does not host any concrete functionality except documentation.
+This facilitates decentralized code development under a unified framework.
+
+| Package | Description | Version | Status |
+|:--------|:------------|:--------|:-------|
+[DiffinDiffsBase](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl/tree/master/lib/DiffinDiffsBase) | Base package for DiffinDiffs.jl | [![version](https://juliahub.com/docs/DiffinDiffsBase/version.svg)](https://juliahub.com/ui/Packages/DiffinDiffsBase/AGMId) | [![pkgeval](https://juliahub.com/docs/DiffinDiffsBase/pkgeval.svg)](https://juliahub.com/ui/Packages/DiffinDiffsBase/AGMId) |
+[InteractionWeightedDIDs](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl/tree/master/lib/InteractionWeightedDIDs) | Regression-based multi-period DID | [![version](https://juliahub.com/docs/InteractionWeightedDIDs/version.svg)](https://juliahub.com/ui/Packages/InteractionWeightedDIDs/Vf93d) | [![pkgeval](https://juliahub.com/docs/InteractionWeightedDIDs/pkgeval.svg)](https://juliahub.com/ui/Packages/InteractionWeightedDIDs/Vf93d) |
+
+More components will be included in the future as development moves forward.
+
+## Installation
+
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+can be installed with the Julia package manager
+[Pkg](https://docs.julialang.org/en/v1/stdlib/Pkg/).
+From the Julia REPL, type `]` to enter the Pkg REPL and run:
+
+```
+pkg> add DiffinDiffs
+```
+
+This will install all the component packages of
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+as dependencies.
+There is no need to explicitly add the individual components
+unless one needs to access internal objects.
diff --git a/docs/src/lib/ScaledArrays.md b/docs/src/lib/ScaledArrays.md
@@ -0,0 +1,6 @@
+# ScaledArrays
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/ScaledArrays.jl"]
+```
diff --git a/docs/src/lib/StatsProcedures.md b/docs/src/lib/StatsProcedures.md
@@ -0,0 +1,5 @@
+# StatsProcedures
+
+```@autodocs
+Modules = [StatsProcedures]
+```
diff --git a/docs/src/lib/estimators.md b/docs/src/lib/estimators.md
@@ -0,0 +1,6 @@
+# Estimators
+
+```@autodocs
+Modules = [DiffinDiffsBase, InteractionWeightedDIDs]
+Filter = t -> typeof(t) === DataType && t <: DiffinDiffsEstimator
+```
diff --git a/docs/src/lib/inference.md b/docs/src/lib/inference.md
@@ -0,0 +1,5 @@
+# Inference
+
+```@autodocs
+Modules = [Vcov]
+```
diff --git a/docs/src/lib/miscellanea.md b/docs/src/lib/miscellanea.md
@@ -0,0 +1,6 @@
+# Miscellanea
+
+```@autodocs
+Modules = [DiffinDiffsBase, InteractionWeightedDIDs]
+Pages = ["src/utils.jl"]
+```
diff --git a/docs/src/lib/panel.md b/docs/src/lib/panel.md
@@ -0,0 +1,6 @@
+# Panel Operations
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/operations.jl", "src/time.jl"]
+```
diff --git a/docs/src/lib/parallels.md b/docs/src/lib/parallels.md
@@ -0,0 +1,6 @@
+# Parallel Types
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/parallels.jl"]
+```
diff --git a/docs/src/lib/procedures.md b/docs/src/lib/procedures.md
@@ -0,0 +1,6 @@
+# Procedures
+
+```@autodocs
+Modules = [DiffinDiffsBase, InteractionWeightedDIDs]
+Pages = ["src/procedures.jl"]
+```
diff --git a/docs/src/lib/results.md b/docs/src/lib/results.md
@@ -0,0 +1,7 @@
+# Results
+
+```@autodocs
+Modules = [DiffinDiffsBase, InteractionWeightedDIDs]
+Pages = ["src/did.jl"]
+Filter = t -> !(typeof(t) === DataType && t <: DiffinDiffsEstimator)
+```
diff --git a/docs/src/lib/tables.md b/docs/src/lib/tables.md
@@ -0,0 +1,6 @@
+# Tables
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/tables.jl"]
+```
diff --git a/docs/src/lib/terms.md b/docs/src/lib/terms.md
@@ -0,0 +1,6 @@
+# Treatment Terms
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/terms.jl"]
+```
diff --git a/docs/src/lib/treatments.md b/docs/src/lib/treatments.md
@@ -0,0 +1,6 @@
+# Treatment Types
+
+```@autodocs
+Modules = [DiffinDiffsBase]
+Pages = ["src/treatments.jl"]
+```
diff --git a/docs/src/man/getting-started.md b/docs/src/man/getting-started.md
@@ -0,0 +1,119 @@
+# Getting Started
+
+To demonstrate the basic usage of
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl),
+we walk through the processes of reproducing empirical results from relevant studies.
+Please refer to the original papers for details on the context.
+
+## Dynamic Effects in Event Studies
+
+As a starting point,
+we reproduce results from the empirical illustration in [SunA21E](@cite).
+
+### Data Preparation
+
+[DiffinDiffs.jl](https://github.com/JuliaDiffinDiffs/DiffinDiffs.jl)
+requires that the data used for estimation
+are stored in a column table compatible with the interface defined in
+[Tables.jl](https://github.com/JuliaData/Tables.jl).
+This means that virtually all types of data frames,
+including [DataFrames.jl](https://github.com/JuliaData/DataFrames.jl),
+are supported.
+For the sake of illustration,
+here we directly load the dataset that is bundled with the package
+by calling [`exampledata`](@ref):
+
+```@example reprSA
+using DiffinDiffs
+hrs = exampledata("hrs")
+```
+
+In this example, `hhidpn`, `wave`, and `wave_hosp`
+are columns for the unit IDs, time IDs and treatment time respectively.
+The rest of the columns contain the outcome variables and covariates.
+It is important that the time IDs and treatment time
+refer to each time period in a compatible way
+so that subtracting a value of treatment time from a value of calendar time
+(represented by a time ID) with operator `-` yields a meaningful value of relative time,
+the amount of time elapsed since treatment time.
+
+### Empirical Specifications
+
+To produce the estimates reported in panel (a) of Table 3 from [SunA21E](@cite),
+we specify the estimation via [`@did`](@ref) as follows:
+
+```@example reprSA
+r = @did(Reg, data=hrs, dynamic(:wave, -1), notyettreated(11),
+    vce=Vcov.cluster(:hhidpn), yterm=term(:oop_spend), treatname=:wave_hosp,
+    treatintterms=(), xterms=(fe(:wave)+fe(:hhidpn)))
+nothing # hide
+```
+
+Before we look at the results,
+we briefly explain some of the arguments that are relatively more important.
+[`Reg`](@ref), which is a shorthand for [`RegressionBasedDID`](@ref),
+is the type of the estimation to be conducted.
+Here, we need estimation that is conducted by directly solving least-squares regression
+and hence we use [`Reg`](@ref) to inform [`@did`](@ref)
+the relevant set of procedures,
+which also determines the set of arguments that are accepted by [`@did`](@ref).
+
+We are interested in the dynamic treatment effects.
+Hence, we use [`dynamic`](@ref) to specify the data column
+containing values representing calendar time of the observations
+and the reference period, which is `-1`.
+For identification, a crucial assumption underlying DID
+is the parallel trends assumption.
+Here, we assume that the average outcome paths of units treated in periods before `11`
+would be parallel to the observed paths of units treated in period `11`.
+That is, we are taking units with treatment time `11` as the not-yet-treated control group.
+We specify `treatname` to be `:wave_hosp`,
+which indicates the column that contains the treatment time.
+The interpretation of `treatname` depends on the context
+that is jointly determined by the type of the estimator, the type of the treatment
+and possibly the type of parallel trends assumption.
+The rest of the arguments provide additional information on the regression specifications.
+The use of them can be found in the documentation for [`RegressionBasedDID`](@ref).
+
+We now move on to the result returned by [`@did`](@ref):
+
+```@example reprSA
+r # hide
+```
+
+The object returned is of type [`RegressionBasedDIDResult`](@ref),
+which contains the estimates for treatment-group-specific average treatment effects
+among other information.
+Instead of printing the estimates from the regression,
+which can be very long if there are many treatment groups,
+REPL prints a summary table for `r`.
+Here we verify that the estimate for relative time `0` among the cohort
+who received treatment in period `8` is about `2826`,
+the value reported in the third column of Table 3(a) in the paper.
+
+```@example reprSA
+coef(r, "wave_hosp: 8 & rel: 0")
+```
+
+Various accessor methods are defined for retrieving values from a result such as `r`.
+See [Results](@ref) for a full list of them.
+
+### Aggregation of Estimates
+
+The treatment-group-specific estimates in `r`
+are typically not the ultimate objects of interest.
+We need to estimate the path of the average dynamic treatment effects
+across all treatment groups.
+Such estimates can be easily obtained
+by aggregating the estimates in `r` via [`agg`](@ref):
+
+```@example reprSA
+a = agg(r, :rel)
+```
+
+Notice that `:rel` is a special value used to indicate that
+the aggregation is conducted for each value of relative time separately.
+The aggregation takes into account sample weights of each treatment group
+and the variance-covariance matrix.
+The resulting estimates match those reported in the second column of Table 3(a) exactly.
+
diff --git a/paper/paper.bib b/paper/paper.bib
@@ -0,0 +1,12 @@
+@Article{SunA21E,
+  author   = {Liyang Sun and Sarah Abraham},
+  title    = {Estimating Dynamic Treatment Effects in Event Studies with Heterogeneous Treatment Effects},
+  journal  = {Journal of Econometrics},
+  year     = {2021},
+  volume   = {225},
+  number   = {2},
+  pages    = {175--199},
+  issn     = {0304-4076},
+  doi      = {https://doi.org/10.1016/j.jeconom.2020.09.006},
+  url      = {https://www.sciencedirect.com/science/article/pii/S030440762030378X},
+}

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# References
++
 +```@bibliography
 +```