Inheritance diagram for PACentroid:

Public Member Functions
function	PACentroid (in loadShapes, in settings, in axesOrLineH, in textHandle, in loadShapeIDs, in loadShapeDayOfWeek, in delayedStart)

function	removeHandleReferences (in this)
	Removes any graphic handle to references. This is a helpful precursor to calling 'save' on the object, as it avoids the issue of recreating the figure handles when the object is later loaded with a 'load' call. More...

function	cancelCalculations (in this, in varargin)
	Sets the calculationState property to the cancel state value (-2). More...

function	getUserCancelled (in this)
	Checks if we have a user cancel state. More...

function	failedToConverge (in this)
	Determines if clustering failed or succeeded (i.e. do centroidShapes exist) More...

function	getHistogram (in this)

function	numCentroids (in this)
	Returns the number of centroids/clusters obtained. More...

function	getNumCentroids (in this)
	Alias for numCentroids. More...

function	numLoadShapes (in this)
	Returns the number of load shapes clustered. More...

function	getNumLoadShapes (in this)
	Alias for numLoadShapes. More...

function	init (in this)
	Initializes (sets to empty) member variables. More...

function	toggleOnNextCOI (in this)

function	toggleOnPreviousCOI (in this)

function	toggleOnCOISortOrder (in this, in sortOrder)
	This sets the given index into coiToggleOrder to true and also sets the coiSortOrder value to the given index. This performs similarly to setCOISortOrder, but here the coiToggleOrder is not reset (i.e. all toggles turned off). More...

function	increaseCOISortOrder (in this)

function	decreaseCOISortOrder (in this)

function	setCOISortOrder (in this, in sortOrder)

function	toggleCOISortOrder (in this, in toggleSortIndex)

function	getDaysOfInterest (in this)

function	toggleDayOfInterestOrder (in this, in dayOfInterest)

function	getClusteringPerformance (in this)

function	getCOIIndex (in this, in sortOrder)
	Returns the index of centroid matching the current sort order value (i.e. of member variable `coiSortOrder`) or of the input sortOrder provided. More...

function	getCOISortOrder (in this, in coiIndex)

function	getCOIToggleOrder (in this)

function	getCentroidOfInterest (in this, in sortOrder)
	Returns a descriptive struct for the centroid of interest (coi) which is determined by the member variable coiSortOrder. More...

function	getLoadShapeIDs (in this)
	Returns the loadshape IDs. These are the identifiers number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder. More...

function	getUniqueLoadShapeIDs (in this)

function	getUniqueLoadShapeIDsCount (in this)

function	getCentroidsOfInterestCount (in this)
	Returns the number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder. More...

function	getCentroidsOfInterest (in this)
	Returns the number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder. More...

function	calculateCentroids (in this, in inputLoadShapes, in inputSettings)
	Clusters input load shapes by centroid using adaptive k-means, determines the distribution of centroids by load shape frequency, and stores the sorted centroids, load shapes, and distribution, and sorted indices vector as member variables. See reset() method for a list of instance variables set (or reset on failure) from this method. More...

function	plotPerformance (in this, in axesH)

function	getWCSS (in varargin)
	Calculates within-cluster sum of squares (WCSS); a metric of cluster tightness. More...

function	getCovariateStruct (in this)
	Returns struct useful for logisitic or linear regression modelling. More...

Static Public Member Functions
static function	getCalinskiHarabaszIndex (in loadShapeMap, in centroids, in sumD)
	Validation metric for cluster separation. Useful in determining if clusters are well separated. If clusters are not well separated, then the Adaptive K-means threshold should be adjusted according to the segmentation resolution desired. More...

static function	plot (in performanceAxesH, in X, in Y)

static function	getPlotOptions ()

Public Attributes
Constant Property	WEEKDAY_ORDER = 0

Protected Member Functions
function	adaptiveKmedoids (in this, in loadShapes, in settings, in defaultRandomizer, in performanceAxesH, in textStatusH)
	Performs adaptive k-medoids clustering of input data. More...

function	adaptiveKmeans (in this, in loadShapes, in settings, in defaultRandomizer, in performanceAxesH, in textStatusH)
	Performs adaptive k-means clustering of input data. More...

Protected Attributes
Property	calculationState
	Numeric value indicating current state: values include. More...

Constructor & Destructor Documentation

function PACentroid::PACentroid	(	in	loadShapes,
		in	settings,
		in	axesOrLineH,
		in	textHandle,
		in	loadShapeIDs,
		in	loadShapeDayOfWeek,
		in	delayedStart
	)

Parameters

loadShapes	NxM matrix to be clustered (Each row represents an M dimensional value).
settings	Optional struct with following fields [and default values] `minClusters` [40] Used to set initial K `maxClusters` [0.5*N] `clusterThreshold` [1.5] `method` - {'kmeans','kmedoids','kmedians'}; clustering method. Default is kmeans.
Optional	axes or line handle for displaying clustering progress. If argument is a handle to a MATLAB axes, then a line handle will be added to the axes and adjusted with clustering progress. If argument is a handle to a MATLAB line, then the handle will be manipulated directly in its current context (i.e. whatever axes it currently falls under). If argument is not included, empty, or is not a line or axes handle then progress will only be displayed to the console (default)

Note: Including a handle increases processing time as additional calculations are made to measuring clustering separation and performance.

Parameters

Optional	text handle to send status updates to via set(textHandle,'string',statusString) type calls. Status updates are sent to the command window by default.
Optional	Nx1 cell string with load shape source identifiers (e.g. which participant they came from).
Optional	Nx1 vector with entries defining day of week corresponding to the load shape entry found at the same row index in the loadShapes matrix.
delayedStart	Boolean. If true, the centroids are not automatically calculated, instead 'calculateCentroids()' needs to be called directly from the instantiated class. The default is 'false': centroids are calculated in the constructor.

Return values

Instance of PACentroid on success. Empty matrix on failure.

Member Function Documentation

function PACentroid::adaptiveKmeans	(	in	this,
		in	loadShapes,
		in	settings,
		in	defaultRandomizer,
		in	performanceAxesH,
		in	textStatusH
	)

protected

Performs adaptive k-means clustering of input data.

Parameters

loadShapes	NxM matrix to be clustered (Each row represents an M dimensional value).
settings	Optional struct with following fields [and default values] `minClusters` [40] Used to set initial K `maxClusters` [0.5*N] `thresholdScale` [1.5] `method` 'kmeans'
Boolean
Boolean	Set randomizer seed to default `true` Use 'default' for randomizer (rng) `false` (default) Do not update randomizer seed (rng). `true` Display calinski index at each adaptive k-means iteration (slower) `false` (default) Do not calcuate Calinzki index.

Return values

idx	= Rx1 vector of cluster indices that the matching (i.e. same) row of the loadShapes is assigned to.
centroids	- KxC matrix of cluster centroids.
The	Calinski index for the returned idx and centroids Struct of X and Y fields containing the progression of cluster sizes and corresponding Calinksi indices obtained for each iteration of k means.

function PACentroid::adaptiveKmedoids	(	in	this,
		in	loadShapes,
		in	settings,
		in	defaultRandomizer,
		in	performanceAxesH,
		in	textStatusH
	)

protected

Performs adaptive k-medoids clustering of input data.

Parameters

loadShapes	NxM matrix to be clustered (Each row represents an M dimensional value).
settings	Optional struct with following fields [and default values] `minClusters` [40] Used to set initial K `maxClusters` [0.5*N] `thresholdScale` [1.5] `method` 'kmedoids'
Boolean
Boolean	Set randomizer seed to default `true` Use 'default' for randomizer (rng) `false` (default) Do not update randomizer seed (rng). `true` Display calinski index at each adaptive k-mediods iteration (slower) `false` (default) Do not calcuate Calinzki index.

Return values

idx	= Rx1 vector of cluster indices that the matching (i.e. same) row of the loadShapes is assigned to.
centroids	- KxC matrix of cluster centroids.
The	Calinski index for the returned idx and centroids Struct of X and Y fields containing the progression of cluster sizes and corresponding Calinksi indices obtained for each iteration of k means.

function PACentroid::calculateCentroids	(	in	this,
		in	inputLoadShapes,
		in	inputSettings
	)

Clusters input load shapes by centroid using adaptive k-means, determines the distribution of centroids by load shape frequency, and stores the sorted centroids, load shapes, and distribution, and sorted indices vector as member variables. See reset() method for a list of instance variables set (or reset on failure) from this method.

Parameters

Instance	of PACentroid
inputLoadShapes
Structure	of centroid configuration parameters. These are passed to adaptiveKmeans method.

function PACentroid::cancelCalculations	(	in	this,
		in	varargin
	)

Sets the calculationState property to the cancel state value (-2).

Parameters

this	Instance of PACentroid.

function PACentroid::decreaseCOISortOrder ( in this )

function PACentroid::failedToConverge ( in this )

Determines if clustering failed or succeeded (i.e. do centroidShapes exist)

Parameters

Instance of PACentroid

Return values

failedState

- boolean

true - The clustering failed
false - The clustering succeeded.

static function PACentroid::getCalinskiHarabaszIndex	(	in	loadShapeMap,
		in	centroids,
		in	sumD
	)

static

Validation metric for cluster separation. Useful in determining if clusters are well separated. If clusters are not well separated, then the Adaptive K-means threshold should be adjusted according to the segmentation resolution desired.

Note: See Calinski, T., and J. Harabasz. "A dendrite method for cluster analysis." Communications in Statistics. Vol. 3, No. 1, 1974, pp. 1?27.; See also http://www.mathworks.com/help/stats/clustering.evaluation.calinskiharabaszevaluation-class.html

Parameters

Vector	of output from mapping loadShapes to parent centroids.
Centroids	calculated via kmeans
sum	of euclidean distances

Return values

The	Calinzki-Harabasz index

function PACentroid::getCentroidOfInterest	(	in	this,
		in	sortOrder
	)

Returns a descriptive struct for the centroid of interest (coi) which is determined by the member variable coiSortOrder.

Parameters

Instance	of PACentroid
sortOrder	Optional index to use to obtain a centroid of interest according to the given sort order ; default is to use the value of this.coiSortOrder.

Return values

Structure

for centroid of interest. Fields include

sortOrder The sort order of coi. If all centroids are placed in a line numbering from 1 to the number of centroids in increasing order of the number of load shapes the centroid has clustered to it, then the sort order is the value of the number on the line for the coi. The sort order of a coi having the fewest number of load shape members is 1, while the sort sort order of a coi having the largest proportion of load shape members has the value C (centroid count).
index - id of the coi. This is its original, unsorted index value which is the range of [1, C]
shape - 1xM vector. The coi.
memberIndices = Lx1 logical vector indices of member shapes obtained from the loadShapes member variable, for the coi. L is the number of load shapes (see numLoadShapes()).

Note

memberShapes = loadShapes(memberIndices,:)

memberShapes - NxM array of load shapes clustered to the coi.
numMembers - N, the number of load shapes clustered to the coi.

function PACentroid::getCentroidsOfInterest ( in this )

Returns the number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder.

Parameters

this	Instance of PACentroid.

Return values

cois	Cell of centroid of interest structs. See getCentroidOfInterest for description of centroid of interest struct.

function PACentroid::getCentroidsOfInterestCount ( in this )

Returns the number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder.

Parameters

this	Instance of PACentroid.

Return values

numCOIs Number of centroids currently of interest: value is in the range [1, this.numCentroids].

function PACentroid::getClusteringPerformance ( in this )

function PACentroid::getCOIIndex	(	in	this,
		in	sortOrder
	)

Returns the index of centroid matching the current sort order value (i.e. of member variable coiSortOrder) or of the input sortOrder provided.

Parameters

this	Instance of PACentroid.
sortOrder	(Optional) sort order for the centroid of interest to retrive the index of. If not provided, the value of member variable `coiSortOrder` is used.

Return values

coiIndex The centroid index or tag.

Note: The coiIndex is the original index given to it during clustering. The sortOrder is the centroids rank in comparison to all centroids found during clustering, with 1 being the least popular and N (the number of centroids found) being the most popular.

function PACentroid::getCOISortOrder	(	in	this,
		in	coiIndex
	)

function PACentroid::getCOIToggleOrder ( in this )

function PACentroid::getCovariateStruct ( in this )

Returns struct useful for logisitic or linear regression modelling.

Parameters

Instance of PACentroid.

Return values

Struct

with fields defining dependent variables to use in the model. Fields include:

values NxM array of counts for M centroids (the covariate index) for N subject keys.
memberIDs Nx1 array of unique keys corresponding to each row.
colnames 1xM cell string of names describing the covariate columns.

function PACentroid::getDaysOfInterest ( in this )

function PACentroid::getHistogram ( in this )

function PACentroid::getLoadShapeIDs ( in this )

Returns the loadshape IDs. These are the identifiers number of centroids that are currently of interest, based on the number of positive indices flagged in coiToggleOrder.

Parameters

this	Instance of PACentroid.

Return values

loadShapeIDs Parent identifier for each load shape. Duplicate values in loadShapeIDs represent the same source (e.g. a specific person).

function PACentroid::getNumCentroids ( in this )

Alias for numCentroids.

Parameters

Instance of PACentroid

Return values

Number of centroids/clusters found.

function PACentroid::getNumLoadShapes ( in this )

Alias for numLoadShapes.

Parameters

Instance of PACentroid

Return values

Number of load shapes clustered.

static function PACentroid::getPlotOptions ( )

static

function PACentroid::getUniqueLoadShapeIDs ( in this )

function PACentroid::getUniqueLoadShapeIDsCount ( in this )

function PACentroid::getUserCancelled ( in this )

Checks if we have a user cancel state.

Parameters

this	Instance of PACentroid.

Return values

userCancel Boolean: true if calculationState is equal to user cancel value (-2)

function PACentroid::getWCSS ( in varargin )

Calculates within-cluster sum of squares (WCSS); a metric of cluster tightness.

Note: This measure is not helpful when clusters are not well separated (see getCalinskiHarabaszIndex).

Parameters

Instance PACentroid

Return values

The	within-cluster sum of squares (WCSS); a metric of cluster tightness

function PACentroid::increaseCOISortOrder ( in this )

function PACentroid::init ( in this )

Initializes (sets to empty) member variables.

Parameters

Instance of PACentroid

Note

Initialzed member variables include

loadShape2CentroidShapeMap
centroidShapes
histogram
loadShapes
sortIndices
coiSortOrder

function PACentroid::numCentroids ( in this )

Returns the number of centroids/clusters obtained.

Parameters

Instance of PACentroid

Return values

Number of centroids/clusters found.

function PACentroid::numLoadShapes ( in this )

Returns the number of load shapes clustered.

Parameters

Instance of PACentroid

Return values

Number of load shapes clustered.

static function PACentroid::plot	(	in	performanceAxesH,
		in	X,
		in	Y
	)

static

function PACentroid::plotPerformance	(	in	this,
		in	axesH
	)

function PACentroid::removeHandleReferences ( in this )

Removes any graphic handle to references. This is a helpful precursor to calling 'save' on the object, as it avoids the issue of recreating the figure handles when the object is later loaded with a 'load' call.

function PACentroid::setCOISortOrder	(	in	this,
		in	sortOrder
	)

function PACentroid::toggleCOISortOrder	(	in	this,
		in	toggleSortIndex
	)

function PACentroid::toggleDayOfInterestOrder	(	in	this,
		in	dayOfInterest
	)

function PACentroid::toggleOnCOISortOrder	(	in	this,
		in	sortOrder
	)

This sets the given index into coiToggleOrder to true and also sets the coiSortOrder value to the given index. This performs similarly to setCOISortOrder, but here the coiToggleOrder is not reset (i.e. all toggles turned off).

Parameters

this	Instance of PACentroid
sortOrder

Return values

didChange

A boolean response

True if the coiToggleOrder(sortOrder) was set to true and coiSortOrder was set equal to sortOrder
False otherwise

function PACentroid::toggleOnNextCOI ( in this )

function PACentroid::toggleOnPreviousCOI ( in this )

Member Data Documentation

Property PACentroid::calculationState

protected

Numeric value indicating current state: values include.

0 Ready
-1 Failed to converge
1 Calculating
-2 User cancelled
2 Converged successfully

Constant Property PACentroid::WEEKDAY_ORDER = 0

The documentation for this class was generated from the following file:

c_version_comments/PACentroid.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation