Visits and Protocols - Jordan Woerndle
Video
Part 1: Introduction to Visits and Protocols
Part 2: How to use Visits and Protocols
Notes:
- This talk was re-recorded on July 16, 2012.
- To load the video, you may be prompted by your browser to "display insecure content."
- Click the "HD" icon at the lower right to see a full-resolution video, and get rid of the fuzzy text.
Goal:
This session will describe the concepts behind the experimental Visit and Protocol features that are being added to XNAT. These features enable native support for longitudinal studies and provide fine-grained data validation designed to help data managers in their day-to-day activities.
Materials:
Participants will need a working copy of the workshop VM. They also need the experimental protocols module (zip file), and BOGUS-XNAT's protocol specification which is a JSON formatted text file:
Prerequisites:
This session assumes:
- XNAT is installed and running in a VM with all BOGUS data types enabled and working.
- At least one sample subject is in the database along with complete sample data such as MR, PET, and Ego Master 3.7 for both baseline and follow-up visits.
- That subject is a member of a project (not shared into) and all experiments are also native to that project.
- Session participants are already familiar with Modules and have already installed and tested at least one.
- The user is able to download the Protocols module and BOGUS_OUA protocol json file noted above.
Agenda:
20 min: Detailed description of Protocols and Visits
- Feel free to download the PowerPoint or PDF version of the presentation that is attached to this page.
40 min: Install the Module and Work an Example
Start up your XNAT Workshop VM and follow along:
- Go to a subject in your BOGUS_OUA project and assure there is some data there. This page will change when we associate a protocol with the study.
- Download the module and JSON files
- These can be found in the “materials” section or click the paperclip icon in the upper left of the wiki page to access attachments.
- Find "protocols.zip" right-click->"save link as" and pick your ~/Downloads directory.
- Find "bogus.json" right-click->"save link as" and pick your ~/Downloads directory.
- "protocols.zip" is the module we will install. Make sure it is in your ~/Downloads directory.
- "bogus.json" is your protocol definition for the BOGUS_OUA project. Make sure it is in your ~/Downloads directory.
- Open a terminal
- "cd" to your xnat builder directory:
cd /opt/xnat/xnat_builder_1_6
- Copy the module to your XNAT:
cp ~/Downloads/protocols.zip /opt/xnat/modules/.
- Stop tomcat
sudo service tomcat6 stop (note: this command will ask you for your vm's password)
- Update your XNAT:
./bin/update.sh -Ddeploy=true (note: this will take some time depending on the speed of your vm)
- Start tomcat
sudo service tomcat6 start (note: this command will ask you for your vm's password)
- Browse to http://localhost:8080/xnat/
- log in to assure everything is running.
- Assure a project called BOGUS_OUA exists. If not, create it.
- Assure a BOGUS_OUA has a subject with some data.
- cd to your ~/Downloads directory:
cd ~/Downloads
- Upload the protocol configuration using curl:
curl -X PUT -u admin:admin http://localhost:8080/xnat/REST/projects/BOGUS_OUA/protocol?inbody=true -d @bogus.json
(Note: in case the curl command above fails, you can upload to the configuration framework directly using: curl -X PUT -u admin:admin http://localhost:8080/xnat/data/projects/BOGUS_OUA/config/protocols/protocol?inbody=true -d @bogus.json )
- Check the protocol by browsing to http://localhost:8080/xnat/REST/projects/BOGUS_OUA/protocol/ The bogus.json file should appear in your browser window.
- Add the Pvisitdata datatype (this is a step that will not be necessary in an official 1.6 release)
- Log into XNAT as admin
- Go to Administer -> Data Types
- Click - "Setup Additional Data Type" this will open a popup.
find "xnat:pVisitData" in the drop down and select it. Click Submit. (Note, do not select visit:visitData)
- Add 2 values:
- Singular Name: Visit
- Plural Name: Visits
- Click Next.
- Click Next.
- Close the popup.
- Go back to a subject page in the BOGUS_OUA project.
- Notice how it changed. If you forgot, compare it to a project that doesn't have a protocol.
- Create a baseline visit by clicking the "Create a Visit +" link on the Baseline visit placeholder.
- Sort your experiments by adding your baseline experiments to the baseline visit.
- Remove a visit. Notice all assigned experiments wind up in the unsorted list again.
- Modify and upload the protocol
- Modify the bogus.json file using a text editor. Maybe change the baseline and f/u visit names to "first visit" and "last visit"
- Upload the configuration JSON file using the curl command above.
- Reload the subject page. Notice the changes take place immediately.
- Gotchas:
- Protocol specification and visits are highly decoupled. If you change your protocol too much, the existing visits will simply show up as "Invalid." The user has to reorganize visits and experiments manually.
- You can access the protocol through the configuration framework using a url like
Questions or Comments?
Jordan Woerndle
XNAT Discussion Group - Google Groups
Backout
Interestingly, this alpha release module may have introduced a bug on subject details pages for projects that do not have a protocol. A quick way to back out the change that causes this issue, you need to delete 2 templates in xnat's webapp directory.
A script is available in the workshop2012 repository or you can run the following commands manually:
rm /var/lib/tomcat6/webapps/xnat/templates/screens/xnat_subjectData/report/preAssessors/protocolEnabled.vm
rm /var/lib/tomcat6/webapps/xnat/templates/screens/xnat_subjectData/report/postAssessors/protocolEnabled.vm
OR:
If you'd like to use the script. Use the following commands to update your workshop2012 repository and run the script:
cd /opt/xnat/workshop2012/d3s9-cleanup/
./cleanProtocols.sh