Merge pull request #48 from Public-Health-Scotland/update_readme

Overhaul the README

Author: bnowok

DESCRIPTION

@@ -31,3 +31,4 @@ Config/roxygen2/version: 8.0.0
 Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
+RoxygenNote: 7.3.3

NEWS.md

@@ -2,6 +2,7 @@
 
 -   Fixed a typo in the lookup path that meant the package wouldn't work on Windows (RStudio Desktop).
 -   Make the minimum required R version 4.1
+-   Overhaul the README; fixed out of date information, and added more detail and examples.
 -   Metadata is now available! Currently, this is only for the Scottish Postcode Directory (`get_spd()`), but we will bring it to the other lookups soon, too. You can see the metadata by using `metadata()` on the lookup object, for example:
 ```r
 spd <- get_spd()

README.Rmd

@@ -25,20 +25,62 @@ The goal of phslookups is to provide helper functions to easily access and use l
 
 ## Installation
 
-You can install the latest version of phslookups from [GitHub](https://github.com) with:
+If you are internal to PHS, you can install the latest version of phslookups from the internal Posit Package Manager.
+
+``` r
+# On the Posit Workbench
+install.packages("phslookups")
+
+# On RStudio Desktop it might be nessecary to specify the repository
+install.packages("phslookups", repos = "https://ppm-prod.publichealthscotland.org/phs-github/latest")
+```
+
+To install the development version directly from GitHub.
 
 ``` r
 remotes::install_github("Public-Health-Scotland/phslookups")
 ```
 
-It is not yet available from the PHS Posit Package Manager, it will never be available on CRAN as it is intended to be an internal only package.
+Note that phslookups will never be available on CRAN as it is intended to be an internal-only package, and relies on lookup files on internal-only drives.
+
+## Available lookups
+
+-   The Scottish Postcode Directory - `get_spd()`
+-   HSCP Localities - `get_hscp_locality()`
+-   SIMD lookups - `get_simd_datazone()` and `get_simd_postcode()`
 
 ## Example
 
-Load the Scottish Postcode Directory
+Load the latest available version of the full Scottish Postcode Directory.
 
-```{r example}
+```{r spd_latest_full}
 library(phslookups)
 
 spd <- get_spd()
+head(spd)
+```
+
+Get a specific version of a file, great if you want to 'lock' your code to a specific version too.
+
+```{r version_examples}
+library(phslookups)
+
+spd_23 <- get_spd(version = "2023_2")
+localities_mar_24 <- get_hscp_locality(version = "20240308")
+simd_dz_2016 <- get_simd_datazone(simd_version = "2016")
+simd_pc_2016_2012 <- get_simd_postcode(postcode_version = "2016_1", simd_version = "2012")
+```
+
+Select only the necessary columns to reduce memory use and improve speed.
+
+```{r col_select_examples}
+library(phslookups)
+library(dplyr)
+
+postcode_coords <- get_spd(col_select = c("pc7", "latitude", "longitude"))
+dz_locality_lookup <- get_hscp_locality(col_select = c("datazone2011", "hscp_locality"))
+dz_simd2016_quintiles <- get_simd_datazone(
+  simd_version = "2016",
+  col_select = c("DataZone2011", contains("quintile"))
+)
 ```

README.md

@@ -15,24 +15,104 @@ and use lookups which have been provided for analysis.
 
 ## Installation
 
-You can install the latest version of phslookups from
-[GitHub](https://github.com) with:
+If you are internal to PHS, you can install the latest version of
+phslookups from the internal Posit Package Manager.
+
+``` r
+# On the Posit Workbench
+install.packages("phslookups")
+
+# On RStudio Desktop it might be nessecary to specify the repository
+install.packages("phslookups", repos = "https://ppm-prod.publichealthscotland.org/phs-github/latest")
+```
+
+To install the development version directly from GitHub.
 
 ``` r
 remotes::install_github("Public-Health-Scotland/phslookups")
 ```
 
-It is not yet available from the PHS Posit Package Manager, it will
-never be available on CRAN as it is intended to be an internal only
-package.
+Note that phslookups will never be available on CRAN as it is intended
+to be an internal-only package, and relies on lookup files on
+internal-only drives.
+
+## Available lookups
+
+- The Scottish Postcode Directory - `get_spd()`
+- HSCP Localities - `get_hscp_locality()`
+- SIMD lookups - `get_simd_datazone()` and `get_simd_postcode()`
 
 ## Example
 
-Load the Scottish Postcode Directory
+Load the latest available version of the full Scottish Postcode
+Directory.
 
 ``` r
 library(phslookups)
 
 spd <- get_spd()
-#> ℹ Using "Scottish_Postcode_Directory_2024_1.parquet".
+#> ℹ Using the latest available version:
+#> "Scottish_Postcode_Directory_2026_1".
+#> If you require an older version or for reproducibility purposes
+#> please specify the version argument accordingly.
+head(spd)
+#> # A tibble: 6 × 95
+#>   pc7     pc8     split_char pc_district pc_sector date_of_introduction
+#>   <chr>   <chr>   <chr>      <chr>       <chr>     <date>              
+#> 1 AB1 0AA AB1 0AA <NA>       AB1         AB1 0     1980-01-01          
+#> 2 AB1 0AB AB1 0AB <NA>       AB1         AB1 0     1973-08-01          
+#> 3 AB1 0AD AB1 0AD <NA>       AB1         AB1 0     1973-08-01          
+#> 4 AB1 0AE AB1 0AE <NA>       AB1         AB1 0     1994-02-01          
+#> 5 AB1 0AF AB1 0AF <NA>       AB1         AB1 0     1990-12-01          
+#> 6 AB1 0AG AB1 0AG <NA>       AB1         AB1 0     1990-12-01          
+#> # ℹ 89 more variables: date_of_deletion <date>, postcode_type <chr>,
+#> #   pc_su_link <chr>, split_su_link <chr>, imputed <chr>, dpc <int>,
+#> #   dpc_nr <int>, hhc <int>, grid_reference_easting <int>,
+#> #   grid_reference_northing <int>, latitude <dbl>, longitude <dbl>,
+#> #   split_indicator <chr>, ca2019 <chr>, ca2019name <chr>, ca2018 <chr>,
+#> #   ca2011 <chr>, upc2024 <chr>, spr2021 <chr>, spc2021 <chr>, ew2022 <chr>,
+#> #   hb2019 <chr>, hb2019name <chr>, hb2018 <chr>, hb2014 <chr>, hb2006 <chr>, …
+```
+
+Get a specific version of a file, great if you want to ‘lock’ your code
+to a specific version too.
+
+``` r
+library(phslookups)
+
+spd_23 <- get_spd(version = "2023_2")
+localities_mar_24 <- get_hscp_locality(version = "20240308")
+simd_dz_2016 <- get_simd_datazone(simd_version = "2016")
+simd_pc_2016_2012 <- get_simd_postcode(postcode_version = "2016_1", simd_version = "2012")
+```
+
+Select only the necessary columns to reduce memory use and improve
+speed.
+
+``` r
+library(phslookups)
+library(dplyr)
+#> 
+#> Attaching package: 'dplyr'
+#> The following objects are masked from 'package:stats':
+#> 
+#>     filter, lag
+#> The following objects are masked from 'package:base':
+#> 
+#>     intersect, setdiff, setequal, union
+
+postcode_coords <- get_spd(col_select = c("pc7", "latitude", "longitude"))
+#> ℹ Using the latest available version:
+#> "Scottish_Postcode_Directory_2026_1".
+#> If you require an older version or for reproducibility purposes
+#> please specify the version argument accordingly.
+dz_locality_lookup <- get_hscp_locality(col_select = c("datazone2011", "hscp_locality"))
+#> ℹ Using the latest available version:
+#> "HSCP Localities_DZ11_Lookup_20240513".
+#> If you require an older version or for reproducibility purposes
+#> please specify the version argument accordingly.
+dz_simd2016_quintiles <- get_simd_datazone(
+  simd_version = "2016",
+  col_select = c("DataZone2011", contains("quintile"))
+)
 ```