How to Write an Anonymization Script

This section provides guidance on how to use XNAT to create an anonymization script that meets your requirements. XNAT depends on DicomEdit to provide anonymization capabilities. The operations performed during anonymization are determined by the contents of a script written in a custom DicomEdit Language.  See  DicomEdit 6.1 Language Reference and DicomEdit 4.2 Language Reference for details on script syntax.  For details on all the places anonymiztion occurs in XNAT, see Where Anonymization Happens in XNAT.  For details on how to provide your script to XNAT, see Site-wide Session Upload and Anonymization Settings and Project Data Import and Anonymization Settings. But, how do you use XNAT to create a correct script in the first place?

There are two aspects to writing a valid script: syntax and semantics.

Getting the Syntax Right

The DicomEdit script must be written to conform with the rules of the language. We currently do not have a tool that will automatically validate a script. We must resort to trial and error. Sending data to XNAT through an invalid script will cause the underlying DicomEdit to throw errors. These errors will be captured in XNAT's log files. Of particular interest are dicom.log and anon.log. We currently do not have a user interface that allows access to these logs. The log files must be viewed on the server by other means. See XNAT Installation Guide for guidance on where to find the log files on your XNAT. Searching the log files for string "MizerExcpetion" should help you zero in on problems.


  1. Anonymization may be failing without clear indication in XNAT's user interface. DicomEdit errors are low-level errors that do not surface effectively in the UI. The errors that currently do occur in the UI are due to problems that occur downstream of the anonymization errors.  Especially when changing a script, check the log files.
  2. Error messages may not be at the best level of detail. DicomEdit uses ANTLR to parse the script files. ANTLR, when confused, can generate some very low-level messages that can be very cryptic. 

Getting the Semantics Right

Even if the script is valid syntax, does it really do what you intend it to do?  Here, there is no substitute for running test data through your script and manually verifying that the contents of the transformed DICOM objects are as intended.  XNAT provides a number of places that provide access to a "DICOM Dump". This is a view of all the attributes that exist in the DICOM object and their values. Use the DICOM Dump to view the details of objects as stored by XNAT.

Accessing a DICOM Dump:

  1. From the Prearchive page
    1.  select a session with status "Ready".
    2. Click "Details" button 
    3. On session-details page, Click "Review DICOM Tags" button
  2. For an archived scan
    1. Navigate to the session page.
    2. Click the "+" to expand the scan details.
    3. Click the link "View DICOM Headers"

Related Documentation