pfdicom-agesort

Process ChRIS trees of DICOM data and reorder by age.


License
MIT
Install
pip install pfdicom-agesort==1.0.0

Documentation

pfdicom_agesort

https://travis-ci.org/FNNDSC/pfdicom_agesort.svg?branch=master

Quick Overview

  • pfdicom_agesort processes ChRIS conformant PACS pull trees and reorders
    content according to an explicit <year>/<month>/<exanmple> structure.

Overview

pfdicom_agesort repacks a ChRIS-default tree of MRI/DICOM data to an explicit age-reflecting organization. The program performs a mulit-pass loop over the file tree space as defined in the [--stage <stage>] flag below.

NOTE:

  • pfdicom_agesort is dervied from pfdicom_tagExtract. Please consult the documentation for pfdicom_tagExtract for additional information.

Installation

Dependencies

The following dependencies are installed on your host system/python3 virtual env (they will also be automatically installed if pulled from pypi):

  • pfmisc (various misc modules and classes for the pf* family of objects)
  • pftree (create a dictionary representation of a filesystem hierarchy)
  • pfdicom (handle underlying DICOM file reading)

Using PyPI

The best method of installing this script and all of its dependencies is by fetching it from PyPI

pip3 install pfdicom_agesort

Command line arguments

-I|--inputDir <inputDir>
Input DICOM directory to examine. By default, the first file in this
directory is examined for its tag information. There is an implicit
assumption that each <inputDir> contains a single DICOM series.

[-e|--extension <DICOMextension>]
An optional extension to filter the DICOM files of interest from the
<inputDir>.

-O|--outputDir <outputDir>
The output root directory that will contain a tree structure identical
to the input directory, and each "leaf" node will contain the analysis
results.

In the case of `pfdicom_agesort`, this <outputDir> is the root of the
age sorted tree.

[--outputLeafDir <outputLeafDirFormat>]
If specified, will apply the <outputLeafDirFormat> to the output
directories containing data. This is useful to blanket describe
final output directories with some descriptive text, such as
'anon' or 'preview'.

This is a formatting spec, so

    --outputLeafDir 'preview-%s'

where %s is the original leaf directory node, will prefix each
final directory containing output with the text 'preview-' which
can be useful in describing some features of the output set.

[-F|--tagFile <tagFile>]
Read the tags, one-per-line in <tagFile>, and print the
corresponding tag information in the DICOM <inputFile>.

[-T|--tagList <tagList>]
Read the list of comma-separated tags in <tagList>, and print the
corresponding tag information parsed from the DICOM <inputFile>.

[-S|--symlinkDCMdata]
If true/specified, perform a symlink of the original DICOM data to
the final output directory tree. If false, a copy of the original
DICOM data is performed.

[-D|--doNotCleanUp]
If true, do not cleanup the original tag data tree created when
analysing the original DICOM tree structure.

[-m|--image <[<index>:]imageFile>]
If specified, also convert the <inputFile> to <imageFile>. If the
name is preceded by an index and colon, then convert this indexed
file in the particular <inputDir>.

[-s|--imageScale <factor>[:<interpolation>]]
If an image conversion is specified, this flag will scale the image
by <factor> and use an interpolation <order>. This is useful in
increasing the size of images for the html output.

Note that certain interpolation choices can result in a significant
slowdown!

    interpolation order:

    'none', 'nearest', 'bilinear', 'bicubic', 'spline16',
    'spline36', 'hanning', 'hamming', 'hermite', 'kaiser', 'quadric',
    'catrom', 'gaussian', 'bessel', 'mitchell', 'sinc', 'lanczos'

-o|--outputFileStem <outputFileStem>
The output file stem to store data. This should *not* have a file
extension, or rather, any "." in the name are considered part of
the stem and are *not* considered extensions.

[-t|--outputFileType <outputFileType>]
A comma specified list of output types. These can be:

    o <type>    <ext>       <desc>
    o raw       -raw.txt    the raw internal dcm structure to string
    o json      .json       a json representation
    o html      .html       an html representation with optional image
    o dict      -dict.txt   a python dictionary
    o col       -col.txt    a two-column text representation (tab sep)
    o csv       .csv        a csv representation

Note that if not specified, a default type of 'raw' is assigned.

[--stage <stage>]
Stage to execute -- mostly for debugging purposes and useful if running a
particular stage repeatedly.

[--infoJSON <infoJSONfile>]
The name of the study JSON file.

Defaults to 'info.json'.

[--threads <numThreads>]
If specified, break the innermost analysis loop into <numThreads>
threads.

[-x|--man]
Show full help.

[-y|--synopsis]
Show brief help.

[--json]
If specified, output a JSON dump of final return.

[--followLinks]
If specified, follow symbolic links.

[-v|--verbosity <level>]
Set the app verbosity level.

    0: No internal output;
    1: Run start / stop output notification;
    2: As with level '1' but with simpleProgress bar in 'pftree';
    3: As with level '2' but with list of input dirs/files in 'pftree';
    5: As with level '3' but with explicit file logging for
            - read
            - analyze
            - write

Examples

Process a ChRIS tree containing DICOM:

pfdicom_agesort                                             \\
            -I /neuro/users/chris/data/mrn                  \\
            -O /neuro/users/chris/data/age                  \\
            --threads 0 --printElapsedTime                  \\
            -e dcm                                          \\
            -o '%_md5|6_PatientID-%PatientAge'              \\
            -m 'm:%_nospc|-_ProtocolName.jpg'               \\
            -s 3:none                                       \\
            --useIndexhtml                                  \\
            -t raw,json,html,dict,col,csv                   \\
            --followLinks                                   \\
            --symlinkDCMdata                                \\
            -v 3                                            \\
            --threads 0

which will reorganize the file trees as shown, printing the final elapsed processing time.