Skip to main content

Repository: govuk-related-links-recommender

Machine learning model to recommend related content

Data science


Main things this repo does:

  1. Training an ML model for creating suggested related links like these (on the right sidebar)
  2. Getting suggested recommended links from the trained model
  3. Uploading the model, data, logs and recommended links to aws
  4. Feeding links from AWS to the publishing api

More details here:

Project Organization

├── Makefile           <- Makefile with commands like `make data` or `make train`
├──          <- The top-level README for developers using this project.
├── data
│   ├── external       <- Data from third party sources.
│   ├── interim        <- Intermediate data that has been transformed.
│   ├── processed      <- The final, canonical data sets for modeling.
│   └── raw            <- The original, immutable data dump.
├── docs               <- A default Sphinx project; see for details
├── models             <- Trained and serialized models, model predictions, or model summaries
├── notebooks          <- Jupyter notebooks. Naming convention is a number (for ordering),
│                         the creator's initials, and a short `-` delimited description, e.g.
│                         `1.0-jqp-initial-data-exploration`.
├── references         <- Data dictionaries, manuals, and all other explanatory materials.
├── reports            <- Generated analysis as HTML, PDF, LaTeX, etc.
│   └── figures        <- Generated graphics and figures to be used in reporting
├── requirements.txt   <- The requirements file for reproducing the analysis environment, e.g.
│                         generated with `pip freeze > requirements.txt`
├──           <- makes project pip installable (pip install -e .) so src can be imported
├── src                <- Source code for use in this project.
│   ├──    <- Makes src a Python module
│   │
│   ├── data           <- Scripts to download or generate data
│   │   └──
│   │
│   ├── features       <- Scripts to turn raw data into features for modeling
│   │   └──
│   │
│   ├── models         <- Scripts to train models and then use trained models to make
│   │   │                 predictions
│   │   ├──
│   │   └──
│   │
│   └── visualization  <- Scripts to create exploratory and results oriented visualizations
│       └──
└── tox.ini            <- tox file with settings for running tox; see

<!– raw HTML omitted –>

Python environment

Need to set and activate environment variables before running pipeline. To run the script, use command line to export GOOGLE_APPLICATION_CREDENTIALS='path/to/GOV-UK BigQuery analytics-fa2ed548d98c.json'

Environment variables are also used to locate data and model directories: DATA_DIR and MODEL_DIR. Make sure these are activated before running data pipeline.


Preprocessing config


Set the names for the structural (hyperlink) and functional (user movement) graphs/networks output csvs, from/to dates for GA data, if you want to use intraday data (cheap and quick!), and where the mongodb instance containing the content store is serving from

Node2vec config


Set whether you want to use weighted edges in node2vec (weights=user movement), various hyperparameters and output filenames for the model and embeddings

Important: Output file names

The names of the files that get uploaded to AWS (and ingested into the content api) are hardcoded in run_link_generation and run_link_ingestion. So any other file name (ie youve changed it in node2vec-config.yml) won’t get picked up.

Running the complete pipeline (high level)

  1. Downloads content store backup from aws
  2. sets up mongodb of content store
  3. Runs (see below for the contents of that)
  4. Uploads to aws

  1. Feeds links from AWS to the publishing api

Running the pipeline (low level)

Here’s a run through of what does:

Get the functional network


The functional network is how users move around Function queries govuk-bigquery-analytics for a list of source and destination content ids and a count of how many times users made that transition. Outputs a csv of weighted source-destination pairs. See src/config/preprocessing-config.yml for settings. Runs quickly. Runs cheaply if you use use_intraday: True in the config.

Get the structural network


The structural network is the network of hyperlinks in Function assumes there is a mongodb instance containing the content store on the ip and port configured in src/config/preprocessing-config.yml

Extracts all the links from content store content. Outputs csv of unweighted source - destination pairs. Seems extremely faffy and takes a long time.

How to set up mongodb instance locally:

Create functional + structural network


Concatenates the structural and functional edgelists. Untravelled edges (ie from the structural network) get assigned weight = 1. Everything else has weight = n users that travelled that edge

Outputs csv of unique weighted source-destination pairs

Training node2vec


Config in src/config/node2vec-config.yml. Trains the model and saves the embeddings and model.


Gets the top 5 most similar nodes for every node (not explicitly excluded in the source_exclusions_that_are_not_linked_from.yml ) ! Filters out results subject to lots of uncertainty (ie low user traversal). Outputs a csv

Do-not-display-automated-related-links-from these-pages

  • items with curated related links (ordered-related-items)
  • document_type==“fatality_notice”
  • document_type==“smart_answer” [except we have previously identified these looking for string matches]
("/y/")) &
                              ("/y")) &
                              ("/no/")) &
                              ("/no")) &
  • ‘/contact-student-finance-england’
  • ‘/student-finance-forms’
  • ‘/funding-for-postgraduate-study’
  • ‘/advanced-learner-loan’
  • ‘/teacher-training-funding’
  • ‘/extra-money-pay-university’
  • ‘/nhs-bursaries’
  • ‘/travel-grants-students-england’
  • ‘/career-development-loans’
  • ‘/care-to-learn’
  • ‘/dance-drama-awards’
  • ‘/social-work-bursaries’
  • ‘/apply-for-bankruptcy’
  • ‘/view-driving-licence’
  • ‘/being-taken-to-employment-tribunal-by-employee’
  • ‘/employment-tribunals’
  • ‘/staying-uk-eu-citizen’
  • ‘/report-driving-medical-condition’
  • ‘/check-flood-risk’


  • document_type is in this list: [“consultation_outcome”, “closed_consultation”, “open_consultation”, “fatality_notice”]
  • ‘/apply-for-bankruptcy’
  • ‘/view-driving-licence’
  • ‘/being-taken-to-employment-tribunal-by-employee’
  • ‘/employment-tribunals’
  • ‘/staying-uk-eu-citizen’
  • ‘/report-driving-medical-condition’
  • ‘/check-flood-risk’ (edited)


MIT License