Merge 93c686c into e2a35b6

xKDR · Oct 31, 2022 · 72ce5a1 · 72ce5a1
2 parents e2a35b6 + 93c686c
commit 72ce5a1
Show file tree

Hide file tree

Showing 21 changed files with 303 additions and 485 deletions.
diff --git a/clean_examples.jl b/clean_examples.jl
diff --git a/docs/src/assets/hist.png b/docs/src/assets/hist.png
diff --git a/docs/src/assets/scatter.png b/docs/src/assets/scatter.png
diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -1,7 +1,62 @@
 # Examples
 
-The following examples use the Academic Performance Index (API) dataset for Californian schools.
+The following examples use the
+[Academic Performance Index](https://r-survey.r-forge.r-project.org/survey/html/api.html)
+(API) dataset for Californian schools. The data sets contain information for all schools
+with at least 100 students and for various probability samples of the data.
 
-```@docs
-svyby(formula::Symbol, by, design::svydesign, func::Function, params = [])
+The API program has been discontinued at the end of 2018. Information is archived at
+[https://www.cde.ca.gov/re/pr/api.asp](https://www.cde.ca.gov/re/pr/api.asp)
+
+## Simple Random Sample
+
+Firstly, a survey design needs a dataset from which to gather information. A dataset
+can be loaded as a `DataFrame` using the `load_data` function:
+
+```julia
+julia> apisrs = load_data("apisrs");
+```
+
+Next, we can build a design. The most basic survey design is a simple random sample design.
+A [`SimpleRandomSample`](@ref) can be instantianted by calling the constructor:
+
+```julia
+julia> srs = SimpleRandomSample(apisrs; weights = :pw)
+SimpleRandomSample:
+data: 200x42 DataFrame
+weights: 31.0, 31.0, 31.0, ..., 31.0
+probs: 0.0323, 0.0323, 0.0323, ..., 0.0323
+fpc: 6194, 6194, 6194, ..., 6194
+popsize: 6194
+sampsize: 200
+sampfraction: 0.0323
+ignorefpc: false
 ```
+
+With a `SimpleRandomSample` (as well as with any subtype of [`AbstractSurveyDesign`](@ref))
+it is possible to calculate estimates of the mean or population total for a given variable,
+along with the corresponding standard errors.
+
+```julia
+julia> svymean(:api00, srs)
+1×2 DataFrame
+ Row │ mean     sem     
+     │ Float64  Float64 
+─────┼──────────────────
+   1 │ 656.585  9.24972
+
+julia> svytotal(:api00, srs)
+1×2 DataFrame
+ Row │ total      se_total 
+     │ Float64    Float64  
+─────┼─────────────────────
+   1 │ 4.06689e6   57292.8
+```
+
+The design can be tweaked by specifying the population or sample size or whether
+or not to account for finite population correction (fpc). By default the weights
+are equal to one, the sample size is equal to the number of rows in `data` and the
+fpc is not ignored. The population size is calculated from the weights.
+
+When `ignorefpc` is set to `false` the `fpc` is calculated from the sample and population
+sizes. When it is set to `true` it is set to 1.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -10,8 +10,32 @@ This package is the Julia implementation of the [Survey package in R](https://cr
 
 At [xKDR](https://xkdr.org/) we processed millions of records from household surveys using the survey package in R. This process took hours of computing time. By implementing the code in Julia, we are able to do the processing in seconds. In this package we have implemented the functions `svymean`, `svyquantile` and `svysum`. We have kept the syntax between the two packages similar so that we can easily move our existing code to the new language.
 
-Documentation for [Survey](https://github.com/Survey.jl).
+## Index
 
-```@autodocs
-Modules = [Survey]
+```@index
+Module = [Survey]
+Private = false
+```
+
+## API
+```@docs
+load_data
+AbstractSurveyDesign
+SimpleRandomSample
+StratifiedSample
+ClusterSample
+dim(design::AbstractSurveyDesign)
+colnames(design::AbstractSurveyDesign)
+dimnames(design::AbstractSurveyDesign)
+svymean(x::Symbol, design::SimpleRandomSample)
+svytotal(x::Symbol, design::SimpleRandomSample)
+svyby
+svyglm
+svyplot(design::AbstractSurveyDesign, x::Symbol, y::Symbol; kwargs...)
+svyhist(design::AbstractSurveyDesign, var::Symbol,
+				 bins::Union{Integer, AbstractVector} = freedman_diaconis(design, var);
+				 normalization = :density,
+				 kwargs...
+    			)
+svyboxplot(design::AbstractSurveyDesign, x::Symbol, y::Symbol; kwargs...)
 ```
diff --git a/shikharTests.jl b/shikharTests.jl
diff --git a/src/Survey.jl b/src/Survey.jl
@@ -11,19 +11,19 @@ using AlgebraOfGraphics
 using CategoricalArrays
 
 include("SurveyDesign.jl")
-include("show.jl")
 include("svydesign.jl")
 include("svymean.jl")
 include("svyquantile.jl")
 include("svytotal.jl")
-include("example.jl")
+include("load_data.jl")
 include("svyglm.jl")
 include("svyhist.jl")
 include("svyplot.jl")
 include("dimnames.jl")
 include("svyboxplot.jl")
 include("svyby.jl")
 include("ht.jl")
+include("show.jl")
 
 export load_data
 export AbstractSurveyDesign, SimpleRandomSample, StratifiedSample