Phase 2 Design

[rmanaem]

functional requirements

• select a configuration for the annotation process
  • only the default neurobagel config will be available
• map columns to predefined variables (coming from config file)
• download data dictionary only at the last step/page
  • the data dictionary will include the annotations field for all mapped columns
  • columns will have empty strings for TermURL and Label fields both in the bids section and the Annotation field

{
  "age": {

    "Description": "Participant age",
    "Unit": "Years",
    "IsAbout": {
        "TermURL": "nb:Age",
        "Label": "Chronological age"
     },
    "Transformation": {
        "TermURL": "",
        "Label": ""
      },
    "Annotations": {
      "IsAbout": {
        "TermURL": "nb:Age",
        "Label": "Chronological age"
      },
      "Transformation": {
        "TermURL": "",
        "Label": ""
      }
    }
  }
}

{
  "sex": {
    "Description": "Sex variable",
    "Levels": {
      "M": {
          "Description": "Male"
          "TermURL": "",
        },
      "F": {
          "Description": "Female"
          "TermURL": "",
        }
    },
    "Annotations": {
      "IsAbout": {
        "TermURL": "nb:Sex",
        "Label": "Sex"
      },
      "Levels": {
        "M": {
          "TermURL": "",
          "Label": ""
        },
        "F": {
          "TermURL": "",
          "Label": ""
        }
      }
    }
  }
}

user flows

actions users can take in the app (high level)

1

• upload data table and no data dictionary or bids data dictionary
• edit data dictionary
  • optional actions include: providing/editing description for columns, designating the appropriate field for column, providing/editing descriptions for Levels, and specifying/editing the unit
• select/check configuration (neurobagel config is selected by default)
• proceed to the next step/page
• map columns to the appropriate predefined variables
• download the augmented data dictionary

2

• upload data table and upload an output data dictionary
• edit data dictionary
  • optional actions include: editing the description for columns, editing the description for levels, editing the unit*
• select/check configuration (neurobagel config is selected by default)
  • a validation will inform the user if the selected config doesn't match their output data dictionary**
• proceed to the next step/page
• check/edit the existing mapping of columns to the predefined variables
• download augmented data dictionary

notes
* UI elements for designating the appropriate field Levels/Unit have been disabled since the dictionary now contains information on the mapping and changing this would result in a mismatch between a column type and the type of the predefined variable the column was mapped to
** If there is a mismatch between the predefined vars in the data dictionary and the newly selected configuration the user should be informed but how should the tool handle it? (Also can we store the configuration name in the Annotations field?)

• don't allow the user to proceed?

structure of state

_what things to keep track of and what objects / structure to use to keep track of them

• default state
• data table
• data dictionary
• selected configuration
• mapping of columns to predefined variables

structure of configuration file

what things should the file entail and what objects / structure to use for them

• predefined variables
  • label/name
  • TermURL e.g., nb:sex
  • explanation (for later on how to annotate)
  • type of variable: continuous/categorical
  • if categorical, the list of possible options/ontology
    • Do we want to allow configuring possible transformations? that would mean we have to implement logic for every additional transformation

UI mock/sketches that can be discussed (based on user flows)

Refer to Miro board for better view:
https://miro.com/app/board/uXjVLwM4YiM=/?share_link_id=181392246748

rough idea of what components to make for UI

• parent/page component
  • table, instruction, download button

[surchs]

Thanks @rmanaem. Can you link the miro board you want us to look at?

[rmanaem]

Closing this as addressed since we now have the entire user flow available here: neurobagel/planning#224 (comment)