From 4433fff79cb3866ede6acbf3d32d9ff0b2b0f9e8 Mon Sep 17 00:00:00 2001 From: ConnorDonegan Date: Thu, 4 Apr 2024 13:30:06 -0500 Subject: [PATCH] document y_mis functionality --- DESCRIPTION | 2 +- NEWS.md | 9 +- R/prep-censored-data.R | 8 +- R/stan_car.R | 2 +- R/stan_esf.R | 2 +- R/stan_glm.R | 7 + R/stan_icar.R | 2 +- R/stan_sar.R | 2 +- README.Rmd | 87 ++- README.html | 733 ++++++++++++++++++ README.md | 182 +++-- docs/LICENSE.html | 75 +- docs/articles/custom-spatial-models.html | 693 +++++++---------- docs/articles/measuring-sa.html | 422 ++-------- .../figure-html/unnamed-chunk-14-1.png | Bin 145694 -> 145939 bytes docs/articles/raster-regression.html | 143 +--- docs/articles/spatial-me-models.html | 405 +++------- .../figure-html/unnamed-chunk-14-1.png | Bin 41014 -> 41030 bytes .../figure-html/unnamed-chunk-9-1.png | Bin 161507 -> 161623 bytes docs/index.html | 129 +-- docs/news/index.html | 9 +- docs/pkgdown.yml | 4 +- .../figures/README-unnamed-chunk-3-1.png | Bin 51130 -> 51920 bytes .../figures/README-unnamed-chunk-5-1.png | Bin 57740 -> 57817 bytes .../figures/README-unnamed-chunk-6-1.png | Bin 0 -> 57825 bytes docs/reference/prep_car_data.html | 2 +- docs/reference/priors.html | 8 +- docs/reference/resid_geostan_fit.html | 12 +- docs/reference/stan_car.html | 6 +- docs/reference/stan_esf.html | 6 +- docs/reference/stan_glm.html | 16 +- docs/reference/stan_icar.html | 86 +- docs/reference/stan_sar.html | 6 +- man/figures/README-unnamed-chunk-3-1.png | Bin 51130 -> 51920 bytes man/figures/README-unnamed-chunk-5-1.png | Bin 57740 -> 57817 bytes man/figures/README-unnamed-chunk-6-1.png | Bin 0 -> 57825 bytes man/stan_esf.Rd | 2 +- man/stan_icar.Rd | 2 +- tests/testthat/test-missing-y.R | 23 +- 39 files changed, 1640 insertions(+), 1445 deletions(-) create mode 100644 README.html create mode 100644 docs/reference/figures/README-unnamed-chunk-6-1.png create mode 100644 man/figures/README-unnamed-chunk-6-1.png diff --git a/DESCRIPTION b/DESCRIPTION index 834934ed..893e8009 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: geostan Title: Bayesian Spatial Analysis Version: 0.6.0 -Date: 2024-03-01 +Date: 2024-04-04 URL: https://connordonegan.github.io/geostan/ BugReports: https://github.com/ConnorDonegan/geostan/issues Authors@R: c( diff --git a/NEWS.md b/NEWS.md index bd168f6f..1324fbcb 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,13 @@ # geostan 0.6.0 -## New Additions +Updates: + +1. Missing outcome data is now allowed in most models +2. A bug in `prep_icar_data` has been fixed + +The model fitting functions (`stan_glm`, `stan_car`, etc.) now allow for missing data in the outcome variable. This is explained in the `geostan::stan_glm` documentation, next to the discussion of handling censored observations. When missing observations are present, there will (only) be a warning issued. This functionality is available for any GLM (`stan_glm`), any ESF model (`stan_esf`), and any model for count data (Poisson and binomial models including CAR and SAR models). The only models for which this functionality is not currently available are CAR and SAR models that are being been fit to continuous outcome variables. -The model fitting functions (`stan_glm`, `stan_car`, etc.) now allow for missing data in the outcome variable and a new vignette provides the details. This functionality is not available for auto-Gaussian models - that is, CAR and SAR models that have been fit to continuous outcome variables - but is available for all other available models (including eigenvector spatial filtering `stan_esf` models for continuous outcomes, and all models for count outcomes [binomial and Poisson models]). +The `prep_icar_data` function, which is used inside `stan_icar`, did not have the expected behavior in all cases - this has been fixed thanks to this [pull request](https://github.com/ConnorDonegan/geostan/pull/18). # geostan 0.5.4 diff --git a/R/prep-censored-data.R b/R/prep-censored-data.R index 5143e48a..4e8672c9 100644 --- a/R/prep-censored-data.R +++ b/R/prep-censored-data.R @@ -1,8 +1,8 @@ -#' @description Return index of observed, censored y; elsewhere, use results to replace NAs with zeros -#' This will stop if there are missing values and the censor_point argument is not being used; outside of this call, must check that censor_point argument is only used with Poisson likelihood. +#' @description Return index of observed and missing y (elsewhere, these results hould be used to replace NAs with zeros or an indicator integer: Stan cannot accept NA values) +#' Outside of this call, must check that censor_point argument is only used with Poisson likelihood. #' #' @param censor the censor_point argument #' @param frame from model.frame(formula, tmpdf, na.action = NULL) @@ -15,6 +15,10 @@ handle_censored_y <- function(censor, frame) { } y_mis_idx <- which(is.na(y_raw)) y_obs_idx <- which(!is.na(y_raw)) + n_mis <- length(y_mis_idx) + if ( n_mis > 0 ) { + message( paste0(n_mis, " NA values identified in the outcome variable\nFound in rows: ", paste0(y_mis_idx, collapse = ', ' )) ) + } return (list(n_mis = length(y_mis_idx), n_obs = length(y_obs_idx), y_mis_idx = y_mis_idx, diff --git a/R/stan_car.R b/R/stan_car.R index 90e3b775..482e033f 100644 --- a/R/stan_car.R +++ b/R/stan_car.R @@ -144,7 +144,7 @@ #' #' ## Additional functionality #' -#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. +#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. #' #' @return An object of class class \code{geostan_fit} (a list) containing: #' \describe{ diff --git a/R/stan_esf.R b/R/stan_esf.R index 00f2a507..665de95c 100644 --- a/R/stan_esf.R +++ b/R/stan_esf.R @@ -97,7 +97,7 @@ #' #' ## Additional functionality #' -#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. +#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. #' #' @return An object of class class \code{geostan_fit} (a list) containing: #' \describe{ diff --git a/R/stan_glm.R b/R/stan_glm.R index 6baffb3f..57469ff0 100644 --- a/R/stan_glm.R +++ b/R/stan_glm.R @@ -132,6 +132,13 @@ #' \deqn{x \sim Gauss(z, s^2)} #' \deqn{logit(z) \sim student(\nu_z, \mu_z, \sigma_z)} #' +#' +#' ### Missing data +#' +#' For most geostan models, missing (NA) observations are allowed in the outcome variable. However, there cannot be any missing covariate data. Models that can handle missing data are: any Poisson or binomial model (GLM, SAR, CAR, ESF, ICAR), all GLMs and ESF models. The only models that cannot handle missing outcome data are the CAR and SAR models when the outcome is a continuous variable (auto-normal/Gaussian models). +#' +#' When observations are missing, they will simply be ignored when calculating the likelihood in the MCMC sampling process (reflecting the absence of information). The estimated model parameters (including any covariates and spatial trend) will then be used to produce estimates or fitted values for the missing observations. The `fitted` and `posterior_predict` functions will work as normal in this case, and return values for all rows in your data. +#' #' ### Censored counts #' #' Vital statistics systems and disease surveillance programs typically suppress case counts when they are smaller than a specific threshold value. In such cases, the observation of a censored count is not the same as a missing value; instead, you are informed that the value is an integer somewhere between zero and the threshold value. For Poisson models (`family = poisson())`), you can use the `censor_point` argument to encode this information into your model. diff --git a/R/stan_icar.R b/R/stan_icar.R index 52bf7503..f0b5307a 100644 --- a/R/stan_icar.R +++ b/R/stan_icar.R @@ -162,7 +162,7 @@ #' ``` #' ## Additional functionality #' -#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. +#' The CAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. #' #' @return An object of class class \code{geostan_fit} (a list) containing: #' \describe{ diff --git a/R/stan_sar.R b/R/stan_sar.R index d4663bb8..a7473860 100644 --- a/R/stan_sar.R +++ b/R/stan_sar.R @@ -147,7 +147,7 @@ #' #' ## Additional functionality #' -#' The SAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. +#' The SAR models can also incorporate spatially-lagged covariates, measurement/sampling error in covariates (particularly when using small area survey estimates as covariates), missing outcome data, and censored outcomes (such as arise when a disease surveillance system suppresses data for privacy reasons). For details on these options, please see the Details section in the documentation for \link[geostan]{stan_glm}. #' #' #' @return An object of class class \code{geostan_fit} (a list) containing: diff --git a/README.Rmd b/README.Rmd index 5fb011b7..2ab573ec 100644 --- a/README.Rmd +++ b/README.Rmd @@ -15,42 +15,20 @@ knitr::opts_chunk$set( fig.align = 'center' ) ``` - ## 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. For demonstrations and discussion, see the package [help pages](https://connordonegan.github.io/geostan/reference/index.html) and [vignettes](https://connordonegan.github.io/geostan/articles/index.html) on spatial autocorrelation, spatial measurement error models, spatial regression with raster layers, and building custom spatial model in Stan. - -The package is particularly suitable for public health research with spatial data, and complements the [**surveil**](https://connordonegan.github.io/surveil/) R package for time series analysis of public health surveillance data. - -**geostan** models were built using [**Stan**](https://mc-stan.org), a state-of-the-art platform for Bayesian modeling. - -[![DOI](https://joss.theoj.org/papers/10.21105/joss.04716/status.svg)](https://doi.org/10.21105/joss.04716) - -### Disease mapping and spatial regression - -Statistical models for data recorded across areal units like states, counties, or census tracts. - -### Observational uncertainty +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. -Incorporate information on data reliability, such as standard errors of American Community Survey estimates, into any **geostan** model. +Features include: -### 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 with censored observations. - -### Spatial analysis tools - -Tools for visualizing and measuring spatial autocorrelation and map patterns, for exploratory analysis and model diagnostics. - -### 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/). +* **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. +* **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/). ## Installation @@ -62,26 +40,29 @@ install.packages("geostan") ## 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 data analysis, spatial measurement error models, and spatial regression with large raster layers. +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. To ask questions, report a bug, or discuss ideas for improvements or new features please visit the [issues](https://github.com/ConnorDonegan/geostan/issues) page, start a [discussion](https://github.com/ConnorDonegan/geostan/discussions), or submit a [pull request](https://github.com/ConnorDonegan/geostan/pulls). ## Usage -Load the package and the `georgia` county mortality data set (ages 55-64, years 2014-2018): +Load the package and the `georgia` county mortality data set: ```{r} library(geostan) data(georgia) ``` -The `sp_diag` function provides visual summaries of spatial data, including a histogram, Moran scatter plot, and map: +This has county population and mortality data by sex for ages 55-64, and for the period 2014-2018. As is common for public access data, some of the observations missing because the CDC has censored them. + +The `sp_diag` function provides visual summaries of spatial data, including a histogram, Moran scatter plot, and map. Here is a visual summary of crude female mortality rates (as deaths per 10,000): ```{r fig.width = 8} A <- shape2mat(georgia, style = "B") -sp_diag(georgia$rate.female, georgia, w = A) +mortality_rate <- georgia$rate.female * 10e3 +sp_diag(mortality_rate, georgia, w = A) ``` -There are three censored observations in the `georgia` female mortality data, which means there were 9 or fewer deaths in those counties. The following code fits a spatial conditional autoregressive (CAR) model to female county mortality data. By using the `censor_point` argument we include our information on the censored observations to obtain results for all counties: +The following code fits a spatial conditional autoregressive (CAR) model to female county mortality data. These models are used for estimating disease risk in small areas like counties, and for analyzing covariation of health outcomes with other area qualities. The R syntax for fitting the models is similar to using `lm` or `glm`. We provide the population at risk (the denominator for mortality rates) as an offset term, using the log-transform. In this case, three of the observations are missing because they have been censored; per CDC criteria, this means that there were 9 or fewer deaths in those counties. By using the `censor_point` argument and setting it to `censor_point = 9`, the model will account for the censoring process when providing estimates of the mortality rates: ```{r} cars <- prep_car_data(A) @@ -93,7 +74,9 @@ fit <- stan_car(deaths.female ~ offset(log(pop.at.risk.female)), cores = 4, # for multi-core processing refresh = 0) # to silence some printing ``` + Passing a fitted model to the `sp_diag` function will return a set of diagnostics for spatial models: + ```{r fig.width = 8} sp_diag(fit, georgia, w = A) ``` @@ -103,5 +86,37 @@ The `print` method returns a summary of the probability distributions for model ```{r} print(fit) ``` -More demonstrations can be found in the package [help pages](https://connordonegan.github.io/geostan/reference/index.html) and [vignettes](https://connordonegan.github.io/geostan/articles/index.html). + +Applying the `fitted` method to the fitted model will return the fitted values from the model - in this case, the fitted values are the estimates of the county mortality rates. Multiplying them by 10,000 gives mortality rate per 10,000 at risk: + +```{r} +mortality_est <- fitted(fit) * 10e3 +county_name <- georgia$NAME +head( cbind(county_name, mortality_est) ) +``` + +The mortality estimates are stored in the column named "mean", and the limits of the 95\% credible interval are found in the columns "2.5%" and "97.5%". + +Details and demonstrations can be found in the package [help pages](https://connordonegan.github.io/geostan/reference/index.html) and [vignettes](https://connordonegan.github.io/geostan/articles/index.html). + +## Citing geostan + +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). + +[![DOI](https://joss.theoj.org/papers/10.21105/joss.04716/status.svg)](https://doi.org/10.21105/joss.04716) + +``` +@Article{, + title = {{geostan}: An {R} package for {B}ayesian spatial analysis}, + author = {Connor Donegan}, + journal = {The Journal of Open Source Software}, + year = {2022}, + volume = {7}, + number = {79}, + pages = {4716}, + doi = {10.21105/joss.04716}, +} +``` diff --git a/README.html b/README.html new file mode 100644 index 00000000..7f088a9b --- /dev/null +++ b/README.html @@ -0,0 +1,733 @@ + + + + + + + + + + + + + + + + + + + + + + + +

geostan: Bayesian spatial analysis

+

The 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, 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 R package for time series analysis of public health surveillance data.

+

Features include:

+ +

Installation

+

Install geostan from CRAN using:

+
install.packages("geostan")
+

Support

+

All functions and methods are documented (with examples) on the website reference page. See the package vignettes for more on exploratory spatial analysis, spatial measurement error models, spatial regression with raster layers, and building custom spatial model in Stan.

+

To ask questions, report a bug, or discuss ideas for improvements or new features please visit the issues page, start a discussion, or submit a pull request.

+

Usage

+

Load the package and the georgia county mortality data set:

+
library(geostan)
+data(georgia)
+

This has county population and mortality data by sex for ages 55-64, and for the period 2014-2018. As is common for public access data, some of the observations missing because the CDC has censored them.

+

The sp_diag function provides visual summaries of spatial data, including a histogram, Moran scatter plot, and map. Here is a visual summary of crude female mortality rates (as deaths per 10,000):

+
A <- shape2mat(georgia, style = "B")
+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
+#> Warning: Removed 3 rows containing
+#> non-finite values (`stat_bin()`).
+ + +

The following code fits a spatial conditional autoregressive (CAR) model to female county mortality data. These models are used for estimating disease risk in small areas like counties, and for analyzing covariation of health outcomes with other area qualities. The R syntax for fitting the models is similar to using lm or glm. We provide the population at risk (the denominator for mortality rates) as an offset term, using the log-transform. In this case, three of the observations are missing because they have been censored; per CDC criteria, this means that there were 9 or fewer deaths in those counties. By using the censor_point argument and setting it to censor_point = 9, the model will account for the censoring process when providing estimates of the mortality rates:

+
cars <- prep_car_data(A)
+#> Range of permissible rho values:  -1.661134 1
+fit <- stan_car(deaths.female ~ offset(log(pop.at.risk.female)),
+                censor_point = 9,
+        data = georgia,
+        car_parts = cars,
+        family = poisson(),
+        cores = 4, # for multi-core processing
+        refresh = 0) # to silence some printing
+#> 
+#> *Setting prior parameters for intercept
+#> Distribution: normal
+#>   location scale
+#> 1     -4.7     5
+#> 
+#> *Setting prior for CAR scale parameter (car_scale)
+#> Distribution: student_t
+#>   df location scale
+#> 1 10        0     3
+#> 
+#> *Setting prior for CAR spatial autocorrelation parameter (car_rho)
+#> Distribution: uniform
+#>   lower upper
+#> 1  -1.7     1
+

Passing a fitted model to the sp_diag function will return a set of 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 (`geom_pointrange()`).
+ + +

The print method returns a summary of the probability distributions for model parameters, as well as Markov chain Monte Carlo (MCMC) diagnostics from Stan (Monte Carlo standard errors of the mean se_mean, effective sample size n_eff, and the R-hat statistic Rhat):

+
print(fit)
+#> Spatial Model Results 
+#> Formula: deaths.female ~ offset(log(pop.at.risk.female))
+#> Spatial method (outcome):  CAR 
+#> Likelihood function:  poisson 
+#> Link function:  log 
+#> Residual Moran Coefficient:  0.0015345 
+#> WAIC:  1290.42 
+#> Observations:  159 
+#> 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%    25%    50%    75%  97.5% n_eff  Rhat
+#> intercept -4.679   0.011 0.178 -4.888 -4.718 -4.674 -4.633 -4.480   267 1.014
+#> car_rho    0.925   0.001 0.059  0.776  0.896  0.937  0.968  0.998  2766 1.001
+#> car_scale  0.457   0.001 0.035  0.394  0.432  0.455  0.480  0.532  3518 1.000
+#> 
+#> Samples were drawn using NUTS(diag_e) at Thu Apr  4 16:19:11 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).
+

Applying the fitted method to the fitted model will return the fitted values from the model - in this case, the fitted values are the estimates of the county mortality rates. Multiplying them by 10,000 gives mortality rate per 10,000 at risk:

+
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.64041  9.519141  83.73978  93.36796 101.31662
+#> fitted[2]     Candler 137.30390 15.999801 108.73333 123.23183 136.35141
+#> fitted[3]      Barrow  94.19814  6.141840  82.55457  88.89596  94.11255
+#> fitted[4]      DeKalb  59.73895  1.559960  56.71691  58.39545  59.69778
+#> fitted[5]    Columbia  53.31653  3.216973  47.31274  50.57770  53.26367
+#> fitted[6]        Cobb  54.11649  1.518304  51.17859  52.82489  54.11122
+#>                 80%     97.5%
+#> fitted[1] 109.55245 120.85305
+#> fitted[2] 150.48176 170.97901
+#> fitted[3]  99.37661 106.39628
+#> fitted[4]  61.05971  62.76113
+#> fitted[5]  56.08382  59.67599
+#> fitted[6]  55.39974  57.13810
+

The mortality estimates are stored in the column named “mean”, and the limits of the 95% credible interval are found in the columns “2.5%” and “97.5%”.

+

Details and demonstrations can be found in the package help pages and vignettes.

+

Citing geostan

+

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.

+

DOI

+
@Article{,
+  title = {{geostan}: An {R} package for {B}ayesian spatial analysis},
+  author = {Connor Donegan},
+  journal = {The Journal of Open Source Software},
+  year = {2022},
+  volume = {7},
+  number = {79},
+  pages = {4716},
+  doi = {10.21105/joss.04716},
+}
+
+ + + diff --git a/README.md b/README.md index 775418be..36db85b1 100644 --- a/README.md +++ b/README.md @@ -8,54 +8,33 @@ 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. For demonstrations and discussion, see the package -[help -pages](https://connordonegan.github.io/geostan/reference/index.html) and -[vignettes](https://connordonegan.github.io/geostan/articles/index.html) -on spatial autocorrelation, spatial measurement error models, spatial -regression with raster layers, and building custom spatial model in -Stan. - -The package is particularly suitable for public health research with -spatial data, and complements the +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. -**geostan** models were built using [**Stan**](https://mc-stan.org), a -state-of-the-art platform for Bayesian modeling. - -[![DOI](https://joss.theoj.org/papers/10.21105/joss.04716/status.svg)](https://doi.org/10.21105/joss.04716) - -### Disease mapping and spatial regression - -Statistical models for data recorded across areal units like states, -counties, or census tracts. - -### Observational uncertainty - -Incorporate information on data reliability, such as standard errors of -American Community Survey estimates, into any **geostan** model. - -### 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 with censored observations. - -### Spatial analysis tools - -Tools for visualizing and measuring spatial autocorrelation and map -patterns, for exploratory analysis and model diagnostics. - -### 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/). +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. + - **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/). ## Installation @@ -71,8 +50,9 @@ 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 data analysis, spatial measurement error -models, and spatial regression with large raster layers. +for more on exploratory spatial analysis, spatial measurement error +models, spatial regression with raster layers, and building custom +spatial model in Stan. To ask questions, report a bug, or discuss ideas for improvements or new features please visit the @@ -82,33 +62,44 @@ submit a [pull request](https://github.com/ConnorDonegan/geostan/pulls). ## Usage -Load the package and the `georgia` county mortality data set (ages -55-64, years 2014-2018): +Load the package and the `georgia` county mortality data set: ``` r library(geostan) -#> This is geostan version 0.5.3 data(georgia) ``` +This has county population and mortality data by sex for ages 55-64, and +for the period 2014-2018. As is common for public access data, some of +the observations missing because the CDC has censored them. + The `sp_diag` function provides visual summaries of spatial data, -including a histogram, Moran scatter plot, and map: +including a histogram, Moran scatter plot, and map. Here is a visual +summary of crude female mortality rates (as deaths per 10,000): ``` r A <- shape2mat(georgia, style = "B") -sp_diag(georgia$rate.female, georgia, w = A) +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 -#> Warning: Removed 3 rows containing non-finite values (`stat_bin()`). +#> Warning: Removed 3 rows containing +#> non-finite values (`stat_bin()`). ``` -There are three censored observations in the `georgia` female mortality -data, which means there were 9 or fewer deaths in those counties. The -following code fits a spatial conditional autoregressive (CAR) model to -female county mortality data. By using the `censor_point` argument we -include our information on the censored observations to obtain results -for all counties: +The following code fits a spatial conditional autoregressive (CAR) model +to female county mortality data. These models are used for estimating +disease risk in small areas like counties, and for analyzing covariation +of health outcomes with other area qualities. The R syntax for fitting +the models is similar to using `lm` or `glm`. We provide the population +at risk (the denominator for mortality rates) as an offset term, using +the log-transform. In this case, three of the observations are missing +because they have been censored; per CDC criteria, this means that there +were 9 or fewer deaths in those counties. By using the `censor_point` +argument and setting it to `censor_point = 9`, the model will account +for the censoring process when providing estimates of the mortality +rates: ``` r cars <- prep_car_data(A) @@ -135,12 +126,6 @@ fit <- stan_car(deaths.female ~ offset(log(pop.at.risk.female)), #> Distribution: uniform #> lower upper #> 1 -1.7 1 -#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable. -#> Running the chains for more iterations may help. See -#> https://mc-stan.org/misc/warnings.html#bulk-ess -#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable. -#> Running the chains for more iterations may help. See -#> https://mc-stan.org/misc/warnings.html#tail-ess ``` Passing a fitted model to the `sp_diag` function will return a set of @@ -150,7 +135,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 (`geom_pointrange()`). +#> Warning: Removed 3 rows containing missing +#> values (`geom_pointrange()`). ``` @@ -168,8 +154,8 @@ print(fit) #> Spatial method (outcome): CAR #> Likelihood function: poisson #> Link function: log -#> Residual Moran Coefficient: -0.0004015 -#> WAIC: 1290.5 +#> Residual Moran Coefficient: 0.0015345 +#> WAIC: 1290.42 #> Observations: 159 #> Data models (ME): none #> Inference for Stan model: foundation. @@ -177,16 +163,66 @@ print(fit) #> post-warmup draws per chain=1000, total post-warmup draws=4000. #> #> mean se_mean sd 2.5% 25% 50% 75% 97.5% n_eff Rhat -#> intercept -4.620 0.055 0.418 -4.851 -4.719 -4.674 -4.627 -4.334 57 1.074 -#> car_rho 0.926 0.001 0.057 0.783 0.896 0.937 0.968 0.999 1494 1.002 -#> car_scale 0.457 0.001 0.035 0.394 0.433 0.455 0.479 0.529 3559 1.000 +#> intercept -4.679 0.011 0.178 -4.888 -4.718 -4.674 -4.633 -4.480 267 1.014 +#> car_rho 0.925 0.001 0.059 0.776 0.896 0.937 0.968 0.998 2766 1.001 +#> car_scale 0.457 0.001 0.035 0.394 0.432 0.455 0.480 0.532 3518 1.000 #> -#> Samples were drawn using NUTS(diag_e) at Tue Mar 19 14:14:50 2024. +#> Samples were drawn using NUTS(diag_e) at Thu Apr 4 16:19:11 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). ``` -More demonstrations can be found in the package [help +Applying the `fitted` method to the fitted model will return the fitted +values from the model - in this case, the fitted values are the +estimates of the county mortality rates. Multiplying them by 10,000 +gives mortality rate per 10,000 at risk: + +``` r +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.64041 9.519141 83.73978 93.36796 101.31662 +#> fitted[2] Candler 137.30390 15.999801 108.73333 123.23183 136.35141 +#> fitted[3] Barrow 94.19814 6.141840 82.55457 88.89596 94.11255 +#> fitted[4] DeKalb 59.73895 1.559960 56.71691 58.39545 59.69778 +#> fitted[5] Columbia 53.31653 3.216973 47.31274 50.57770 53.26367 +#> fitted[6] Cobb 54.11649 1.518304 51.17859 52.82489 54.11122 +#> 80% 97.5% +#> fitted[1] 109.55245 120.85305 +#> fitted[2] 150.48176 170.97901 +#> fitted[3] 99.37661 106.39628 +#> fitted[4] 61.05971 62.76113 +#> fitted[5] 56.08382 59.67599 +#> fitted[6] 55.39974 57.13810 +``` + +The mortality estimates are stored in the column named “mean”, and the +limits of the 95% credible interval are found in the columns “2.5%” and +“97.5%”. + +Details and demonstrations can be found in the package [help pages](https://connordonegan.github.io/geostan/reference/index.html) and [vignettes](https://connordonegan.github.io/geostan/articles/index.html). + +## Citing geostan + +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. +. + +[![DOI](https://joss.theoj.org/papers/10.21105/joss.04716/status.svg)](https://doi.org/10.21105/joss.04716) + + @Article{, + title = {{geostan}: An {R} package for {B}ayesian spatial analysis}, + author = {Connor Donegan}, + journal = {The Journal of Open Source Software}, + year = {2022}, + volume = {7}, + number = {79}, + pages = {4716}, + doi = {10.21105/joss.04716}, + } diff --git a/docs/LICENSE.html b/docs/LICENSE.html index 665d0f87..bf475b4e 100644 --- a/docs/LICENSE.html +++ b/docs/LICENSE.html @@ -50,7 +50,6 @@

GNU General Public License

-

Version 3, 29 June 2007
Copyright © 2007 Free Software Foundation, Inc. <http://fsf.org/>

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

@@ -69,7 +68,7 @@

Preamble

TERMS AND CONDITIONS

-

0. Definitions

+

0. Definitions

“This License” refers to version 3 of the GNU General Public License.

“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

@@ -80,7 +79,7 @@

0. DefinitionsAn interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

-

1. Source Code

+

1. Source Code

The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

@@ -89,23 +88,23 @@

1. Source CodeThe Corresponding Source for a work in source code form is that same work.

-

2. Basic Permissions

+

2. Basic Permissions

All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

- +

No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.

-

4. Conveying Verbatim Copies

+

4. Conveying Verbatim Copies

You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

-

5. Conveying Modified Source Versions

+

5. Conveying Modified Source Versions

You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

  • a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
  • @@ -118,7 +117,7 @@

    5. Conveying Modified Source Ve

A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

-

6. Conveying Non-Source Forms

+

6. Conveying Non-Source Forms

You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

  • a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
  • @@ -138,7 +137,7 @@

    6. Conveying Non-Source Forms -

    7. Additional Terms

    +

    7. Additional Terms

    “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

    When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

    Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

    @@ -159,24 +158,24 @@

    7. Additional Terms -

    8. Termination

    +

    8. Termination

    You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

-

9. Acceptance Not Required for Having Copies

+

9. Acceptance Not Required for Having Copies

You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

-

10. Automatic Licensing of Downstream Recipients

+

10. Automatic Licensing of Downstream Recipients

Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

-

11. Patents

+

11. Patents

A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

@@ -187,30 +186,30 @@

11. Patents -

12. No Surrender of Others’ Freedom

+

12. No Surrender of Others’ Freedom

If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

-

13. Use with the GNU Affero General Public License

+

13. Use with the GNU Affero General Public License

Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.

-

14. Revised Versions of this License

+

14. Revised Versions of this License

The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

-

15. Disclaimer of Warranty

+

15. Disclaimer of Warranty

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

-

16. Limitation of Liability

+

16. Limitation of Liability

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

-

17. Interpretation of Sections 15 and 16

+

17. Interpretation of Sections 15 and 16

If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

@@ -219,27 +218,27 @@

17. Interpretation of Sectio

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

-
<one line to give the program's name and a brief idea of what it does.>
-Copyright (C) <year>  <name of author>
-
-This program is free software: you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation, either version 3 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
<one line to give the program's name and a brief idea of what it does.>
+Copyright (C) <year>  <name of author>
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

-
<program>  Copyright (C) <year>  <name of author>
-This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
-This is free software, and you are welcome to redistribute it
-under certain conditions; type 'show c' for details.
+
<program>  Copyright (C) <year>  <name of author>
+This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type 'show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <http://www.gnu.org/licenses/>.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <http://www.gnu.org/philosophy/why-not-lgpl.html>.

diff --git a/docs/articles/custom-spatial-models.html b/docs/articles/custom-spatial-models.html index 1825b657..d6bd2b6b 100644 --- a/docs/articles/custom-spatial-models.html +++ b/docs/articles/custom-spatial-models.html @@ -73,13 +73,11 @@ -
+