MBIRN:BIRNDUP:Distribution - Revision history

Grundlett: Text replacement - "http://www.slicer.org/slicerWiki/index.php/" to "https://www.slicer.org/wiki/"

2017-07-10T17:51:27Z

Text replacement - "http://www.slicer.org/slicerWiki/index.php/" to "https://www.slicer.org/wiki/"

Pieper at 17:21, 11 June 2014

2014-06-11T17:21:38Z

Melonakos at 17:59, 6 November 2008

2008-11-06T17:59:47Z

Pieper: /* Development Versions */

2008-05-03T12:55:51Z

Development Versions

Pieper: /* Batch Mode for Non-Defacing */

2007-03-02T20:09:27Z

Batch Mode for Non-Defacing

Pieper: /* Batch Mode for Non-Defacing */

2007-03-02T20:09:16Z

Batch Mode for Non-Defacing

Pieper: /* Batch Mode */

2007-03-02T20:07:55Z

Batch Mode

Andy at 15:03, 20 December 2006

2006-12-20T15:03:49Z

Andy: Update from Wiki

2006-12-18T13:26:41Z

Update from Wiki

New page

This page includes information about the distribution of the BIRN Deidentification and Upload Pipeline (BIRNDUP).

<div class="thumb tleft"><div style="width: 152px">[[Image:Deface-example.png|[[Image:150px-Deface-example.png|Example output of BIRNDUP]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:Deface-example.png|[[Image:magnify-clip.png|Enlarge]]]]</div>Example output of BIRNDUP</div></div></div>

Note: this software is experimental. Although it is functional as described, further development is on hold pending further feedback from the BIRN data sharing groups about the extent of the need for facial deidentification (if it is needed at all for MRI data).

== Features ==

BIRNDUP supports:

* Removes patient identifiers from DICOM headers and replaces them with valid, but non-identifyable fields (Note: only [[MBIRN:BIRNDUP:Removed_DICOM_Fields|these fields]] are removed.)
* Removes the faces from MR brain scans and replaces the data with zero valued voxels
* Sorts DICOM studies into the BIRN-standard directory hierarchy
* Provides an interactive review step to confirm that images have been correctly deidentified by showing 3D renderings of the defaced images
* Pseudorandom one-way hash BIRNID generated automatically from Subject ID and Site ID so that subsequent uploads always get the same BIRNID for longitudinal studies.

== Supported Data Formats and Image Types ==

* Only DICOM data is supported
* A T1 scan is used for the defacing calculation. Each additional series in the study are masked by registering it to the T1.

== Platform Requirements ==

Linux on x86. Red Hat Enterprise Linux tested, other Linux platforms probably also work.

Processing a single study can take approximately 2 hours and take about 200Meg of disk space. At least 1Gig of RAM is suggested.

The screen is used to render movies during part of the process. ''Please turn off any screen savers and do not use the display'' for any other purposes while the program is running.

== Installation ==

=== Directory Hierarchy ===

Install the code in any convenient directory on your machine. Put slicer2 and the birndup distribution at the same level. By default, a directory called 'deface' is needed at the same level as a place to store your projects and linktable. The directory structure should look as follows:

% cd <install dir>
% ls
birndup deface slicer2
% ls birndup
atlas bin dcanon fsl README scripts

The command line to start the BIRNDUP interface is:

<install dir>/slicer2/slicer2-linux-x86 -y --all-info --no-tkcon --eval package require BIRNDUP ,. dup_main | & tee /tmp/dataprovraw.txt

you may wish to create a handy alias or shell script wrapper for this command. No additional environment variables are needed (everything is found local to the install directory). For example:

alias birndup ~/birndup/slicer2/slicer2-linux-x86 -y --all-info --no-tkcon --eval package require BIRNDUP ,. dup_main

The final pipe to tee will record the raw unparsed [[Data_Provenance:Documentation|data provenance]] information in a temporary text file. To convert it to xml, use this command line:

<install dir>/birndup/scripts/dataprov_progelem.tcl /tmp/dataprovraw.txt > /tmp/dataprov.xml

=== Packaged Distribution ===

Packaged distributions of this code will be released after further testing.

=== Development Versions ===

The distribution software for BIRNDUP can be obtained as follows

cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer login

respond with '''bwhspl''' when prompted for password.

cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer checkout birndup

A web interface to cvs is viewable here: http://splweb.bwh.harvard.edu:8000/cgi-bin/develop/viewcvs.cgi/birndup/?cvsroot=slicer

The user interface requires a current cvs version Slicer2. See the instructions [[Slicer:Slicer_2.6_Building|here ]].

== Usage ==

=== Interactive Mode ===

==== Step by Step Instructions ====

[[Media:BIRNDUP-howto-2006-03-17.ppt| This powerpoint presentation]] has an overview of the methodology plus step by step instructions.

==== Output Directory Format ====

=== Batch Mode ===

See usage information [[Mbirn:_BIRNDUP#Command_Line_Version_Usage|here]].

== Output Directory Hierarchy ==

In the output directory (the DEFACE_DIR as configured in the Preferences Dialog) the working copies of all the image data processed by BIRNDUP. The format of the data is as follows:

* Each Study is stored in a unique directory with the following pattern:

<DEFACE_DIR>/Project_<Project>/<BIRNID>/Visit_<Visit>/Study_<Study>/Raw_Data

* <Project>, BIRNID, <Visit>, and <Study> are as specified in the Sort Pane

The Study Directory contains:

* 001, 002, ... <-- these are the original dicom image series (NOT deidentified!)
* 001-anon, 002-anon, ... <-- the deidentified dicom series to upload
** each <series>-anon directory contains a Deface subdirectory with png formated images of the volume rendered face files plus the axial, sagittal, and coronal images.
* upload_list.txt <-- the series have been approved for upload
* defer_list.txt <-- the series which should ''not'' be upload
* source_directory <-- text file with the original sort directory
* ready_for_upload <-- an empty file as a flag (if it exists, study is approved for upload)
* deidentify_operations <-- list of deidentification commands

== Licensing ==

BIRNDUP is built using technology collected from mBIRN Partner sites and from 3rd party packages; as a result, different parts of the program are covered by different licenses.

* The User Interface is based on 3D Slicer: [http://www.slicer.org/copyright/copyright.txt [1]]
* The birndup/bin/mri_* binaries are part of FreeSurfer: [http://surfer.nmr.mgh.harvard.edu/registration.html [2]] (note: only non-clinical, non-commercial uses are allowed).
* The flirt binary is part of FSL: [http://www.fmrib.ox.ac.uk/fsldownloads/main.html [3]] (note: only non-clinical, non-commercial uses are allowed).
* DICOM tools from [http://www.dclunie.com/dicom3tools.html [4]] and [http://dicom.offis.de [5]]
* Other software in the distribution is covered by the BIRN Public License [http://www.nbirn.net/Resources/Downloads/SoftwareLicense/BIRN_License_v1_0_include.htm [6]]

== Acknowledgements ==

BIRNDUP is a joint work of the Morphometry BIRN (http://www.nbirn.net) which draws on technology developed by the collaborator sites including the Neuroimage Analysis Center ([http://www.spl.harvard.edu:8000/pages/projects/grants/nac/ NAC at BWH]) and the [http://www.nmr.mgh.harvard.edu/ Martinos Center at MGH].

@@ Line 80: / Line 80: @@
 http://www.na-mic.org/ViewVC/index.cgi/birndup/?root=Slicer2
-The user interface requires a current cvs version Slicer2. See the instructions [http://www.slicer.org/slicerWiki/index.php/Slicer:Slicer_2.6_Building here ].
+The user interface requires a current cvs version Slicer2. See the instructions [https://www.slicer.org/wiki/Slicer:Slicer_2.6_Building here ].
 == Usage ==

← Older revision		Revision as of 17:21, 11 June 2014
Line 1:		Line 1:
		+	'''This page is out of date. If you want to deidentify DICOM files please refer to these tools:
		+
		+	* http://www.dclunie.com/pixelmed/software/webstart/DicomCleanerUsage.html
		+
		+	* https://www.rsna.org/ctp.aspx
		+	'''
		+
		+
		+	----
		+
		+
	This page includes information about the distribution of the BIRN Deidentification and Upload Pipeline (BIRNDUP).		This page includes information about the distribution of the BIRN Deidentification and Upload Pipeline (BIRNDUP).

@@ Line 69: / Line 69: @@
 http://www.na-mic.org/ViewVC/index.cgi/birndup/?root=Slicer2
-The user interface requires a current cvs version Slicer2. See the instructions [[Slicer:Slicer_2.6_Building|here ]].
+The user interface requires a current cvs version Slicer2. See the instructions [http://www.slicer.org/slicerWiki/index.php/Slicer:Slicer_2.6_Building here ].
 == Usage ==

@@ Line 86: / Line 86: @@
 === Batch Mode for Non-Defacing ===
-To call the underlying code, you can use the command <pre>dcanon</pre> from the dcanon directory of the distribution (see [[MBIRN:BIRNDUP:Distribution#Development_Versions | cvs checkout information above]].
+To call the underlying code, you can use the command <pre>dcanon</pre> from the dcanon directory of the distribution (see [[MBIRN:BIRNDUP:Distribution#Development_Versions | cvs checkout information above]]).
 Usage is:

@@ Line 86: / Line 86: @@
 === Batch Mode for Non-Defacing ===
-To call the underlying code, you can use the command <pre>dcanon</pre> from the dcanon directory of the distribution.
+To call the underlying code, you can use the command <pre>dcanon</pre> from the dcanon directory of the distribution (see [[MBIRN:BIRNDUP:Distribution#Development_Versions | cvs checkout information above]].
 Usage is:

@@ Line 66: / Line 66: @@
   cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer checkout birndup
-A web interface to cvs is viewable here: http://splweb.bwh.harvard.edu:8000/cgi-bin/develop/viewcvs.cgi/birndup/?cvsroot=slicer
+A web interface to cvs is viewable here:
 The user interface requires a current cvs version Slicer2. See the instructions [[Slicer:Slicer_2.6_Building|here ]].

@@ Line 80: / Line 80: @@
 ==== Output Directory Format ====
-=== Batch Mode ===
+=== Batch Mode for Defacing ===
 See usage information [[Mbirn:_BIRNDUP#Command_Line_Version_Usage|here]].
 == Output Directory Hierarchy ==

@@ Line 1: / Line 1: @@
 This page includes information about the distribution of the BIRN Deidentification and Upload Pipeline (BIRNDUP).
-<div class="thumb tleft"><div style="width: 152px">[[Image:Deface-example.png|[[Image:150px-Deface-example.png|Example output of BIRNDUP]]]]<div class="thumbcaption"><div class="magnify" style="float: right">[[Image:Deface-example.png|[[Image:magnify-clip.png|Enlarge]]]]</div>Example output of BIRNDUP</div></div></div>
+[[Image:Deface-example.png|thumb|left|152px|Example output of BIRNDUP]]
 Note: this software is experimental. Although it is functional as described, further development is on hold pending further feedback from the BIRN data sharing groups about the extent of the need for facial deidentification (if it is needed at all for MRI data).
@@ Line 60: / Line 60: @@
 The distribution software for BIRNDUP can be obtained as follows
-  cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer login
+  cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer login
 respond with '''bwhspl''' when prompted for password.
-  cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer checkout birndup
+  cvs -d :pserver:anonymous@cvs.spl.harvard.edu:/projects/cvs/slicer checkout birndup
 A web interface to cvs is viewable here: http://splweb.bwh.harvard.edu:8000/cgi-bin/develop/viewcvs.cgi/birndup/?cvsroot=slicer