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

    All Methods Static Methods Instance Methods Concrete Methods
    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.