Home

Welcome to the mindcontrol wiki!

Introduction

What is mindcontrol?

Mindcontrol is a web application that can be configured to be a:

• quality checking tool
• pipeline output/status tracker
• brain editing tool
• data visualization tool

Core functionality

The features include:

• brain-voxel editor
• interactive histogram brushing based off metrics associated w/ an image
• brain volume viewer (and eventually brain surface viewer)

The user is expected to:

• fill the database with appropriate entries
• configure the UI
• apply brain-voxel edits to the actual nifti

Database Schema

A database entry (document) should look something like:

{entry_type: "",
subject_id:"examID",
metrics: {metric_name: metric_value}, //optional
check_masks: ["relative/path/to/nii.gz", "relative/path/to/other_nii.gz"] //optional
}

• entry_type corresponds to a particular table in the mindcontrol app. If you want a table that shows freesurfer output and another that shows the resting-state fMRI default mode network (and their associated metrics), you would have two separate documents, one with {entry_type: "freesurfer"} and another with {entry_type: "rsfmri"}
• subject_id isn't named appropriately - it refers to a specific subject+session, and should be a unique value that only corresponds to a particular subject at a particular session. One example could be "sub01sess01".
• metrics is another object with key,value pairs where the key is the metric name and value is a number
• check_masks isn't named appropriately for now, but it is a list of strings of relative paths to .nii.gz volumes

Connect to mongodb

In the mindcontrol folder, type

meteor mongo

The name of the collection is called subjects, so in the mongo shell, type:

db.subjects.findOne({})

This will return an entry in the database. If you want to find one entry of a particular entry type, do:

db.subjects.findOne({entry_type:"freesurfer"})

You can learn more about querying mongodb here: https://docs.mongodb.com/manual/tutorial/query-documents/

View/add/remove/update with Python

Most likely you want to update your database entries or add new ones, and you don't want to go through the mongo shell - instead, you can use python:

def get_collection(port=3001):
    from pymongo import MongoClient
    client = MongoClient("localhost", port)
    db =  client.meteor
    collection = db.subjects
    return collection, client

coll, cli = get_collection()
all_results = coll.find({"entry_type":"demographic"})
for results in all_result:
    print(r)    

For more info on using pymongo, see the documentation: https://api.mongodb.com/python/current/

You can insert a document by doing:

coll.insert_one({"subject_id":"fake_session", "msid":"fake_subject", "entry_type": "demographic",  'metrics': {'DCM_StudyDate': 20160907}, 'Study Tag': 'NHW2016', "DCM_InstitutionName": "WashU"})

You can update a document:

coll.update_one({"subject_id": 'sub17017', "entry_type": "demographic"}, {"$set": {"DCM_InstitutionName": "WashU"}})

Setting up the UI

To set up the different "modules", you must edit the mindcontrol/imports/python_generate/generator.json:

"modules": [
  {"name": "Exams", //title
    "entry_type": "demographic", //this matches the entry_type value in the collection
  "fields": [
    {"function_name": "get_filter_field", //this is a function that will allow you to filter the table by id
      "id": "subject_id", //field name 
      "name": "Exam ID" //title in the table
    },
    {"function_name": "get_filter_list_field", //this function allows you to filter by items in list
      "id": "Study Tag", //field name
      "name": "Study Tag" //title
    },
    {"function_name": "get_filter_list_field",
      "id": "status",
      "name": "pipeline status"
    },
    {"function_name": "get_filter_field",
      "id": "metrics.DCM_StudyDate",
      "name": "Date"
    }
  ],
  "graph_type":"datehist", //do the date histogram plot
  "showgraph": true} //by default, show the plot (might want to change to false if there is a lot of data)
]

A freesurfer entry could look like:

{
      "name": "Freesurfer",
      "entry_type": "freesurfer",
      "fields": [
        {
          "function_name": "get_filter_field",
          "id": "subject_id",
          "name": "Exam ID"
        },
        {
          "function_name": "get_qc_viewer", //when you click on a freesurfer ID, the QC viewer page will open
          "id": "name",
          "name": "Freesurfer ID"
        },
        {
          "function_name": "get_qc_filter_field", //allows you to filter by QC status 
          "id": "quality_check.QC",
          "name": "QC"
        },
        {
          "function_name": "get_filter_field",
          "id": "checkedBy",
          "name": "checked by"
        },
        {
          "function_name": "get_filter_list_field",
          "id": "quality_check.user_assign",
          "name": "Assigned To"
        },
        {
          "function_name": null,
          "id": "quality_check.notes_QC",
          "name": "Notes"
        }
      ],
      "graph_type": "histogram", //do the histogram plot
      "colormaps": {
        "0":{"name": "Grayscale", //the first image in "check_masks" will be rendered w/ a grayscale colormap
            "alpha": 1,
            "min": 0
        },
        "1": {
          "name": "custom.Freesurfer", //this is a custom colormap defined in mindcontrol
          "alpha": 0.25
        }
      }

Once this is edited, in python run:

python imports/python_generate/generate_mindcontrol.py

This script writes 3 files:

mindcontrol/api/module_tables.js
mindcontrol/ui/module_templates.js
mindcontrol/ui/module_templates.html

Anytime you edit this .json, you should rerun this python command.