Objects and classes in Ramses

11 February 2024

Source: vignettes/ramses-objects.Rmd

Introduction and rationale

This article introduces the way Ramses handles entities such as patients, prescriptions, or therapy episodes. Each of these entities is associated with specific data analysis operations, and is represented in their own type of records in the backend database.

To ensure users can access the relevant records and perform the desired analytical operations, Ramses employs a object model that consists of S4 classes representing each of these entities, and giving access to relevant functions or methods.

More information on, objects, classes, and methods in R is available from the Object-oriented programming section by Wickham (2019).

Objects in Ramses

Ramses objects are S4 classes. They all conform to the RamsesObject virtual class specification:

  • they contain an id slot corresponding to a primary key in the database backend
  • they contain a conn slot corresponding to the database backend connection, currently either of duckdb_connection or PqConnection class (see database objects)
  • they can be passed to compute() in order to compute the corresponding database records (faster to retrieve)
  • they can be passed to collect() in order to retrieve the corresponding database records (returns a tbl_df object)
  • they can be passed to Patient() in order to retrieve the corresponding patient entity (returns a Patient object).

MedicationRequest objects, which represent a single drug-dose order, which may or may not participate in combination therapy (2 or more drugs). MedicationRequest objects are associated with one episode of antimicrobial therapy (represented by TherapyEpisode objects). It is possible to retrieve the TherapyEpisode entity from any MedicationRequest object x by passing it to the TherapyEpisode() function.

G RamsesObject «interface» RamsesObject+ class: character + id: character/integer + conn: DBIConnection - record: tbl_sql+ class(): character + show(): void + compute(): RamsesObject + collect(): tbl_df + Patient(): PatientMedicationRequest MedicationRequest+ MedicationRequest(DBICon, id) + TherapyEpisode(): TherapyEpisode + longitudinal_table(collect = T/F): tbl + therapy_timeline(): htmlwidgetsRamsesObject->MedicationRequest TherapyEpisode TherapyEpisode- longitudinal_table: tbl_sql+ TherapyEpisode(DBICon, id): TherapyEpisode + parenteral_changes(): list + longitudinal_table(collect = T/F): tbl + clinical_feature_last(): TherapyEpisode + clinical_feature_mean(): TherapyEpisode + clinical_feature_ols_trend(): TherapyEpisode + clinical_feature_interval(): TherapyEpisode + therapy_timeline(): htmlwidgetsRamsesObject->TherapyEpisode Patient Patient+ Patient(DBICon, id): Patient + therapy_timeline(): htmlwidgetsRamsesObject->Patient Encounter Encounter- longitudinal_table: tbl_sql+ Encounter(DBICon, id): Encounter + longitudinal_table(collect = T/F): tbl + clinical_feature_last(): Encounter + clinical_feature_mean(): Encounter + clinical_feature_ols_trend(): Encounter + clinical_feature_interval(): Encounter + therapy_timeline(): htmlwidgetsRamsesObject->Encounter TherapyEpisode->MedicationRequest 1..*  1   

Database objects

Ramses uses other objects for backend database connections and tables. They follow the dbplyr architecture:

  • database connections have class DBIConnection. Currently, duckdb_connection (package duckdb) and PqConnection (package RPostgres) are supported
  • database table are created using the tbl() function and are represented by tbl_sql objects which, although they inherit from the tbl class, are distinct from the common tbl_df tibble class.
G dataframe data.frametbl_df tbl_dfdataframe->tbl_df tbl_duckdb_connection tbl_duckdb_connectiontbl_PqConnection tbl_PqConnectionDBIConnection DBIConnectionduckdb_connection duckdb_connectionDBIConnection->duckdb_connection PqConnection PqConnectionDBIConnection->PqConnection tbl tbltbl_lazy tbl_lazytbl->tbl_lazy tbl->tbl_df tbl_sql tbl_sqltbl_lazy->tbl_sql tbl_dbi tbl_dbitbl_sql->tbl_dbi tbl_dbi->tbl_duckdb_connection tbl_dbi->tbl_PqConnection DBIObject DBIObjectDBIObject->DBIConnection

References

Wickham, Hadley. 2019. Advanced r. 2nd ed. Chapman & Hall/CRC. https://adv-r.hadley.nz/.