Skip to content

Latest commit

 

History

History
489 lines (360 loc) · 21.8 KB

LocalSkillsDeveloperGuide.md

File metadata and controls

489 lines (360 loc) · 21.8 KB
Raw

Local skills developer guide

Introduction

The Local Skills dashboard is an R shiny dashboard displaying published local data from a variety of sources in an easy to navigate format. To support local skills planning, the dashboard covers topics such as employment, qualifications, and education outcomes across England.

This guide is for developers to update data or change the dashboard.

I want to see the dashboard

The public dashboard is here:

https://department-for-education.shinyapps.io/local-skills-dashboard/

The pre production (where we test the dashboard before publishing) is here (you may need to get access):

https://department-for-education.shinyapps.io/local-skills-dashboard-preprod/

I want to run the dashboard in R

  1. Connect to the git hub branch you want to run and pull to ensure you have the latest version:

    • Main is the public facing branch - any pushes to this will be live on the web.

    • Development is the pre-production (preprod) branch - any pushes to this will be live on the private preprod site.

    • Or any other branch you would like to run.

The github page is here: https://github.com/dfe-analytical-services/lsip_dashboard.

  1. Align your packages with the dashboards packages in your branch using renv: renv::restore()

  2. Run the dashboard. The dashboard will open in a new window: runApp()

The dashboard runs off the data held within /Data/AppData, so will just run without having to have data within your local Environment.

There may be times when you want to look at the dashboard in a browser (checking formatting across browsers or window sizes, or checking download functions). To do this click on the “Open in Browser” button at the top of the dashboard pop up window.

I want to update a dataset

The Data Sources tab of the dashboard has a list of all the datasets and their next release date.

Update schedule

These are the common release points, however be aware that there may be revisions to any of the datasets throughout the year.

  • Annual population survey is released four times a year: 1) Jan 2) Apr 3) Jul/Aug/Sept 4) Oct. We update employment volumes and split by industry at every release. However:

    • Highest qualification is only updated in the APS once a year in the Apr release.

  • Individualised learner record is updated quarterly but we only update with the final data, usually release in November (the in year data is provisional and subject to lag).

  • UK business count is released and updated in the dashboard once a year in Sept/Oct.

  • Business demography is released and updated in the dashboard once a year in Nov.

  • Destination measures are released and updated in the dashboard once a year in Oct.

  • Job adverts were released for the first time in Feb 23. No release schedule has been announced.

  • Skills Imperative 2035 was released in Mar 23. No release schedule has been announced.

Month Release
Jan APS emp vols APS emp ind
Feb
Mar
Apr APS emp vols APS emp ind APS emp qual
May
Jun
Jul APS emp vols APS emp ind
Aug
Sep Business count
Oct APS emp vols APS emp ind Destinations
Nov ILR
Dec

Update process

  1. Make yourself a new github branch off (probably) the latest public version, so off Main. Pull and run renv::restore() to align packages with the dashboard.

For non-NOMIS datasets:

2a. Download the latest version of the dataset. If you need help finding the dataset source, have a look at the “Data Sources” tab in the dashboard - this gives info and links to data sources.

2b. Navigate to /Data folder (either in R Files or in Windows Explorer). All raw datasets are held in /Data. They are the numbered datasets.

  • 1-x are geographical files (look ups and boundary files)

  • 2-x are the raw local skills data files

  • 3-x are excel files which populate tables within the dashboard and a 3-2_dataText helps populates the dynamic text in the Local Skills tab

2c. Once you have figured out where the dataset you want to update is currently kept, navigate to that folder

2d. Delete the currently held dataset(s) in that folder. The folder should now be empty.

2e. Paste the new dataset in that folder.

For Nomis Datasets:

You should just be able to skip to stage (4) as ExtractLoadData.R in step (5) will pull all the latest Nomis data. However, please take note that the highest qualifications data currently includes data from two timeseries (NVQ and RQF), as RQF replaced NVQ in January 2022. The code for this section will need to be updated at each release (yearly) to use all available RQF data, and NVQ data for the remaining quarters. Once there have been five releases of the RQF data the code can be changed to use only the five latest releases of RQF data.

  1. Dashboard admin:

  • You need to update the dashboard’s Data Sources tab with information about your new data. Open /Data/3-1_DataTable/DataTable.xlsx in Excel. Update the relevant row with new dates, links and information.

  • Update the dashboard’s Version Log. This is done in ui.R under the “2.1.3 Version control” header. Move the current Latest Version text down into the Previous Version area, and repopulate the Current Version with new details.

  • You may need to update the Latest Period and/or the data caveats in the /Data/3-2_dataText/dataText.xlsx file as well. These are used to populate dynamic text on the dashboard’s Local Skills tab.

  1. Run the ExtractLoadData.R script. This runs all the scripts in /importData and goes through all the numbered folders in /Data and loads the datasets in each folder as a R object. As we have datasets from a wide range of sources that come in all kinds of formats, we do a lot of data cleaning, manipulating and formatting to get into a format the dashboard can work with.

source("~/RProjects/lsip_dashboard/ExtractLoadData.R", echo=TRUE)

This takes about 20 mins. You should see your environment is populated with new, clean datasets and your Data/AppData folder has been updated with the updated versions of the files the dashboard uses.

  1. Check any changes to the data used in the dashboard. As a step in the QA run this file and have a look at the outputs:

    source("~/RProjects/lsip_dashboard/checkUpdateChanges.R", echo=TRUE)

    This will show you if there has been any changes to the geography names, the metric names, the time periods and also check for any changes in the NAs within the data (a sign that something has gone awry).

  2. Run the dashboard: runApp()

  3. Update the shiny tests by running shinytest2::test_app() and checking that any newly generated snapshots look as expected.

  4. QA. Create a new QA log in “Analytical Projects\Analysis\S005 LSIP dashboard\Documentation\QA”. Follow the structure of one already in there. Some checks you may do:

  • Check that your dataset has been updated correctly (by comparing with the version you branched off of and cross checking with the raw data).
  • Check the Data Sources table has been updated correctly
  • Check the text in the Local Skills tab makes sense for your updated metric.
  • Get sign off Hannah Cox and/or Harris (see here and here for process)

  1. If everything looks ok, commit, push and merge to Development. Wait for that to deploy (can take 15mins or more - you can track this in Actions · dfe-analytical-services/lsip_dashboard (github.com)). Again check everything looks ok in the preprod environment: https://department-for-education.shinyapps.io/local-skills-dashboard-preprod/ 13 If you have done sufficient QA and you are satisfied, merge to Main and wait for that to deploy. Check again everything looks ok in the live environment: https://department-for-education.shinyapps.io/local-skills-dashboard/

  2. Consider communicating the change to the wider Team or other stakeholders.

I want to add a metric to the dashboard

Make yourself a new github branch off (probably) the latest public version, so off Main. Pull and run renv::restore() to align packages with the dashboard.

It’s a metric that already exists in the data.

We currently have a fair few metrics that exist in the data but aren’t being shown in the dashboard:

“all”, “economicallyactive”, “employees”, “starts_rate_per_100000_population”, “starts”, “active”, “births”, “deaths”, “qualNone”, “qualL1”, “qualL2”, “qualApp”, “qualL3”, “qualL4”, “qualOther”,“employmentProjection”

To add one of these into the dashboard:

  1. Remove the metric from the unused list in importData/combineData.R under the “4.1 Unused metrics” header.

  2. Add your metric into metricChoices in global.R and assign it a more user friendly name for use in the dashboard.

  3. Add a row into /Data/3-2_dataText/dataText.xlsx for your metric assigning it the relevant text.

  4. Run extractLoadData.R

  5. Run runApp() and check the metric is available in the Local Skills tab.

  6. Update the shiny tests by running shinytest2::test_app() and checking that any newly generated snapshots look as expected.

  7. QA. Create a new QA log in “Analytical Projects\Analysis\S005 LSIP dashboard\Documentation\QA”. Follow the structure of one already in there. Some checks you may do:

    • Check that your dataset has been added correctly (by comparing with the version you branched off of and cross checking with the raw data).
    • Check the Data Sources table has been updated correctly
    • Check the text in the Local Skills tab makes sense for your updated metric.
    • Check the charts are in the format you want especially looking at whether it needs to be a percentage or volume

  8. If everything looks ok, commit, push and merge to Development. Wait for that to deploy (can take 15mins or more - you can track this in Actions · dfe-analytical-services/lsip_dashboard (github.com)). Again check everything looks ok in the preprod environment: https://department-for-education.shinyapps.io/local-skills-dashboard-preprod/

  9. If you have done sufficient QA and you are satisfied, merge to Main and wait for that to deploy. Check again everything looks ok in the live environment: https://department-for-education.shinyapps.io/local-skills-dashboard/

  10. Consider communicating the change to the wider Team or other stakeholders.

Optional extras/troubleshooting

  • You might need to make some adjustments to how it is presented in the charts ie percentage vs vol. If the problem is in the time chart or map, check server.R where there are a few if statements to assign a metric to either % or vol. If the problem is in the breakdown chart check the server and combineData.R where some metrics are split into proportions and some are not.

  • If you want it to appear in the Data Explorer tab, remove it from the exclusion list in combineData.r/4.4 C_dataHub and give it a good name in there as well.

  • You may want to add to the Overview page. If so, add to ui.R wherever you want and create KPIs and charts in server.R using the following function: createOverviewKPI, createOverviewChart, renderOverviewChart.

It’s a brand new metric

  1. Create a new folder for your new dataset in /Data. Labels the folder 2-x_datasetName.

  2. Paste your data into this folder.

  3. Dashboard admin:

    1. You need to update the dashboard’s Data Sources tab with information about your new data. Open /Data/3-1_DataTable/DataTable.xlsx in Excel. Add a new row with new dates, links and information. You also need to add some information about the dataset on this page. You can do this in ui.R/2.5.2 Data details text.

    2. Update the dashboard’s Version Log. This is done in ui.R under the “2.1.3 Version control” header. Move the current Latest Version text down into the Previous Version area, and repopulate the Current Version with new details.

    3. Populate a new row in /Data/3-2_dataText/dataText.xlsx file. These are used to populate dynamic text on the dashboard’s Local Skills tab.

    4. Add some overview information about the dataset on the User Guide page of the dashboard. an do this in ui.R/2.1.2 Contents

  4. Add a new script to /importData to extract and clean the data and add the script to the run list in ExtractLoadData.R (copy one of the examples in there). This file should direct to your new folder and import the data. It will also need to format your data so that it matches the form the dashboard is prepared for.

    a. Firstly clean the raw data so it is a usable format with headings and data rows. There are some functions within the functions folder that might help (formatNomis cleans Nomis data, formatLong puts data into long format)

    b. Ensure you have data for all the geographic areas used in the dashboard: LADUs, LSIPs, LEPs, MCAs, and national.

    If your data only comes in LADU form, you can groups these up to get the bigger geographcal areas. The function addGeos will help with this, but might not always be exacly what you want, so check. If you are grouping up, there will likely be some rounding errors so make sure to add that caveat to the Data Sources tab.

    c. You then need to manipulate your now clean data into the following form:

Column name Description Format Example
geogConcat Area name and geography character Black Country LEP
metric Variable of interest character inemployment
breakdown If the dataset has a breakdown they are listed here. Every metric must have a “Total” as well as any breakdowns. character Age
subgroup Any subgroups of the breakdown. If breakdown is “Total” this is also “Total” character 19-24
chartPeriod The period which the data relates to in plain English. character AY20/21
timePeriod The start date of the period. character 01/08/2020
latest 1 if this is the most recent period in the data. -1 is one year before that. 0 for any other. numeric -1
valueText The value of the metric in this subgroup. Includes any supression from the source. character 5000
value The value of the metric in this subgroup in numeric terms. NA if suppressed. numeric 5000

  1. Give the now clean and formatted dataset a name like C_dataName and add into importData/combineData.R file.

  2. Run ExtractLoadData.R. You should see some new files in your local environment and the data in Data/AppData will have updated to include your new metric.

  3. Add your metric into metricChoices in global.R and assign it a more user friendly name for use in the dashboard.

  4. Give your metric a good name for the Data Explorer tab in combineData.r/4.4 C_dataHub.

  5. Run the app runApp().

  6. Update the shiny tests by running shinytest2::test_app() and checking that any newly generated snapshots look as expected.

  7. QA. Create a new QA log in “Analytical Projects\Analysis\S005 LSIP dashboard\Documentation\QA”. Follow the structure of one already in there. Some checks you may do:

    • Check that your dataset has been added correctly (by comparing with the version you branched off of and cross checking with the raw data).
    • Check the Data Sources table has been updated correctly
    • Check the text in the Local Skills tab makes sense for your updated metric.
    • Check the charts are in the format you want especially looking at whether it needs to be a percentage or volume

  8. Take a renv snapshot to help future users allign to any packages you have changed/added:renv::snapshot()

  9. If everything looks ok, commit, push and merge to Development. Wait for that to deploy (can take 15mins or more - you can track this in Actions · dfe-analytical-services/lsip_dashboard (github.com)). Again check everything looks ok in the preprod environment: https://department-for-education.shinyapps.io/local-skills-dashboard-preprod/

  10. If you have done sufficient QA and you are satisfied, merge to Main and wait for that to deploy. Check again everything looks ok in the live environment: https://department-for-education.shinyapps.io/local-skills-dashboard/

  11. Consider communicating the change to the wider Team or other stakeholders.

Optional extras/troubleshooting

  • You might need to make some adjustments to how it is presented in the charts ie percentage vs vol. If the problem is in the time chart or map, check server.R where there are a few if statements to assign a metric to either % or vol. If the problem is in the breakdown chart check the server and combineData.R where some metrics are split into proportions and some are not.

  • You may want to add to the Overview page. If so, add to ui.R wherever you want and create KPIs and charts in server.R using the following function: createOverviewKPI, createOverviewChart, renderOverviewChart

I want to monitor dashboard usage

We use Google Analytics to see a range of metrics on dashboard users. Log in here (you may need access): https://analytics.google.com/analytics/web/.

As well as the more generic metrics (users, new users, event clicks, time spent), we have been collecting specific events from the dashboard. You can see the things we monitor in /google-analytics.html. You can add tracking for whatever dashboard event you want and then monitor that event within Google Analytics.

In Google Analytics we have started creating custom reports to collect some interesting data. You can see these (and create these) by clicking the “Explore” tab in the left of the Google Analytics page.

Troubleshooting

The most common problems occur when something changes in an input data set. That might be :

  • renaming of a column

  • moving of data within an excel input

  • renaming geographical areas

  • adding or removing or changing the definition of some data

Another source of problem is changing geographical areas:

  • updating boundaries (pages like this are good to keep an eye on https://en.wikipedia.org/wiki/2019%E2%80%932023_structural_changes_to_local_government_in_England but changes to LSIPs, MCAs and LEPs you are better off looking at the latest data on https://geoportal.statistics.gov.uk/)

  • area name changes. These can be random eg typos, or genuine updates to names. In the /importData files there are a number of bits of correcting code to allign names. We attempt to use codes where possible but some data sets do not have them.

  • some data sets use the boundaries at the time in their historical data. Some project the current projections back. In the dashboard we apply the latest boundaries to all files.

The best way to check for all of these is to try and spot any NAs in the final data (that in /Data/AppData). This will catch most, but may not catch all so it is also good to check the final dashboard for errors in the charts and maps.

We are looking to implement more QA tests to check these things automatically.