Libraries.Compute.Statistics.Sorting.LabelComparison Documentation

The LabelComparison class is a Comparison that orders text labels according to a caller-supplied order, instead of the default alphabetical or hash-code order. This is useful for ordering the categories of a factor column in a chart. For example, a column of sizes can be displayed in the order Low, Medium, High rather than alphabetically. The desired order is provided once through the SetOrder action. Internally, each label is mapped to its position using a HashTable, so each comparison is a constant time lookup. Labels that are not present in the supplied order are sorted after all known labels.

Example Code

use Libraries.Compute.Statistics.Sorting.LabelComparison
use Libraries.Compute.Statistics.DataFrame
use Libraries.Compute.Statistics.DataFrameColumn
use Libraries.Containers.Array

class Main
    action Main
        DataFrame frame
        frame:Load("data/items.csv")
        frame:AddSelectedColumns("Count")
        frame:AddSelectedFactors("Size")

        Array<text> order
        order:Add("Low")
        order:Add("Medium")
        order:Add("High")

        LabelComparison sorter
        sorter:SetOrder(order)

        DataFrameColumn column = frame:GetColumn("Size")
        column:SetSortComparison(sorter)
    end
end

Inherits from: Libraries.Containers.Support.Comparison, Libraries.Language.Object

Actions Documentation

Compare(number a, number b)

This action provides a way to compare two objects. The returned values from its sole action is an integer with the value of -1 (the left item is smaller), 0 (the items are equal) or 1 (the left item is larger).It can be used to override the standard comparison in Object for various applications (e.g., sorting).

Parameters

  • number a
  • number b

Return

integer:

Compare(integer a, integer b)

This action provides a way to compare two objects. The returned values from its sole action is an integer with the value of -1 (the left item is smaller), 0 (the items are equal) or 1 (the left item is larger).It can be used to override the standard comparison in Object for various applications (e.g., sorting).

Parameters

  • integer a
  • integer b

Return

integer:

Compare(Libraries.Language.Object a, Libraries.Language.Object b)

This action compares two label objects according to the order supplied to SetOrder. It returns -1 if the first label comes before the second, 1 if it comes after, and 0 if they share the same position. This action is called automatically by the sorting machinery and is not usually called directly.

Parameters

Return

integer: -1, 0, or 1 indicating the relative order of the labels.

Example

use Libraries.Compute.Statistics.Sorting.LabelComparison
use Libraries.Containers.Array
use Libraries.Language.Types.Text

Array<text> order
order:Add("Low")
order:Add("High")

LabelComparison sorter
sorter:SetOrder(order)

Text low
low:SetValue("Low")
Text high
high:SetValue("High")
integer result = sorter:Compare(low, high)

Compare(Libraries.Language.Object object)

This action compares two object hash codes and returns an integer. The result is larger if this hash code is larger than the object passed as a parameter, smaller, or equal. In this case, -1 means smaller, 0 means equal, and 1 means larger. This action was changed in Quorum 7 to return an integer, instead of a CompareResult object, because the previous implementation was causing efficiency issues.

Parameters

Return

integer: The Compare result, Smaller, Equal, or Larger.

Example

Object o
Object t
integer result = o:Compare(t) //1 (larger), 0 (equal), or -1 (smaller)

Compare(boolean a, boolean b)

This action provides a way to compare two objects. The returned values from its sole action is an integer with the value of -1 (the left item is smaller), 0 (the items are equal) or 1 (the left item is larger).It can be used to override the standard comparison in Object for various applications (e.g., sorting). In the case of booleans, by default, false is considered less than true.

Parameters

  • boolean a
  • boolean b

Return

integer:

Equals(Libraries.Language.Object object)

This action determines if two objects are equal based on their hash code values.

Parameters

Return

boolean: True if the hash codes are equal and false if they are not equal.

Example

use Libraries.Language.Object
use Libraries.Language.Types.Text
Object o
Text t
boolean result = o:Equals(t)

GetHashCode()

This action gets the hash code for an object.

Return

integer: The integer hash code of the object.

Example

Object o
integer hash = o:GetHashCode()

GetPosition(text label)

This action returns the sort position of a label. If the label was part of the order supplied to SetOrder, its index is returned. Otherwise a position after all known labels is returned, so unknown labels sort last.

Parameters

  • text label: The text label to look up.

Return

integer: The integer sort position of the label.

Example

use Libraries.Compute.Statistics.Sorting.LabelComparison
use Libraries.Containers.Array

Array<text> order
order:Add("Low")
order:Add("High")

LabelComparison sorter
sorter:SetOrder(order)
integer position = sorter:GetPosition("High")

SetOrder(Libraries.Containers.Array<text> labels)

This action sets the order in which labels should be sorted. Each label is mapped to its index in the supplied array, so comparisons are constant time. Any label not in this array is treated as coming after all of the supplied labels.

Parameters

Example

use Libraries.Compute.Statistics.Sorting.LabelComparison
use Libraries.Containers.Array

Array<text> order
order:Add("Low")
order:Add("Medium")
order:Add("High")

LabelComparison sorter
sorter:SetOrder(order)