From c154418b3c07962c5c72c5b1d58b05ef65390370 Mon Sep 17 00:00:00 2001 From: Craig Robert Shenton Date: Mon, 24 Oct 2022 15:50:18 +0100 Subject: [PATCH] 18 documentation (#19) * added docs pages * docs update * Create 3.3-useful-functions.qmd * Update 3.3-useful-functions.qmd * new link to Futures --- docs/1.0-nhs-style-guide.qmd | 4 ++ docs/{nhs-colours.qmd => 1.1-nhs-colours.qmd} | 0 docs/1.2-r-language.qmd | 47 +++++++++++++++++++ docs/1.3-udal.qmd | 10 ++++ ...o-publish-to-github.qmd => 1.4-github.qmd} | 22 +++++++-- ...to-add-new-page.qmd => 1.5-contribute.qmd} | 0 ...isualisation.qmd => 2.1-visualisation.qmd} | 14 +++++- docs/2.2-tables.qmd | 4 ++ docs/2.3-statistics.qmd | 14 ++++++ docs/2.4-methods.qmd | 13 +++++ ...3.1-reproducible-analytical-pipelines.qmd} | 4 +- docs/3.2-best-practice.qmd | 11 +++++ docs/3.3-useful-functions.qmd | 15 ++++++ docs/_quarto.yml | 38 ++++++++++----- docs/index.qmd | 28 +++++------ docs/r-programming.qmd | 15 ------ 16 files changed, 189 insertions(+), 50 deletions(-) create mode 100644 docs/1.0-nhs-style-guide.qmd rename docs/{nhs-colours.qmd => 1.1-nhs-colours.qmd} (100%) create mode 100644 docs/1.2-r-language.qmd create mode 100644 docs/1.3-udal.qmd rename docs/{quarto-publish-to-github.qmd => 1.4-github.qmd} (62%) rename docs/{quarto-add-new-page.qmd => 1.5-contribute.qmd} (100%) rename docs/{r-visualisation.qmd => 2.1-visualisation.qmd} (89%) create mode 100644 docs/2.2-tables.qmd create mode 100644 docs/2.3-statistics.qmd create mode 100644 docs/2.4-methods.qmd rename docs/{intro-to-rap.qmd => 3.1-reproducible-analytical-pipelines.qmd} (92%) create mode 100644 docs/3.2-best-practice.qmd create mode 100644 docs/3.3-useful-functions.qmd delete mode 100644 docs/r-programming.qmd diff --git a/docs/1.0-nhs-style-guide.qmd b/docs/1.0-nhs-style-guide.qmd new file mode 100644 index 0000000..fcfe96b --- /dev/null +++ b/docs/1.0-nhs-style-guide.qmd @@ -0,0 +1,4 @@ +--- +title: NHS R-Markdown Style Guide +subtitle: "Coming soon" +--- \ No newline at end of file diff --git a/docs/nhs-colours.qmd b/docs/1.1-nhs-colours.qmd similarity index 100% rename from docs/nhs-colours.qmd rename to docs/1.1-nhs-colours.qmd diff --git a/docs/1.2-r-language.qmd b/docs/1.2-r-language.qmd new file mode 100644 index 0000000..b8a2ea1 --- /dev/null +++ b/docs/1.2-r-language.qmd @@ -0,0 +1,47 @@ +--- +title: R Programming Language +subtitle: "Under development" +--- + +- [Learning R](https://github.com/nhs-r-community/intro_r) +- [Reports](https://ukgovdatascience.github.io/rap_companion/pub.html) +- [Markdown](https://ukgovdatascience.github.io/rap_companion/pub.html#r-markdown-basics) +- Dashboards (Shiny) +- [Packages](https://ukgovdatascience.github.io/rap_companion/package.html) + +## Quarto + +It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub Actions](http://github.com). This is very new and incredibly cool. This is an example of a quarto website with an NHS Theme --- it is a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you and/or your colleagues use for analyses, whether or not you write code. + +Quarto integrates with R, Python or HTML, CSS so you can make your websites as complex and beautiful as you like as you see examples and reuse and remix from others in the open community. + +### What is Quarto? + +Quarto helps you have your ideas and your code in one place, and present it in a beautiful way. + +**Quarto unifies and extends the RMarkdown ecosystem** - it unifies by combining the functionality of R Markdown, bookdown, distill, xaringian, etc into a single consistent system. And it extends in several ways: all features are possible beyond R too, including Python and Javascript. It also has more “guardrails”: accessibility and inclusion are centered in the design. Quarto is for people who love R-Markdown, and it's for people who have never used RMarkdown. + +[Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials! + +### Example Quarto sites + +A few Quarto websites from Openscapes - so far we have been using Quarto for documentation using Quarto and Markdown files and Jupyter Notebooks. + +- [Champions Lessons Series](https://openscapes.github.io/series) +- [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/)\ +- [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/) +- [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/) +- [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel + +## Resource List + +NHS specific resources from the NHS-R Community + +### NHS Themes + +- [NHS-R Theme](https://nhs-r-community.github.io/NHSRtheme/) [[code](https://github.com/nhs-r-community/NHSRtheme)] + +### NHS code + +- [NHS-R how-tos](https://github.com/nhs-r-community/demos-and-how-tos) +- [NHS-R R-Markdown functions](https://github.com/nhs-r-community/demos-and-how-tos/tree/main/rmarkdown/rmarkdown_functions_and_functionals) diff --git a/docs/1.3-udal.qmd b/docs/1.3-udal.qmd new file mode 100644 index 0000000..0d91f62 --- /dev/null +++ b/docs/1.3-udal.qmd @@ -0,0 +1,10 @@ +--- +title: National Data Platform (UDAL) +subtitle: "Under development" +--- + +- Getting access +- Virtual Machines +- R Studio + - [Using Git](https://github.com/NHSDigital/rap-community-of-practice/blob/main/implementing_RAP/R/git_with_RStudio.md) +- Loading data into R \ No newline at end of file diff --git a/docs/quarto-publish-to-github.qmd b/docs/1.4-github.qmd similarity index 62% rename from docs/quarto-publish-to-github.qmd rename to docs/1.4-github.qmd index ada83ec..f1c4d68 100644 --- a/docs/quarto-publish-to-github.qmd +++ b/docs/1.4-github.qmd @@ -1,10 +1,18 @@ --- -title: Publish to GitHub pages -subtitle: "Publish a Quarto website project to your GitHub pages using GitHub actions." +title: NHS England GitHub +subtitle: "Under development" --- +- [Git](https://github.com/NHSDigital/rap-community-of-practice/blob/main/implementing_RAP/git/intro-to-git.md) +- [Getting access](https://github.com/nhsengland/github-WoW) +- [Version Control](https://ukgovdatascience.github.io/rap_companion/vs.html) +- [Publishing Code](https://github.com/NHSDigital/rap-community-of-practice/blob/main/implementing_RAP/general_guidance/how-to-publish-your-code-in-the-open.md) +- [Social Coding](https://github.com/NHSDigital/rap-community-of-practice/blob/main/implementing_RAP/git/using-git-collaboratively.md) + ## GitHub Pages +Publish a Quarto website project to your GitHub pages using GitHub actions. + ### Add the GitHub Actions workflow to your project Copy [quarto-publish.yml](https://github.com/craig-shenton/nhs-r-reporting/blob/main/_assets/actions/quarto-publish-example.yml) to the folder `.github/workflows/quarto-publish.yml`. @@ -54,10 +62,14 @@ If your Quarto project is not in the top level folder of your repository (in thi Do *not* edit the `GITHUB_TOKEN` to add a personal secret to this file. This file has the same permissions as your repository, and might be publicly readable. ::: -### Run `quarto publish gh-pages` locally, once +### Configure the repository before publishing -> Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run `quarto publish gh-pages` locally once. +Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run `quarto publish gh-pages` locally once. + +### Commit and push the workflow Now, add and commit the workflow file you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through GitHub pages. -Note that GitHub Pages uses a `gh-pages` branch in your repository, which will be automatically created if one doesn't exist. \ No newline at end of file +::: {.callout-note} +Note that GitHub Pages uses a `gh-pages` branch in your repository, which will be automatically created if one doesn't exist. +::: \ No newline at end of file diff --git a/docs/quarto-add-new-page.qmd b/docs/1.5-contribute.qmd similarity index 100% rename from docs/quarto-add-new-page.qmd rename to docs/1.5-contribute.qmd diff --git a/docs/r-visualisation.qmd b/docs/2.1-visualisation.qmd similarity index 89% rename from docs/r-visualisation.qmd rename to docs/2.1-visualisation.qmd index b428eb5..dcbdd14 100644 --- a/docs/r-visualisation.qmd +++ b/docs/2.1-visualisation.qmd @@ -1,8 +1,20 @@ --- title: Visualising Data in R +subtitle: Under development --- -## NHS-R Plot-the-dots + +- Bar Chart +- Pyramid Chart +- Line Chart +- Multi-line Chart +- Targets & Benchmarks +- KPIs +- Scatter Plot +- Box Plot +- Maps + +## Statistical Process Control (SPC) The [NHSR Plot the Dots](https://github.com/nhs-r-community/NHSRplotthedots) package is built by the [NHS-R community](https://nhsrcommunity.com) to provide tools for drawing statistical process control (SPC) charts. The package supports the NHS England programme ['Making Data Count'](https://www.england.nhs.uk/publication/making-data-count/). The programme encourages boards, managers, and analyst teams to present data in ways that show change over time, and drive better understanding of indicators than 'RAG' (red, amber, green) rated reports often present. diff --git a/docs/2.2-tables.qmd b/docs/2.2-tables.qmd new file mode 100644 index 0000000..0c6a308 --- /dev/null +++ b/docs/2.2-tables.qmd @@ -0,0 +1,4 @@ +--- +title: R-Markdown Tables +subtitle: "Coming soon" +--- \ No newline at end of file diff --git a/docs/2.3-statistics.qmd b/docs/2.3-statistics.qmd new file mode 100644 index 0000000..0a46e8e --- /dev/null +++ b/docs/2.3-statistics.qmd @@ -0,0 +1,14 @@ +--- +title: Statistics in R +subtitle: "Under development" +--- + +- [Means](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/Means.R) +- [Proportions](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/Proportions.R) +- [Confidence Intervals](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/utils.R) +- Correlation +- Regression +- Funnel Plots +- [Rates](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/Rates.R) +- [Directly Standardised Rates](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/DSR.R) +- [Indirectly Standardised Rates](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/ISRate.R) \ No newline at end of file diff --git a/docs/2.4-methods.qmd b/docs/2.4-methods.qmd new file mode 100644 index 0000000..b50b027 --- /dev/null +++ b/docs/2.4-methods.qmd @@ -0,0 +1,13 @@ +--- +title: NHS England Methods in R +subtitle: "Under development" +--- + +- [Quantiles](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/Quantiles.R) +- Statistical Neighbours +- Pareto Chart +- Z-Scores +- Disclosure Control +- [Standardised Mortality Ratios](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/ISRatio.R) +- [Life Expectancy](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/LifeExpectancy.R) +- [Slope Index of Inequality](https://github.com/publichealthengland/PHEindicatormethods/blob/master/R/SII_function.R) \ No newline at end of file diff --git a/docs/intro-to-rap.qmd b/docs/3.1-reproducible-analytical-pipelines.qmd similarity index 92% rename from docs/intro-to-rap.qmd rename to docs/3.1-reproducible-analytical-pipelines.qmd index 5118893..14de6ee 100644 --- a/docs/intro-to-rap.qmd +++ b/docs/3.1-reproducible-analytical-pipelines.qmd @@ -1,8 +1,10 @@ --- title: Reproducible Analytical Pipelines (RAP) -subtitle: " RAP brings together a number of best practices to ensure published NHS statistics meet the highest standards of transparency and reproducibility." +subtitle: Under development" --- +Reproducible Analytical Pipelines (RAP) brings together a number of best practices to ensure published NHS statistics meet the highest standards of transparency and reproducibility. + ## Resources ### NHS England diff --git a/docs/3.2-best-practice.qmd b/docs/3.2-best-practice.qmd new file mode 100644 index 0000000..1e2a583 --- /dev/null +++ b/docs/3.2-best-practice.qmd @@ -0,0 +1,11 @@ +--- +title: Coding Best Practices +subtitle: "Under development" +--- + +- Cleaning +- Transformations +- [Tidy Data](https://github.com/NHSDigital/rap-community-of-practice/blob/main/implementing_RAP/general_guidance/tidy-data.md) +- [Unit Tests](https://ukgovdatascience.github.io/rap_companion/test.html) +- [Quality Assurance](https://ukgovdatascience.github.io/rap_companion/qa-data.html) +- [Dependency Management](https://ukgovdatascience.github.io/rap_companion/dep.html) \ No newline at end of file diff --git a/docs/3.3-useful-functions.qmd b/docs/3.3-useful-functions.qmd new file mode 100644 index 0000000..6b0cba6 --- /dev/null +++ b/docs/3.3-useful-functions.qmd @@ -0,0 +1,15 @@ +--- +title: Useful Functions +subtitle: "Under development" +--- + +## Open Issues + +- [Notts Methods](https://github.com/CDU-data-science-team/nottshcMethods/tree/main/R) +- [Deduplication keeping latest ingest value](https://github.com/nhsengland/nhs-r-reporting/issues/15) +- [Dataset schema best practice](https://github.com/nhsengland/nhs-r-reporting/issues/13) +- [Shortening provider names into a readable format](https://github.com/nhsengland/nhs-r-reporting/issues/12) +- [Identify and convert with poorly formatted dates](https://github.com/nhsengland/nhs-r-reporting/issues/11) +- [Apply statistical disclosure control](https://www.nhsbsa.nhs.uk/sites/default/files/2020-10/nhsbsa-sdc-protocol.pdf) +- [Loop though all geographies and render a custom report]() +- [Import parquet file from Azure datalake into R dataframe](https://github.com/nhsengland/nhs-r-reporting/issues/3) \ No newline at end of file diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 8dc1d8a..6505387 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -39,7 +39,7 @@ website: href: https://github.com/nhsengland/nhs-r-reporting aria-label: GitHub - icon: cloud-fill - href: https://future.nhs.uk/NationalRCommunity/groupHome + href: https://future.nhs.uk/NHSERcommunity aria-label: NHS England R Community sidebar: @@ -52,24 +52,36 @@ website: contents: - text: "Introduction" file: index.qmd + - text: "NHS Style Guide" + file: 1.0-nhs-style-guide.qmd - text: "NHS Colours" - file: nhs-colours.qmd - - section: "R" + file: 1.1-nhs-colours.qmd + - text: "Contribute to this site" + file: 1.5-contribute.qmd + - section: "Tools" contents: - text: "R-Language" - file: r-programming.qmd - - text: "Data Visualisation" - file: r-visualisation.qmd - - section: "Quarto" + file: 1.2-r-language.qmd + - text: "National Data Platform (UDAL)" + file: 1.3-udal.qmd + - text: "NHS England GitHub" + file: 1.4-github.qmd + - section: "Analysis" contents: - - text: "Contribute to this site" - file: quarto-add-new-page.qmd - - text: "Publish to GitHub pages" - file: quarto-publish-to-github.qmd - - section: "RAP" + - text: "Visualisations" + file: 2.1-visualisation.qmd + - text: "Tables" + file: 2.2-tables.qmd + - text: "Statistics" + file: 2.3-statistics.qmd + - text: "Methods" + file: 2.4-methods.qmd + - section: "Data & Code" contents: - text: "Reproducible Analytical Pipelines" - file: intro-to-rap.qmd + file: 3.1-reproducible-analytical-pipelines.qmd + - text: "Coding Best Practices" + file: 3.2-best-practice.qmd format: html: theme: diff --git a/docs/index.qmd b/docs/index.qmd index 7bdda80..da58ccb 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,28 +1,26 @@ --- -title: "Quarto" -subtitle: "Create open-source reports, documentation, and much more" +title: "NHSE R Reporting Documentation" --- ## Welcome {#welcome} -It's possible to create beautiful documentation to share online with [Quarto](https://quarto.org) that auto-updates with [GitHub Actions](http://github.com). This is very new and incredibly cool. This is an example of a quarto website with an NHS Theme --- it is a really powerful way to create and share your work. You can communicate about science using the same reproducible workflow you and/or your colleagues use for analyses, whether or not you write code. +A repository to share code, good practice, resources, and knowledge about using R across NHS England. -Quarto integrates with R, Python or HTML, CSS so you can make your websites as complex and beautiful as you like as you see examples and reuse and remix from others in the open community. +::: {.callout-note} +No data, public or private are shared in this repository. +::: -## What is Quarto? +## Contributing -Quarto helps you have your ideas and your code in one place, and present it in a beautiful way. +Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. -**Quarto unifies and extends the RMarkdown ecosystem** - it unifies by combining the functionality of R Markdown, bookdown, distill, xaringian, etc into a single consistent system. And it extends in several ways: all features are possible beyond R too, including Python and Javascript. It also has more “guardrails”: accessibility and inclusion are centered in the design. Quarto is for people who love R-Markdown, and it's for people who have never used RMarkdown. +See [CONTRIBUTING.md](/1.5-contribute.html) for detailed guidance. -[Quarto.org](https://quarto.org) is the go-to place for full documentation and more tutorials! +## License -## Example Quarto sites +Distributed under the MIT License. See [LICENSE.md](https://github.com/nhsengland/nhs-r-reporting/blob/main/LICENSE) for more information. -A few Quarto websites from Openscapes - so far we have been using Quarto for documentation using Quarto and Markdown files and Jupyter Notebooks. +## About + +To find out more about the [NHS England R Community](https://future.nhs.uk/NHSERcommunity) visit our [project website](https://future.nhs.uk/NHSERcommunity). -- [Champions Lessons Series](https://openscapes.github.io/series) -- [Openscapes Approach Guide](https://openscapes.github.io/approach-guide/)\ -- [2021 NASA Cloud Hackathon](https://nasa-openscapes.github.io/2021-Cloud-Hackathon/) -- [Faylab Lab Manual](https://thefaylab.github.io/lab-manual/) -- [A Quarto tip a day](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/), by Mine Çetinkaya-Rundel \ No newline at end of file diff --git a/docs/r-programming.qmd b/docs/r-programming.qmd deleted file mode 100644 index 1f1a7c7..0000000 --- a/docs/r-programming.qmd +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: R Programming Language -subtitle: "NHS specific resources from the NHS-R Community" ---- - -## Resource List - -### NHS Themes - -- [NHS-R Theme](https://nhs-r-community.github.io/NHSRtheme/) [[code](https://github.com/nhs-r-community/NHSRtheme)] - -### NHS code - -- [NHS-R how-tos](https://github.com/nhs-r-community/demos-and-how-tos) -- [NHS-R R-Markdown functions](https://github.com/nhs-r-community/demos-and-how-tos/tree/main/rmarkdown/rmarkdown_functions_and_functionals)