This page describes the minimal requirements a package must meet to be considered for inclusion in HADES.

Functionality

Implement OHDSI best practices

A HADES package should implement OHDSI best practices, ideally as established through systematic emprical evaluation. Best practices include the ability to apply methods at large scale (e.g. across many exposures and outcomes). Methods should provide diagnostics, allowing the user to verify wether the results are accurate. (E.g. computing the standardized difference of the mean after propensity score matching).

Minimize duplication of functionality

There should be no two HADES packages that provide the same functionality. For example, all communication with WebAPI should go through ROhdsiWebApi, all comparative cohort analytics should go in the CohortMethod package, etc.

Cross-platform support

Cross-database-platform support

When a package needs to communicate with a user’s database server, the package must support a wide variety of database platforms. The main mechanisms for this in HADES are the DatabaseConnector and SqlRender packages.

Cross-operating system

A HADES package should run without problems on Microsoft Windows, MacOS, and Linux.

Code style and organization

All HADES R package follow the basic structure of R packages. See R packages for a thorough discussion on R packages.

Extras folder

The extras folder contains all files used by the package developer. These files will not be part of the package once installed. A required file in this folder is PackageMaintenance.R, which contains the code executed when releasing a package.

Versioning

Each package has a three-digit version number.

New micro versions (e.g. from 4.3.2 to 4.3.3) indicate bug fixes only. No new functionality, and forward and backward compatibility are guaranteed
New minor versions (e.g. from 4.3.3 to 4.4.0) indicate added functionality. Only backward compatibility is guaranteed
New major versions (e.g. from 4.4.0 to 5.0.0) indicate major revisions. All bets are off in terms of compatibility

Branches and tags

The ‘main’ branch at all times should contain the latest released version. Each version, including the latest release, should be tagged as ‘vx.x.x’, for example ‘v1.0.0’.

It is highly recommended to keep the latest develop version in a branch called ‘develop’.

Code style

A HADES package should adhere to the HADES codes style guide.

Copyright header

In each source file should start with a copyright header like this:

# Copyright 2022 Observational Health Data Sciences and Informatics
#
# This file is part of CohortMethod
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

Packages must not have invisible side effects

When a user calls a function, the effect of that call should be aparent to the user. This means:

Do not call library or require in a function, as this changes the user’s search path.
Do not set options.
Do not write to files other than those specified by the user in the function call.
Do not use global variables.

Intead of using library, always explicitly reference the packge a function belongs to, for example SqlRender::translate().

License

All HADES packages should licensed as Apache 2.0.

Documentation

Function documentation

The roxygen2 package should be used for function documentation. Each function and function argument must be documented.

Vignettes

Vignettes are highly recommended as a way to explain how the package can be used for one or more typical use cases.

README.md and website

The README.md and package website should follow HADES style and organization. The package website should be generated using the pkgdown package. See any HADES package for examples.

NEWS.md

Changes should be maintained in NEWS.md. This should be aimed at the user, to explain what has changed from the user’s perspective. Avoid referencing GitHub issues, which are aimed at developers.

Announce new releases on the OHDSI forums

Each release should be announced in the OHDSI Forums, in this thread. Provide a link to the change log, and briefly described the most important changes.

Continuous integration and unit test

Use the OHDSI GitHub Actions for continuous integration, so R check is performed at every push to the repo. Released packages must pass R without warnings on Windows, MacOS, and Linux. Tagging the released version should be done automatically, as described in the release process.

Unit tests

OHDSI unit testing for R follows the standard R practice using test_that: A folder named ‘tests’ is created in the root of the package, and this folder contains

A sub-folder called ’testthat`
A file called ‘testthat.R’
The file ‘testthat.R’ should have the following content:

library(testthat)
library(<package name>)
test_check("<package name>")

The sub-folder ‘testthat’ should contain one or more R scripts whose file name starts with ‘test-’ (e.g. ‘test-connection.R’. Each file should contain one or more test_that blocks, for example

test_that("Function x returns 2", {
  expect_equal(x(), 2)
})

Each package should have unit tests. Unit test coverage must be around 80%.

Dependencies

HADES or CRAN

A HADES package may only depend on other HADES packages or packages in CRAN. HADES dependencies not in CRAN should be in Remotes section of the DESCRIPTION file.

Minimize overall dependencies

Dependencies lead to instability. Only add dependencies to other packages if completely unavoidable. We have more or less accepted we need to depend on the core tidyverse packages, so any of those packages are allowed.

Minimize added dependencies

Where possible, only use packages that are already used by other HADES packages. For example, when storing objects too large to fit in memory, use Andromeda, not ff. Similarly, avoid adding a new technology; HADES packages primarily use R, C++ (embedded in R packages), Java (through rJava), and some Python (through reticulate). Avoid requiring for example Julia or .Net.

HADES Package Requirements