WebAPI Release 2.2.0 Planning

[chrisknoll]

Update 9/21/2017:
We've extended the deadline for submitting pull requests to 9/29/2017.

Update 9/7/2017:
Below is an enhancement matrix of completed requests:

• Cohort Characterization @alondhe
• Cohort Comparison @pbr6cornell
• Vulnerability Fixes @gklebanov
• Cohort Analysis code sharing @gklebanov
• Cohort Definition external library @gklebanov , @chrisknoll
• Atlas charting library externalized and upgraded to d3v4 @gklebanov , @chrisknoll
• New graph in datasources @PRijnbeek
• Performance enhancements in data sources @PRijnbeek
• Data completeness @chen-regen
• Observation Entropy @chen-regen
• Timeliness @chen-regen
• WebAPI PLP specification and editor @jreps
• Cohort collapse option (era-fy) @gowthamrao
• Same-visit cohort criteria @gowthamrao
• Cost table option in cohort criteria @gowthamrao
• Use payer plan period in cohort criteria @gowthamrao
• Combine cohrots into new cohorts @gowthamrao
• Additional cohort characterization options @gowthamrao
• Concept set quickview in Atlas @jhardin29
• Big Query support @t-abdul-basser
• Assorted Achilles Heel enhacements @t-abdul-basser
• Embeded DB into WebAPI @t-abdul-basser, @alondhe
• Estimation enhancements @anthonysena

Please comment in this thread if any of the above has been merged into master and should be marked completed.

Original Message:

The OHDSI Web Architecture group is planning a 2.2.0 release prior to the 2017 OHDSI Symposium. This thread is to call for contributions for features that we'd like to include in this release scheduled for 10/1/2017.

Contributions are due 9/22/2017 for inclusion in the release, to be provided as a pull request .

In order to submit an idea for a feature, please respond to this thread with the following information by 8/22/2017 so that we can anticipate any potential challenges for incorporating the features:

• A short description of the feature
• The organization or developers that are involved in the implementation
• Any anticipated impact to current WebAPI/Atlas functionality (if applicable)

After you have responded to this thread, please create a new issue so that the specific feature can be tracked in the V2.2.0 milestone.

Thank you!

[alondhe]

Hi @chrisknoll ,

I'm interested in adding a cohort characterization feature to Atlas.

- A short description of the feature
This feature would allow us to generate characteristics of cohorts designed in Atlas's cohort designer. It would run a version of FeatureExtraction (in a Java wrapper) to obtain a set of patient features that then could be viewable in Atlas.

- The organization or developers that are involved in the implementation
Aside from myself, @chrisknoll , @pbr6cornell , @fdefalco , @anthonysena have expressed interest in working on this.

- Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
This would replace the existing "Reporting" tab in Atlas.

Thanks,
Ajit

[pbr6cornell]

@alondhe @chrisknoll

If we add a 'cohort characterization' feature, I would like to work on adding a 'cohort comparison' functionality.

-A short description of the feature
Input: Select 2 cohorts that have been generated and have characterization completed.
Output: View the cohort characterization results 'side-by-side' and calculate comparative metrics, such as standardized difference, relative risk, risk difference. Display the results in tabular form for quick sort/filter capability, but also as a scatterplot, with cohort 1 covariate mean on y-axis and cohort 2 covariate mean on x-axis, 45 degree line to show where we expect comparable covariates. Each covariate would be a dot on the graph, we could use color and size elements of the dots for covariate attributes, such as domain or standardized difference.

-The developers that are involved
I can write the OHDSql that would take 2 cohort characterization results and pull together one dataframe that also calculates the summary statistics. I'll need help from @chrisknoll @anthonysena @fdefalco to get that new WebAPI call into ATLAS and build out the UI.

• Any antipicated impact on current WebAPI/Atlas functionality
  I see this as a new feature, which would represent a new component on the left-hand menu. It does not change or replace existing functions, but is dependent on the new cohort characterization component that @alondhe is leading.

[jreps]

I'm interested in adding a PLP specification editor and viewer

[gowthamrao]

@alondhe We would like to contribute to cohort characterization and cohort comparison.
We want to add financial and exposure measures to the features being compared

[gklebanov]

@pbr6cornell , @chrisknoll , @alondhe, @gowthamrao - we would also be interested in being a part of the contributing team. Thank you for sharing this!

[gklebanov]

we (Odysseus) would like to contribute to the following:

• vulnerability fixes (based on VA/HP code). This will require merging existing code with the latest branch but also additional SQLRenderer development as this code is not available from VA/HP.
• improve cohort and analysis code sharing (server side rendering, enhancing API) e.g. server side population level effect estimation code generation and export
• discuss a possibility of having some additional shared components (modules) e.g. decoupling CohortExpressionQueryBuilder from WebAPI to enable re-usable SQL cohort generation, finish updating D3.js
• templated and pre-packaged (packrat) analysis code. This is probably not directly related to ATLAS however might affect what ATLAS generates

[anthonysena]

Thanks everyone! Per @chrisknoll's original note, let's create new issues so that we can start the individual discussions required for each feature. I'll then work to link them to both the V2.2.0 milestone, this issue and even to issues in the other repositories where contributions will be made.

@alondhe - please be sure to tag @gowthamrao in your issue so that we can take a look at inclusion of the measures he mentioned for the cohort characterization work.

@gklebanov - thanks for putting these items forward! Along with creating a new issue for each of these contributions, can you share any work that has been done? This will be helpful us to understand the feature itself and the impact when we want to merge all of these contributions together.

Tagging contributors not directly mentioned above: @jreps, @fdefalco, @pbr6cornell

[PRijnbeek]

Great initiative!

From the European Medical Information Framework we like to add the following features:

Feature 1.

A short description of the feature
Add a new graph in DataSources that shows the number of people that have more than 1,2,3,4 etc occurrences of a concept, e.g. number of BMIs

The organization or developers that are involved in the implementation
EMIF, persons involved: @PRijnbeek, @lhalvors, Michel Van Speybroeck

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
This has impact on Achilles R, WebApi, (Achilles Web), Atlas

Feature 2.

A short description of the feature
Improve the performance of the datasource tab considerably. Currently, the report loading is very slow because of the on-the-fly creation of the graphs from the Achilles results set. We have improved the speed by adding new intermediate Achilles tables created by Achilles R. This makes the interface responsive again.

The organization or developers that are involved in the implementation
EMIF, persons involved: @PRijnbeek, @lhalvors, Michel Van Speybroeck

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
This has impact on Achilles R, WebApi, (Achilles Web), Atlas

These features will be combined in one pull request.

Thanks,
Peter, Lars, Michel

[chen-regen]

Per @anthonysena , I am summarizing what Regenstrief has been working on and will work on below. Those new features are cohort analysis (old Heracles) related.

1. Data completeness

A short description of the feature
Generate a table with percentages to indicate how complete the person data is for gender, race and ethnicity. For example, for patients age 0~10, 65% has race data, etc.

The organization or developers that are involved in the implementation
Chen at Regenstrief

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
Back-end will be in WebAPI cohort analysis
Atlas changes will be under cohort->reporting

2. Observation entropy

A short description of the feature
Calculate Shannon entropy for column observation.value_as_string per day and show them in a line chart.

The organization or developers that are involved in the implementation
Chen at Regenstrief

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
Back-end will be in WebAPI cohort analysis
Atlas changes will be under cohort->reporting

3. Timeliness

A short description of the feature
Calculate average delay time between observation.observation_date and row_created_db_time each day and show them in chart.

The organization or developers that are involved in the implementation
Chen at Regenstrief

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
Back-end will be in WebAPI cohort analysis
Atlas changes will be under cohort->reporting

I have pushed changes for the first 2 features into WebAPI and Atlas R21 branches. I will create pull requests later after I get Anthony's OK.

Thanks,
Chen

[anthonysena]

@PRijnbeek - thank you for detailing the work that you and the EMIF team have done. Would you please create a separate WebAPI issue that references this one? You may refer to the one Ajit just created (#222) and we can then use this issue to reference the code that your team will contribute back across the different OHDSI repositories.

@chen-regen - I'd kindly ask you to do the same as @PRijnbeek and create a new issue for your work that references this one so we can keep these connected. We'll have to discuss how to best bring your work into this release given the work being done in #222. If you'd like to put in a PR for the items you've completed to start, we can look at possibly bringing those into a 2.1.1 build.

[chen-regen]

Hi @anthonysena , I have created issue #223 . Thank you!

[gowthamrao]

1. New options during Atlas cohort build process

A short description of the feature

• Cohort collapse criteria - Era-fy (COMPLETE)
  Subsumes
  Option for Cohort end-date to be visit-end-date instead of observation period end date
  Select the maximum of two records with same cohort start date
  Collapse overlapping cohort eligibility period into a continuous period

• Cost table: option to select visits with certain costs (discussed Atlas Cohort issue - cohort with certain procedure in the same visit with a certain diagnosis Atlas#454 (comment)) . e.g. select all visits with costs > 25,000$s or visits with 0$s paid amount and > 0 copay amount. Dependent on Cost table changes (add PERSON_ID, dates and normalize) CommonDataModel#81 proposal.

• Use payer-plan-period table during cohort build. Be able to define primary events, qualifying inclusion criteria or cohort exit criteria based on payer_source_value, plan_source_value, family_source_value, payer_plan_period_start_date and/or payer_plan_period_end_date Cohort build - using payer-plan-period circe-be#4 Contract_owner in payer_plan_period table CommonDataModel#107 Payer_plan_period - new fields to allow standardized health economic analysis CommonDataModel#120 Contract_owner in payer_plan_period table CommonDataModel#107

• Cohort with events from various domains in the same visit (COMPLETE) during cohort build, use an option to restrict to same visit_occurrence_id (or visit_detail_id) Atlas Cohort issue - cohort with certain procedure in the same visit with a certain diagnosis Atlas#454 and PR here Events within visit circe-be#7

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
WebApi changes: additions/modifications to cohortdefinition resource
Atlas changes: new UX options under cohort definition

2. Combine Atlas Cohorts to a new cohort

OHDSI/Atlas#398

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
WebApi changes: needs a new resource that combines cohorts.
Atlas changes: new section 'Combine cohorts' between Cohorts and Incidence Rates in Atlas.

3. Cohort characterization, add ability to compute the following:

Exposure of a cohort #235

• Given a cohort, return unique number of dates of exposure for cohort.
• Number of months may then be calculated by total unique person-dates/30.5)

Total Cost computation

• Total cost during cohort period, stratified by cost_domain_id and cost_type_concept_id
• cost_type_concept_id differentiates between amount_allowed, total_cost, total_charge etc
• cost_domain_id differentiates between costs related to visit, drug, condition, procedure etc.
  dependent on pending proposal Cost table changes (add PERSON_ID, dates and normalize) CommonDataModel#81

Characterize cohorts based on following person-time metrics

• unique visits per 1,000 subjects per 1 year of exposure (total unique visits by all subjects * 365.25)/(total unique person-dates for all subjects)
• costs per subject per month (total unique cost* 30.5)/(total unique person-dates)

The organization or developers that are involved in the implementation
@gowthamrao, Tommy, Cedrick

[jhardin29]

Hi @chrisknoll ,

I'm interested in adding a concept set enhancement feature to Atlas.

• A short description of the feature
  This feature would allow us to easily navigate concept sets in the ATLAS UI. Specifically one could click on the concept set and automatically be taken to the concept set and visualize the exclusions, descendants vs. having to click to the concept set tab filter to the concept set to examine the contents.

• The organization or developers that are involved in the implementation
  Aside from myself, @chrisknoll.

• Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
  This would enhance the existing method for examining concept set contents in Atlas.

Thanks,
Jill

[t-abdul-basser]

1. BigQuery Support

Short description of the feature

Add (partial) BigQuery support to core OHDSI component applications (Achilles, WebAPI & Atlas), specifically, allow users to generate Achilles results from a OMOP CDM 5.x in BigQuery, view the generated profiling reports in the Atlas Data Sources component, define and generate cohorts against BigQuery, etc.

Organization/developers involved in the implementation

@t-abdul-basser (Columbia DBMI) @myl-google (Google) with assistance from several others.

Anticipated impact to current WebAPI/Atlas functionality

SqlRender, Achilles, WebAPI, Atlas have been or will enhanced

See

WebAPI PR #210

Changes have already been made to SqlRender SQlRender/#70,SQlRender/#71,SQlRender/#72,SQlRender/#77,SQlRender/#79.

2. Assorted Achilles Heel enhancements

Short description of the feature

Cleans up Achilles Heel including

• enhance the text in the Achilles Heels error/warning/notifications for readability
• add category description to each error/warning/notifications
• adding sortability by n

Organization/developers involved in the implementation

@t-abdul-basser (Columbia), @mark-velez (Columbia).

Anticipated impact to current WebAPI/Atlas functionality

Atlas, Achilles

3. Add embedded DB WebAPI to contain OHDSI schema

Short description of the feature

Add an embedded DB (such as H2) to contain OHDSI schema.

Organization/developers involved in the implementation

@t-abdul-basser (Columbia)

Anticipated impact to current WebAPI/Atlas functionality

WebAPI will support same functionality as current version but will be made easier to deploy, configure, update and maintain.

[alondhe]

Hey @t-abdul-basser and @mark-velez -- just curious about the Achilles Heel enhancements. I've made a few enhancements in the Janssen version of this report in AchillesWeb, see below. If you haven't already begun, perhaps we can utilize some of this work. Let me know!

[t-abdul-basser]

Yes I was planning to reach out to you to see if we could coordinate :) This looks great!

Two points:

1. I propose to pull out n to a separate sortable column and make messages more readable.
2. These changes should be made to Atlas not in AchillesWeb since new features should be added to Atlas and AchillesWeb development should restricted to maintenance (fixes) of existing functionality.

[mark-velez]

@alondhe this looks great, something many, no, all of us want. Where and how are annotations currently stored? I think we'll have a bunch of questions; is there a branch somewhere to help us find the answers? :)

[alondhe]

@mark-velez currently this is just a "quick and dirty" approach. Our annotations are currently just stored in Excel files, but in the new version of AchillesWeb, I've added support for displaying 'Annotation Status' and 'Annotation Message' as columns if the AchillesHeel JSON file has these two columns as JSON arrays.

I'll make a branch of AchillesWeb and tag it here soon.

@t-abdul-basser -- fully agree that we shouldn't do too much more with AchillesWeb, but rather, Atlas Data Sources should be the focus. This was just a little "quick win" since we still use AchillesWeb over Atlas Data Sources.

I would add that a good long-term vision I'm interested in is to add an annotation WebAPI hook that could be leveraged throughout Atlas. Annotations could sit in the metadata table that is proposed here: OHDSI/CommonDataModel#79. And the UI could be altered to support inline editing (which could be locked down to key users through Shiro).

[alondhe]

Here's that branch: https://github.com/OHDSI/AchillesWeb/tree/heel_annotations

[anthonysena]

Hi,

I'm adding another item that I'd like to target for this next release related to the Estimation feature in Atlas/WebAPI:

A short description of the feature
Extend the Atlas estimation specification feature to allow for the specification of multiple target/comparator/outcomes. Revise the JSON representation of the estimation specification produced in Atlas to match ones that can be consumed directly by CohortMethod (e.g. analysis specification and t/c/o specification). We'd also like to follow this approach for the PLP feature proposed in #224.

The organization or developers that are involved in the implementation
@fdefalco @schuemie

Any anticipated impact to current WebAPI/Atlas functionality (if applicable)
This will be a breaking change as estimation specification storage will likely change as part of this enhancement. We'll attempt to preserve backwards compatibility or provide a migration path for existing specifications.

[gklebanov]

@anthonysena @schuemie @pavgra @fdefalco

Hi Anthony,

Fantastic proposal. Our team has done some work in this domain and we would like to collaborate with you guys, including sharing our findings and ideas as a start.

[vojtechhuser]

This listing table must have a column called RuleID. It is in the result table. It leads the user to what logic generated the message.

[anthonysena]

Closing out this thread since the V2.2.0 release has been completed. We'll revisit some of these items when we start the V2.3.0 release planning.