project.yaml in the editor. This file will be near the end of the
56 | list of files and folders. This file describes how each step in your analysis should
57 | be run. It already defines a single generate_dataset action
58 | which defines the output that we've generated so far. This file is in a format
59 | called YAML: the way it's indented matters, so be careful to copy and paste the
60 | following carefully.
61 | generate_report action to the file, so the entire file looks like this:
64 | output folder only contains a .gitkeep file.
52 | output/dataset.csv.gz, and that it should be considered highly sensitive
83 | data. What you see here is exactly the same process that would happen on a real, secure
84 | server.
85 | output folder
89 | and see that it contains a dataset.csv.gz file.
90 | element
25 | [
26 | ...document.querySelectorAll(
27 | `button.md-clipboard[data-clipboard-target$="code"]`,
28 | ),
29 | ].map((btn) =>
30 | btn.setAttribute(
31 | "data-clipboard-text",
32 | getTextWithoutPromptAndOutput(btn.dataset.clipboardTarget),
33 | ),
34 | );
35 | }
36 |
37 | document.addEventListener("DOMContentLoaded", () => {
38 | patchCopyCodeButtons();
39 | });
40 |
41 | /**
42 | * Move the existing footer buttons to the main content section to make them more visible.
43 | * Material MKDocs doesn’t seem to have any options to do this natively.
44 | * @returns {void}
45 | */
46 | function moveNavButtons() {
47 | /** @type {HTMLDivElement} */
48 | const contentArea = document.querySelector(`[data-md-component="content"]`);
49 | /** @type {HTMLElement} */
50 | const footerNav = document.querySelector(`[aria-label="Footer"]`);
51 | /** @type {HTMLElement} */
52 | const footClone = footerNav.cloneNode(true);
53 | footClone.classList.add("footer-nav-buttons");
54 | contentArea.appendChild(footClone);
55 | footerNav.setAttribute("hidden", "true");
56 | }
57 |
58 | /** @type {string[]} */
59 | const buttonPaths = [
60 | "/ehrql/tutorial/",
61 | "/getting-started/tutorial/",
62 | "/outputs/output-checking/",
63 | "/outputs/releasing-overview/",
64 | "/outputs/requesting-file-release/",
65 | "/outputs/sdc/",
66 | "/outputs/viewing-released-files/",
67 | ];
68 | /** @type {string} */
69 | const docPath = window.location.pathname;
70 |
71 | for (const path of buttonPaths) {
72 | if (docPath.startsWith(path)) {
73 | moveNavButtons();
74 | }
75 | }
76 |
--------------------------------------------------------------------------------
/docs/legacy/requesting-release-offline-process.md:
--------------------------------------------------------------------------------
1 | !!! note
2 | This page describes the process used for requesting release of file prior to
3 | Airlock. New release requests should be made using [Airlock](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/index.md) wherever possible.
4 |
5 |
6 | ### Create a folder for outputs
7 |
8 | First, create one folder in your workspace called `release` (if you have previously made a release, we suggest appending the date to the new folder name to distinguish it) and copy from your `output` folder to this `release` folder the data files that require review. The number of study outputs requested for review must be kept to a minimum and include only the results you absolutely need to export from the secure server.
9 |
10 | ### Complete a output review request form
11 |
12 | When you are ready to request a release of your aggregated results please [complete this form](../documents/OpenSAFELY_Output_Review_Form_ADD_WORKSPACE_NAME_ADD_DATE.docx), renaming the form to replace the placeholders with your workspace name and the date.
13 |
14 | #### Context requirements
15 |
16 | For each output wishing to be released you will need to provide a clear contextual description including:
17 |
18 | 1. The file path for each output
19 | 2. Variable descriptions
20 | 3. A description and count of the underlying sample of the population for each output.
21 | 4. Population size and degrees of freedom for all regression outputs.
22 | 5. Relationship to other data/tables which through combination may introduce secondary disclosive risks.
23 |
24 | Each section in the review request form should normally describe a single file, but where necessary for similar files, these can be grouped together and wildcards can be used for the file path (e.g. `release/hospitalisation_rate_by_*.csv`). **If you use a wildcard, please indicate how many files this captures**.
25 |
26 | ### Checklist
27 |
28 | Please run through [the checklist](../outputs/requesting-file-release.md#checklist) before making a review request. In addition, check:
29 |
30 | 1. Are all of the outputs in a [separate release folder](#create-a-folder-for-outputs)?
31 | 1. Are all of the outputs clearly described?
32 | * Is the filename sensible and is the filepath provided in the request form correct?
33 | * Have you provided all of the context needed to review each output in isolation in the request form?
34 | * Have you described the disclosure controls you have applied to each output?
35 |
36 | ### Submitting the form
37 |
38 | Once you have completed this form, please send it to ****. The requested outputs will undergo independent review by two OpenSAFELY output checkers who will check that the outputs are within the scope of your original project proposal and that they do not present any disclosure risks. **Please allow up to 5 working days for feedback on your request**.
39 |
40 |
41 | ### Responding to requests
42 |
43 | Once reviewed, the completed review request will be emailed back to you. We aim to provide a response to review requests within **5 working days**. If all outputs are approved, they will then be released. If one or more outputs are approved subject to change, you will need to address the disclosure issues and submit a new review form detailing the changes you have made.
44 |
--------------------------------------------------------------------------------
/docs/legacy/study-def-codelists.md:
--------------------------------------------------------------------------------
1 | ---
2 | search:
3 | boost: 0.001
4 | ---
5 | ---8<-- 'includes/cohort-extractor-deprecated.md'
6 |
7 | A *Codelist* is a collection of clinical codes that classifies patients as having certain conditions or demographic properties. For example, in an clinical system, an asthma diagnosis may be indicated by [any of more than 100 codes](https://www.opencodelists.org/codelist/primis-covid19-vacc-uptake/ast/v1/#full-list).
8 |
9 | Codelists must be stored as data within your study repository, from where they can be used in your study definition.
10 |
11 | To help you create, edit, and manage codelists, OpenSAFELY provides a web-based tool called [OpenCodelists](https://www.opencodelists.org). For more information about how to create and edit codelists on the website, see the [codelists documentation](../codelist-intro.md).
12 |
13 | ## Pulling codelists into your study definition
14 |
15 | Many functions for defining variables take *codelists* as arguments.
16 |
17 | Codelists live as CSV files in the `codelists/` directory (see instructions in the [Adding codelists to a project](../codelist-project.md) page).
18 |
19 | Codelists are loaded into variables as follows:
20 |
21 | ```py
22 | chronic_cardiac_disease_codes = codelist_from_csv(
23 | "codelists/opensafely-chronic-cardiac-disease.csv", system="ctv3", column="CTV3ID"
24 | )
25 | ```
26 |
27 | You should put code that creates codelist variables before your `StudyDefinition()`, so it can refer to them, and users know where to look.
28 |
29 | You can do this in `analysis/study_definition.py`, but we recommend that you put all your codelist definitions into a file called `codelists.py` and importing it in at the top of your file:
30 |
31 | ```py
32 | from codelists import *
33 | ```
34 |
35 | This keeps it cleaner and easier to read.
36 |
37 | ## Combining codelists
38 |
39 | Codelists can be combined where appropriate.
40 | This has the advantage of keeping codeslists separate for some studies but easily combining them for others.
41 |
42 |
43 | Codelists can be combined using the `combine_codelist` function from `cohortextractor`, for example:
44 |
45 | ```py
46 | from cohortextractor import combine_codelists
47 |
48 | all_cardiac_disease_codes = combine_codelists(
49 | chronic_cardiac_disease_codes,
50 | acute_cardiac_disease_codes
51 | )
52 | ```
53 |
54 | ## Using a single code
55 |
56 | In some cases you may only want a variable to use a one or two codes, e.g you want to look at use of a single code within a codelist. You can create a codelist object directly as follows:
57 |
58 | ```py
59 | weight_codes = codelist(
60 | ["27113001", "162763007"], system="snomed"
61 | )
62 | ```
63 |
64 | Whilst you can pass this a list of codes of any length, we recommend building or using existing codelists on OpenCodelists for ease of discoverability and reproducibility.
65 |
--------------------------------------------------------------------------------
/docs/legacy/study-def-flowcharts.md:
--------------------------------------------------------------------------------
1 | ---
2 | search:
3 | boost: 0.001
4 | ---
5 | ---8<-- 'includes/cohort-extractor-deprecated.md'
6 |
7 | ## Flowcharts (temporary workaround)
8 |
9 | Many studies will require a flowchart to show inclusion/exclusion of patients in the study. Eventually the numbers of patients excluded/included will be summarised automatically following cohort extract, but for now, a slightly manual approach is required:
10 |
11 | - Make a copy of the study definition (called `study_definition_flow_chart.py`). The `population=patients.satisfying()` function should be replaced with `population=patients.all()`. Then all variables except for those that appeared in the population definition logic should be removed (this will mean that it runs much faster than the main study definition). An example of such a study definition can be seen in [this repository on NSAIDS use and COVID-related outcomes](https://github.com/opensafely/nsaids-covid-research/commit/e5ad58c72926d7c73ba131099486409f6876883d).
12 | - Then write a script that reads the `input_flow_chart.csv` and then sequentially drops each of the variables and counts the remaining population, in whatever order you'd like to report them; [Stata example](https://github.com/opensafely/nsaids-covid-research/blob/23069312944ea1fc6d79ec4d9b45eea25df96ab0/analysis/flowchart_numbers.do).
13 |
--------------------------------------------------------------------------------
/docs/level-4-server.md:
--------------------------------------------------------------------------------
1 | All outputs from OpenSAFELY pipelines are subject to [tiered levels of scrutiny](security-levels.md), to provide assurance that identifiable data is not leaked accidentally, or maliciously.
2 |
3 | The final tier is review of so-called "Level 4" outputs, where the OpenSAFELY framework stores outputs labelled as `moderately_sensitive` in the `project.yaml` file.
4 |
5 | If you have Level 4 access you can use [Airlock](outputs/viewing-with-airlock.md) to review your aggregated results and request files to be released.
6 |
7 |
8 | !!! note
9 |
10 | **Mac users**
11 |
12 | If intending to use a Mac for Level 4 access, please check your
13 | hardware is suitable first.
14 |
15 | Level 4 access requires a working Windows installation. Mac users
16 | with older *Intel* hardware have had success in accessing Level 4
17 | when running Windows in a virtual machine.
18 |
19 | However, Mac users with newer Macs that have *Apple* processors —
20 | for example, the M1 processor — can only run Windows in a virtual
21 | machine via the Windows on ARM release: **this configuration is
22 | currently incompatible with the client necessary for Level 4
23 | access.**
24 |
25 | Macs with Apple processors are still suitable for writing, testing
26 | and submitting OpenSAFELY code to be run on the secure server.
27 | **This issue only affects access to Level 4 server.**
28 |
29 | See [this support
30 | discussion](https://github.com/opensafely/documentation/discussions/251#discussioncomment-1767887)
31 | for a description of the problem.
32 |
--------------------------------------------------------------------------------
/docs/open-data-manifesto.md:
--------------------------------------------------------------------------------
1 |
2 | ## Better Data for the NHS
3 |
4 | Operational research is key to understanding what works in the NHS. However the methods and code used to carry out this research are rarely seen in public. Standards are variable. One-off point-and-click analytics are common. This living document aims to start a discussion about best practice for research and analysis using NHS data. Send us your feedback! [bennett@phc.ox.ac.uk](mailto:bennett@phc.ox.ac.uk)
5 |
6 | ### Publish everything
7 | * **Share** your methods and code, so other teams can review it and learn.
8 | * Permit other people to **re-use** your code and content.
9 | * Publish **imperfect** code fearlessly.
10 | * Work in public from the **start** where possible.
11 |
12 |
13 | ### Make collaboration easy
14 | * Use Jupyter notebooks or R Markdown to **tell a story** for generalists _and_ analysts.
15 | * Do the hard work to make it **easy** for others to run the code.
16 | * Use code **comments** to inform a technical audience.
17 | * **Document** key decisions alongside your code.
18 | * Maintain a single **repository** for each project, with a _README_.
19 | * Develop a **supportive** culture.
20 |
21 | ### Automate tasks with code where possible
22 | * Use **scripts**, not point-and-click tools.
23 | * Make **live** dashboards rather than occasional reports.
24 | * Turn recurring work into **libraries** and share them.
25 |
26 | ### Use coders' best practice
27 | * Do regular code **reviews**.
28 | * Use **version control**.
29 | * Write **tests** for your code.
30 | * Help develop and follow local **conventions** around coding.
31 |
--------------------------------------------------------------------------------
/docs/open-methods.md:
--------------------------------------------------------------------------------
1 |
2 | We are using modern open working methods to carry out important analyses whilst preserving patient privacy and keeping all patient data secure.
3 |
4 | ## What do we mean by Open Working Methods?
5 |
6 | We believe that researchers should be openly sharing all analytic cods and development insights in order to accelerate development of analyses and tools by other groups with other datasets.
7 |
8 | Our tools are build using Python, SQL and Docker. Analyses can be carried out in Python, R or Stata.
9 | All our code including analytic code is shared on GitHub and is open access for efficiency, reuse and collaboration.
10 | We encourage external review and reuse of our code.
11 |
--------------------------------------------------------------------------------
/docs/outputs/index.md:
--------------------------------------------------------------------------------
1 | ## Viewing research outputs
2 |
3 | - [Viewing outputs with Airlock](viewing-with-airlock.md)
4 |
5 |
6 | ## Releasing research outputs
7 |
8 | - [Overview](releasing-overview.md)
9 | - [Applying statistical disclosure control](sdc.md)
10 | - [Requesting release of research outputs](requesting-file-release.md)
11 | - [Review process for release requests](output-checking.md)
12 | - [Viewing released outputs](viewing-released-files.md)
13 |
14 | ## Using Airlock
15 | - [Using Airlock to view and releasing outputs](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/index.md)
16 |
--------------------------------------------------------------------------------
/docs/outputs/output-checking.md:
--------------------------------------------------------------------------------
1 | Before any files are released from the secure server, they are checked independently by two trained OpenSAFELY output checkers. Each checked output is marked as one of the following categories:
2 |
3 | * **Approve** — output meets disclosure requirements and is safe to be released
4 | * **Request changes** — output is an acceptable type for release, but has outstanding disclosure issues that must be addressed before release
5 | * **Reject** — output is not an acceptable type for release. An example is the release of practice level data which does not meet the [permitted study results policy](https://www.opensafely.org/policies-for-researchers/#permitted-study-results-policy)
6 |
7 | ### Responding to requests
8 | Requests submitted via Airlock will also be reviewed by output checkers on Airlock. If
9 | the output checkers require changes or have questions about the requested files, they
10 | will return the release request to you. You will receive an email notification when this happens.
11 |
12 | For further information on how to submit and respond to returned requests, please see the
13 | documentation on [releasing with Airlock](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/index.md).
14 |
15 | ### Most common problems with output review requests
16 |
17 | Below are the most common problems encountered by output checkers when reviewing output review requests. **Avoiding these issues makes it more likely your files can be released first time round**, saving reviewer time and allowing quicker file release for you and other researchers.
18 |
19 | 1. **There are unrounded counts in the outputs**. All counts should be [rounded](sdc.md#rounding-counts). This includes rounding counts prior to them being used to calculate further statistics, such as percentages or odds ratios. Commonly raw counts are rounded, but downstream statistics are calculated using the raw counts rather than the rounded counts. Unrounded counts account for **~30%** of rejections.
20 | 2. **Insufficicent context is provided for the outputs**. **~25%** of rejected outputs are due to insufficient context. Make sure you have provided all of the context needed to review each output in isolation in the request form. Common errors include:
21 | * Using unclear column/variable names or poorly describing the presented data. Refer to the [context requirements](requesting-file-release.md#context-and-controls).
22 | * Not clearly indicating the relationship between different outputs.
23 | * Where an output has previously been requested, not indicating how the output differs to previously reviewed version.
24 | 3. **There are unredacted counts in the outputs**. Prior to rounding counts, [any counts <=7 should be redacted](sdc.md#redacting-counts-less-than-or-equal-to-7). The redaction approach should be clearly described when making a review request. It is not uncommon for the stated redaction approach to be improperly implemented in the outputs. Inappropriate redaction of low counts accounts for **~20%** of rejected outputs.
25 | 4. **Underlying data is not provided**. To ensure the low number threshold is met, reviewers require to see the underlying data for each output. This includes the data used to generate figures and to calculate summary statistics such as mean or median. **~10%** of rejected outputs are due to underlying data not being provided.
26 | 5. **Unsupported file types being requested**. Files requested for release should be one of the [allowed file types](requesting-file-release.md#allowed-file-types). If you are requesting the release of HTML files, please make sure you have followed the [guidance for HTML files](requesting-file-release.md#allowed-file-types). **~10%** of rejected outputs are due to unsupported file types being requested. (Note: Airlock will automatically restrict output files in a request to only allowed file types.)
27 |
28 | To help avoid these issues, please make sure you have read the [checklist](requesting-file-release.md#checklist) before submitting your review request.
29 |
--------------------------------------------------------------------------------
/docs/outputs/releasing-overview.md:
--------------------------------------------------------------------------------
1 | OpenSAFELY follows the [Five Safes](../five-safes.md) framework for data access to allow safe and efficient use of data.
2 |
3 | The Five Safes are:
4 |
5 | - Safe projects
6 | - Safe people
7 | - Safe data
8 | - Safe settings
9 | - **Safe outputs**
10 |
11 | When we release files from the Level 4 server, we need to take particular care of the
12 | **Safe Outputs** dimension of the Five Safes framework, which assesses any residual risk of disclosure of patient information in outputs wishing to be released from the secure environment. This risk is minimised by researchers applying **statistical disclosure controls** to their research outputs, followed by **output checking** of these outputs by our team of trained output checkers.
13 |
14 | In OpenSAFELY, there are 4 key “Safe Outputs” activities:
15 |
16 | **1. [Apply Statistical disclosure controls](sdc.md)**
17 |
18 | Researchers must apply statistical disclosure controls to their research outputs.
19 |
20 | **2. [Requesting release of outputs](requesting-file-release.md)**
21 |
22 | Researchers must follow a defined procedure for requesting release of outputs from the Level 4 server. This includes:
23 |
24 | - only requesting release of files that are necessary to fulfil the purpose of a project
25 | - describing the context (why the files are requested for release) and statistical disclosure controls applied
26 | - restricting files to specific allowed types
27 | - limits on file size and number of rows in tables
28 | - Airlock, a dedicated OpenSAFELY tool for managing the release request and review process
29 |
30 | **3. [Output checking](output-checking.md)**
31 |
32 | Review of the requested outputs by two trained OpenSAFELY output checkers.
33 |
34 | **4. [Retricted viewing of released files](viewing-released-files.md)**
35 |
36 | Outputs that meet our disclosure rules and have undergone thorough output checking are
37 | released to the relevant workspace on the [Jobs site](../jobs-site.md). Viewing of
38 | released outputs is restricted to individuals with the relevant roles on the jobs
39 | site, and is not publicly accessible until outputs are published.
40 |
--------------------------------------------------------------------------------
/docs/outputs/viewing-released-files.md:
--------------------------------------------------------------------------------
1 | All approved OpenSAFELY outputs are released to the workspace they belong to on the [Jobs site](../jobs-site.md).
2 |
3 | ### Viewing released outputs
4 |
5 | View your released outputs by navigating to "Released Outputs" in the "Releases" section of your workspace on the Jobs site.
6 |
7 | These outputs can be shared with project collaborators and published in line with our [data sharing and publication policy](https://www.opensafely.org/policies-for-researchers/#acknowledgment-and-data-sharing--publication-policy). Please note that you should check this for each dataset that you have used: rules may vary.
8 |
9 | ### Running further analyses on released outputs
10 |
11 | If you have had [aggregated results released](requesting-file-release.md#release-of-aggregated-results-to-be-used-to-generate-final-outputs) and you wish to run further analyses on them, such as reformatting figures, there are a few things to consider.
12 |
13 | 1. You should include the code for these steps in your GitHub repo.
14 | 2. You **should not** commit any of the released outputs (including final processed charts/tables) to your GitHub repo. Make sure to include them in the `.gitignore` file.
15 | 3. Consider adding the code as an action in your project pipeline.
16 |
17 | ### Reporting a data breach
18 |
19 | If you discover files released to the Jobs site that have been insufficiently redacted and still contain sensitive information, you should immediately contact and email the following (providing as much information as possible): Amir Mehrkar (); Ben Goldacre (); [disclosurecontrol@opensafely.org](mailto:disclosurecontrol@opensafely.org); and your co-pilot. Ensure you do not share these files and if they have already been shared please identify as best as possible with whom they have been shared.
20 |
--------------------------------------------------------------------------------
/docs/outputs/viewing-with-airlock.md:
--------------------------------------------------------------------------------
1 | Research outputs and log files can be viewed from within the
2 | secure environment using Airlock.
3 |
4 | The [Airlock documentation](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/index.md) provides information on how to
5 | [log in](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/how-tos/access-airlock.md) to Airlock and how to [view moderately sensitive workspace outputs](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/how-tos/view-workspace-files.md).
6 |
7 | ## Log files
8 |
9 | In addition to workspace output files, you can also view log
10 | files from your jobs on Airlock (including logs from failed
11 | jobs).
12 |
13 | To view log files, [navigate to your workspace](../using-opensafely/viewing-and-releasing-outputs/viewing-and-releasing-with-airlock/how-tos/view-workspace-files.md) in Airlock.
14 | Log files are found in the `metadata/` folder in your workspace,
15 | and are named with the name of the action from the `project.yaml` file.
16 |
--------------------------------------------------------------------------------
/docs/paper_template.txt:
--------------------------------------------------------------------------------
1 | ---
2 | # the full paper title, but remove any extra subtitles added by the journal
3 | title: "Computing and statistics in the eighteenth century"
4 |
5 | # the date the paper was published on the journal's website
6 | date: "1850-06-24"
7 |
8 | # List of authors
9 | authors:
10 | - Ada Lovelace # Enter each authors full name in plain text
11 | - Florence Nightingale # One author per line
12 |
13 | # List of categories
14 | categories:
15 | - OpenSAFELY # Enter each category name in plain text
16 | - OpenPrescribing # One category per line
17 |
18 | # Full citation for the paper - this can usually be obtained from the online version of the paper or from a reference manager
19 | citation: "Lovelace A, Nightingale F. Computing and statistics in the eighteenth century: a Primer. Journal of Theory and Practice, XX(x)X.123 1850"
20 |
21 | # A short description that will display under the paper title across the
22 | # Bennett website and when the link is shared
23 | # For examples see https://www.opensafely.org/research/
24 | description: "This paper investigated..."
25 |
26 | # the DOI identifier for the paper *after* the `https://doi.org/`
27 | doi: "10.1111/ABC(12).16030"
28 |
29 | # Paper details from the journal, if published
30 | paper:
31 | # the full title as it is displayed on the journal website
32 | title: "Computing and statistics in the eighteenth century: A Primer"
33 | # the name of the journal if the paper is published
34 | journal: "Journal of Theory and Practice"
35 |
36 | # If the paper is now published, enter information of the preprint version of the paper
37 | preprint:
38 | title: "Computing and statistics in the eighteenth century" # Preprint title
39 | doi: "abc-101232" # Preprint DOI
40 | link: https://www.preprintserver.com/abc123 # Link to preprint version of the paper
41 |
42 | # If the paper used OpenSAFELY, it should be linked to a project and repo
43 | opensafely:
44 | project: 123 # the project number from the Approved Projects page - see https://www.opensafely.org/approved-projects/
45 | repo: "test-repo" # the name of the repo in the github.com/opensafely org
46 |
47 | # The slug is the second part of the url after the
48 | # The slug should match the DOI, but with the following amendments:
49 | # - If the DOI has brackets in it, remove them from the slug
50 | # - If the DOI has upper case characters, replace them with lowercase
51 | # For example, a DOI of the form "10.1111/ABC(12).16030", becomes "10.1111/abc12.16030"
52 | slug: "10.1111/abc12.16030"
53 |
54 | # Set the status of the paper to "preprint" or "published"
55 | status: "published"
56 |
57 | ---
58 |
59 | ## Markdown-formatted abstract goes here!
60 |
--------------------------------------------------------------------------------
/docs/plan-s.md:
--------------------------------------------------------------------------------
1 | ### Academic Journal Destination: Plan S and OpenSAFELY
2 |
3 | [Plan S](https://www.coalition-s.org/) is an initiative for Open Access publishing. Plan S requires that scientific publications that result from research funded by public grants must be published in compliant Open Access journals or platforms. Wellcome are a core funder of the OpenSAFELY platform, therefore we ask that academic outputs comply with Wellcome's Plan S requirements for journal publication. It is likely that teams will be required to comply with this for other reasons, such as receiving funding from NIHR / UKRI. For further details see [openaccess.ox.ac.uk/wellcome](https://openaccess.ox.ac.uk/wellcome).
4 |
5 | ### How do I check journal open access compliance?
6 |
7 | Before you submit a paper to a journal, please check open access arrangements.
8 |
9 | [journalcheckertool.org](https://journalcheckertool.org) is our recommended tool for checking journal compliance.
10 |
11 | If you have any questions, please ask your co-pilot and post in the `#opensafely-users` slack channel.
12 |
--------------------------------------------------------------------------------
/docs/project-changes.md:
--------------------------------------------------------------------------------
1 | **Here is some information about the new process for telling us about changes to your project:**
2 |
3 | **Project Update Form**
4 |
5 | When leaving your research position or if you are ending a project, a step by step guide for handing over a **‘single’** OpenSAFELY project will need to be adhered to by completing a [Project Update Form](https://docs.google.com/document/d/1WqABEzk6sfmjO1Fyekj55aChwaVm6qHDw5A1QgR7R84/edit). Completion of this form is required for any project that meets any of the following circumstances:
6 |
7 | 1. **One or more researchers are leaving their research position at their home institution.**
8 | 1. **One or more roles within the project need to be handed over (i.e study lead, researcher, etc,.)**
9 | 1. **The project can no longer continue i.e the project needs to be either postponed, or retired.**
10 | 1. **The project is completed.**
11 |
12 | This form must be returned by the Study Lead. If you are not the study lead, this form must be completed in collaboration with them (or as a minimum review by). For any questions that arise while filling in this form, researchers are advised to contact their Co-pilot in the first instance, or the OpenSAFELY Research Administrator via the applications inbox applications@opensafely.org.
13 |
--------------------------------------------------------------------------------
/docs/protocol.md:
--------------------------------------------------------------------------------
1 | ## Pre-specifying your Research Question and Writing a Study Protocol
2 |
3 | !!! note
4 | This section is a work in progress, and will be further developed.
5 |
6 | Briefly, pre-specifying your research question and developing a study protocol which outlines your planned methodology is an important open science principle. Doing so can help reduce 'researcher degrees of freedom', and in turn minimise the risk for questionable research practices (such as ["hypothesising after the results are known" (HARKing)](https://en.wikipedia.org/wiki/HARKing) or [p-hacking](https://en.wikipedia.org/wiki/Data_dredging)).
7 |
8 | Taken together, this can improve both the quality and credibility of your research. Developing a detailed study plan, including figure and table shells, can be particularly helpful when using a federated analytics platform such as OpenSAFELY, as there is less scope for interactively developing these whilst working with the data.
9 |
10 | This page will eventually contain resources for how to develop an effective study protocol, as well as tips for how to pre-register these formally on [OSF](https://osf.io/) or [ENCePP](http://www.encepp.eu/), or informally by uploading "locked" protocol versions to GitHub. There is no specific template for a protocol that you should use when working with OpenSAFELY, but you can see examples of protocols we've written for OpenSAFELY studies on most of our public repositories — for example [this inhaled corticosteroid (ICS) research repository](https://github.com/opensafely/ics-research/tree/master/protocol) or [this ethnicity research repository](https://github.com/opensafely/ethnicity-covid-research/tree/master/protocol).
11 |
--------------------------------------------------------------------------------
/docs/reports/create-a-draft.md:
--------------------------------------------------------------------------------
1 |
2 | ## Create a draft report
3 | After logging into the [administration area](https://reports.opensafely.org/admin/) click "Add" next to Reports:
4 |
5 | 
6 |
7 | ### Organisation
8 | Select your organisation from the list.
9 | If it's missing from the list, please [contact us](../how-to-get-help.md).
10 |
11 |
12 | ### Navigation
13 | Pick the `Category` you want to host your report under in the side nav of the site.
14 |
15 | Then set a `Menu name`.
16 |
17 |
18 | ### Report file details (GitHub)
19 | !!! note
20 | It was previously possible to release outputs to GitHub and the reports site was originally built to use those outputs.
21 | OpenSAFELY has moved away from this method and all outputs are now released to the jobs site.
22 | Please make sure to use the jobs site field in this form for your output location instead of the GitHub ones.
23 |
24 |
25 | ### Report file details (Jobs site)
26 | Find your workspace on [the jobs site](https://jobs.opensafely.org).
27 | Click `Released Outputs` to view the most recent version of each of your released outputs:
28 |
29 | 
30 |
31 | Select the file you want to make your report with from the list on the left, and copy the direct URL which shows at the top of the file viewer. This is the URL you will need in the reports admin.
32 |
33 | 
34 |
35 |
36 | ### Front matter
37 | These fields are displayed above your report on the site.
38 |
39 |
40 | ### DOI
41 | Fill this in after you have published your report.
42 |
43 |
44 | ### Visibility
45 | `Is draft` will be ticked by default.
46 | Reports should start as drafts so they are private before being reviewed.
47 |
48 |
49 | ### External
50 | If you are creating a report from an external organisation, then you should fill in this section to explain why the report is being hosted on the OpenSAFELY platform.
51 |
52 |
53 | ### Related links
54 | You should also add a link to the source code on GitHub which generated the outputs your report is built around.
55 |
56 | If the report has an associated paper, preprint or blog, ensure their links are added.
57 |
58 |
59 | ## Next step
60 | [Have your report reviewed](./review-process.md).
61 |
--------------------------------------------------------------------------------
/docs/reports/images/job-server-direct-output-file-link-published.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/docs/reports/images/job-server-direct-output-file-link-published.jpg
--------------------------------------------------------------------------------
/docs/reports/images/job-server-direct-output-file-link-release.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/docs/reports/images/job-server-direct-output-file-link-release.jpg
--------------------------------------------------------------------------------
/docs/reports/images/job-server-published-outputs.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/docs/reports/images/job-server-published-outputs.jpg
--------------------------------------------------------------------------------
/docs/reports/images/job-server-workspace-latest-outputs.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/docs/reports/images/job-server-workspace-latest-outputs.jpg
--------------------------------------------------------------------------------
/docs/reports/images/reports-admin-add-report.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/docs/reports/images/reports-admin-add-report.jpg
--------------------------------------------------------------------------------
/docs/reports/publish-a-report.md:
--------------------------------------------------------------------------------
1 | The report you've created so far is only a draft.
2 | Edit your report and complete the steps below to make it available for public viewing.
3 |
4 | ## Switch to a published outputs
5 | Published reports require the output they're based on to also be published.
6 |
7 | Follow [the instructions on publishing your output](../jobs-site.md#publishing-outputs).
8 |
9 | Select a set of published outputs from the list:
10 | 
11 |
12 | !!! note
13 | Published outputs can be in a draft status while they are being reviewed.
14 | A badge saying "published" will be displayed next to those which have moved out of that state.
15 |
16 | Select the file you want to use for your report from the list on the left, and copy the direct URL which shows at the top of the file viewer.
17 |
18 | 
19 |
20 | Replace the `Job server url` you currently have with this URL.you will need in the reports admin.
21 |
22 |
23 | ## Create a DOI
24 | All published reports should have a DOI.
25 | You will need your own [CrossRef user credentials](https://www.crossref.org/documentation/member-setup/account-credentials/) in order to register DOIs.
26 |
27 | How to create and add a DOI:
28 |
29 | 1. Make sure your report is published and not still draft. (CrossRef requires that all DOIs link to a landing page which is publicly accessible.)
30 | 2. Find the suggested DOI on the admin page for your report.
31 | 3. Go to the [CrossRef Web Deposit page](https://apps.crossref.org/webDeposit/) and fill in the basic information:
32 | - select `Report` as the Data Type.
33 | - Enter the suggested DOI from your report, prefixed with our organisation code: `10.53764/xxxxxxxxxxxx`.
34 | - Add the URL for the report.
35 | - `OpenSAFELY` as Publisher.
36 | - Authors have to be added one-by-one so you may wish to use `The OpenSAFELY Collaborative` in place of some or all authors, if appropriate.
37 | - Use the report's first publication date as the `online` publication date (`Print` publication date can be left blank).
38 | 4. Submit DOI, you'll then be prompted for your login credentials and then your/an email address.
39 | 5. Enter the DOI URL in the `DOI` field (`https://doi.org/10.53764/xxxxxxxxxxxx`)
40 |
41 | See the [Crossref documentation](https://www.crossref.org/documentation/member-setup/web-deposit-form/) for more information.
42 |
43 |
44 | ## Publish your report
45 | Untick the `Is draft` check box and click Save.
46 |
47 | Your report has now been published and will be visible to the public on the reports site.
48 |
--------------------------------------------------------------------------------
/docs/reports/review-process.md:
--------------------------------------------------------------------------------
1 | When you are ready to publish your report, several steps should be followed:
2 |
3 | * It must be checked by NHSE (may simply reference the corresponding paper where applicable). Contact [publications@opensafely.org](mailto:publications@opensafely.org).
4 | * Send your report to your co-pilot so they can review it.
5 | * Make sure the linked code repository is also public and has gone through the [checking process](../project-completion.md).
6 |
7 |
8 | ## Next step
9 | [Publish your report](./publish-a-report.md)
10 |
--------------------------------------------------------------------------------
/docs/system-integration.md:
--------------------------------------------------------------------------------
1 | !!! warning
2 |
3 | These notes are a work-in-progress.
4 | This page provides an overview as guidance only,
5 | and not a series of definite instructions.
6 | We plan to further expand on this information.
7 |
8 | ## Audience
9 |
10 | This page is aimed at people who want to run their own installation of OpenSAFELY
11 | as a proof-of-concept trial prior to integrating into the live system.
12 |
13 | These people are likely to have one of the following professional roles:
14 |
15 | * software developers
16 | * clinical data providers
17 | * system integrators
18 |
19 | ### Assumed knowledge
20 |
21 | It is taken that you have some familiarity with OpenSAFELY.
22 |
23 | If not, you should first refer to:
24 |
25 | * [this general overview of OpenSAFELY](https://www.opensafely.org/about/)
26 | * [the typical researcher workflow](workflow.md)
27 | * [the introductory tutorial](getting-started/tutorial/index.md)
28 |
29 | ## Software components
30 |
31 | The [OpenSAFELY technical architecture diagram](technical-architecture.md) shows all of the platform software components
32 | and how they interact.
33 |
34 | The specific steps required to create a minimal setup are:
35 |
36 | 1. Deploy a [*job runner*](https://github.com/opensafely-core/job-runner) within your secure environment.
37 | A minimal configuration simply runs Docker containers
38 | and stores any resulting container output on a local disk.
39 |
40 | 2. Deploy a [*job server*](https://github.com/opensafely-core/job-server)
41 | that the *job runner* polls for jobs that end users request to be run.
42 |
43 | It is possible to use our existing instance of this server at our [*jobs site*](https://jobs.opensafely.org);
44 | [contact us](how-to-get-help.md#data-providers)
45 | if you would like us to configure this for you.
46 |
47 | 3. Create a secure network with our [*GitHub proxy*](https://github.com/opensafely-core/proxy).
48 | This provides access to repositories with research study code to run
49 | and Docker images used to run the code.
50 |
51 | 4. To provide *access to your database* from within your setup,
52 | integrate into our [*ehrQL*](https://github.com/opensafely-core/ehrql) ETL tool:
53 |
54 | * via an implementation of a backend interface; [this is an example for TPP](https://github.com/opensafely-core/ehrql/blob/main/ehrql/backends/tpp.py)
55 | * and, if you are using an as-yet unsupported database, a query engine; [this is an example for Trino](https://github.com/opensafely-core/ehrql/blob/main/ehrql/query_engines/trino.py)
56 |
57 | 5. *Releasing job outputs* requires:
58 |
59 | * the [*release-hatch*](https://github.com/opensafely-core/release-hatch) tool for reviewing outputs
60 | * the [*output-publisher*](https://github.com/opensafely-core/output-publisher) tool for publishing outputs
61 |
62 | ### Deployment
63 |
64 | We use Ubuntu in our deployments.
65 | Our deployments use [deploy scripts](https://github.com/opensafely-core/backend-server)
66 | that you can refer to.
67 |
68 | ## Support
69 |
70 | See our [support page](how-to-get-help.md#data-providers)
71 | for details of how to get more assistance on integration.
72 |
--------------------------------------------------------------------------------
/docs/technical-architecture.md:
--------------------------------------------------------------------------------
1 |
2 | This shows the architecture of OpenSAFELY. It is intended for a more technical audience.
3 |
4 | ## System context
5 |
6 | How OpenSAFELY fits into the wider world.
7 |
8 | 
9 |
10 | ## Container diagram
11 |
12 | This shows the high-level technical building blocks of the system.
13 |
14 | [](./images/c4-container.svg)
15 |
--------------------------------------------------------------------------------
/docs/updating-the-docs.md:
--------------------------------------------------------------------------------
1 | OpenSAFELY is a rapidly changing platform and the user documentation should be updated frequently to keep pace.
2 | If you are an OpenSAFELY user and want to contribute corrections, clarifications, or new materials to the documentation, please do!
3 | You can either:
4 |
5 | * Suggest improvements in an [issue](https://github.com/opensafely/documentation/issues).
6 | * Run the documentation [in GitHub Codespaces](#running-in-github-codespaces) for editing.
7 | * Clone [the repo](https://github.com/opensafely/documentation) locally, make edits on a new branch, then create a pull request for it.
8 | * [Edit directly on GitHub](https://github.com/opensafely/documentation/tree/main/docs) ([instructions](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository)), making sure to "Create a new branch for this commit and start a pull request".
9 |
10 | Do not commit changes directly to the main branch.
11 |
12 | ## Running in GitHub Codespaces
13 |
14 | Clicking the button below will open a codespace
15 | that allows you to run and edit the site.
16 |
17 | [](https://codespaces.new/opensafely/documentation)
18 |
19 | When you see "Your application running on port 8910 is available",
20 | you can click "Open in Browser" to see a preview,
21 | and edit the content files in `docs/` to change the content.
22 | It may take a few seconds for changes you make to appear.
23 |
24 | ## Documentation style
25 |
26 | When adding or revising text, use [Semantic Line Breaks](https://sembr.org/) rather than fixed length lines.
27 | With semantic line breaks, the diff is more concise and easier to interpret than with fixed length lines,
28 | where a single change can propagate through a whole paragraph.
29 |
--------------------------------------------------------------------------------
/docs/workflow.md:
--------------------------------------------------------------------------------
1 | This section introduces the typical OpenSAFELY workflow for a single research project.
2 |
3 | The workflow consists of a number of key steps which may be iterated over as the code is developed and the study evolves.
4 | The following assumes that a well-defined and ethically-approved research agenda has been specified, with an accompanying study protocol, and all necessary permissions for accessing the OpenSAFELY platform are in place.
5 |
6 | The workflow for a single study can typically be broken down into the following steps:
7 |
8 | 1. **Create a git repository** from the [template repository provided](https://github.com/opensafely/research-template) and clone it on your local machine.
9 | This repo will contain all the code relating to your project, and a history of its development over time.
10 | 2. **Write a [dataset definition](ehrql/index.md)** that specifies what data you want to extract from the database:
11 | - specify the patient population (dataset rows) and variables (dataset columns)
12 | - specify the expected distributions of these variables for use in dummy data
13 | - specify (or create) the [codelists](codelist-intro.md) required by the dataset definition, hosted by [OpenCodelists](https://www.opencodelists.org), and import them to the repo.
14 | 3. **Generate [dummy data](ehrql/how-to/dummy-data.md)** based on the dataset definition, for writing and testing code.
15 | 4. **Develop analysis scripts** using the dummy data in R, Stata, or Python. This will include:
16 | - importing and processing the dataset(s) created by the dataset definition
17 | - importing any other external files needed for analysis
18 | - generating analysis outputs like tables and figures
19 | - generating log files to debug the scripts when they run on the real data.
20 | 5. **Test the code** by running the analysis steps specified in the [_project pipeline_](actions-pipelines.md), which specifies the execution order for data extracts and analyses and the outputs to be released.
21 | 6. **Execute the analysis on the real data** via OpenSAFELY's [jobs site](jobs-site.md). This will generate outputs on the secure server.
22 | 7. **Check the output for [disclosivity](outputs/sdc.md)** within the server, and redact if necessary.
23 | 8. **[Request release](outputs/requesting-file-release.md) of the outputs**
24 | 9. **Repeat and iterate steps 2 to 8 as necessary**.
25 |
26 | These steps should always proceed with frequent git commits and code reviews where appropriate. Steps 2-5 can all be progressed on your local machine without accessing the real data.
27 |
28 | It is possible to automatically test that the analytical pipeline defined in step 5 can be successfully executed on dummy data, using the `opensafely run` command.
29 | This pipeline is also [automatically tested](actions-pipelines.md#running-your-code-with-github-actions) against dummy data every time a new version of the study repository is saved ("pushed") to GitHub.
30 |
31 | As well as your own Python, R or Stata scripts, other non-standard actions are available.
32 | For example, it's possible to run a matching routine that extracts a matched control population to the population defined in the dataset definition, without having to extract all candidate matches into a dataset first.
33 |
--------------------------------------------------------------------------------
/hooks/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/opensafely/documentation/afe23da1bcde0212b2d7bd0785fad7346c33928c/hooks/__init__.py
--------------------------------------------------------------------------------
/hooks/ehrql_branch.py:
--------------------------------------------------------------------------------
1 | import logging
2 |
3 | import mkdocs.plugins
4 |
5 |
6 | log = logging.getLogger("mkdocs")
7 |
8 |
9 | @mkdocs.plugins.event_priority(100)
10 | def on_config(config):
11 | """
12 | Update config with specified ehrQL branch
13 | This is done first, before any imported repos are processed, or nav sections
14 | hidden.
15 | """
16 | ehrql_branch = config["extra"]["ehrql_branch"]
17 | if ehrql_branch == "main":
18 | return config
19 | ehrql_nav_index, ehrql_nav_section = next(
20 | (i, section)
21 | for i, section in enumerate(config["nav"])
22 | if list(section.keys())[0] == "ehrQL"
23 | )
24 | new_import_string = ehrql_nav_section["ehrQL"].replace(
25 | "branch=main", f"branch={ehrql_branch}"
26 | )
27 | config["nav"][ehrql_nav_index] = {"ehrQL": new_import_string}
28 |
29 | log.info("ehrQL docs imported from branch '%s'", ehrql_branch)
30 | return config
31 |
--------------------------------------------------------------------------------
/hooks/ehrql_css.py:
--------------------------------------------------------------------------------
1 | import logging
2 | import pathlib
3 |
4 | from mkdocs.structure.files import File
5 |
6 |
7 | log = logging.getLogger("mkdocs")
8 |
9 |
10 | def on_files(files, config, **kwargs):
11 | """
12 | Update files available to MkDocs with ehrQL documentation CSS.
13 |
14 | This hook is necessary because
15 | * paths provided to `extra_css` must be in the `docs_dir` directory
16 | (the default being `docs/`)
17 | * the multi-repo plugin pulls in the ehrQL docs to a different path,
18 | outside of `docs/`
19 |
20 | This approach is one of the suggested workarounds in:
21 | https://github.com/mkdocs/mkdocs/issues/1662
22 | """
23 | for css_config_entry in config["extra"]["ehrql_imported_css"]:
24 | css_path = pathlib.Path(css_config_entry)
25 |
26 | # This MkDocs API is not well documented anywhere.
27 | # We want to create a MkDocs File object:
28 | # whose source is the `src_dir` concatenated to the ehrQL CSS path
29 | # whose destination is an appropriate CSS directory in the `site_dir`.
30 | # `use_directory_urls` only affects Markdown files, and this is a CSS file.
31 | css_file = File(
32 | path=css_path,
33 | src_dir=config["docs_dir"] + "/../",
34 | dest_dir=config["site_dir"] + "/css",
35 | use_directory_urls=False,
36 | )
37 | log.info("ehrQL CSS imported from '%s'", css_path)
38 | files.append(css_file)
39 | return files
40 |
--------------------------------------------------------------------------------
/hooks/parent_snippets.py:
--------------------------------------------------------------------------------
1 | def on_page_markdown(markdown, page, **kwargs):
2 | """
3 | Replace parent_snippet markers from imported repos with appropriate snippet notation
4 |
5 | on_page_* methods are called for each Page in a mkdocs site and can modify the
6 | markdown they are given as input. We're using this method to look for the
7 | parent_includes markers in pages that come from an imported repo, and replace it
8 | with the pymdownx.snippets syntax to retrieve the snippet from this (the parent
9 | repo).
10 |
11 | For example:
12 | !!! parent_snippet:'includes/glossary.md'
13 |
14 | will be replaced with:
15 | ---8<-- 'includes/glossary.md'
16 |
17 | This allows docs imported from other repos (e.g. ehrQL) to reference snippets
18 | in the parent docs, such as the glossary.
19 | """
20 |
21 | return markdown.replace("!!! parent_snippet:", "---8<-- ")
22 |
--------------------------------------------------------------------------------
/includes/cohort-extractor-deprecated.md:
--------------------------------------------------------------------------------
1 | !!! warning
2 | cohort-extractor is now deprecated.
3 | All new projects should use [ehrQL](../ehrql/index.md) to extract data from an OpenSAFELY database.
4 |
--------------------------------------------------------------------------------
/includes/imd-warning-header.md:
--------------------------------------------------------------------------------
1 | !!! warning
2 | The original IMD ranking is rounded to the nearest 100 in the OpenSAFELY-TPP and OpenSAFELY-EMIS databases.
3 | The rounded IMD ranking ranges from 0 to 32,800.
4 | If there is no original ranking, then the rounded ranking is -1 in the OpenSAFELY-TPP database and `NULL` in the OpenSAFELY-EMIS database.
5 |
6 | !!! warning
7 | Avoid extracting the rounded IMD ranking to a binary format, such as `.feather` or `.dta`.
8 | Either nest it within a variable,
9 | such as when [grouping rounded IMD by quintile](https://docs.opensafely.org/legacy/study-def-tricks/#grouping-imd-by-quintile),
10 | or extract it to a non-binary format, such as `.csv.gz`.
11 |
--------------------------------------------------------------------------------
/includes/isaric-warning-header.md:
--------------------------------------------------------------------------------
1 | !!! warning
2 | ISARIC data can only be used in collaboration with ISARIC researchers who must be involved in working on the study and writing it up.
3 |
4 | Please contact your co-pilot, or if you have any questions.
5 |
--------------------------------------------------------------------------------
/includes/vmp-ids-warning.md:
--------------------------------------------------------------------------------
1 | !!! warning
2 | dm+d codes for Virtual Medicinal Products (VMPs) can change.
3 | cohort-extractor handles this by automatically expanding a medication codelist
4 | to include all current and previous codes of any VMPs in the codelist.
5 | However, this means that when a VMP code has changed, a query using
6 | `patients.with_these_medications(codelist, returning="code", ...)`
7 | might return a code that is not in the provided codelist.
8 |
--------------------------------------------------------------------------------
/justfile:
--------------------------------------------------------------------------------
1 | # just has no idiom for setting a default value for an environment variable
2 | # so we shell out, as we need VIRTUAL_ENV in the justfile environment
3 | export VIRTUAL_ENV := `echo ${VIRTUAL_ENV:-.venv}`
4 |
5 | # TODO: make it /scripts on windows?
6 | export BIN := VIRTUAL_ENV + "/bin"
7 | export PATH := env_var('PATH') + ":" + justfile_directory() + "/" + BIN
8 | export PIP := BIN + "/python -m pip"
9 | # enforce our chosen pip compile flags
10 | export COMPILE := BIN + "/pip-compile --allow-unsafe --generate-hashes"
11 |
12 |
13 | # list available commands
14 | default:
15 | @{{ just_executable() }} --list
16 |
17 |
18 | # clean up temporary files
19 | clean:
20 | rm -rf .venv
21 |
22 |
23 | # ensure valid virtualenv
24 | virtualenv:
25 | #!/usr/bin/env bash
26 | set -euo pipefail
27 |
28 | # allow users to specify python version in .env
29 | PYTHON_VERSION=${PYTHON_VERSION:-python3.11}
30 |
31 | # create venv and upgrade pip
32 | test -d $VIRTUAL_ENV || { $PYTHON_VERSION -m venv $VIRTUAL_ENV && $PIP install --upgrade pip; }
33 |
34 | # ensure we have pip-tools so we can run pip-compile
35 | test -e $BIN/pip-compile || $PIP install pip-tools
36 |
37 |
38 | _compile src dst *args: virtualenv
39 | #!/usr/bin/env bash
40 | set -euo pipefail
41 |
42 | # exit if src file is older than dst file (-nt = 'newer than', but we negate with || to avoid error exit code)
43 | test "${FORCE:-}" = "true" -o {{ src }} -nt {{ dst }} || exit 0
44 | $BIN/pip-compile --allow-unsafe --generate-hashes --output-file={{ dst }} {{ src }} {{ args }}
45 |
46 |
47 | # update requirements.prod.txt if requirements.prod.in has changed
48 | requirements-prod *args:
49 | {{ just_executable() }} _compile requirements.prod.in requirements.prod.txt {{ args }}
50 |
51 |
52 | # update requirements.dev.txt if requirements.dev.in has changed
53 | requirements-dev *args: requirements-prod
54 | {{ just_executable() }} _compile requirements.dev.in requirements.dev.txt {{ args }}
55 |
56 |
57 | # ensure prod requirements installed and up to date
58 | prodenv: requirements-prod fetch-cohort-extractor
59 | #!/usr/bin/env bash
60 | set -euo pipefail
61 |
62 | # exit if .txt file has not changed since we installed them (-nt == "newer than', but we negate with || to avoid error exit code)
63 | test requirements.prod.txt -nt $VIRTUAL_ENV/.prod || exit 0
64 |
65 | $PIP install -r requirements.prod.txt
66 | touch $VIRTUAL_ENV/.prod
67 |
68 |
69 | # && dependencies are run after the recipe has run. Needs just>=0.9.9. This is
70 | # a killer feature over Makefiles.
71 | #
72 | # ensure dev requirements installed and up to date
73 | devenv: prodenv requirements-dev && install-precommit
74 | #!/usr/bin/env bash
75 | set -euo pipefail
76 |
77 | # exit if .txt file has not changed since we installed them (-nt == "newer than', but we negate with || to avoid error exit code)
78 | test requirements.dev.txt -nt $VIRTUAL_ENV/.dev || exit 0
79 |
80 | $PIP install -r requirements.dev.txt
81 | touch $VIRTUAL_ENV/.dev
82 |
83 |
84 | # ensure precommit is installed
85 | install-precommit:
86 | #!/usr/bin/env bash
87 | set -euo pipefail
88 |
89 | BASE_DIR=$(git rev-parse --show-toplevel)
90 | test -f $BASE_DIR/.git/hooks/pre-commit || $BIN/pre-commit install
91 |
92 |
93 | # upgrade dev or prod dependencies (specify package to upgrade single package, all by default)
94 | upgrade env package="": virtualenv
95 | #!/usr/bin/env bash
96 | set -euo pipefail
97 |
98 | opts="--upgrade"
99 | test -z "{{ package }}" || opts="--upgrade-package {{ package }}"
100 | FORCE=true {{ just_executable() }} requirements-{{ env }} $opts
101 |
102 | # Fetch cohort-extractor submodule
103 | fetch-cohort-extractor:
104 | git submodule update --init
105 |
106 | # Update cohort-extractor submodule
107 | update-cohort-extractor:
108 | git submodule update --remote src/cohort-extractor
109 |
110 | # Requires Vale: https://github.com/errata-ai/vale
111 | lint-docs:
112 | vale ./docs
113 |
114 | # Run the tests
115 | test: devenv
116 | echo "Not implemented here"
117 |
118 |
119 | format *args=".": devenv
120 | $BIN/ruff format --check {{ args }}
121 |
122 | lint *args=".": devenv
123 | $BIN/ruff check {{ args }}
124 |
125 | # run the various dev checks but does not change any files
126 | check: format lint
127 |
128 |
129 | # fix formatting and import sort ordering
130 | fix: devenv
131 | $BIN/ruff check --fix .
132 | $BIN/ruff format .
133 |
134 | # Run the dev project
135 | run: devenv
136 | $BIN/mkdocs serve -a localhost:8910
137 |
138 | # Build the documentation
139 | build: devenv
140 | $BIN/mkdocs build
141 |
142 | # Count words in generated documentation content (within tags)
143 | wordcount: build
144 | #!/usr/bin/env bash
145 | set -euo pipefail
146 | find site/ -name '*.html' -exec python scripts/wordcount.py {} + | awk '{sum += $1} END {print "Total words in documentation:", sum}'
147 |
--------------------------------------------------------------------------------
/main.py:
--------------------------------------------------------------------------------
1 | def define_env(env):
2 | "Hook function"
3 |
4 | @env.macro
5 | def build_toc(nav, page):
6 | """
7 | Build a nested list of page links from a navigation section index, to be inserted into the index page itself
8 | """
9 | assert page.is_index, (
10 | "`build_toc` macro is only available for navigation index pages"
11 | )
12 | parent_section = page.parent
13 | links = [make_link(item) for item in parent_section.children if item != page]
14 | html = f"{''.join(links)}
"
15 | return html
16 |
17 |
18 | def make_link(item):
19 | """
20 | Create the html list links for a nav item
21 | `item` may be a Section or a Page
22 | """
23 | if item.is_page:
24 | # Note that we prepend / so the URL extracted from the navigation is relative to the
25 | # root, and not to the location of this index page. This means we can deal with nested
26 | # nav links from any point in the document structure
27 | return f"{item.title} "
28 | else:
29 | items = [make_link(sub_item) for sub_item in item.children]
30 | return f"{item.title}{''.join(items)}
"
31 |
--------------------------------------------------------------------------------
/overrides/main.html:
--------------------------------------------------------------------------------
1 | {% extends "base.html" %}
2 |
3 | {% block fonts %}
4 |
5 |
6 |
11 |
12 |
18 |
19 |
25 | {% endblock %}
26 |
--------------------------------------------------------------------------------
/overrides/partials/integrations/analytics/plausible.html:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
1 | [project]
2 | name = "documentation"
3 | requires-python = ">=3.11"
4 |
5 | [tool.ruff]
6 | line-length = 88
7 | exclude = [
8 | ".direnv",
9 | ".git",
10 | ".github",
11 | ".ipynb_checkpoints",
12 | ".pytest_cache",
13 | ".venv",
14 | "__pycache__",
15 | "docker",
16 | "htmlcov",
17 | "venv",
18 | "src/cohort-extractor",
19 | ]
20 |
21 | [tool.ruff.lint]
22 | extend-select = [
23 | "A", # flake8-builtins
24 | "I", # isort
25 | "INP", # flake8-no-pep420
26 | "ISC", # flake8-implicit-str-concat
27 | "UP", # pyupgrade
28 | "W", # pycodestyle warning
29 | ]
30 | extend-ignore = [
31 | "E501",
32 | "E731",
33 | ]
34 |
35 | [tool.ruff.lint.isort]
36 | lines-after-imports = 2
37 |
--------------------------------------------------------------------------------
/requirements.dev.in:
--------------------------------------------------------------------------------
1 | --constraint requirements.prod.txt
2 |
3 | # Additional dev requirements
4 | # To generate a requirements file that includes both prod and dev requirements, run:
5 | # pip-compile --generate-hashes --output-file=requirements.dev.txt requirements.dev.in
6 |
7 | pip-tools
8 | pre-commit
9 | ruff
10 |
--------------------------------------------------------------------------------
/requirements.prod.in:
--------------------------------------------------------------------------------
1 | # Main prod requirements
2 |
3 | # To generate requirements file, run:
4 | # pip-compile --generate-hashes --output-file=requirements.prod.txt requirements.prod.in
5 |
6 | mkdocs
7 | mkdocs-macros-plugin
8 | mkdocs-material
9 | mkdocstrings[python]
10 | mkdocs-multirepo-plugin
11 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | # This file is a shim for CloudFlare Pages which expects a requirements.txt,
2 | # but we want to maintain requirements.prod.txt for our general dev tooling.
3 | -r requirements.prod.txt
4 |
--------------------------------------------------------------------------------
/scripts/wordcount.py:
--------------------------------------------------------------------------------
1 | from html.parser import HTMLParser
2 | import sys
3 |
4 |
5 | class ArticleParser(HTMLParser):
6 | def __init__(self):
7 | super().__init__()
8 | self.in_article = False
9 | self.text = []
10 |
11 | def handle_starttag(self, tag, _):
12 | if tag == "article":
13 | self.in_article = True
14 |
15 | def handle_endtag(self, tag):
16 | if tag == "article":
17 | self.in_article = False
18 |
19 | def handle_data(self, data):
20 | if self.in_article:
21 | self.text.append(data)
22 |
23 |
24 | if __name__ == "__main__":
25 | total = 0
26 | for filename in sys.argv[1:]:
27 | with open(filename, "r", encoding="utf-8") as f:
28 | parser = ArticleParser()
29 | parser.feed(f.read())
30 | text = " ".join(parser.text)
31 | total += len(text.split())
32 | print(total)
33 |
--------------------------------------------------------------------------------
/styles/OpenSAFELY/Branding.yml:
--------------------------------------------------------------------------------
1 | extends: substitution
2 | scope: text
3 | message: "Consider using '%s' instead of '%s'"
4 | level: suggestion
5 | ignorecase: true
6 | # swap maps tokens in form of bad: good
7 | swap:
8 | # NOTE: The left-hand (bad) side can match the right-hand (good) side; Vale
9 | # will ignore any alerts that match the intended form.
10 | 'github(?!.com)': 'GitHub'
11 | 'open[ -]?safely(?!.org)': 'OpenSAFELY'
12 |
--------------------------------------------------------------------------------
/styles/OpenSAFELY/HereLinks.yml:
--------------------------------------------------------------------------------
1 | extends: existence
2 | scope: raw
3 | message: 'Consider rewording link text to remove the use of "here"'
4 | level: suggestion
5 | ignorecase: true
6 | raw:
7 | - '(\[|\[.*\s)here(\s.*)?\]'
8 |
--------------------------------------------------------------------------------
/styles/OpenSAFELY/InternalLinks.yml:
--------------------------------------------------------------------------------
1 | extends: existence
2 | message: 'Links to other documentation pages should be written with a relative file path, not a link to a specific domain'
3 | link: 'https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages'
4 | scope: raw
5 | level: suggestion
6 | ignorecase: true
7 | raw:
8 | - '[(<].*docs.opensafely.org.*[)>]'
9 |
--------------------------------------------------------------------------------
/templates/python/material/parameters.html:
--------------------------------------------------------------------------------
1 | Parameters:
2 |
3 |
4 |
5 | Name
6 | Description
7 | Default
8 |
9 |
10 |
11 | {% for parameter in parameters %}
12 |
13 | {{ parameter.name }}{{ parameter.description|convert_markdown(heading_level, html_id) }}
15 | {% if parameter.default %}{{ parameter.default }}{% else %}required{% endif %}
16 |
17 | {% endfor %}
18 |
19 |
20 |
--------------------------------------------------------------------------------