(notes on parameters, for San Jose conference, 2019-05-14)

A Graph has one or more sets of data plotted as an XY graph. There may be multiple sets

of data displayed in the Y axis - but all of those share a single X-axis.

There are therefore a number of parameters which can be optionally defined for the entire

graph; then there are other parameters which can be set for each of the datasets to be displayed.

There are two distinct Y axes - the 'normal' one plus optionally one on the right.

Each dataset will describe whether it uses the right axis or defaults to the normal one.

Graphs can have both grids and/or ticks on the axes. There are settings to allow the app

developer to specify the exact values to use for how often each of these occur, and how often

they are labelled.

However, the recommended aproach is to allow GraphMaker to adaptively choose suitabnle values.

hereby (hopefuly) ensuring that the graph remains effective over a wide range of value-ranges

that might be encountered.

There are settings that can be used to bias the adaption;

["hints"] for each axis's TickInterval, TickLabelSpacing and GridInterval, GridLabelSpacing

settings - see below for details.

Global parameters

-----------------

XRangeIncludes - list of x values to be included

XFit - round limits to multiple of this

YRangeIncludes, YFit - same for Y

YRightRangeIncludes, YRightFit - same for Y on right

Title - a title (displayed at the top of the graph)

XAxisTitle, YAxisTitle, YRAxisTitle - titles to be displayed by each axis

XTickInterval - value (in data units) between tick marks

empty (default) adaptively calculate where to put ticks

> 0 put ticks at multiples of interval (0, 2, 4, ...)

0 draw the axis, but no ticks

<0 No ticks or axis at all

XTickLabelSpacing : 'N' = put label at each N'th tick ...

empty (default) for adaptive,

0 for none (i.e. no ticks, no space set aside)

-1 no ticks, but leave space - e.g. for a XTicklabels dataset

XGridInterval - gap (in data units) between vertical grid lines (i.e. for X valuea)

0 or empty (default) for grid at "labelSpacing" points (i.e. adaptive)

-1 for no grid

'N' for one grid line every Nth tick

backgroundcolor - color for background of the whole graph

YGridInterval, YTickInterval, YTickLabelSpacing : same as for X, but for Y

YRGridInterval, YRTickInterval, YRTickLabelSpacing : same but for Y on the right

DataIncludesX - if TRUE, then each line of each dataset contains an X value

- otherwise, no X values are present in the datasets,

and this element contains (up to) two values : initial and step X values

default (i.e. empty) is for inital value of 0, and step value 1

NB - applies to ALL datasets

hints - contains for each axis, hints to determine the interval and labelspacing values for both

Ticks and Grids. This sets the initial, minimum, maximum and step-multiplier to use in

the calculations.

NOT YET IMPLEMENTED

Then there are the datasets.

Data - one or more datasets, numerically indexed, in bottom-to-top drawing order.

(e.g. tA["data"][1])

Dataset Parameters

------------------

NB these 'dataset' parameters can also be set at the top level, and

then become the default for all datasets, but can be overridden for

individual datasets.

name - the name of this dataset (not actually used for anything yet)

graphtype one of bar, line, step, Xticklabels, Yticklabels, Xgridlabels, Ygridlabels

for "line", we can also set

filled - fill in below this line, with fillcolor

invisible (i.e. no line segments, but still draw markers)

for "step", we can also set

horizontalFirst, otherwise we go vertical first

(i.e. whether to go up/down then along, or along then up/down)

Note that bar, step and line graphs can be "stacked" - i.e. there can be multiple Y values

producing "stacked" graphs.

Likely future additional graphtype - bubble charts.

color : colour value, one per line for stacked charts

lineSize : size (width) of the line to be drawn, one per line for stacked charts

fillcolor : color for the filled in polygon, one per line for stacked charts

fillblend : blend level for the filled polygon, one per line for stacked charts

values - list of values for the dataset

- so either Y, or if DataIncludesX then X,Y

- or Y,Y,Y,Y... or if DataIncludesX then X,Y,Y,Y,... - producing 'stacked' lines

NB these all share other values, but can have different colors

- or, if graphtype=Xlabels then it is 'label' or if DataIncludesX then X,Label

allowColonDel : replace ":" with CR in the "values" - for convenience (default ON)

explicitly set to FALSE turn off

blendlevel - blend level for drawing

dropshadow - put in a dropshadow,

either TRUE for a default shadow

or a list of lines of name,value pairs ovrriding

the default

dashed, dotted, dotdashed - set true for GM'sdefault setting, or specify a

"dashes" setting for the line

YRaxis : use the Right axis for scaling, etc.

marker : name of marker shape to use (diamond, square, ???)

markersize : size of marker

markercolor : color for marker

barDensity : specifies the percentage of the ratio between bar and gap

(e.g. 50 would say that each bar is the same size as the gap,

75 would say the bar takes 3/4 of the unit width, while the gap takes the rest, etc.)_

Default is 75

X Value spacing

For a graph consisting only of line charts, the calculation of X_value spacing is straightforward. We calculate the spread of X data values (i.e. min to max values, plus anything specified in an 'XIncludes', and then rounded out to include anything needed for an 'XFit'). Let's call this the "virtual data range". This range of values is then scaled to cover the visual space from the Y-axis to the right-Y-axis.

However, for a bar-chart, we need to allow the space for a 1/2 gap width plus a 1/2 bar width on each side of these (virtual) data values. Also, we need to allow a way to specify the 'density' of the display - i.e. how wide the bars are, and how wide the gaps between them are. And, especially in the case of DataIncludesX

Xunit - Xunit (NB shared for all datasets in the whole graph)

Xunit specifies the unit size (i.e. in 'source data' terms)

The default is for the Xunit to be 1 (as it will be unless DataIncludesX is TRUE), while the default for barDensity is 75.

Parameters and settings NOT implemented

---------------------------------------

(not yet)

---------

YAxis Title

Line type (dotted, dashed, etc.)

Invisible gaps in data (?)

Off-grid line labels

Specified position for axes (e.g. draw the Y axis at X=200, rather

than at minX)

Axis breaks (i.e. to indicate off-scale axis)

XGridMinor - number of minor grids per major grid

set to 0 (default) for no minor grid

(same for YGridMinor and YRGridMinor)

XTGridInterval, XTGridMinor, XTTickInterval - as X for top axis

(and some that probably never will be)

----------------------------

?? XRange - specify min/max in X for drawing (i.e. USE THIS, ignore values in datasets)

?? YRange

?? YRightRange