Update readme.md

twedl · twedl · commit bedd8ed2ebb6 · 2020-03-08T13:52:23.000-04:00
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,4 +1,4 @@
 # Generated by roxygen2: do not edit by hand
 
 export(download_geography)
-export(get_geoinfo)
+export(geoinfo)
diff --git a/R/utils.R b/R/utils.R
@@ -61,9 +61,9 @@ download_geography <- function(geo_path, geo_dir = NULL) {
 #'
 #' @examples
 #' \donttest{
-#' get_geoinfo("lpr_000a16a_e")
+#' geoinfo("lpr_000a16a_e")
 #' }
-get_geoinfo <- function(filename) {
+geoinfo <- function(filename) {
 
   extract_codes <- canmap::code_pos
 
@@ -88,7 +88,6 @@ get_geoinfo <- function(filename) {
 
   dplyr::select(code_descriptions, .data$filename, .data$ref_date,
                 .data$geo_code, .data$geo_level, .data$file_type,
-                .data$format, .data$projection, .data$geo_coverage,
-                .data$language)
+                .data$format, .data$projection, .data$language)
 
 }
diff --git a/README.Rmd b/README.Rmd
@@ -36,10 +36,60 @@ library(canmap)
 tibble::as_tibble(shapefile_paths)
 
 # then pick a shapefile and get the link:
-shapefile_paths[1, c("filepath", "path")]
+(url <- shapefile_paths[1, ]$path)
+
+# then you can download it yourself, or use download_geography(url)
+```
+
+
+## Documentation 
+
+
+A list of useful links to clean up later:
+
+* [Geography definitions and documentation](https://www.statcan.gc.ca/eng/subjects/standard/sgc/geography)
+* [Root for geography downloads and documentation](https://www12.statcan.gc.ca/census-recensement/2016/geo/index-eng.cfm) 
+* [Direct link to download directory for 2016 shapefiles](https://www12.statcan.gc.ca/census-recensement/2011/geo/bound-limit/bound-limit-2016-eng.cfm)
+* [Heirarchy of geography](https://www150.statcan.gc.ca/n1/pub/92-195-x/2011001/other-autre/hierarch/h-eng.htm)
+
+
+### Parsing the filename for metadata
+
+Suppose you've downloaded the geography file ```lpr_000a16a_e.zip```. The filename defines the important geographic characteristics of the file (you can process using the ```code_pos``` dataset for code positions, or ```get_geoinfo```).
+
+```{r codes, warning = FALSE, message = FALSE}
+str(geoinfo("lpr_000a16a_e"))
+```
+
+And each of these codes has a meaning that can be found (sometimes) in the geography guide that accompanies a downloaded file (but you can't find out the details until *after* you've downloaded it, and is missing some information).
+
+Your first default parameters should be: 
+
+- ```file_type == "a"``` (digital boundary file---it doesn't look as good but it's smaller) 
+- ```format == "a"``` (ArcGIS/ArcInfo®/.shp---for use with ```sf``` and other ```R``` geographic packages)
+- ```geo_coverage == "000"``` (Canada---the only option AFAIK)
+- ```projection == "g"``` (geographic projection/lat-long---this makes it less likely for the user to get caught up in coordinate reference systems [CRS] conversion issues)
+
+The most important choices for the user are: year (2016 is the latest census year currently available), language (english or french) and geo_code/geo_level. A list of geo codes and geo levels are given in the ```code_book``` dataset:
+
+``` {r geos}
+dplyr::filter(code_book, code_type == "geo_level")
+```
+
+Business data usually isn't released below the economic region level (```er_```), while census data can go down to census tract (```ct_```), dissemination area (```da_```) or dissemination block (```db_```). 
+
+These are english codes, while the french codes are also in the dataset---english and french maps are in different files, so they have different codes: ```lpr_000a16a_e.zip``` has the english province/territory maps and ```lpr_000a16a_f.zip``` has the french province/territory maps. The only difference, AFAIK, is that the guide and geography names are in french in the french version.
+
+
+## Download and extract shapefiles to ```./geography/```
+
+``` {r eval = FALSE}
+download_geography(url)
 ```
 
 
+## Notes
+
 Please note that the 'canmap' project is released with a
 [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).
 By contributing to this project, you agree to abide by its terms.
diff --git a/README.md b/README.md
@@ -41,13 +41,104 @@ tibble::as_tibble(shapefile_paths)
 #> # … with 24 more rows, and 1 more variable: language <chr>
 
 # then pick a shapefile and get the link:
-shapefile_paths[1, c("filepath", "path")]
-#> # A tibble: 1 x 2
-#>   filepath      path                                                            
-#>   <chr>         <chr>                                                           
-#> 1 lada000b16a_e http://www12.statcan.gc.ca/census-recensement/2011/geo/bound-li…
+(url <- shapefile_paths[1, ]$path)
+#> [1] "http://www12.statcan.gc.ca/census-recensement/2011/geo/bound-limit/files-fichiers/2016/lada000b16a_e.zip"
+
+# then you can download it yourself, or use download_geography(url)
+```
+
+## Documentation
+
+A list of useful links to clean up later:
+
+  - [Geography definitions and
+    documentation](https://www.statcan.gc.ca/eng/subjects/standard/sgc/geography)
+  - [Root for geography downloads and
+    documentation](https://www12.statcan.gc.ca/census-recensement/2016/geo/index-eng.cfm)
+  - [Direct link to download directory for 2016
+    shapefiles](https://www12.statcan.gc.ca/census-recensement/2011/geo/bound-limit/bound-limit-2016-eng.cfm)
+  - [Heirarchy of
+    geography](https://www150.statcan.gc.ca/n1/pub/92-195-x/2011001/other-autre/hierarch/h-eng.htm)
+
+### Parsing the filename for metadata
+
+Suppose you’ve downloaded the geography file `lpr_000a16a_e.zip`. The
+filename defines the important geographic characteristics of the file
+(you can process using the `code_pos` dataset for code positions, or
+`get_geoinfo`).
+
+``` r
+str(get_geoinfo("lpr_000a16a_e"))
+#> Classes 'tbl_df', 'tbl' and 'data.frame':    1 obs. of  9 variables:
+#>  $ filename    : chr "lpr_000a16a_e"
+#>  $ ref_date    : chr "2016"
+#>  $ geo_code    : chr "pr_"
+#>  $ geo_level   : chr "province and territory"
+#>  $ file_type   : chr "digital boundary file"
+#>  $ format      : chr "ArcGIS (.shp)"
+#>  $ projection  : chr "projection in Lambert conformal conic"
+#>  $ geo_coverage: chr "canada"
+#>  $ language    : chr "english"
 ```
 
+And each of these codes has a meaning that can be found (sometimes) in
+the geography guide that accompanies a downloaded file (but you can’t
+find out the details until *after* you’ve downloaded it, and is missing
+some information).
+
+Your first default parameters should be:
+
+  - `file_type == "a"` (digital boundary file—it doesn’t look as good
+    but it’s smaller)
+  - `format == "a"` (ArcGIS/ArcInfo®/.shp—for use with `sf` and other
+    `R` geographic packages)
+  - `geo_coverage == "000"` (Canada—the only option AFAIK)
+  - `projection == "g"` (geographic projection/lat-long—this makes it
+    less likely for the user to get caught up in coordinate reference
+    systems \[CRS\] conversion issues)
+
+The most important choices for the user are: year (2016 is the latest
+census year currently available), language (english or french) and
+geo\_code/geo\_level. A list of geo codes and geo levels are given in
+the `code_book` dataset:
+
+``` r
+dplyr::filter(code_book, code_type == "geo_level")
+#> # A tibble: 34 x 3
+#>    code_type code  code_desc                                        
+#>    <chr>     <chr> <chr>                                            
+#>  1 geo_level pr_   province and territory                           
+#>  2 geo_level cd_   census division                                  
+#>  3 geo_level ccs   census consolidated subdivision                  
+#>  4 geo_level csd   census subdivision                               
+#>  5 geo_level er_   economic region                                  
+#>  6 geo_level cma   census metropolitan area and census agglomeration
+#>  7 geo_level fed   federal electoral district                       
+#>  8 geo_level ct_   census tract                                     
+#>  9 geo_level dpl   designated place                                 
+#> 10 geo_level pc_   population centre                                
+#> # … with 24 more rows
+```
+
+Business data usually isn’t released below the economic region level
+(`er_`), while census data can go down to census tract (`ct_`),
+dissemination area (`da_`) or dissemination block (`db_`).
+
+These are english codes, while the french codes are also in the
+dataset—english and french maps are in different files, so they have
+different codes: `lpr_000a16a_e.zip` has the english province/territory
+maps and `lpr_000a16a_f.zip` has the french province/territory maps. The
+only difference, AFAIK, is that the guide and geography names are in
+french in the french version.
+
+## Download and extract shapefiles to `./geography/`
+
+``` r
+download_geography("lpr_000a16a_e")
+```
+
+## Notes
+
 Please note that the ‘canmap’ project is released with a [Contributor
 Code of Conduct](.github/CODE_OF_CONDUCT.md). By contributing to this
 project, you agree to abide by its terms.
diff --git a/man/geoinfo.Rd b/man/geoinfo.Rd
