Help for package CohortSymmetry

Title:

Sequence Symmetry Analysis Using the Observational Medical Outcomes Partnership Common Data Model

Version:

0.4.0

Maintainer:

Danielle Newby <danielle.newby@ndorms.ox.ac.uk>

Description:

Calculates crude sequence ratios, adjusted sequence ratios and confidence intervals using data mapped to the Observational Medical Outcomes Partnership Common Data Model. The methodology for sequence symmetry analysis is described by Pratt et al. (2015) <doi:10.1002/pds.3780> and Hendrix et al. (2024) <doi:10.1186/s12874-023-02108-y>.

License:

Apache License (≥ 2)

Encoding:

UTF-8

RoxygenNote:

7.3.3

Depends:

R (≥ 4.1.0)

Suggests:

testthat (≥ 3.1.5), DBI (≥ 1.0.0), cli, odbc, RPostgres, tidyselect, knitr, dbplyr (≥ 2.5.0), visOmopResults (≥ 1.5.1), DrugUtilisation (≥ 0.7.0), CohortConstructor (≥ 0.6.3), CodelistGenerator (≥ 3.1.0), flextable, gt, ggplot2, duckdb, CDMConnector, rmarkdown

Imports:

dplyr, PatientProfiles (≥ 1.0.0), rlang, tibble, tidyr, stats, here, omock (≥ 0.6.2), omopgenerics (≥ 1.0.0), clock

Config/testthat/edition:

URL:

https://ohdsi.github.io/CohortSymmetry/

BugReports:

https://github.com/OHDSI/CohortSymmetry/issues

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2026-11-06 18:06:16 UTC; dnewby

Author:

Danielle Newby

[aut, cre], Xihang Chen

[aut], Tyman Stanford

[aut], Berta Raventós

[aut], Nicole Pratt

[aut], Ed Burn

[aut], Marti Català

[aut], Núria Mercadé-Besora

[aut], Mike Du

[aut], Yuchen Guo

[aut], Kim Lopez

[aut], Marta Alcalde-Herraiz

[aut]

Repository:

CRAN

Date/Publication:

2026-11-07 17:20:07 UTC

CohortSymmetry: Sequence Symmetry Analysis Using the Observational Medical Outcomes Partnership Common Data Model

Description

Calculates crude sequence ratios, adjusted sequence ratios and confidence intervals using data mapped to the Observational Medical Outcomes Partnership Common Data Model. The methodology for sequence symmetry analysis is described by Pratt et al. (2015) doi:10.1002/pds.3780 and Hendrix et al. (2024) doi:10.1186/s12874-023-02108-y.

Author(s)

Maintainer: Danielle Newby danielle.newby@ndorms.ox.ac.uk (ORCID)

Authors:

Xihang Chen xihang.chen@ndorms.ox.ac.uk (ORCID)
Tyman Stanford tyman.stanford@unisa.edu.au (ORCID)
Berta Raventós braventos@idiapjgol.info (ORCID)
Nicole Pratt Nicole.Pratt@unisa.edu.au (ORCID)
Ed Burn ed.burn@ndorms.ox.ac.uk (ORCID)
Marti Català marti.catalasabate@ndorms.ox.ac.uk (ORCID)
Núria Mercadé-Besora nuria.mercadebesora@ndorms.ox.ac.uk (ORCID)
Mike Du mike.du@ndorms.ox.ac.uk (ORCID)
Yuchen Guo yuchen.guo@ndorms.ox.ac.uk (ORCID)
Kim Lopez kim.lopez@spc.ox.ac.uk (ORCID)
Marta Alcalde-Herraiz marta.alcaldeherraiz@ndorms.ox.ac.uk (ORCID)

Creates mock cdm object for testing

Description

Creates a mock cdm with two default synthetic cohorts, one is the index cohort and the other one is the marker cohort. However the users could specify them should they wish.

Usage

mockCohortSymmetry(seed = 1, indexCohort = NULL, markerCohort = NULL)

Arguments

seed

The seed to be inputted.

indexCohort

The tibble of your index cohort. Default is NULL, which means the default indexCohort is being used.

markerCohort

The tibble of your marker cohort. Default is NULL, which means the default markerCohort is being used.

Value

A mock cdm object contains your index and marker cohort

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm

A plot for the sequence ratios.

Description

It provides a ggplot of the sequence ratios of index and marker cohorts.

Usage

plotSequenceRatios(
  result,
  onlyASR = FALSE,
  plotTitle = NULL,
  style = "default",
  labs = c("Sequence Ratio", "Index Marker Pair"),
  colours = NULL,
  facet = NULL
)

Arguments

result

Table output from summariseSequenceRatios.

onlyASR

If set to be TRUE then only adjusted SR will be plotted. Otherwise if it is set to be FALSE then both adjusted and crude SR will be plotted.

plotTitle

Title of the plot, if NULL no title will be included in the plot.

style

Style used for the plot. Passed to visOmopResults::themeVisOmop().

labs

Axis labels for the plot.

colours

Colours for sequence ratio.

facet

The variable to facet by.

Value

A plot for the sequence ratios of index and marker cohorts.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohort <- sequenceCohort(cdm = cdm,
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2",
                                 name = "joined_cohort")
sequence_ratio <- summariseSequenceRatios(cohort = cdm$joined_cohort)
plotSequenceRatios(result = sequence_ratio)
CDMConnector::cdmDisconnect(cdm = cdm)

A plot for the temporal symmetry of cohorts.

Description

It provides a ggplot of the temporal symmetry of two or more cohorts.

Usage

plotTemporalSymmetry(
  result,
  plotTitle = NULL,
  labs = c("Time (days)", "Individuals (N)"),
  xlim = c(-365, 365),
  colours = c("blue", "red"),
  scales = "free"
)

Arguments

result

Table output from summariseTemporalSymmetry.

plotTitle

Title of the plot, if NULL no title will be plotted.

labs

Axis labels for the plot.

xlim

Limits for the x axis of the plot.

colours

Colours for both parts of the plot, pre- and post- time 0.

scales

Whether to set free y scales for the facet wrap when there are multiple plots (i.e. each plot has its own scaled y axis) or set them equal for all. Only accepts "free" for the former and "fixed" for the latter.

Value

A plot for the temporal symmetry of cohorts.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohort <- sequenceCohort(cdm = cdm,
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2",
                                 name = "joined_cohort")
temporal_symmetry <- summariseTemporalSymmetry(cohort = cdm$joined_cohort)
plotTemporalSymmetry(result = temporal_symmetry)
CDMConnector::cdmDisconnect(cdm = cdm)

Intersecting the index and marker cohorts prior to calculating Sequence Symmetry Ratios

Description

Join two tables in the CDM (one for index and the other for marker cohorts) into a new table in the cdm taking into account the maximum time interval between events. Index and marker cohorts should be instantiated in advance by the user.

Usage

sequenceCohort(
  cdm,
  indexCohortTable,
  markerCohortTable,
  name,
  indexCohortId = NULL,
  markerCohortId = NULL,
  cohortDateRange = as.Date(c(NA, NA)),
  sequencePriorObservation = 365,
  indexMarkerWashout = 365,
  indexMarkerGap = Inf,
  combinationWindow = c(0, 365)
)

Arguments

cdm

A CDM reference.

indexCohortTable

A table in the CDM that the index cohorts should come from.

markerCohortTable

A table in the CDM that the marker cohorts should come from.

name

The name within the cdm that the output is called. Default is joined_cohorts.

indexCohortId

Cohort definition IDs in indexCohortTable to be considered for the analysis. Change to NULL if all indices are wished to be included.

markerCohortId

Cohort definition IDs in markerCohortTable to be considered for the analysis. Change to NULL if all markers are wished to be included.

cohortDateRange

Two dates indicating study period and the sequences that the user wants to restrict to.

sequencePriorObservation

The minimum amount of prior observation required on the index marker sequence. Default is 365 days.

indexMarkerWashout

A washout window to be applied on both the index cohort and marker cohort. Default is 365 days.

indexMarkerGap

The maximum allowable gap between the end of the first episode and the start of the second episode in a sequence/combination. Default is Inf.

combinationWindow

A constrain to be placed on the gap between two initiations. Default c(0,365), meaning the gap should be larger than 0 but less than or equal to 365.

Value

A table within the cdm reference.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohorts <- sequenceCohort(
  cdm = cdm,
  name = "joined_cohorts",
  indexCohortTable = "cohort_1",
  markerCohortTable = "cohort_2"
)
 cdm$joined_cohorts

Sequence ratio calculations

Description

Using generateSequenceCohortSet to obtain sequence ratios for the desired outcomes.

Usage

summariseSequenceRatios(cohort, cohortId = NULL, confidenceInterval = 95)

Arguments

cohort

A cohort table in the cdm.

cohortId

The Ids in the cohort that are to be included in the analyses.

confidenceInterval

Default is 95, indicating the central 95% confidence interval.

Value

A local table with all the analyses.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohorts <- sequenceCohort(cdm = cdm,
                                 name = "joined_cohorts",
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2")
pssa_result <- summariseSequenceRatios(cohort = cdm$joined_cohorts)
pssa_result

Summarise temporal symmetry

Description

Using generateSequenceCohortSet to obtain temporal symmetry (aggregated counts) of two cohorts.

Usage

summariseTemporalSymmetry(cohort, cohortId = NULL, days = 30)

Arguments

cohort

A cohort table in the cdm.

cohortId

The Ids in the cohort that are to be included in the analyses.

days

Numerical timescale for the x axis of the plot in days (Default is 30 days, if users want years put 365, days put 1).

Value

An aggregated table with difference in time (marker - index) and the relevant counts.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohorts <- sequenceCohort(cdm = cdm,
                                 name = "joined_cohorts",
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2")
temporal_symmetry <- summariseTemporalSymmetry(cohort = cdm$joined_cohorts)
CDMConnector::cdmDisconnect(cdm)

A formatted visualization of sequence_symmetry objects.

Description

It provides a formatted table with the contents of the summariseSequenceRatios output.

Usage

tableSequenceRatios(
  result,
  header = "marker_cohort_name",
  groupColumn = "cdm_name",
  type = "gt",
  style = "default",
  hide = "variable_level"
)

Arguments

result

A sequence_symmetry object.

header

A vector specifying the elements to include in the header. See visOmopResults package for more information on how to use this parameter.

groupColumn

Columns to use as group labels. See visOmopResults package for more information on how to use this parameter.

type

The desired format of the output table.

style

Style used for the table.

hide

Columns to drop from the output table.

Value

A formatted version of the sequence_symmetry object.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohort <- sequenceCohort(cdm = cdm,
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2",
                                 name = "joined_cohort")
res <- summariseSequenceRatios(cohort = cdm$joined_cohort)
gtResult <- tableSequenceRatios(res)
CDMConnector::cdmDisconnect(cdm = cdm)

A formatted visualization of temporal_symmetry objects.

Description

It provides a formatted table with the contents of the summariseTemporalSymmetry output.

Usage

tableTemporalSymmetry(
  result,
  header = "variable_level",
  groupColumn = c("cdm_name", "index_name"),
  type = "gt",
  style = "default",
  hide = "variable_name"
)

Arguments

result

A temporal_symmetry object.

header

A vector specifying the elements to include in the header. See visOmopResults package for more information on how to use this parameter.

groupColumn

Columns to use as group labels. See visOmopResults package for more information on how to use this parameter.

type

The desired format of the output table.

style

Style used for the table.

hide

Columns to drop from the output table.

Value

A formatted version of the temporal_symmetry object.

Examples


library(CohortSymmetry)
cdm <- mockCohortSymmetry()
cdm$joined_cohort <- sequenceCohort(cdm = cdm,
                                 indexCohortTable = "cohort_1",
                                 markerCohortTable = "cohort_2",
                                 name = "joined_cohort")
res <- summariseTemporalSymmetry(cohort = cdm$joined_cohort)
gtResult <- tableTemporalSymmetry(result = res)
CDMConnector::cdmDisconnect(cdm = cdm)

Package {CohortSymmetry}

CohortSymmetry: Sequence Symmetry Analysis Using the Observational Medical Outcomes Partnership Common Data Model

Description

Author(s)

See Also

Creates mock cdm object for testing

Description

Usage

Arguments

Value

Examples

A plot for the sequence ratios.

Description

Usage

Arguments

Value

Examples

A plot for the temporal symmetry of cohorts.

Description

Usage

Arguments

Value

Examples

Intersecting the index and marker cohorts prior to calculating Sequence Symmetry Ratios

Description

Usage

Arguments

Value

Examples

Sequence ratio calculations

Description

Usage

Arguments

Value

Examples

Summarise temporal symmetry

Description

Usage

Arguments

Value

Examples

A formatted visualization of sequence_symmetry objects.

Description

Usage

Arguments

Value

Examples

A formatted visualization of temporal_symmetry objects.

Description

Usage

Arguments

Value

Examples