Introduction to VivoScript – Part I: Looping through data in a project

In this post, I would like to show an example of how to iterate through all the patients of a project on an iPACS system using a VivoScript. This can for instance be useful for the automation of pre-processing data, or two produce quality control images for an entire project. The looping technique shown here will be used in subsequent tutorials, so this is the best starting point to get familiar with VivoScript.

var dm = VQ.dataManager();

var dcmRepUrl   = 'ipacss://vqintro:blog42@training.ipacs.invicro.com';  // don't write pwd in scripts outside of this tutorial!
var projectName = '/examples';

var dcmRep = VQ.dcmRep( dcmRepUrl );
dcmRep.setProject( projectName );

var studies = VQ.queryStudies(dcmRep, "Mouse*"); // search for patient "Mouse*"
for (var i=0; i<studies.length; ++i) {
    VQ.debug("patient["+i+"]: " +studies[i].PatientsName);    // print meta-info
    VQ.debug("  studyuid["+i+"]: "+studies[i].StudyDescription);

    var series = VQ.querySeries(dcmRep, studies[i].StudyInstanceUID);   // fetch series by study id
    for (var j=0; j<series.length; ++j) {
        VQ.debug("    series["+j+"]: "+series[j].SeriesDescription + ", "+series[j].Modality);

        if (0) {
            var files = VQ.downloadImages(dcmRep, 
                studies[i].StudyInstanceUID, series[j].SeriesInstanceUID);
            dm.openDat(0, files);                           // open data
            dm.setDesc(0, "__repository_url", dcmRep.toString());   // set source (to be able to load datapoints,
            dm.setDesc(0, "__project", dcmRep.project());        // such as 3D ROIs, annotations, etc...)
        }
    }
}

VQ.showMessage("Written report to debug console")

The details

First we create a shortcut to the VivoQuant data manager and  configured the iPACS we would like to access:

var dm = VQ.dataManager();

var dcmRepUrl   = 'ipacs://training.ipacs.invicro.com';
var projectName = '/examples';

var dcmRep = VQ.dcmRep( dcmRepUrl );
dcmRep.setProject( projectName );

For this example we are using inviCRO’s training iPACS, and you can the account vqintro/blog42 for your testing. This account is read-only, however, allows you access to a couple of mouse CT datasets.

The next important step is fetching a list of all projects using VQ.queryStudies(dcmRep, …):

var studies = VQ.queryStudies(dcmRep, "Mouse*"); // search for patient "Mouse*"
// or alternatively:
var studies = VQ.queryStudies(dcmRep, "PatientsName", "PatientID", "Date-Range", "StudyDesc");

The dcmRep is a mandatory field to tell VQ which repository you would like to query, while the other parameters such as PatientsName, ID, DateRange or StudyDescription are optional. Use an empty string (“”) to ignore these filters. The star (*) can be used as a wildcard. Finally, queryStudies(…) will return a list of all matching studies in the given project. You can loop through all these studies with:

for (var i=0; i<studies.length; ++i) {
    ...
}

Inside the loop you have access to study- and patient-level metadata and access for instance the PatientsName or StudyDescription:

    VQ.debug("patient["+i+"]: " +studies[i].PatientsName);    // print meta-info
    VQ.debug("  studyuid["+i+"]: "+studies[i].StudyDescription);

Also, you can fetch all series that belong to a study using VQ.querySeries(…) and the StudyInstanceUID:

    var series = VQ.querySeries(dcmRep, studies[i].StudyInstanceUID);   // fetch series by study id

The loop through all series is the then same again as we used it for the studies. More interesting is the function to actually download DICOM data:

            var files = VQ.downloadImages(dcmRep,
                studies[i].StudyInstanceUID, series[j].SeriesInstanceUID);

which expects a dcmRep object, as well as the StudyInstanceUID and the SeriesInstanceUID (to download an entire series) and optionally an image SOPInstanceUID (to download an individual image, to get those use VQ.queryImages(…) for the given series). The function returns a list of local filesnames for the downloaded DICOM data. These filenames can finally be feed into the data manager function openDat(id, files), where id is 0 for the reference, 1 for the first input, etc… image:

            dm.openDat(0, files);                           // open data

The final two lines just make sure VivoQuant knows where the data was loaded from, so it can fetch datapoints, ROIs, etc… for the data. If you don’t plan to use any datapoints or ROIs you can ignore these two lines:

            dm.setDesc(0, "__repository_url", dcmRep.toString());   // set source (to be able to load datapoints,
            dm.setDesc(0, "__project", dcmRep.project());        // such as 3D ROIs, annotations, etc...)

Instead of an iPACS you can also use any other type of DICOM repository (basically DICOM servers or local folders with DICOM files) by creating a different type of dcmRep object:

// scan folder full of DICOM files:
var dcmRep = VQ.dcmRep("folder://C:/path/to/files");

// scan DICOM server
var dcmRep = VQ.dcmRep("dicom://callingAET:calledAET@server.com:port');

Please let me know how this worked for you, and post any questions or comments below.

Continue with the next part: Writing meta information to a local file.