Main Content

changeFilePaths

Change file paths in ground truth data for medical images

Since R2022b

collapse all in page

    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.

    example

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

    Examples

    collapse all

    Open Live Script

    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

    collapse all

    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.

    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 [pcurrent pnew].

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

    • pnew is the alternative path replacing pcurrent. Specify pnew 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, [pcurrentPartial pnewPartial], the function determines the full current and alternate paths using these steps:

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

    2. The final list of alternative paths is the list of current full file paths with the portion pcurrentPartial replaced with pnewPartial.

    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

    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

    collapse all

    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

    See Also