Girder for MindLogger

Data Management Platform

Contents

1. Requirements
2. Installation
3. Deployment
4. Data Structure
5. Links
6. Contributing
7. Girder Source

Requirements

• MongoDB >= 3.6
• Python >= 3.5 - CherryPy <=11.0.0
• Node >= 8.0

Installation

Linux/Mac

1. Create and activate a virtual environment (replace ~/girder_env if you want your virtual environment somewhere else). On launches after the first, only the line beginning with source is necessary.

   python3 -m venv ~/girder_env
   source ~/girder_env/bin/activate
   pip install -U pip setuptools

2. Start MongoDB.

   mongod &

3. From the root of this repository, install and build Girder for MindLogger.

   pip install -e .
   girderformindlogger build

   Note: if pip install -e . fails with assert tag is not None, 'cant parse version %s' % tag from setuptools_scm, check for git tags with ``-``s and delete those tags or replace them with ``+``s.

4. Start Girder for MindLogger.

   girderformindlogger serve

5. When you're finished

   1. kill Girder for MindLogger,

      <Ctrl> + c

   2. kill MongoDB, and

      fg

      <Ctrl> + c

   3. deactivate your virtual environment.

   deactivate

Windows

1. In Windows Powershell, create and activate a virtual environment (replace $HOME\girder_env if you want your virtual environment somewhere else). On launches after the first, only the line ending with Activate.ps1 is necessary.

   python3 -m venv $HOME\girder_env
   $HOME\girder_env\Scripts\Activate.ps1
   pip install -U pip setuptools

2. Start MongoDB.

   mongod

3. Open a new PowerShell terminal and navigate to the root of this repository. Reactivate the virtual environment and then install and build Girder for MindLogger.

   $HOME\girder_env\Scripts\Activate.ps1
   pip install -e .
   girderformindlogger build

4. Start Girder for MindLogger.

   girderformindlogger serve

5. When you're finished

   1. kill Girder for MindLogger

      <Ctrl> + c

   2. kill MongoDB

      <Ctrl> + c

   3. deactivate your virtual environment.

   deactivate

Deployment

See CONTRIBUTING.rst#deployment.

Elastic Beanstalk

If you're updating an existing Girder 2.x instance of Elastic Beanstalk, be sure to change your static files path from clients/web/static to girderformindlogger/web_client/static/.

Data Structure

Girder for MindLogger uses reprolib and has the following underlying data structure. Note: This project is still in version 0 and these descriptions and diagrams may sometimes diverge from the actual data structure as we develop.

The diagram below shows how the reproschema classes (protocol, activity and screen) fit between the user handling (access and customization, in applet in the Girder for Mindlogger backend) and the display implementation (the UI components handled in the front-end applications).

https://api.mindlogger.org/api/v1 displays a comprehensive list of currently available API calls including parameters, notes about what the operations do, and notes about deprecation.

In transit between the (access-controlled) API and the (BSON storage) database, all data in MindLogger are shaped into one or more of the data models defined in the submodules of girderformindlogger.models. Here is a brief overview of those data models. Rather than duplicate documentation provided elsewhere (and risk sliding out of sync), links are provided to further documentation where appropriate.

Because all of these data are stored in BSON, arbitrary additional keys and values can be included in an instance of any of the data models. For models unique to MindLogger (ie, involved in implementation beyond the protocol level), a data dictionary is provided here.

activity

An Activity as defined in reproschema, stored as a Girder folder.

cached is autogenerated once the activity is parsed on the server.

api_key

A model inherited from Girder.

applet

An access-controlled, potentially customized, implementation of a protocol within MindLogger, stored as a Girder folder.

Attribute Name	Required	Type	Autogenerated
{keys required for Girder Folders}	true	{various}	{mostly}
meta.applet	true	dict	false
meta.protocol	true	dict	false
roles	true	dict	true
cached	true	dict	true

meta.protocol defines the protocol for the the applet.

meta.applet defines applet-level customization, including scheduling.

roles is an Object with the following structure, where the innermost array is populated with ObjectIds:

{
  "coordinator": {
    "groups": []
  },
  "editor": {
    "groups": []
  },
  "manager": {
    "groups": []
  },
  "reviewer": {
    "groups": []
  },
  "user": {
    "groups": []
  }
}

cached is autogenerated once the applet is parsed on the server.

assetstore

A model inherited from Girder.

assignment

Deprecated. Do not use.

collection

A model inherited from Girder.

file

A model inherited from Girder.

folder

A model inherited from Girder.

group

A model inherited from Girder.

ID_code

In order to protect user privacy, reviewers cannot see any information from a profile or its underlying user. Rather, users are identified through ID codes which are tied to profiles. ID codes need not be unique, and a profile can have more than one ID code. ID codes are autogenerated if not supplied through the API.

Attribute Name	Required	Type	Autogenerated
_id	true	ObjectId	true
code	true	string	optional
profileId	true	ObjectId	false
created	true	datetime	true
updated	true	datetime	true

invitation

An invitation is a single-use document, tied to a particular applet and user role, that persists until someone accepts or declines. If an invitation is accepted, a profile is created for the user who accepted the invitation if one does not already exist, and the user is inducted into a group authorizing the role in the applet as defined in the invitation. Invitations also include information about who created the invitation and when.

Attribute Name	Required	Type	Autogenerated
_id	true	ObjectId	true
appletId	true	ObjectId	false
role	true	string	false
invitedBy	true	dict	true
coordinatorDefined	false	dict	false
created	true	datetime	true
updated	true	datetime	true

item

A model inherited from Girder.

model_base

A model inherited from Girder.

notification

A model inherited from Girder.

profile

A profile stores information specific to the intersection of a user and an applet. The API should handle selecting the appropriate value for customizable fields in this order of preference (profile.userDefined is most preferred, component default is least preferred):

profile.userDefined > profile.coordinatorDefined > applet > protocol > activity > screen > component default

Every UI component should have a default in case of a cascade of undefined``s all the way down the chain above. If no coordinator-defined or user-defined value is provided for ``displayName, that field will be auto-populated from the profile's associated user.

Attribute Name	Required	Type	Autogenerated
_id	true	ObjectId	true
appletId	true	ObjectId	false
userId	true	ObjectId	false
profile	true	Boolean	true
coordinatorDefined	false	dict	false
userDefined	false	dict	optional
created	true	datetime	true
updated	true	datetime	true

protocol

An ActivitySet as defined in reproschema, stored as a Girder folder.

cached is autogenerated once the protocol is parsed on the server.

protoUser

Deprecated. Do not use.

response_folder

The response_folder module contains 2 models: ResponseItem and ResponseFolder.

A ResponseItem is created (as a Girder item) each time a user completes an activity. ResponseItems are stored in ResponseFolders (each a Girder folder) which are access controlled to allow authorized reviewers to see all data they are authorized to see and only data they are authorized to see.

roles

Roles are applet-specific and handled through groups. When a new applet is created, the creator of the applet is automatically inducted into all groups with roles for that applet.

• editors can modify the content of protocols, activities, and screens
• managers can modify the customization of applets and can manage all user roles
• coordinators can manage a limited set of user roles: coordinator and user
• users can perform the activities in an applet's protocol, can customize their own settings, and can see their own data
• reviewers can access all data collected from an applet

An individual, through group memberships, can have any combination of roles per applet and can have roles in any number of applets. Roles that manager users can see limited personal information (eg, displayName). Reviewers see users identified only by ID code. Take care to limit the number of reviewers with user-management permissions to minimize the risk of reidentification.

screen

An Item as defined in reproschema, stored as a a Girder item.

cached is autogenerated once the screen is parsed on the server.

setting

A model inherited from Girder.

token

A model inherited from Girder.

upload

A model inherited from Girder.

user

A model inherited from Girder.

Links

• reprolib specification
• Development instance
• Production instance
• Run a local instance

Contributing

See CONTRIBUTING.

Girder Source

This source code is a customization of girder/girder@e97b1f7

Girder is a free and open source web-based data management platform developed by Kitware as part of the Resonant data and analytics ecosystem.

Documentation of the Girder platform can be found at 📕 Read the Docs.

For questions, comments, or to get in touch with the maintainers, head to their Discourse forum, or use their Gitter Chatroom.

We'd love for you to contribute to Girder.