Adding a relationship layer to associate instruments with projects outside of the test battery

[ridz1208]

As it stands in our database we have associations between Projects and cohorts, projects and visits and visits and cohorts. There exist no core association between instruments and any other study entity.

An association can be weakly derived in one of 2 ways:

1. check the flag data for what instruments exist under what session and map the instruments using session to sites/projects/cohorts. Not ideal as the flag table is only populated when data is collected, the instrument is not affiliated to anyone upon its creation.
2. check the test_battery table and do a similar mapping to visits which leads to projects and cohorts (no affiliation to sites in this path). the Test battery is an optional table only used in cases where the study has a predefined battery of instruments per session.

In either of these cases, there exist no guarantees that any and all instruments can be linked to either a Project or a site in any reliable manner.

Suggestion:

Establish an instrument_visit_project_cohort_rel table to exhaustively list the instruments and their possible affiliations to different visits/cohorts/projects. This table does NOT replace the test battery, it doesn't server the same purpose.

This table can serve to derive which Projects can view and use which instruments (critical for institutional instances to manage ownership and access on project's instruments).

The primary key of this table can then be used in the test_battery table to simplify it, it would strip the cohort column, visit column and testname column and ensures instruments are not incorrectly set in the battery of visits not linked to the proper cohorts and cohorts not linked to the proper projects and visits. it also allows the possibility to now link a battery all the way up to a project (project is currently not a factory in battery matching).

with the added granularity, instruments can be associated to different subgroups for different visits/cohorts/projects instead of relying on a single subgroup association across the entire database.

Implementing these changes would result in a test_battery with the following fields:

`ID` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `AgeMinDays` int(10) unsigned DEFAULT NULL,
  `AgeMaxDays` int(10) unsigned DEFAULT NULL,
  `Active` enum('Y','N') NOT NULL DEFAULT 'Y',
  `Stage` varchar(255) DEFAULT NULL,
  `InstrumentVisitProjectCohortRelID` int(10) unsigned NOT NULL,
  `CenterID` int(11) DEFAULT NULL,
  `firstVisit` enum('Y','N') DEFAULT NULL,
  `instr_order` tinyint(4) DEFAULT NULL,
  `DoubleDataEntryEnabled` enum('Y','N') NOT NULL DEFAULT 'N',

While the new table would look like

REATE TABLE `instrument_visit_project_cohort_rel` (
  `InstrumentVisitProjectCohortRelID` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `TestNameID` int(10) unsigned NOT NULL,
  `VisitProjectCohortRelID` int(10) unsigned NOT NULL,

  PRIMARY KEY (`InstrumentVisitProjectCohortRelID`),

  CONSTRAINT `UK_instrument_visit_project_cohort_rel`
    UNIQUE KEY (`TestNameID`, `VisitProjectCohortRelID`),

  CONSTRAINT `FK_ivpcr_TestNameID`
    FOREIGN KEY (`TestNameID`)
    REFERENCES `test_names` (`ID`)
    ON DELETE CASCADE
    ON UPDATE CASCADE,

  CONSTRAINT `FK_ivpcr_VisitProjectCohortRelID`
    FOREIGN KEY (`VisitProjectCohortRelID`)
    REFERENCES `visit_project_cohort_rel` (`VisitProjectCohortRelID`)
    ON DELETE CASCADE
    ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Automatic population of the new table is possible through a combination check on the flag and test_battery table establishing it as the ultimate source of truth for this association.

Further discussion required o nthe possibility to activate/disactivate such entries if needed and the impact of the canidate --> session --> flag table's integrity (should they link to the new structure or remain independent)

[regisoc]

I was starting to try something on that line to manage dynamic battery changes we have on HBCD.
We might also extend it by simplifying all rel tables associated with the visit/cohort/project side.

I did not dig it much, is there a reason and/or strong incentive to keep the structure LORIS has? i.e.:

adding the FK_ivpcr_VisitProjectCohortRelID constraint will add another level on top of that structure.

What if we put all CohortID, ProjectID, VisitID, InstrumentID/TestNameID as direct references in this new rel table (instrument_visit_project_cohort_rel) as non null values, i.e.

CREATE TABLE `instrument_visit_project_cohort_rel` (
    `InstrumentVisitProjectCohortRelID` int(10) unsigned NOT NULL AUTO_INCREMENT,
    `ProjectID` int(10) unsigned NOT NULL,
    `CohortID` int(10) unsigned NOT NULL,
    `VisitID` int(10) unsigned NOT NULL,
    `TestNameID` int(10) unsigned NOT NULL,
    
    PRIMARY KEY (`InstrumentVisitProjectCohortRelID`),
    
    CONSTRAINT `UK_instrument_visit_project_cohort_rel`
        UNIQUE KEY (`ProjectID`,`VisitID`,`CohortID`,`TestNameID`),
    
    CONSTRAINT `FK_ivpcr_TestNameID`
        FOREIGN KEY (`TestNameID`)
        REFERENCES `test_names` (`ID`)
        ON DELETE CASCADE
        ON UPDATE CASCADE,
    
    CONSTRAINT `FK_ivpcr_VisitID`
        FOREIGN KEY (`VisitID`)
        REFERENCES `visit` (`VisitID`)
        ON DELETE CASCADE
        ON UPDATE CASCADE,

    CONSTRAINT `FK_ivpcr_ProjectID`
        FOREIGN KEY (`ProjectID`)
        REFERENCES `Project` (`ProjectID`)
        ON DELETE CASCADE
        ON UPDATE CASCADE,

    CONSTRAINT `FK_ivpcr_CohortID`
        FOREIGN KEY (`CohortID`)
        REFERENCES `cohort` (`CohortID`)
        ON DELETE CASCADE
        ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

and migrate data + remove visit_project_cohort_rel and project_cohort_rel?

What I can see immediately:

• [good] it is does not modify the change you already put for the test_battery.
• [good] it is a single table, exhaustive and centralized.
• [good] it is far easier to understand i.e. querying it will give all information about these entities with joins to the main tables (e.g. to get the name/activate state). This is less cumbersome than doing (and remembering the name ordering of):
  • test_battery
  • joins instrument_visit_project_cohort_rel
  • joins visit_project_cohort_rel
  • joins project_cohort_rel
  • joins project/cohort/instrument/visit with correct bindings.
• [bad] it asks for a refactor, searching all queries involved with this change.

The session should also have a FK coming from instrument_visit_project_cohort_rel to replace the corresponding ProjectID/CohortID/Visit_label.