countEachLabel

(To be removed) Count number of pixel labels for each class of bigimageDatastore object

The countEachLabel function of the bigimageDatastore object will be removed in a future release. Use the countEachLabel function associated with the blockedImageDatastore object instead. For more information, see Version History.

Syntax

counts = countEachLabel(bigds)

Description

counts = countEachLabel(bigds) returns the number of each pixel label for all big images in big image datastore bigds.

Examples

Calculate Class Weights of Labeled Big Images

Load pixel label data.

load('buildingPixelLabeled.mat');

Specify the classes and pixel label IDs of the pixel label data.

pixelLabelID = [1 2 3 4];
classNames = ["sky" "grass" "building" "sidewalk"];

Create a bigimage to manage the pixel label data.

bigLabeledImage = bigimage(uint8(label),'Classes',classNames,'PixelLabelIDs',pixelLabelID);
bigimageshow(bigLabeledImage)

Create a bigimageDatastore that reads blocks of size 200-by-150 pixels at the finest resolution level from bigLabeledImage.

level = 1;
blockSize = [200 150];
biglabelds = bigimageDatastore(bigLabeledImage,level,'BlockSize',blockSize);

Count the number of pixel labels for each class.

tbl = countEachLabel(biglabelds)

tbl=4×3 table
       Name       PixelCount    BlockPixelCount
    __________    __________    _______________

    "sky"              81525        1.58e+05   
    "grass"            32983           51200   
    "building"    1.8036e+05       3.072e+05   
    "sidewalk"         10491           51200   

Balance the classes by using uniform prior weighting.

prior = 1/numel(classNames);
uniformClassWeights = prior ./ tbl.PixelCount

uniformClassWeights = 4×1
10-4 ×

    0.0307
    0.0758
    0.0139
    0.2383

Balance the classes by using inverse frequency weighting.

 totalNumberOfPixels = sum(tbl.PixelCount);
 freq = tbl.PixelCount / totalNumberOfPixels;
 invFreqClassWeights = 1./freq

invFreqClassWeights = 4×1

    3.7456
    9.2580
    1.6931
   29.1067

Balance the classes by using median frequency weighting.

freq = tbl.PixelCount ./ tbl.BlockPixelCount;
medFreqClassWeights = median(freq) ./ freq

medFreqClassWeights = 4×1

    1.0689
    0.8562
    0.9394
    2.6917

Input Arguments

bigds — Big image datastore

bigimageDatastore object

Big image datastore, specified as a bigimageDatastore object.

Output Arguments

counts — Label information

table

Label information, returned as a table that contains three variables.

Pixel Count Variables	Description
Name	Pixel label class name
PixelCount	Number of pixels in class
BlockPixelCount	Total number of pixels in blocks that have an instance of the class

Tips

You can use the label information returned by countEachLabel to calculate class weights for class balancing. For example, for labeled pixel data information in tbl:

• Uniform class balancing weights each class such that each contains a uniform prior probability:

  numClasses = height(tbl)
  prior = 1/numClasses;
  classWeights = prior./tbl.PixelCount

• Inverse frequency balancing weights each class such that underrepresented classes are given higher weight:

  totalNumberOfPixels = sum(tbl.PixelCount)
  frequency = tbl.PixelCount / totalNumberOfPixels;
  classWeights = 1./frequency

• Median frequency balancing weights each class using the median frequency:

  imageFreq = tbl.PixelCount ./ tbl.BlockPixelCount
  classWeights = median(imageFreq) ./ imageFreq
  

Version History

Introduced in R2020a

R2024b: Warns

The countEachLabel function issues a warning that it will be removed in a future release.

R2023b: To be removed

The bigimageDatastore object and this function will be removed in a future release. Use the countEachLabel function of the blockedImageDatastore object instead.

To update your code, follow these steps to create a blockedImageDatastore object and count class labels:

• Optionally, if you have categorical data and want to specify the order of the class labels, then you can convert the data to a numeric data type.

• Create a blockedImage object to read your numeric or categorical image data.

• Create a blockedImageDatastore object to manage blocks of the data.

• In the call to the countEachLabel function, replace the first input argument with the blockedImageDatastore object. If the image data is numeric, also specify the class names and pixel label IDs using the Classes and PixelLabelIDs name-value arguments, respectively.

The countEachLabel function of blockedImageDatastore and blockedImageDatastore can return different results for the BlockPixelCount variable of the counts output argument.

Discouraged Usage	Recommended Replacement
This example counts the number of pixel labels for each class of a bigimageDatastore object. load("buildingPixelLabeled.mat"); numericLabels = uint8(label); pixelLabelID = [1 2 3 4]; classNames = ["sky" "grass" "building" "sidewalk"]; bigLabeledImage = bigimage(numericLabels,BlockSize=[200 150], ... Classes=classNames,PixelLabelIDs=pixelLabelID); bigLabeledDS = bigimageDatastore(bigLabeledImage,1); tbl = countEachLabel(bigLabeledDS)	Here is approximately equivalent code using a blockedImageDatastore object with numeric data. The classes in the table are ordered according to the classNames variable. load("buildingPixelLabeled.mat"); numericLabels = uint8(label); pixelLabelID = [1 2 3 4]; classNames = ["sky" "grass" "building" "sidewalk"]; blockedIm = blockedImage(numericLabels,BlockSize=[200 150]); blockedDS = blockedImageDatastore(blockedIm); tbl = countEachLabel(blockedDS, ... Classes=classNames,PixelLabelIDs=pixelLabelID)
	Here is approximately equivalent code using a blockedImageDatastore object with categorical data. The classes in the table are ordered alphabetically by class name. load("buildingPixelLabeled.mat"); blockedLabeledImage = blockedImage(label,BlockSize=[200 150]); blockedLabeledDS = blockedImageDatastore(blockedLabeledImage); tbl = countEachLabel(blockedLabeledDS)

R2021a: countEachLabel function is not recommended

Starting in R2021a, the bigimageDatastore object and its object functions, which operate on data from bigimage objects, are no longer recommended. Instead, use the blockedImageDatastore object and its object functions, which operate on data from blockedImage objects. The blockedImage object offers several advantages including extension to N-D processing, a simpler interface, and custom support for reading and writing nonstandard image formats.