library(usethis)
use_readme_rmd()15 README
The README.md is a very important part of an R package. It is probably the first thing the users will read once they decide to try out our package. The README must contain the goal of the package and clear examples so users can start using the package. Now we will so how to create it and how to populate it.
15.1 Create the .Rmd file
In general we will populate our README.md using a rmarkdown file (README.Rmd) if you don’t have it created you can create it with:
this will create the README.Rmd file that generates the README.md. To later build the README.md you can use the following command:
library(devtools)
build_readme()If you are new to rmakdown probable this introduction will be useful: Introduction to R Markdown.
Note
README.md and README.Rmd
Note that for cran/website/github only the README.md exists, so any change that you do to the README.Rmd file wont affect the ‘real’ README.md file till you build it. Make sure to build the .md file every time that you modify the .Rmd.
15.2 Content
A good README.md file must contain the following sections:
15.2.1 Badges
Badges are quite useful to display at the top of your README, they contain information of the package in a synthetic and consistent way. The badges are generated from usethis functions. You will have to manually copy the badge that will be printed in the console in the desired README section, usually at the top:
<!-- badges: start -->
PASTE BADGES HERE
<!-- badges: end -->lifecycle status The development status badge can provide the user the development status of the package. We would usually use “experimental” for packages still under development (usually version < 1.0.0) and “stable” for stable packages, note if you add the stable badge this sets some expectations about the package like backwards compatibility. A lifecycle badge is highly recommended.
use_lifecycle_badge("experimental")
use_lifecycle_badge("stable")cran version The cran badge informs about the current version in cran (if submitted to cran). This badge is also highly recommended (even before submitting to cran).
use_cran_badge()build status The badge indicates if the last checks ran in your package passed or not. This badge should also be green otherwise this means the continuous integration is broken. If at some point actions break in main, fix it as soon as possible. This badge is also highly recommended. The badge is generated when GitHub Actions are set.
[](https://github.com/{user/organisation}/{package_name}/actions?query=workflow%3AR-CMD-check)test coverage
cran downloads
15.2.2 Tested sources
If your packages is designed to work with different cdm sources (e.g. duckdb, local, postgres, sql server, …) we would encourage you to include the different sources you actively test against. We will later see the Testing multiple DBMS chapter where we explain how to do this automatically using GitHub actions. A good display to show the tested sources would be:
| Source | Driver | CDM reference | Status |
|------------------|------------------|------------------|------------------|
| Local R dataframe | N/A | `omopgenerics::cdmFromTables()` | [](https://github.com/OHDSI/CohortConstructor/actions/workflows/test-local-omopgenerics.yaml) |
| In-memory duckdb datatabase | duckdb | `CDMConnector::cdmFromCon()` | [](https://github.com/OHDSI/CohortConstructor/actions/workflows/test-duckdb-CDMConnector.yaml) |
| Postgres database | RPostgres | `CDMConnector::cdmFromCon()` | |
| Postgres database | DatabaseConnector | `CDMConnector::cdmFromCon()` | |
| SQL Server database | odbc | `CDMConnector::cdmFromCon()` | |
| SQL Server database | DatabaseConnector | `CDMConnector::cdmFromCon()` | |15.2.3 Goal of your package
Clearly state the goal of your package, do not extend much, usually 2/3 sentences are enough to describe what your package does.
15.2.4 How to install
Make sure to include information on how to install the package the current release from cran and the development version from GitHub. this section would usually look like:
# Installation
{pakage_name} can be installed from CRAN:
```r
install.packages("{pakage_name}")or
library(pak)
pkg_install("{pakage_name}")If you prefere to use pak.
The development version can be installed from GitHub:
library(pak)
pkg_install("{user/organisation}/{package_name}")```
15.2.5 Simple examples
This is the most important section. Catch user attention, show how your package can solve a problem they have. Usually try to include visualisations (like ‘flextable’ or ‘ggplot2’). If you have a table* function that depends on visOmopResults please use type = "flextable" in the README as it is better displayed than ‘gt’.
We also recommend to include diagrams on how some functions relate or how your package works. Spend some time on this section, remember that’s the first thing they will read about your package.
15.3 Example
Here we created a simple example of how a good README would look like: