New type: Histogram

[pedro-andrade-inpe]

Implement type Histogram, an observer to draw a set of values as bars that can be updated along the simulation.

[pedro-andrade-inpe]

An initial implementation of Histogram that does not work well as it is not possible to draw everything at once:

Histogram_ = {
    type_ = "Histogram",
    --- Save a Histogram into a file. Supported extensions are bmp, jpg, png, and tiff.
    -- @arg file A string with the file name.
    save = function(self, file)
        self.chart:save(file)
    end,
    --- Update the Histogram with the latest values of its target. It is usually recommended
    -- to use the Histogram as action of an Event instead of calling this function explicitly.
    update = function(self)
        local total = {}

        for i = 0, self.slices do
            total[i] = 0
        end

        forEachAgent(society, function(agent)
            local dist = math.ceil(agent[self.select](agent))
            print(dist)
            total[dist] = total[dist] + 1
        end)

        self.chart:restart()

        for i = 0, self.slices do
            self.counter.total = total[i]
            self.chart:update(i)
        end
    end
}

metaTableHistogram_ = {__index = Histogram_}

--- Create a histogram showing counts of values grouped into classes.
-- @arg attrTab.target The object to be observed. Supported types are Society and CellularSpace.
-- @arg attrTab.color An optional table where each position is a color for the respective attribute,
-- described as strings ("red", "green", "blue", "white", "black",
-- "yellow", "brown", "cyan", "gray", "magenta", "orange", "purple", and their light and dark
-- compositions, such as "lightGray" and "darkGray"), or as tables with three integer numbers
-- representing RGB compositions.
-- @arg attrTab.title An overall title to the Histogram. The default value is "".
-- @arg attrTab.symbol The symbol to be used to draw the points of the Histogram. It can be a string to
-- be used by all lines, or a vector of strings, describing the symbol for each line. The available
-- values are: "square", "diamond", "triangle", "ltriangle" (left), "dtriangle" (downwards triangle),
-- "rtriangle" (right), "cross", "vcross" (vertical cross), "hline", "vline", "asterisk",
-- "star", "hexagon", and "none" (default).
-- @arg attrTab.size The size of the symbol, in pixels. It can be a number to be used by all lines.
-- or a vector of numbers, describing the size for each line. The default value is 7.
-- @arg attrTab.pen The pen style for drawing lines. It can be one of "solid" (default), "dash",
-- "dot", "dashdot", or "dashdotdot". It can be a vector or a single value.
-- @arg attrTab.style The style of each line to be drawn. It can be a string, indicating that all lines
-- will have the same style, or a vector of strings describing each line. The possible values are:
-- "lines", "dots", "none", "steps", and "sticks". The default value is "lines" for all lines.
function Histogram(attrTab)
    verifyNamedTable(attrTab)

    verifyUnnecessaryArguments(attrTab, {
        "target", "select", "max", "slices",
    })

    if not belong(type(attrTab.target), {"Society", "CellularSpace"}) then
        customError("soc or cs!")
    end

    mandatoryTableArgument(attrTab, "select", "string")
    mandatoryTableArgument(attrTab, "max", "number")
    mandatoryTableArgument(attrTab, "slices", "number")
    defaultTableValue(attrTab, "min", 0)

    attrTab.counter = Cell{total = 0}

    attrTab.chart = Chart{
        target = attrTab.counter,
        xLabel = "Distance",
        yLabel = "Proportion"
    }

    setmetatable(attrTab, metaTableHistogram_)

    attrTab:update()
    return attrTab
end