Bioinfo Design Review

[MitchellShiell]

Dictionary Viewer Feedback Meeting

Goal

Gather feedback on design and usability of our dictionary viewer(s).

Objective

• Briefly demo table & ER diagram views
• Discuss table view design and usability feedback
• Carry out ER-diagram requirements gathering

Background

We have developed (and are potentially further developing) two complementary views for displaying Lectern data dictionary schemas:

• Table View: Transforms schema specifications into readable tables
• ER-Diagram View (in planning): Visualizes relationships between schemas

The dictionary table viewer is available as a standalone npm package and has been deployed to PCGL, with an additional Stage integration in progress.

---

Data Dictionary Viewer Feedback Summary

Key Links

• Table View: https://dictionary-viewer.submission.ingress.dev.k8s.pcgl.dev-sd4h.ca/
• ER Diagram View (Figma): https://www.figma.com/design/LILnnxiWOSiDF7k7IhBYmj/Overture_DataDictionary?node-id=3994-1550&t=XfdHLcMatLj8fhxU-1

---

Table View Feedback

What Works Well

• Conditional logic boxes are very useful and easy to understand (major improvement over ARGO's brief notes which were frequently overlooked)
• Table of Contents "jump" navigation is excellent for pointing data submitters to specific schemas
• Overall layout is well-organized and easy to navigate

What's Confusing

• No minimal/core submission definition (may be PCGL constraint)
• No domain responsibility indicators - unclear which domain (lab, clinician, etc.) is responsible for which part of submission (PCGL-specific but broadly applicable)
• Relationships between tables unclear - difficult to identify:
  • Foreign key entities
  • Core/required entities (tables)
  • Requirements/prerequisites for minimal submission

Missing Information

• Custom table/entity tags for filtering (e.g., specifying tables/fields relevant to other data models, domain-specific requirements)
• CPHI-specific requirements - ability to filter for minimal requirements corresponding to CPHI relevant fields
• Version differences - release notes/difference view to help submitters track changes in submission requirements
• Ontology references - no way to see reference ontologies for fields/terms (important for interoperability)
• Field counts - total fields overall and per schema (current filter shows "Required" but not "Optional" counts)
• Ontology mapping improvements (Big Ask): Currently lists strings; need ability to list objects with key-value pairs matching termsAontology:termBontology
  • Implementation consideration: user interaction to translate/transition between ontology terms
  • Could be fulfilled with custom columns using meta information

Navigation Issues

• Risk of overcrowding table view if too much information is added
• Solution: Create ER diagram that can be referenced from dictionary viewer table as a link

Visual Improvements

• Differentiate Required vs Optional fields - use different colors or highlighting for easier visual scanning
• Version selector layout - consider placing "prod_pcgl_schema" heading near version selector and "Clinical Submission Dictionary" on left for clarity

---

ER Diagram Review Feedback

Critical Relationships to Visualize

• Foreign keys - essential for understanding entity connections
• Required table dependencies - especially for conditional fields
• Cardinality - 1-to-1, 1-to-many relationships

Use Cases: When to Use ER Diagram vs Table View

Choose ER Diagram when:

• Understanding how entities are related
• Ensuring foreign keys are submitted correctly (not easy to see in Table view)
• Example: When submitting treatment information, ER diagram shows that submitter_treatment_id appears in both Treatment and Medication entities, indicating same ID must be used in both places
• Onboarding new team members

Choose Table View when:

• Preparing detailed data submissions
• Looking up specific field requirements
• Troubleshooting validation errors

Entity Display Requirements

• Keep minimal - current design is good, shows minimum required information
• Avoid overwhelming users with too much detail

Relationship Display Requirements

Connection lines should indicate:

• Cardinality (1-to-1, 1-to-many relationships) - HIGH PRIORITY

Potential Interactive Features

• Click entities to see details
• Filter relationships
• Filter Tables by custom tags (see domain issue above)
• Export diagrams - (frequent requests for PowerPoint slides showing ER diagram)
• Link to Table View for more detailed field information

---

General Workflow & Use Cases

Primary Use Cases

• Preparing data submissions (most common)
• Troubleshooting validation errors
• Onboarding new team members
• Communicating with data submitters about specific schemas

Current Pain Points Not Addressed

• Regex format unfamiliarity
  • Potential solution: Link regexes to online regex tester for testing values
  • Example: https://www.regexplanet.com/advanced/xregexp/index.html

Additional Features Requested

• Version comparison - this functionality exists in the ARGO viewer
• Ontology visibility - demonstrates data model strength in terms of interoperability
• Filtering improvements - ability to filter by "Optional" fields (currently only "Required") additionally ability to filter by custom meta field values
• Dynamic field counts - update based on active filters

---

Potential Implementations

• OHCRN - discuss with Brandon
• MOH - next year
• iMicroSeq - discuss with Bhavik - not a priority but pathoplexus, emma, may be viable
• Cancer Models (Cancermodels.org) - used them for feedback on initial design - funding gone - teams dead

---

Actionable Items

Prioritization of Proposed Feature Enhancements

Priority	Hardeep	Edmund	Linda
1	Ontology mapping	ER View/info	ER View/info
2	ER View/info	Ontology mapping	Custom tags filtering
3	Difference calc	Difference calc	Ontology mapping
4	Custom tags	Custom tags filtering	Difference calc

Consensus of Priorities

1. ER Diagram View/Information (2 votes for One, 1 vote for Two)
2. Ontology Mapping (1 vote for One, 2 votes for 2-3)
3. Custom Table Tags for Filtering (Quick Win)
4. Difference Calculation

---

Small/Quick Fixes

• Field anchor links
• Fix entity anchor links
• Remove comma from "PCGL reference question"
• Put regex in code blocks
• Add ability to filter entities by groups/domains (domains are meta field in Lectern)
• Implement custom filtering dropdowns based on provided meta properties

Medium/Large Features

• ER Diagram implementation with:
  • Cardinality indicators
  • Clickable entities
  • Export functionality
• Ontology mapping (objects with key-value pairs)
• Version difference view/calculator
• Custom entity tags for filtering
• Required vs Optional visual differentiation
• Link regexes to online testers
• Display field counts (total and per schema)
• Filter for optional fields