amend section headers

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: cholera
 Type: Package
 Title: Amend, Augment and Aid Analysis of John Snow's Cholera Map
-Version: 0.6.0.9033
+Version: 0.6.5
 Date: 2019-06-10
 Authors@R: person("lindbrook", email = "lindbrook@gmail.com",
   role = c("aut", "cre"))

README.Rmd

@@ -18,7 +18,7 @@ library(cholera)
 
 ## cholera: amend, augment and aid analysis of Snow's cholera map
 
-### package features
+#### package features
 
 * Fixes three apparent coding errors in Dodson and Tobler's 1992 digitization of Snow's map.
 * "Unstacks" the data in two ways to make analysis and visualization easier and more meaningful.
@@ -29,7 +29,7 @@ library(cholera)
 * Includes the revised pump data used in the second version of Snow's map from the Vestry report, which also includes the "correct" location of the Broad Street pump.
 * Adds two aggregate time series fatalities data sets, taken from the Vestry report.
 
-### getting started
+#### getting started
 
 To install 'cholera' from CRAN:
 
@@ -60,21 +60,21 @@ By plotting the number and location of fatalities using stacks of bars on a map,
 
 And yet, despite its virtues, the map failed to convince either the authorities or Snow's colleagues in the medical and scientific communities. Even today, many are skeptical of the map's ability to support such claims. Beyond considerations of time and place, what critics past and present are picking up on is that a concentration of cases around the Broad Street pump alone should not be enough to convince us. The problem is the map does not refute the primary rival explanation to waterborne transmission: the pattern we see is not unlike what airborne transmission (miasma theory) might look like. In other words, while the presence of a pump at or near the epicenter of the distribution of fatalities is strong circumstantial evidence, it is nonetheless circumstantial.
 
-### pump neighborhoods
+## pump neighborhoods
 
 This may be the reason why Snow added a graphical annotation to a second lesser-known version of the map, published in the _Report On The Cholera Outbreak In The Parish Of St. James, Westminster, During The Autumn Of 1854_.
 
 ![](vignettes/fig12-6.png)
 
 Despite its hand-drawn, back-of-the-envelope appearance, Snow writes: "The inner dotted line on the map shews [sic] the various points which have been found by careful measurement to be at an equal distance by the nearest road from the pump in Broad Street and the surrounding pumps ..." (Ibid., p. 109). My interpretation of this statement is that, guided by the principle that all else being equal people tend to choose the closest pump, Snow is computing a _pump neighborhood_: the set of addresses or locations defined by their relative proximity to a specific water pump. By doing so, Snow's annotation sets limits on where we should and should _not_ find fatalities. In short, Snow's annotation is a hypothesis or prediction.
 
-## computing pump neighborhoods
+#### computing pump neighborhoods
 
 While his actual data and the specifics method of computation appear to be lost to history, I reverse engineer what I infer to be his approach by doing the following. First, from the quotation above I assume that his measure of proximity is the walking distance along the streets of Soho. Second, putting aside aside questions about the map's accuracy (it's actually a commercial map that Snow annotated), I consider the map to be the definitive "text" and make it the de facto source of data.
 
 I then wrote functions that compute and visualize walking distances on the map. The value of these functions go beyond the ability to replicate and validate Snow's efforts. By allowing you to compute hypothetical neighborhoods via selective inclusion or exclusion of pumps or to allow for different measures of proximity (e.g., Euclidean), they also allow you to explore counterfactual scenarios. Ultimately, this can help us to better assess whether we really can use the map to "prove" Snow's claims.
 
-## walking v. Euclidean neighborhoods
+#### walking v. Euclidean neighborhoods
 
 While walking distanced based neighborhoods are based on paths that follow streets, Euclidean distance based neighborhoods are based on straight line paths between a location and the nearest (or selected) pump:
 
@@ -102,7 +102,7 @@ plot(neighborhoodWalking(case.set = "expected"), "area.polygons")
 plot(neighborhoodVoronoi())
 ```
 
-### Walking neighborhoods
+#### exploring walking neighborhoods
 
 To explore "observed" walking neighborhoods, use `neighborhoodWalking()` with the `pump.select` argument:
 
@@ -118,7 +118,7 @@ plot(neighborhoodWalking(6:7, case.set = "expected"), type = "area.polygons")
 plot(neighborhoodWalking(-7, case.set = "expected"), type = "area.polygons")
 ```
 
-### Euclidean neighborhoods
+#### exploring Euclidean neighborhoods
 
 To explore "observed" Euclidean neighborhoods, use `neighborhoodEuclidean()` with the `pump.select` argument:
 
@@ -134,16 +134,15 @@ plot(neighborhoodVoronoi(6:7))
 plot(neighborhoodVoronoi(-7))
 ```
 
-### note on `neighborhoodWalking()` and `neighborhoodEuclidean()`
+#### note on computational performance
 
 `neighborhoodWalking()` and `neighborhoodEuclidean()` are computationally intensive. Using R version 3.6.0 on a single core of a 2.3 GHz Intel i7, the former plots observed paths to PDF in about 4.4 seconds and expected paths in 27 seconds. Using the function's parallel implementation on 4 physical (8 logical) cores, the times fall to about 3.9 and 12 seconds. The latter plots observed paths to PDF in about 3.6 seconds and expected paths in 109 seconds. Using the function's parallel implementation on 4 physical (8 logical) cores, the times fall to about 1.4 and 28 seconds.
 
 Note that parallelization is currently only available on Linux and Mac.
 
 Also, note that although some precautions are taken in R.app on macOS, the developers of the 'parallel' package, which both functions use, strongly discourage against using parallelization within a GUI or embedded environment. See `vignette("parallel")` for details.
 
-
-### warning message
+#### warning message
 
 With R version 3.6.0, you may see the warning below when loading 'cholera':
 
@@ -163,7 +162,7 @@ My understanding is that this is more annoying than problematic. It's fixed in '
 devtools::install_github("tidyverse/ggplot2", build_opts = c("--no-resave-data", "--no-manual"))
 ```
 
-### vignettes
+#### vignettes
 
 The vignettes are available in the package as well as online at the links below.
 
@@ -179,7 +178,7 @@ The vignettes are available in the package as well as online at the links below.
 
 [Time Series](https://github.com/lindbrook/cholera/blob/master/docs/vignettes/time.series.md) discusses functions and data related to the aggregate time series fatalities data and the questions surrounding the effect of the removal of the handle from the Broad Street pump.
 
-### lab notes
+#### lab notes
 
 The lab notes, which are only available online, go into detail about certain issues and topics discussed in the vignettes:
 

README.md

@@ -1,10 +1,10 @@
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 [![CRAN\_Status\_Badge](http://www.r-pkg.org/badges/version/cholera)](https://cran.r-project.org/package=cholera)
-[![GitHub\_Status\_Badge](https://img.shields.io/badge/GitHub-0.6.0.9033-red.svg)](https://github.com/lindbrook/cholera/blob/master/NEWS)
+[![GitHub\_Status\_Badge](https://img.shields.io/badge/GitHub-0.6.5-red.svg)](https://github.com/lindbrook/cholera/blob/master/NEWS)
 ## cholera: amend, augment and aid analysis of Snow’s cholera map
 
-### package features
+#### package features
 
   - Fixes three apparent coding errors in Dodson and Tobler’s 1992
     digitization of Snow’s map.
@@ -25,7 +25,7 @@
   - Adds two aggregate time series fatalities data sets, taken from the
     Vestry report.
 
-### getting started
+#### getting started
 
 To install ‘cholera’ from CRAN:
 
@@ -74,7 +74,7 @@ words, while the presence of a pump at or near the epicenter of the
 distribution of fatalities is strong circumstantial evidence, it is
 nonetheless circumstantial.
 
-### pump neighborhoods
+## pump neighborhoods
 
 This may be the reason why Snow added a graphical annotation to a second
 lesser-known version of the map, published in the *Report On The Cholera
@@ -95,7 +95,7 @@ water pump. By doing so, Snow’s annotation sets limits on where we
 should and should *not* find fatalities. In short, Snow’s annotation is
 a hypothesis or prediction.
 
-## computing pump neighborhoods
+#### computing pump neighborhoods
 
 While his actual data and the specifics method of computation appear to
 be lost to history, I reverse engineer what I infer to be his approach
@@ -114,7 +114,7 @@ you to explore counterfactual scenarios. Ultimately, this can help us to
 better assess whether we really can use the map to “prove” Snow’s
 claims.
 
-## walking v. Euclidean neighborhoods
+#### walking v. Euclidean neighborhoods
 
 While walking distanced based neighborhoods are based on paths that
 follow streets, Euclidean distance based neighborhoods are based on
@@ -158,7 +158,7 @@ plot(neighborhoodVoronoi())
 
 <img src="man/figures/README-unnamed-chunk-6-1.png" width="50%" /><img src="man/figures/README-unnamed-chunk-6-2.png" width="50%" />
 
-### Walking neighborhoods
+#### exploring walking neighborhoods
 
 To explore “observed” walking neighborhoods, use `neighborhoodWalking()`
 with the `pump.select` argument:
@@ -181,7 +181,7 @@ plot(neighborhoodWalking(-7, case.set = "expected"), type = "area.polygons")
 
 <img src="man/figures/README-unnamed-chunk-8-1.png" width="50%" /><img src="man/figures/README-unnamed-chunk-8-2.png" width="50%" />
 
-### Euclidean neighborhoods
+#### exploring Euclidean neighborhoods
 
 To explore “observed” Euclidean neighborhoods, use
 `neighborhoodEuclidean()` with the `pump.select` argument:
@@ -203,7 +203,7 @@ plot(neighborhoodVoronoi(-7))
 
 <img src="man/figures/README-unnamed-chunk-10-1.png" width="50%" /><img src="man/figures/README-unnamed-chunk-10-2.png" width="50%" />
 
-### note on `neighborhoodWalking()` and `neighborhoodEuclidean()`
+#### note on computational performance
 
 `neighborhoodWalking()` and `neighborhoodEuclidean()` are
 computationally intensive. Using R version 3.6.0 on a single core of a
@@ -222,7 +222,7 @@ the developers of the ‘parallel’ package, which both functions use,
 strongly discourage against using parallelization within a GUI or
 embedded environment. See `vignette("parallel")` for details.
 
-### warning message
+#### warning message
 
 With R version 3.6.0, you may see the warning below when loading
 ‘cholera’:
@@ -243,7 +243,7 @@ install the development version from GitHub:
 devtools::install_github("tidyverse/ggplot2", build_opts = c("--no-resave-data", "--no-manual"))
 ```
 
-### vignettes
+#### vignettes
 
 The vignettes are available in the package as well as online at the
 links below.
@@ -287,7 +287,7 @@ discusses functions and data related to the aggregate time series
 fatalities data and the questions surrounding the effect of the removal
 of the handle from the Broad Street pump.
 
-### lab notes
+#### lab notes
 
 The lab notes, which are only available online, go into detail about
 certain issues and topics discussed in the vignettes: