org.gicentre.utils.stat

Class LikertChart

java.lang.Object

org.gicentre.utils.stat.LikertChart

public class LikertChart
extends java.lang.Object

Class for storing and drawing Likert scaled data. That is, a set of frequencies in an ordered dataset. Typically, these are questionnaire responses in the form 'strongly disagree', 'disagree', 'neutral', 'agree' and 'strongly agree'. Likert scales can be over any range, but are typically between 3 and 7 and usually odd.

Version:

3.4, 5th February, 2016.

Author:

Jo Wood, giCentre, City University London.

Constructor Summary

Constructors

Constructor and Description
LikertChart(float[] frequencies) Creates a Likert chart of the given set of frequencies.
LikertChart(float[] frequencies, float maxHeight, float minHeight) Creates a Likert chart of the given set of frequencies scaled to the given maximum and minimum value.
LikertChart(float[] frequencies, float numDontKnow, float numNA, float numMissing, java.lang.String title) Creates a Likert chart of the given set of frequencies and non-responses and the given short title.
LikertChart(float[] frequencies, float numDontKnow, float numNA, float numMissing, java.lang.String title, java.lang.String longTitle) Creates a Likert chart of the given set of frequencies and non-responses and the given titles.

Method Summary

Modifier and Type	Method and Description
void	animateFromBars() Triggers an animation away from a histogram representation to the summary state.
void	animateToBars() Triggers an animation to a histogram representation from the summary state.
void	animateToNewValues(float[] newFrequencies, float newNumDontKnow, float newNumNA, float newNumMissing) Provides an animated transition to the given set of values.
void	draw(processing.core.PApplet parent, java.awt.geom.Rectangle2D bounds) Draws the Likert chart within the given rectangle but without any text labelling.
void	draw(processing.core.PApplet parent, java.awt.geom.Rectangle2D bounds, processing.core.PFont font) Draws the Likert chart within the given rectangle with text labelling in the given font.
float	getAnimationSpeed() Reports the animation speed for all transitions (e.g.
int	getBarAt(float xCoord, float yCoord) Reports the bar at the given (x,y) location.
float	getConsensus() Reports the consensus score of this Likert distribution.
static java.util.Comparator<LikertChart>	getConsensusComparator() Provides a comparator that can be used for sorting Likert charts by their consensus scores.
static java.util.Comparator<LikertChart>	getCustomComparator() Provides a custom comparator that can be used for sorting Likert charts in the order implied by the values provided to setOrder().
float[]	getFrequencies() Reports the frequency values that are used to produce the Likert chart.
int	getHighlightBar() Reports the index of the currently highlighted bar or -1 if no bar highlighted.
java.lang.String	getLongTitle() Reports the long title of this Likert chart.
float	getMean() Reports the mean score of this Likert distribution.
static java.util.Comparator<LikertChart>	getMeanComparator() Provides a comparator that can be used for sorting Likert charts by their mean scores.
float	getOrder() Reports the order value used for custom ordering of a collection of Likert charts.
int	getSecondaryColour() Reports the colour to be used for the secondary data in the chart.
LikertChart	getSecondaryData() Reports the seconday data that may be drawn in this chart.
int	getTextColour() Reports the colour to be used for the title of the chart and any other text.
float	getTextPadding() Reports the extra padding between title and chart.
float	getTextSize() Reports the size of the title text in pixels or -1 if text size is calculated automatically.
java.lang.String	getTitle() Reports the title of this Likert chart.
float	getWidthScale() Reports the proportion of the width allocated to each bar that contains a coloured bar.
void	setAnimationSpeed(float numFrames) Sets the animation speed for all transitions (e.g.
void	setColourTable(ColourTable cTable) Sets the colour table to be used to show the Likert chart.
void	setHighlightBar(int barIndex) Allows a bar to be highlighted or highlight removed.
void	setOrder(float order) Sets the order value used for custom ordering of a collection of Likert charts.
void	setScaleToPrimary(boolean usePrimary) Determines whether bars are scaled to the primary data values or the secondary data values (if they exist).
void	setSecondaryChart(LikertChart secondaryChart) Add a secondary chart to the Likert chart.
void	setSecondaryColour(int colour) Sets the colour to be used for the secondary data in the chart.
void	setSecondaryDisplay(boolean showSecondary) Determines whether or not the secondary chart can be displayed.
void	setSecondaryLineWidth(float width) Sets the width of the secondary line symbolisation.
void	setShowBars(boolean showBars) Determines if histogram bars should be shown.
void	setShowTitle(boolean showTitle) Determines whether or not the title is displayed on the chart.
void	setTextColour(int colour) Sets the colour to be used for displaying the title of the chart.
void	setTextPadding(float padding) Sets the extra padding between title and chart.
void	setTextSize(float size) Sets the size of the title text in pixels or -1 if text size is to be calculated automatically.
void	setWidthScale(float widthScale) Sets the proportion of the width allocated to each bar that contains a coloured bar.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LikertChart

public LikertChart(float[] frequencies)

Creates a Likert chart of the given set of frequencies. Chart will be scaled to the maximum frequency provided.

Parameters:

frequencies - An ordered set of frequencies.

LikertChart

public LikertChart(float[] frequencies,
                   float maxHeight,
                   float minHeight)

Creates a Likert chart of the given set of frequencies scaled to the given maximum and minimum value. Can be negative (for example to represent deviation from an expected frequency).

Parameters:

frequencies - An ordered set of frequencies.

maxHeight - Maximum value by which the chart bars are scaled.

minHeight - Minimum value by which the chart bars are scaled.

LikertChart

public LikertChart(float[] frequencies,
                   float numDontKnow,
                   float numNA,
                   float numMissing,
                   java.lang.String title)

Creates a Likert chart of the given set of frequencies and non-responses and the given short title.

Parameters:

frequencies - An ordered set of frequencies.

numDontKnow - Number of 'Don't know' responses.

numNA - Number of 'not applicable' responses.

numMissing - Number of missing responses. This value can be used to provide a fixed vertical scaling of several Likert charts.

title - Short title of chart or null if no title is to be shown.

LikertChart

public LikertChart(float[] frequencies,
                   float numDontKnow,
                   float numNA,
                   float numMissing,
                   java.lang.String title,
                   java.lang.String longTitle)

Creates a Likert chart of the given set of frequencies and non-responses and the given titles.

Parameters:

frequencies - An ordered set of frequencies.

numDontKnow - Number of 'Don't know' responses.

numNA - Number of 'not applicable' responses.

numMissing - Number of missing responses. This value can be used to provide a fixed vertical scaling of several Likert charts.

title - Short title of chart or null if no title is to be shown.

longTitle - Long title of chart or null if no long title is to be shown.

Method Detail

draw

public void draw(processing.core.PApplet parent,
                 java.awt.geom.Rectangle2D bounds)

Draws the Likert chart within the given rectangle but without any text labelling.

Parameters:

parent - Processing applet in which to draw the chart.

bounds - Rectangle within which to scale the chart.

draw

public void draw(processing.core.PApplet parent,
                 java.awt.geom.Rectangle2D bounds,
                 processing.core.PFont font)

Draws the Likert chart within the given rectangle with text labelling in the given font.

Parameters:

parent - Processing applet in which to draw the chart.

bounds - Rectangle within which to scale the chart.

font - Font used to display text, or null if no text to be displayed.

setColourTable

public void setColourTable(ColourTable cTable)

Sets the colour table to be used to show the Likert chart. The colour table should be scaled between +-1, probably using a diverging colour scheme. For a default uniform colour, the cTable value should be null.

Parameters:

cTable - Colour table to use for showing Likert chart.

setWidthScale

public void setWidthScale(float widthScale)

Sets the proportion of the width allocated to each bar that contains a coloured bar. This allows the gaps between adjacent bars to be controlled.

Parameters:

widthScale - Proportion of the width allocated to each bar that is drawn. Should be scaled between 0 and 1.

setShowBars

public void setShowBars(boolean showBars)

Determines if histogram bars should be shown.

Parameters:

showBars - Bars are shown if true.

setSecondaryChart

public void setSecondaryChart(LikertChart secondaryChart)

Add a secondary chart to the Likert chart. If not null, both sets of data from this class and the given secondary chart can be shown together. To remove the secondary chart permanently, set the given value in this method to null. To temporarily stop the display of the secondary chart consider using setSecondaryDisplay(false).

Parameters:

secondaryChart - Second set of data to display in chart, or null if no secondary data to be displayed.

setSecondaryDisplay

public void setSecondaryDisplay(boolean showSecondary)

Determines whether or not the secondary chart can be displayed. If false, the secondary data are never displayed although scaling of charts can still be applied to secondary data if they exist.

Parameters:

showSecondary - Secondary data displayed if true and they exist, otherwise no secondary data displayed.

setSecondaryColour

public void setSecondaryColour(int colour)

Sets the colour to be used for the secondary data in the chart. Colour is represented using a 32 bit integer.

Parameters:

colour - Colour to be used for secondary data (using Processing's integer colour format).

setSecondaryLineWidth

public void setSecondaryLineWidth(float width)

Sets the width of the secondary line symbolisation.

Parameters:

width - Width of lines used to draw Likert summary symbols (can be fractions of a pixel).

getSecondaryColour

public int getSecondaryColour()

Reports the colour to be used for the secondary data in the chart. Colour is represented using a 32 bit integer.

Returns:

Colour to be used for secondary data (using Processing's integer colour format).

setTextColour

public void setTextColour(int colour)

Sets the colour to be used for displaying the title of the chart. Colour is represented using a 32 bit integer.

Parameters:

colour - Colour to be used for chart title and any other text (using Processing's integer colour format).

getTextColour

public int getTextColour()

Reports the colour to be used for the title of the chart and any other text. Colour is represented using a 32 bit integer.

Returns:

Colour to be used for chart title and other text (using Processing's integer colour format).

setHighlightBar

public void setHighlightBar(int barIndex)

Allows a bar to be highlighted or highlight removed. The given value should be the index of the bar to highlight (0 being the first, 1 the second etc.). The bar is highlighted in the current secondary colour. Highlighting can be turned off by providing a negative value to this method.

Parameters:

barIndex - Index of the bar to highlight or -1 if no bar is to be highlighted.

getHighlightBar

public int getHighlightBar()

Reports the index of the currently highlighted bar or -1 if no bar highlighted.

Returns:

Index of the highlighted bar or -1 if no bar is highlighted.

getBarAt

public int getBarAt(float xCoord,
                    float yCoord)

Reports the bar at the given (x,y) location. If there is no bar at this location a -1 is returned. If chart is in the collapsed, non-bar state, this will always return -1.

Parameters:

xCoord - x screen coordinate of point to query.

yCoord - y screen coordinate of point to query.

Returns:

Index of bar found (0 is the first bar, 1 is the second etc.) or -1 if no bar at given location.

animateToBars

public void animateToBars()

Triggers an animation to a histogram representation from the summary state.

animateFromBars

public void animateFromBars()

Triggers an animation away from a histogram representation to the summary state.

animateToNewValues

public void animateToNewValues(float[] newFrequencies,
                               float newNumDontKnow,
                               float newNumNA,
                               float newNumMissing)

Provides an animated transition to the given set of values.

Parameters:

newFrequencies - Frequency distribution of the new values to represent in the chart.

newNumDontKnow - Number of 'don't know' answers in the target distribution.

newNumNA - Number of Not Applicable answers in the target distribution.

newNumMissing - Number of missing values in the target distribution.

getWidthScale

public float getWidthScale()

Reports the proportion of the width allocated to each bar that contains a coloured bar. This allows the gaps between adjacent bars to be controlled.

Returns:

Proportion of the width allocated to each bar that is drawn, scaled between 0 and 1.

getFrequencies

public float[] getFrequencies()

Reports the frequency values that are used to produce the Likert chart.

Returns:

Array of frequency values, one for each bar in the chart.

getSecondaryData

public LikertChart getSecondaryData()

Reports the seconday data that may be drawn in this chart. Can be null if no secondary data are stored. The data are stored in a LikertChart object from which all relevant values can be extracted.

Returns:

Secondary data or null if none exist.

setScaleToPrimary

public void setScaleToPrimary(boolean usePrimary)

Determines whether bars are scaled to the primary data values or the secondary data values (if they exist).

Parameters:

usePrimary - Bars are scaled to primary values if true or secondary values if false and there are secondary values to show.

setShowTitle

public void setShowTitle(boolean showTitle)

Determines whether or not the title is displayed on the chart.

Parameters:

showTitle - Title displayed if true.

getTitle

public java.lang.String getTitle()

Reports the title of this Likert chart.

Returns:

Title of this Likert chart or null if no title defined.

getLongTitle

public java.lang.String getLongTitle()

Reports the long title of this Likert chart.

Returns:

Long title of this Likert chart or null if no long title defined.

getMean

public float getMean()

Reports the mean score of this Likert distribution. The mean will be scaled between 1 and the number of Likert categories. Assumes a uniform interval between adjacent ordered categories.

Returns:

Mean score for this categorical distribution.

getConsensus

public float getConsensus()

Reports the consensus score of this Likert distribution. Consensus is scaled between 0 and 1 where 0 is strongest disagreement (half the values at one extreme of the Likert scale, the other half at the opposite extreme) and 1 is complete agreement (all values in the same Likert category).

Returns:

Mean score for this categorical distribution.

setOrder

public void setOrder(float order)

Sets the order value used for custom ordering of a collection of Likert charts. Ordering is from low to high.

Parameters:

order - Order value used when providing a custom sort of charts.

setAnimationSpeed

public void setAnimationSpeed(float numFrames)

Sets the animation speed for all transitions (e.g. animation to new data).

Parameters:

numFrames - Number of frames to complete a transition.

getAnimationSpeed

public float getAnimationSpeed()

Reports the animation speed for all transitions (e.g. animation to new data).

Returns:

Number of frames to complete a transition.

setTextSize

public void setTextSize(float size)

Sets the size of the title text in pixels or -1 if text size is to be calculated automatically.

Parameters:

size - Title text size in pixels.

getTextSize

public float getTextSize()

Reports the size of the title text in pixels or -1 if text size is calculated automatically.

Returns:

Title text size in pixel units.

setTextPadding

public void setTextPadding(float padding)

Sets the extra padding between title and chart.

Parameters:

padding - Number of extra pixels between the title and the chart.

getTextPadding

public float getTextPadding()

Reports the extra padding between title and chart.

Returns:

Extra padding between title and chart in pixel units.

getOrder

public float getOrder()

Reports the order value used for custom ordering of a collection of Likert charts. Ordering is from low to high.

Returns:

Order value used when constructing an custom sort.

getCustomComparator

public static java.util.Comparator<LikertChart> getCustomComparator()

Provides a custom comparator that can be used for sorting Likert charts in the order implied by the values provided to setOrder(). If two Likert charts have the same order value, they are sorted into a consistent but platform dependent order.

Returns:

Comparator able to compare the order values of two Likert charts.

getMeanComparator

public static java.util.Comparator<LikertChart> getMeanComparator()

Provides a comparator that can be used for sorting Likert charts by their mean scores. If two Likert charts have the same mean, they are sorted by order value.

Returns:

Comparator able to compare the means of two Likert distributions.

getConsensusComparator

public static java.util.Comparator<LikertChart> getConsensusComparator()

Provides a comparator that can be used for sorting Likert charts by their consensus scores. If two Likert charts have the same consensus, they are sorted by mean score.

Returns:

Comparator able to compare the consensus of two Likert distributions.