maintainer-guide

Alexander Newton

09/08/2019

Purpose

This guide is meant to be a handyman’s how-to on updating and maintaining this package. Maintenance of this package will allow it to be used into the future, and will familiarise those responsible for it with the internal structure of the package. This familiarity will allow maintainers to repurpose code, rewrite it to accomodate new needs, and allow its further development.

Structure of CoRe

CoRe is structured as a typical R package. Its source code can be found in R/, its documentation in man/, its data in data/, its raw data in data-raw/, and useful vignettes in vignettes/. Documentation is generated using the roxygen2 package.

R Code

CoRe has six R files.

  • datasets.R only exists to document datasets.
  • data-specific.R implements a number of internal functions used to load, tidy, clean, and validate key datasets.
  • number-reoffences.R implements a number of internal functions that are used to model the number of reoffences.
  • unit-costs.R implements a number of internal functions that are used to map unit costs from the Home Office offences to the MOJ offences.
  • utils. R implements some exported functions useful for dealing with dates.
  • costs-of-crime.R implements a single function used to join data generated using number-reoffences.R and unit-costs.R.
  • API.R implements the core API functions which will be used by the users. These call on functions from the other files.

####INCLUDE FUNCTION TREE IMAGE HERE####

Datasets

Datasets will need the most maintenance as, ideally, they will be updated as frequently as published. It is the aim of the MOJ Rap Champion and Harmonisation lead that data will be uploaded to the analytical platform in the future. This will greatly facilitate this process as functions can be written to automatically extract the data from these data sources. The maintainer of this package should press for this as it will lessen their workload.

The datasets in the package come from:

Dataset Source Comment
all_convictions CJ Statistics Updated quarterly, table Q3.5.
coc_mapping None. This is part of the CoRe package.
crime_severity CSS Updated annually.
csew_crime CSEW Updated quarterly, table A1.
fraud_prc PRC Updated quarterly, table A3.
gdp_deflators GDP Updated quarterly, the data-scripts.R reads straight from URL.
ho_coc None. This is derived from the HO ESCC report.
ho_multi None. This is derived from the HO ESCC report.
personal_commercial_crime None. This is derived from the HO ESCC report.
police_outcomes Police outcomes OD Files labelled “Outcomes open data…”, updated 1ce per year.
police_recorded_crime PRC Updated quarterly, table A4.
proxy_contrib None. This is part of the CoRe package.
reoffending_stats Proven reoffending stats Updated quarterly, table B4.
summary_cjs_costs None. Derived from previous work on unit costs in the CJS. Not strong
summary_oocds Out of court disposals data tool Updated annually. Supplementary table released alongside “year ending December …” CJS statistics

These are our harmonised variable names:

  • year_ending
  • offence_group and its variants:
    • index_offence_group
    • reoffence_group
  • number_offences
  • number_reoffences

Note on dates

We have implemented two functions find_closest_date() and filter_closest_date(). These functions find the closest date within a dataset (on the year_ending column) to a target_date, and filter the dataset by that target_date respectively. As there are no caps on maximum/minimum dates, this can lead to unexpected behaviour. We advise examining the dates available for the internal data where unsure.

The year_ending field refers to a calendar month, however R automatically imports dates as yyyy-mm-dd. Therefore, year_ending appends -01 to each calendar month, even though it technically refers to the end of the month.

Documentation

Function documentation is created using roxygen2. These are created using inline comments beginning with the ##' operator. Documentation generated by roxygen2::roxygenize() is stored in the man/ folder. These documentation files, plus those vignettes/, are used to generate the website using pkgdown. To build/update the website use pkgdown::build_site().

Tests

Xennor will start making tests, at least on the API functions. Come

Dependencies

This package was working using the following environment, future iterations of this package should include a conda environment:

[1] "2019-09-26"
[1] "2019-09-26 14:26:47 UTC"

R version 3.5.1 (2018-07-02)
Platform: x86_64-conda_cos6-linux-gnu (64-bit)
Running under: Debian GNU/Linux 9 (stretch)

Matrix products: default
BLAS/LAPACK: /home/alexander-newton/.conda/envs/rstudio/lib/R/lib/libRblas.so

locale:
 [1] LC_CTYPE=en_GB.UTF-8       LC_NUMERIC=C               LC_TIME=en_GB.UTF-8        LC_COLLATE=en_GB.UTF-8     LC_MONETARY=en_GB.UTF-8    LC_MESSAGES=en_GB.UTF-8   
 [7] LC_PAPER=en_GB.UTF-8       LC_NAME=C                  LC_ADDRESS=C               LC_TELEPHONE=C             LC_MEASUREMENT=en_GB.UTF-8 LC_IDENTIFICATION=C       

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] CoRe_0.2.0     testthat_2.1.1

loaded via a namespace (and not attached):
 [1] Rcpp_1.0.2       rstudioapi_0.10  knitr_1.23       magrittr_1.5     tidyselect_0.2.5 pkgload_1.0.2    R6_2.4.0         rlang_0.4.0      dplyr_0.8.3      tools_3.5.1     
[11] packrat_0.5.0    xfun_0.8         withr_2.1.2      htmltools_0.3.6  yaml_2.2.0       assertthat_0.2.1 rprojroot_1.3-2  digest_0.6.20    tibble_2.1.3     crayon_1.3.4    
[21] purrr_0.3.2      glue_1.3.1       evaluate_0.14    rmarkdown_1.13   compiler_3.5.1   pillar_1.4.2     desc_1.2.0       backports_1.1.4  pkgconfig_2.0.2