changeFilePaths

Change file paths in ground truth data for medical images

Since R2022b

Syntax

unresolvedFilePaths = changeFilePaths(gTruthMed,alternateFilePaths)

unresolvedFilePaths = changeFilePaths(gTruthMed,alternateFilePaths,ChangeProperty=propertyName)

Description

unresolvedFilePaths = changeFilePaths(gTruthMed,alternateFilePaths) changes the file paths stored in the DataSource and LabelData properties of the groundTruthMedical object gTruthMed. The alternateFilePaths argument specifies pairs of current paths in gTruthMed and alternative paths that point to the new data location on your machine. The function returns any unresolved paths in unresolvedPaths. An unresolved path is a current path not found in gTruthMed or an alternative path not found on your machine. In both cases, unresolvedPaths returns only the corresponding current path.

Use this function to update a groundTruthMedical object if you move the data source or label image files to a new folder. If you receive a groundTruthMedical object that was created on a different computer, use this function to point to the data location on your local machine.

unresolvedFilePaths = changeFilePaths(gTruthMed,alternateFilePaths,ChangeProperty=propertyName) replaces only the file paths stored in the specified property, DataSource or LabelData, of gTruthMed.

Examples

Change File Paths in Medical Ground Truth Data

Change the file paths in a medical ground truth data object to point to a subset of the Medical Segmentation Decathlon data set [1]. The subset of data includes two CT chest volumes and corresponding label images, stored in the NIfTI file format. Download the MedicalVolumNIfTIData.zip file from the MathWorks® website, then unzip the file. The size of the data file is approximately 76 MB.

zipFile = matlab.internal.examples.downloadSupportFile("medical","MedicalVolumeNIfTIData.zip");
filepath = fileparts(zipFile);
unzip(zipFile,filepath)
dataFolder = fullfile(filepath,"MedicalVolumeNIfTIData");

Load a groundTruthMedical object containing ground truth data into the workspace. The data source and label data of the object specify file paths to the data at a different location than dataFolder. MATLAB® displays a warning that the path to the data source cannot be found. This can occur when a groundTruthMedical object is created on one computer and loaded on a different computer that stores the image data in a different location.

load("gTruthMed-NIfTI-Chest.MAT")

Warning: Unable to find one or more 'DataSource' or 'LabelData' files. Use the changeFilePaths object function to update the missing file paths.

Display the current path to the data source and label data.

gTruthMed.DataSource.Source

ans=2×1 cell array
    {["C:\CFP\lung_027.nii.gz"]}
    {["C:\CFP\lung_043.nii.gz"]}

gTruthMed.LabelData

ans = 2×1 string
    "C:\CFP\LabelData\lung_027.nii.gz"
    "C:\CFP\LabelData\lung_043.nii.gz"

Specify the current path to the data source and an alternative path and store these paths in a string array alternativePaths.

currentPathDataSource = "C:\CFP";
newPathDataSource = dataFolder;
alternativePaths = [currentPathDataSource newPathDataSource];

Use the changeFilePaths object function to update the data source file paths, based on the paths in the string array. Because the function resolves all paths, it returns an empty array of unresolved paths

unresolvedPaths = changeFilePaths(gTruthMed,alternativePaths)

unresolvedPaths = 

  0×1 empty string array

Verify that the new data source and label data paths are stored in the DataSource and LabelData properties of gTruthMed.

gTruthMed.DataSource;
gTruthMed.LabelData;

References

[1] Medical Segmentation Decathlon. "Lung." Tasks. Accessed May 10, 2018. http://medicaldecathlon.com/.

The Medical Segmentation Decathlon data set is provided under the CC-BY-SA 4.0 license. All warranties and representations are disclaimed. See the license for details.

Input Arguments

gTruthMed — Ground truth data

groundTruthMedical object

Ground truth data, specified as a groundTruthMedical object. You can export a groundTruthMedical object from the Medical Image Labeler app or create one programmatically by using the groundTruthMedical function.

alternateFilePaths — Alternative file paths

n-by-2 string array

Alternative file paths, specified as an n-by-2 string array, where n is the number of paths to update. Each row specifies a current location and its corresponding new location in the format [p_current p_new].

• p_current is a current file path in gTruthMed. Specify p_current using the same file separators, either forward slashes or backslashes, present in gTruthMed.

• p_new is the alternative path replacing p_current. Specify p_new using either forward slashes or backslashes as the path separators.

The function updates the properties of gTruthMed based on the types of files specified:

• Data sources — The DataSource property of gTruthMed contains a VolumeSource or ImageSource object. The changeFilePaths function updates the paths in the Source property of these objects.

• Label data — The changeFilePaths function updates the paths in the LabelData property of gTruthMed.

You can specify paths as full path names to specific files, or as the beginning portion of a file path. If you specify a pair of partial paths, [p_{currentPartial} p_newPartial], the function determines the full current and alternate paths using these steps:

1. The function searches gTruthMed for file names that start with p_{currentPartial}. The final list of current paths consists of all full file paths starting with p_{currentPartial}.

2. The final list of alternative paths is the list of current full file paths with the portion p_{currentPartial} replaced with p_newPartial.

Example: ["C:\VolumeData","C:\VolumeData2"] changes the path of the data directory. The function updates the path for all files in gTruthMed in the folder C:\VolumeData and its subfolders to begin with C:\VolumeData2.

Example: ["C:\VolumeData","B:\VolumeData"] changes the drive letter in the file paths in gTruthMed that begin with C:\VolumeData from C to B.

Data Types: string

propertyName — Property for which to change file paths

"Auto" (default) | "DataSource" | "LabelData"

Property for which to change file paths, specified as one of these values:

• "Auto" — Update file paths stored in both the DataSource and LabelData properties.

• "DataSource" — Update file paths stored in the DataSource property.

• "LabelData" — Update file paths stored in the LabelData property.

Data Types: string

Output Arguments

unresolvedFilePaths — Unresolved file paths

string array

Unresolved file paths, returned as a string array. If the function cannot find either the specified current path in gTruth or the specified alternative path location, then it returns the corresponding current path.

If the function finds and resolves all file paths, then it returns unresolvedFilePaths as an empty string array.

Version History

Introduced in R2022b