14.2.88. camcops_server.cc_modules.cc_redcap

camcops_server/cc_modules/cc_redcap.py


Copyright (C) 2012-2019 Rudolf Cardinal (rudolf@pobox.com).

This file is part of CamCOPS.

CamCOPS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

CamCOPS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with CamCOPS. If not, see <http://www.gnu.org/licenses/>.


Implements communication with REDCap.

(Thoughts from 2019-01-27, RNC.)

REDCap concepts

  • Project: the basic security grouping. Represents a research study.
  • Arms: not an abbreviation. Groups study events into a sequence (an “arm” of a study). See https://labkey.med.ualberta.ca/labkey/wiki/REDCap%20Support/page.view?name=rcarms.
  • Instruments: what we call tasks in CamCOPS. Data entry forms.
  • Metadata/data dictionary: you can download all the fields used by the project.
  • REDCap Shared Library: a collection of public instruments.

My exploration

  • A “record” has lots of “instruments”. The concept seems to be a “study visit”. If you add three instruments to your project (e.g. a PHQ-9 from the Shared Library plus a couple of made-up things) then it will allow you to have all three instruments for Record 1.

  • Each instrument can be marked complete/incomplete/unverified etc. There’s a Record Status Dashboard showing these by record ID. Record ID is an integer, and its field name is record_id. This is the first variable in the data dictionary.

  • The standard PHQ-9 (at least, the most popular in the Shared Library) doesn’t autocalculate its score (“Enter Total Score:”)…

  • If you import a task from the Shared Library twice, you get random fieldnames like this (see patient_health_questionnaire_9b):

    Variable / Field Name           Form Name
    record_id                   my_first_instrument
    name                            my_first_instrument
    age                         my_first_instrument
    ipsum                           my_first_instrument
    v1                          my_first_instrument
    v2                          my_first_instrument
    v3                          my_first_instrument
    v4                          my_first_instrument
    phq9_date_enrolled          patient_health_questionnaire_9
    phq9_first_name                 patient_health_questionnaire_9
    phq9_last_name                  patient_health_questionnaire_9
    phq9_1                          patient_health_questionnaire_9
    phq9_2                          patient_health_questionnaire_9
    phq9_3                          patient_health_questionnaire_9
    phq9_4                          patient_health_questionnaire_9
    phq9_5                          patient_health_questionnaire_9
    phq9_6                          patient_health_questionnaire_9
    phq9_7                          patient_health_questionnaire_9
    phq9_8                          patient_health_questionnaire_9
    phq9_9                          patient_health_questionnaire_9
    phq9_total_score            patient_health_questionnaire_9
    phq9_how_difficult          patient_health_questionnaire_9
    phq9_date_enrolled_cdda47   patient_health_questionnaire_9b
    phq9_first_name_e31fec          patient_health_questionnaire_9b
    phq9_last_name_cf0517           patient_health_questionnaire_9b
    phq9_1_911f02                   patient_health_questionnaire_9b
    phq9_2_258760                   patient_health_questionnaire_9b
    phq9_3_931d98                   patient_health_questionnaire_9b
    phq9_4_8aa17a                   patient_health_questionnaire_9b
    phq9_5_efc4eb                   patient_health_questionnaire_9b
    phq9_6_7dc2c4                   patient_health_questionnaire_9b
    phq9_7_90821d                   patient_health_questionnaire_9b
    phq9_8_1e8954                   patient_health_questionnaire_9b
    phq9_9_9b8700                   patient_health_questionnaire_9b
    phq9_total_score_721d17         patient_health_questionnaire_9b
    phq9_how_difficult_7c7fbd   patient_health_questionnaire_9b
    

The REDCap API

  • The basic access method is a URL for a server/project plus a project-specific security token.
  • Note that the API allows you to download the data dictionary.

Other summaries

So, for an arbitrary CamCOPS-to-REDCap mapping, we’d need:

  1. An export type of “redcap” with a definition including a URL and a project token.
  2. A configurable patient ID mapping, e.g. mapping CamCOPS forename to a REDCap field named forename, CamCOPS ID number 7 to REDCap field my_study_id, etc.
  3. Across all tasks, a configurable CamCOPS-to-REDCap field mapping (potentially incorporating value translation).
    • A specimen translation could contain the “default” instrument fieldnames, e.g. “phq9_1” etc. as above.
    • This mapping file should be separate from the patient ID mapping, as the user is quite likely to want to reuse the task mapping and alter the patient ID mapping for a different study.
    • UNCLEAR: how REDCap will cope with structured sub-data for tasks.
  4. A method for batching multiple CamCOPS tasks into the same REDCap record, e.g. “same day” (configurable?), for new uploads.
  5. Perhaps more tricky: a method for retrieving a matching record to add a new task to it.