The Category Class

Introduction

Purpose: A Category object is, essentially, an interval of values and a corresponding interval of indexes.

Category objects can be used in a wide variety of applications. For example, when used as part of a system for calculating the Air Quality Index (AQI) for carbon monoxide (CO), the Category with a description of "Moderate" would correspond to the values in the interval [4.4,9.5) and indexes in the interval [50,100).

Category objects are immutable.

Background

Definitions:

Interval: An interval is a set of real numbers or integers defined by a lower bound and an upper bound. The notation \([a,b)\) is used to denote the half-open interval defined as \(\{x: a \leq x \lt b\}\).

Linear Interpolation: Interpolation is a method of calculating a number in an interval. In linear interpolation, the number is a linear combination of the lower and upper bounds of the interval. A Category uses linear interpolation to calculate the index from the value. Letting \(I_\text{low}\) and \(I_\text{high}\) denote the left and right ends of the interval of indexes, \(V_\text{low}\) and \(V_\text{high}\) denote the left and right ends of the interval of values, and \(V\) denote the known value, the corresponding index, \(I\), is defined as: \[ I = I_{\text{low}} + \frac{I_\text{high}-I_\text{low}}{V_\text{high}-V_\text{low}} \cdot (V - V_\text{low}) \]

Note that, since \(I\) is an integer index, the right-hand side must be rounded to the nearest integer. For example, given an interval of values of \([4.4, 9.5)\) and an interval of indexes of \([50, 100)\), the value \(8.4\) corresponds to an index of:

\[ 50 + \frac{100 - 50}{9.5 - 4.4} \cdot (8.4 - 4.4) = 50 + \frac{50}{5.1} \cdot 4 = 89.216 \]

which is rounded to \(89\).

Details

Attributes:

This class must, at a minimum, contain the following private attributes:

description

String

Category

indexHigh

int

indexLow

int

valueHigh

double

valueLow

double

It may contain other private attributes as well.

The Explicit Value Constructor:

This class must implement the following explicit value constructor:

    /**
     * Explicit Value Constructor.
     *
     * @param description  A textual description of the Category (e.g., "Moderate")
     * @param indexLow     The left end of the interval of indexes (e.g. 50)
     * @param indexHigh    The right end of the interval of indexes (e.g., 100)
     * @param valueLow     The left end of the interval of values (e.g., 4.4)
     * @param valueHigh    The right end of the interval of values (e.g., 9.5)
     */
    public Category(String description, 
                    int    indexLow, int    indexHigh,
                    double valueLow, double valueHigh) 
    {
    }

The indexOf(double) Method:

This class must implement the following method:

    /**
     * Calculate the corresponding index (using linear interpolation)
     * for a value in the interval of values that defines this Category.
     * For example, if this Category has an interval of values of [4.4,9.5) 
     * and an interval of indexes of [50,100), this method returns 89
     * when passed a value of 8.4. (Note: This method uses Math.round()
     * to perform the rounding and typecasts the result to an int.)
     *
     * @param value  The value of interest
     * @return       The corresponding index (or -1 if the value is invalid)
     */
    public int indexOf(double value)
    {
    }

The includesIndex(int) Method:

This class must implement the following method:

    /**
     * Determine if the given index is included in this
     * Category
     *
     * @param  index   The index of interest
     * @return         true if the index is in this Category; false otherwise
     */
    public boolean includesIndex(int index)
    {
    }

The includesValue(double) Method:

This class must implement the following method:

    /**
     * Determine if the given value is included in this
     * Category
     *
     * @param  value   The value of interest
     * @return         true if the value is in this Category; false otherwise
     */
    public boolean includesValue(double value)
    {
    }

Accessors:

This class must implement the following accessors:

    public String getDescription()