Circe#

The section bellow is adjusted from the Circe docs.

Introduction#

A python-wrapper for Circe, a library for creating queries for the OMOP Common Data Model. These queries are used in cohort definitions (CohortExpression) as well as custom features (CriteriaFeature). This package provides convenient wrappers for Circe functions, and includes the necessary Java dependencies.

Features#

  • Convert a JSON cohort expression into a markdown print-friendly presentation.

  • Convert a JSON cohort expression into SQL.

Installation#

Install the python wrapper with pip:

pip install ohdsi-circe

Since this package only wraps the CirceR both Java and R are required. Full instructions on how to configure your R and Java environment can be found in the OHDSI documentation: Setting up the R environment.

On debian-based systems, install the dependencies boils down to:

sudo apt-get update
sudo apt-get install r-base openjdk-17-jdk openjdk-17-jre

install.packages("remotes")
remotes::install_github("OHDSI/CirceR")

Function Reference#

build_cohort_query(cohort_expression, options=None)#

Build Cohort SQL

Generates the OMOP CDM Sql to generate the cohort expression.

Wraps the R CirceR::buildCohortQuery function defined in CirceR/R/CohortSqlBuilder.R.

Parameters:

  • cohort_expression (RS4 | str) – An R object or a JSON string containing the cohort expression

  • options (RS4, optional) – The options object from create_generate_options, by default None

Returns:

contains the SQL statements

Return type:

StrVector

build_concept_set_query(concept_set_expression)#

Generates the OMOP CDM Sql to resolve the concept set expression

Wraps the R CirceR::buildConceptSetQuery function defined in CirceR/R/ConceptSetSqlBuilder.R.

Parameters:

concept_set_expression (str | dict) – a string containing the JSON for the conceptset expression.

Returns:

OHDSI Sql for the conceptset expression

Return type:

StrVector

cohort_expression_from_json(expression_json)#

Render read JSON into a R CohortExpression instance.

Reads a String (json) and deserializes it into a CohortExpression.

Wraps the R CirceR::cohortExpressionFromJson `` function defined in ``CirceR/R/CohortExpression.R.

Parameters:

expression_json (str | dict) – A JSON str or a dict representing a cohort expression

Returns:

A wrapped cohort expression R object

Return type:

RS4

Examples

>>> from importlib.resources import files
>>> cohort_str = files('ohdsi.circe.data').joinpath('simpleCohort.json')
...    .read_text()
>>> cohort = CohortExpression.cohort_expression_from_json(cohort_str)
cohort_print_friendly(expression)#

Create a print friendly version of a cohort expression.

Wraps the R CirceR::cohortPrintFriendly function defined in CirceR/R/PrintFriendly.R.

Parameters:

expression (RS4 | dict | str) – A str, dict or result of cohort_expression_from_json containing the cohort expression.

Returns:

A character vector containing the print friendly version of the cohort expression.

Return type:

StrVector

concept_set_expression_from_json(expression_json)#

Read JSON into a ConceptSetExpression instance.

Reads a String (json) and deserializes it into a ConceptSetExpression as the R library is a wrapper around the Java library.

Wraps the R CirceR::conceptSetExpressionFromJson function defined in CirceR/R/ConceptSetExpression.R.

Parameters:

concept_set (str | dict) – A JSON str or a dict representing a concept set expression

Returns:

A wrapped concept set expression R object

Return type:

RS4

concept_set_list_print_friendly(concept_set_list)#

Render conceptSet array for print-friendly

Generates a print-friendly (human-readable) representation of an array of concept sets. This can for example be used in a study protocol.

Wraps the R CirceR::conceptSetListPrintFriendly function defined in CirceR/R/PrintFriendly.R.

Parameters:

expression (str | dict) – A JSON str or a dict representing a concept set list

Returns:

A character vector containing the print friendly version of the concept set expression.

Return type:

StrVector

concept_set_print_friendly(concept_set)#

Create a print friendly version of a concept set expression

Wraps the R CirceR::conceptSetPrintFriendly function defined in CirceR/R/PrintFriendly.R.

Parameters:

expression (str | json) – A JSON str or a dict representing a concept set

Returns:

A character vector containing the print friendly version of the concept set expression.

Return type:

StrVector

create_generate_options(cohort_id_field_name=None, cohort_id=None, cdm_schema=None, target_table=None, result_schema=None, vocabulary_schema=None, generate_stats=None)#

Create Generation Options.

Creates the generation options object for use in build_cohort_query

Wraps the R CirceR::createGenerateOptions function defined in CirceR/R/CohortSqlBuilder.R.

Parameters:

  • cohort_id_field_name (str, optional) – The field that contains the cohortId in the cohort table, by default None

  • cohort_id (int, optional) – The generated cohort ID, by default None

  • cdm_schema (str, optional) – The value of the CDM schema, by default None

  • target_table (str, optional) – The cohort table name, by default None

  • result_schema (str, optional) – The schema the cohort table belongs to, by default None

  • vocabulary_schema (str, optional) – The schema of the vocabulary tables (defaults to cdmSchema), by default None

  • generate_stats (bool, optional) – A boolean representing if the query should include inclusion rule statistics calculation, by default None

Returns:

A wrapped generation options R object

Return type:

RS4

Examples

>>> options = create_generate_options()
>>> options = create_generate_options(
...     cohort_id_field_name='cohort_definition_id',
...     cohort_id=1,
...     cdm_schema='cdm',
...     target_table='cohort',
...     result_schema='results',
...     vocabulary_schema='cdm',
...     generate_stats=True
... )