mojrap

Contents

• What is this repo for?
• Using the package
• Functions in the package
• Package infrastructure
• Contributing to the package
• Found a bug?
• The mojverse
• Other RAP Resources

What is this repo for?

This is a collection of quality assured, generalised functions that have been created in the various Reproducible Analytical Pipelines (e.g. Statistics Publications, Financial Reports etc.) within the Ministry of Justice.

If you are implementing RAP within your own department, or just think some of these functions could be of use, please install the package and use away! Also, if you are using any of the functions and find a bug or can think of away to improve them, we would love your input - see Contributing to the package for ways you can help.

Using the package

If you just want to make use of the package, do the following:

• Run devtools::install_github("moj-analytical-services/mojrap") to download the package
• Load the package using library(mojrap)

You will now have access to all the functions in the library, using the following syntax:

Example: to use FUNCTION from the asdrap package, type mojrap::FUNCTION()

Functions in the package

• add_lookups.R - Adds lookup file to dataset
• as_number.R - Turns numerical strings into number format
• arrow_image.R - Outputs the path to an arrow image for the main points table
• arrow_pdf.R - Outputs the path to an arrow image for the PDF version of the main points table
• arrow_utf.R - Outputs UTF arrows
• change.R - Calculates changes over a given time period
• change_desc.R - Describes changes over a given time period
• choose_value.R - Choose a value from a dataframe
• col_series.R - Outputs a colour in hex format with a given number of different shades
• connector.R - Produces a connecting word for a compound sentence
• date_type.R - Takes dates in "%Y%m%d" format, with any or no separators, and outputs them in specified formats
• format_expenditure.R - Formats a number as an expenditure
• format_num.R - Formats numerical values as thousand delimited numerical strings
• format_perc.R - Formats fractions as numerical strings in percentage format
• incdec.R - Quantifies changes in values eg. "increased by ..."
• mojquarter.R - Converts dates in "%Y%m%d" format, with or without separators, to calendar or financial quarters
• moj_col.R - Selects which shades you want from the output of col_series.R, in order of brightest to darkest
• pluralise.R - Pluralises words with an 's', depending on a given value
• previous_quarter - Given the latest quarter, return the previous quarter or quarters further back in time
• pub_date.R - Returns the next publication date
• quarter_dates.R - Calculates the start or end dates of a quarter
• read_cases_to_data.R - Reads in a case-level dataset stored in S3 and aggregates by specified variables
• superscript.R - Add superscripts/subscripts to Excel spreadsheets
• write_tables.R - Write multiple tables (e.g quarterly and monthly data) with formatting to a single existing sheet in a workbook object

Package Infrastructure

A whistle stop tour of the package for those who aren't as familiar with R/package development

R/

This is where most of the code which does the analysis lives. All the code is functions, only some of which are avaiable when you install the package.

man/

This is where the package documentation that can usually be found running ?function_name

tests/

The code here simply tests the functions in the package are working as expected. None of this code does any of the analysis the package was designed for, instead acting as quality assurance for the functions that have been created to do the analysis.

README.md

Contains the text for this document in Markdown format. This is the sole documentation for the package, other than occasional comments in the source code. The source code should be transparent enough that it is best to read the source code to understand how functions in the package work.

NAMESPACE

Is a config file that should not be updated manually - instead use roxygen comments in the code. http://r-pkgs.had.co.nz/namespace.html

DESCRIPTION

Is a config file. Most fields are self explanatory. http://r-pkgs.had.co.nz/description.html

Contributing to the package

Now that you have created a reusable function, how do you share it with everyone?

1. Clone this repo: In the terminal, run git clone [email protected]:moj-analytical-services/mojrap.git Or see the platform guidance if you are having any difficulties.

2. Create a new branch and add your function(s) to it - see the platform guidance if you aren't familiar with doing this

3. Open a Pull Request to merge your functions into the package.

4. Get someone to review your pull request. Approval from at least one admin is also required before the pull request can be merged. The reviewer must check that the function satisfies the following:

• Must have unit testing
• Must pass R CMD checks of the entire package, with no Errors or Warnings, and preferably no Notes.
• Must have documentation around functions with examples
• Should follow coding best practice guidelines, e.g. DASD Coding Principles, MoJ Harmonisation Guidance, ONS Quality Assurance of Code for Analysis and Research guidlines.

5. Once your pull request has been approved and merged by an admin, make sure to post in the #rap Slack channel that your changes have been merged in so people can update their version of the package.

Congratulations! You have now contibuted to the mojrap package! If you reinstall the package you will be able to use your functions.

Found a bug?

You can also contribute by helping to improve the existing functions. If you find a bug, or think there is a better way of doing something, raise an issue and/or open a pull request with your suggested solution.

mojverse

This package is intended to sit within a tidyverse-style ecosystem of packages known as the mojverse, providing functions to assist with building a variety of elements/outputs that may sit in a Reproducible Analytical Pipeline. Below is a list of packages intended to sit within the mojverse:

• mojspeakr: Formatting RMarkdown into govspeak for publishing on gov.uk
• mojchart: Formatting ggplot2 charts and applying MoJ corporate colours
• mojrap: Generalised functions for RAP

Please install the mojverse package, to install all packages listed above.

Other resources

For bespoke code please see other MoJ repos:

• OMSQ_RAP - our first publication that has been entirely RAPed
• JDL_RAP
• CCSQ_RAP

(Note that some of these may be accessible to users within the MoJ, but if you would like access to these let us know!) Or from across government:

• DDCMS Economics Estimates RAP

Slack/MS Teams channels:

• If you are working within government and are looking to get up to speed with RAP, we would recommend joining the #rap_collaboration channel of the Government Data Science Slack and getting involved with the community there.
• To engage with the MoJ RAP community, you can either use the #rap Slack channel, or contact Aidan Mews to join the RAP Publication group on MS Teams.

Documentation:

• Free online resources are available, such as the RAP Companion written by the Government Digital Service (GDS), a Udemy RAP using R course, the RAP Manual written by members of the MoJ RAP Publication group, or the GSS RAP site.