View source for Plot axis thresholds

[[Category:OnGraphDraw annotations library functions]]
''Added in [[Analytica 6.3]]''.

This function is used in the [[OnGraphDraw]] attribute  to display threshold line annotations on top of an existing plot.  It is a function in the [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]].

<center>[[image:Threshold line example - Effective rate.png]]</center>

== Plot_axis_thresholds( canv, info, roles, axis, ...thresholds ) ==

Plots multiple threshold lines on a graph.  To use, call this from [[OnGraphDraw]].

A threshold line can mark a specific value along the X-axis, or a specific value along the Y-axis. The threshold line extends across the plot area at the given value, and then optionally draws a label for the line above or to the right.

This currently only works for an axis that corresponds to a specific variable or index. In particular, it is not possible to use this with a comparison column. 

As it draws, it tests for label overlap with previously drawn threshold labels, and omits a label if it would overlap a previously drawn one. This avoids the ugly case where you get a bunch of unreadable overlapping labels, as would occur if you drew each threshold line indepently. 

The function adapts to changes in the uncertainty view, pivots, manual scaling (zooming), and swap XY. You can customize the appearance of each threshold line separately.

[[image:Threshold Y line example - Effective rate.png]]

== Current limitations ==
* horizontal axis thresholds, draw just above the plot area, may overlap the graph title.
* Does not yet work a categorical axis.

== Usage ==
Pass locals from OnGraphDraw to the first three parameters.
Pass a handle to the variable or index for the axis of interest.
Define each threshold line by calling Axis_threshold_line(...). 

Example (in OnGraphDraw with "after fully drawn" checked):

 [[Plot_axis_thresholds]]( canv, info, roles, Handle( MyResult ), 
       [[Axis_threshold_line]]( 10, "Alarm min", color:'green' ),
       [[Axis_threshold_line]]( 75, "Alarm max", color:'red' )
 )

The two images show above were produced using this [[OnGraphDraw]] expression:

 [[Local]] m := [[Mean]](Self), sd := [[SDeviation]](Self);
 &nbsp;
 [[Plot_axis_thresholds]](canv, info, roles, Handle(Effective_rate),
 	[[Axis_threshold_line]](m,f"Mean:{m:%1}", color:'green', width:2, bold:true),
 	[[Axis_threshold_line]](m-sd,f"Low:{m-sd:%1}",dash:'Dash', width:2),
 	[[Axis_threshold_line]](m+sd,f"High:{m+sd:%1}",dash:'Dash', width:2)	
 )

== <span id="Axis_threshold_line">Axis_threshold_line</span>( value'', label, color, width, dash, font, fontSize, bold, italics'' ) ==

This function is used in conjunction with [[Plot_axis_threshold]] to define a threshold line and its visual properties. It is found in the [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library]]. Pass the result of this function to the «thresholds» parameter of [[Plot_axis_thresholds]]. To draw multiple threshold lines for the same axis, call once for each and pass each result to «thresholds».

«value» is the only required parameter.

== See also ==
* [[:Category:OnGraphDraw annotations library functions|OnGraphDraw annotations library functions]]
* [[OnGraphDraw]]