clean readme

ConnorDonegan · Jul 18, 2024 · a683608 · a683608
1 parent b17e9b1
commit a683608
Show file tree

Hide file tree

Showing 9 changed files with 175 additions and 112 deletions.
diff --git a/README.Rmd b/README.Rmd
@@ -19,26 +19,36 @@ knitr::opts_chunk$set(
 
 ## geostan: Bayesian spatial analysis
 
-The [**geostan**](https://connordonegan.github.io/geostan/) R package supports a complete spatial analysis workflow with Bayesian models for areal data, including a suite of functions for visualizing spatial data and model results. **geostan** models were built using [**Stan**](https://mc-stan.org), a state-of-the-art platform for Bayesian modeling. The package is designed partly for public health research with spatial data, for which it complements the [**surveil**](https://connordonegan.github.io/surveil/) R package for time series analysis of public health surveillance data.
+The [geostan](https://connordonegan.github.io/geostan/) R package supports a complete spatial analysis workflow with Bayesian models for areal data, including a suite of functions for visualizing spatial data and model results. `geostan` models were built using [Stan](https://mc-stan.org), a state-of-the-art platform for Bayesian modeling. 
 
 Features include:
 
 * **Disease mapping and spatial regression** Statistical models for data recorded across areal units like states, counties, or census tracts.
 * **Spatial analysis tools** Tools for visualizing and measuring spatial autocorrelation and map patterns, for exploratory analysis and model diagnostics.  
-* **Observational uncertainty** Incorporate information on data reliability, such as standard errors of American Community Survey estimates, into any **geostan** model.
-* **Missing and Censored observations** Vital statistics and disease surveillance systems like CDC Wonder censor case counts that fall below a threshold number; **geostan** can model disease or mortality risk for small areas with censored observations or with missing observations.
+* **Observational uncertainty** Incorporate information on data reliability, such as standard errors of American Community Survey estimates, into any `geostan` model.
+* **Missing and Censored observations** Vital statistics and disease surveillance systems like CDC Wonder censor case counts that fall below a threshold number; `geostan` can model disease or mortality risk for small areas with censored observations or with missing observations.
 * **The RStan ecosystem** Interfaces easily with many high-quality R packages for Bayesian modeling.
-* **Custom spatial models** Tools for building custom spatial models in [Stan](https://mc-stan.org/).
+* **Custom spatial models** Tools for building custom spatial models in Stan.
+
+For public health research,  complements the [`surveil`](https://connordonegan.github.io/surveil/) R package for time series analysis of public health surveillance data.
 
 ## Installation
 
-Using your R console, you can install **geostan** from CRAN:
+There are two ways to install `geostan: directly from the package github repository or from the Comprehensive R Archive Network (CRAN). 
+
+### From CRAN
+
+Using your R console, you can install `geostan` from CRAN:
 
 ``` r
 install.packages("geostan")
 ```
 
-Or, you can install the latest version from the package github repository:
+If that fails, you can install from github.
+
+### From github
+
+You can install `geostan` from github:
 
 ```r
 if (!require('devtools')) install.packages('devtools')
@@ -52,6 +62,8 @@ If you are using Windows and installing with `install_github`, you may need to i
 3. After selecting the correct version, look for the "Install Rtools" section (just below the introductory text) and click on the "installer" to download it. For example, for Rtools43 (for R version 4.3), click on "<span style="color:blue">Rtools43 installer</span>."
 4. Go to the `.exe` file you just downloaded and double-click to begin installation of Rtools.
 
+If you are using Mac and installing with `install_github` then you may need to install Xcode Command Line Tools first.
+
 ## Support
 
 All functions and methods are documented (with examples) on the website [reference](https://connordonegan.github.io/geostan/reference/index.html) page. See the package [vignettes](https://connordonegan.github.io/geostan/articles/index.html) for more on exploratory spatial analysis, spatial measurement error models, spatial regression with raster layers, and building custom spatial model in Stan.
@@ -115,7 +127,7 @@ Details and demonstrations can be found in the package [help pages](https://conn
 
 ## Citing geostan
 
-If you use geostan in published work, please include a citation.
+If you use `geostan` in published work, please include a citation.
 
 Donegan, Connor (2022) "geostan: An R package for Bayesian spatial analysis" *The Journal of Open Source Software*. 7, no. 79: 4716. [https://doi.org/10.21105/joss.04716](https://doi.org/10.21105/joss.04716).
 

diff --git a/README.html b/README.html
diff --git a/README.md b/README.md
@@ -5,15 +5,12 @@
 
 ## geostan: Bayesian spatial analysis
 
-The [**geostan**](https://connordonegan.github.io/geostan/) R package
+The [geostan](https://connordonegan.github.io/geostan/) R package
 supports a complete spatial analysis workflow with Bayesian models for
 areal data, including a suite of functions for visualizing spatial data
-and model results. **geostan** models were built using
-[**Stan**](https://mc-stan.org), a state-of-the-art platform for
-Bayesian modeling. The package is designed partly for public health
-research with spatial data, for which it complements the
-[**surveil**](https://connordonegan.github.io/surveil/) R package for
-time series analysis of public health surveillance data.
+and model results. `geostan` models were built using
+[Stan](https://mc-stan.org), a state-of-the-art platform for Bayesian
+modeling.
 
 Features include:
 
@@ -25,27 +22,39 @@ Features include:
     and model diagnostics.  
   - **Observational uncertainty** Incorporate information on data
     reliability, such as standard errors of American Community Survey
-    estimates, into any **geostan** model.
+    estimates, into any `geostan` model.
   - **Missing and Censored observations** Vital statistics and disease
     surveillance systems like CDC Wonder censor case counts that fall
-    below a threshold number; **geostan** can model disease or mortality
+    below a threshold number; `geostan` can model disease or mortality
     risk for small areas with censored observations or with missing
     observations.
   - **The RStan ecosystem** Interfaces easily with many high-quality R
     packages for Bayesian modeling.
   - **Custom spatial models** Tools for building custom spatial models
-    in [Stan](https://mc-stan.org/).
+    in Stan.
+
+For public health research, complements the
+[`surveil`](https://connordonegan.github.io/surveil/) R package for time
+series analysis of public health surveillance data.
 
 ## Installation
 
-Using your R console, you can install **geostan** from CRAN:
+There are two ways to install \`geostan: directly from the package
+github repository or from the Comprehensive R Archive Network (CRAN).
+
+### From CRAN
+
+Using your R console, you can install `geostan` from CRAN:
 
 ``` r
 install.packages("geostan")
 ```
 
-Or, you can install the latest version from the package github
-repository:
+If that fails, you can install from github.
+
+### From github
+
+You can install `geostan` from github:
 
 ``` r
 if (!require('devtools')) install.packages('devtools')
@@ -68,6 +77,9 @@ first (this is not needed when installing from CRAN). To install Rtools:
 4.  Go to the `.exe` file you just downloaded and double-click to begin
     installation of Rtools.
 
+If you are using Mac and installing with `install_github` then you may
+need to install Xcode Command Line Tools first.
+
 ## Support
 
 All functions and methods are documented (with examples) on the website
@@ -90,7 +102,6 @@ Load the package and the `georgia` county mortality data set:
 
 ``` r
 library(geostan)
-#> This is geostan version 0.6.0
 data(georgia)
 ```
 
@@ -104,6 +115,14 @@ summary of crude female mortality rates (as deaths per 10,000):
 
 ``` r
 A <- shape2mat(georgia, style = "B")
+#> Contiguity condition: queen
+#> Number of neighbors per unit, summary:
+#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
+#>   1.000   4.000   5.000   5.409   6.000  10.000
+#> 
+#> Spatial weights, summary:
+#>    Min. 1st Qu.  Median    Mean 3rd Qu.    Max. 
+#>       1       1       1       1       1       1
 mortality_rate <- georgia$rate.female * 10e3
 sp_diag(mortality_rate, georgia, w = A)
 #> 3 NA values found in x will be dropped from data x and matrix w
@@ -128,7 +147,7 @@ rates:
 
 ``` r
 cars <- prep_car_data(A)
-#> Range of permissible rho values:  -1.661134 1
+#> Range of permissible rho values: -1.661, 1
 fit <- stan_car(deaths.female ~ offset(log(pop.at.risk.female)),
                 censor_point = 9,
         data = georgia,
@@ -162,8 +181,8 @@ diagnostics for spatial models:
 sp_diag(fit, georgia, w = A)
 #> Using sp_diag(y, shape, rates = TRUE, ...). To examine data as (unstandardized) counts, use rates = FALSE.
 #> 3 NA values found in x will be dropped from data x and matrix w
-#> Warning: Removed 3 rows containing missing values or values outside the scale
-#> range (`geom_pointrange()`).
+#> Warning: Removed 3 rows containing missing values or values outside the
+#> scale range (`geom_pointrange()`).
 ```
 
 <img src="man/figures/README-unnamed-chunk-5-1.png" style="display: block; margin: auto;" />
@@ -181,20 +200,20 @@ print(fit)
 #> Spatial method (outcome):  CAR 
 #> Likelihood function:  poisson 
 #> Link function:  log 
-#> Residual Moran Coefficient:  0.00123875 
-#> WAIC:  1228.29 
+#> Residual Moran Coefficient:  0.00254425 
+#> WAIC:  1228.19 
 #> Observations:  156 
 #> Data models (ME): none
 #> Inference for Stan model: foundation.
 #> 4 chains, each with iter=2000; warmup=1000; thin=1; 
 #> post-warmup draws per chain=1000, total post-warmup draws=4000.
 #> 
 #>             mean se_mean    sd   2.5%    20%    50%    80%  97.5% n_eff  Rhat
-#> intercept -4.666   0.007 0.143 -4.840 -4.729 -4.672 -4.616 -4.484   461 1.006
-#> car_rho    0.924   0.001 0.059  0.778  0.884  0.937  0.973  0.996  3086 1.001
-#> car_scale  0.456   0.001 0.036  0.390  0.427  0.454  0.485  0.533  3776 1.000
+#> intercept -4.679   0.003 0.092 -4.875 -4.731 -4.677 -4.622 -4.509  1154 1.005
+#> car_rho    0.923   0.001 0.059  0.777  0.880  0.937  0.973  0.995  3454 1.000
+#> car_scale  0.457   0.001 0.035  0.393  0.428  0.455  0.485  0.529  3604 1.000
 #> 
-#> Samples were drawn using NUTS(diag_e) at Tue Apr 16 08:52:52 2024.
+#> Samples were drawn using NUTS(diag_e) at Thu Jul 18 15:25:26 2024.
 #> For each parameter, n_eff is a crude measure of effective sample size,
 #> and Rhat is the potential scale reduction factor on split chains (at 
 #> convergence, Rhat=1).
@@ -210,19 +229,19 @@ mortality_est <- fitted(fit) * 10e3
 county_name <- georgia$NAME
 head( cbind(county_name, mortality_est) )
 #>           county_name      mean        sd      2.5%       20%       50%
-#> fitted[1]       Crisp 101.64998  9.384722  84.24670  93.71233 101.29406
-#> fitted[2]     Candler 137.17952 16.264992 107.11368 123.59204 136.39838
-#> fitted[3]      Barrow  94.22368  6.126884  82.75981  89.00941  94.11519
-#> fitted[4]      DeKalb  59.76170  1.595148  56.68882  58.40064  59.76835
-#> fitted[5]    Columbia  53.36728  3.265343  47.21909  50.61056  53.33728
-#> fitted[6]        Cobb  54.13621  1.545304  51.09988  52.81882  54.11181
+#> fitted[1]       Crisp 101.66755  9.446020  84.15801  93.87033 101.32171
+#> fitted[2]     Candler 137.34422 16.276718 107.19396 123.50607 136.72455
+#> fitted[3]      Barrow  94.32419  6.220854  82.48984  89.08894  94.07480
+#> fitted[4]      DeKalb  59.77663  1.533180  56.82430  58.46324  59.77815
+#> fitted[5]    Columbia  53.31888  3.185709  47.07027  50.63469  53.25520
+#> fitted[6]        Cobb  54.12128  1.491083  51.29880  52.85258  54.10095
 #>                 80%     97.5%
-#> fitted[1] 109.51372 120.80189
-#> fitted[2] 150.22007 171.23752
-#> fitted[3]  99.29052 106.43936
-#> fitted[4]  61.09047  62.90342
-#> fitted[5]  56.01686  60.00058
-#> fitted[6]  55.46060  57.14337
+#> fitted[1] 109.39973 121.28989
+#> fitted[2] 150.79794 171.25541
+#> fitted[3]  99.54245 106.91977
+#> fitted[4]  61.10801  62.75864
+#> fitted[5]  55.98086  59.74880
+#> fitted[6]  55.40020  57.06597
 ```
 
 The mortality estimates are stored in the column named “mean”, and the
@@ -235,7 +254,7 @@ pages](https://connordonegan.github.io/geostan/reference/index.html) and
 
 ## Citing geostan
 
-If you use geostan in published work, please include a citation.
+If you use `geostan` in published work, please include a citation.
 
 Donegan, Connor (2022) “geostan: An R package for Bayesian spatial
 analysis” *The Journal of Open Source Software*. 7, no. 79: 4716.

diff --git a/docs/articles/spatial-weights-matrix.html b/docs/articles/spatial-weights-matrix.html