GraphToCanvasCoord

(New to Analytica 5.2)

This function is only used from within the OnGraphDraw attribute expression, or from User-Defined Functions that are called from OnGraphDraw. Use this function when you need to figure out the pixel coordinates of a data point on the graph when annotating a graph using the Canvas Drawing Functions.

GraphToCanvasCoord( info, roles, x,y, cluster, flags )

Returns the pixel coordinates, xPx and yPx in a graph with specified info and roles, given the data coordinates, «x» and «y». «x» is in units of the variable or index used for the independent axis -- i.e. the horizontal axis unless you have checked Swap horizontal and vertical in Graph Setup. «y» is in units of the dependent axis, usually the vertical axis. For example, when viewing a graph of Revenue vs. Time, this code in the OnGraphDraw attribute) draws a circle on the graph at Time=2020, Revenue=1M

Local (x,y) := GraphToCanvasCoord(info, roles, 2020, 1M );

CanvasDrawEllipse(canv, x-5, y-5, 11, 11)

The function returns pixel x and pixel y as separate return values, so you have to capture multiple return values to access y. Hence, in the above example, you must include the parentheses around (x,y) in the Local declaration.

Do not use this function when phase=1 -- before layout -- because info and roles have not yet been established at that point.

When you have a bar chart with a color index and a cluster index, you can use this to map from (x, y, cluster) to pixel x, pixel y. In this case, both «x» and «y» are categorical values, often text. When supplying «cluster», named parameter calling syntax is required (at least for «cluster». At present, the function does not handle clustered bar charts that use a value for the Color role (as opposed to an index for the Color role).

Graphs can be pivoted by the end-user, so your code in OnGraphDraw may need to be cognizant about which value is assigned to which axis.

The function automatically adjusts for linear vs. log axis scaling, continuous vs. categorical axes, Swap horizontal and vertical, and reverse axis order, and manual axis scaling (e.g., zoom) in the current view. As a result, it greatly simplifies the creating of graph annotations.

An end-user can also manually scale an axis, for example to zoom into a part of the graph. In this case, the data point you map to pixels may land outside of the visible plot area. You may want to take this into account in your annotation code. In some cases, you might want to not draw anything for these out-of-range points, for example when annotating points with labels -- otherwise, the label would be dawn outside the plot area. In other cases, you might want to clip the drawing to the plot area (using CanvasContext, for example when drawing lines between points. The 3rd return value is a boolean (or array of booleans when transforming an array of points) that indicates whether the point is within the plot area visible range. Or you can set «flag» to 1 to return null for out-of-range pixel x or pixel y, which will often cause your drawing code to ignore these points automatically without any additional code or your part.

Parameters

• «info», «roles»: These are the values for the local variables info and roles that are available to OnGraphDraw. You need to just forward those as-if to this function. These are not available in the 'before layout' phase, i.e., when phase=1; hence, the function cannot be used in that phase.
• «x»: A value along the dependent-axis -- i.e., along the horizontal axis when Swap horizontal and vertical is off, or along the vertical axis when it is on.
• «y»: A value along the independent-axis -- i.e., along the vertical axis when Swap horizontal and vertical is off, or along the horizontal axis when it is on.
• «cluster»: (Optional) A value in the cluster index in a clustered bar chart. Only use this for a clustered bar chart with an index for Color. (At present, the function does not support the case where a value is used for color). This parameter must be specified using a named-parameter syntax, e.g., cluster:someVal.
• «flags»: (Optional). A sum of zero or more of the following values:
  • 1 = Return Null for pixel x or pixel y when the respective «x» or «y» value is not within the current plot area. When a graph is manually scaled (zoomed), some points may land outside of the plot area. Without this flag, it will return pixel coordinates that may land outside that plot area frame.
  • 2 = Return the "far" end of a categorical interval along the y-axis. This would be the "top" of a bar, for example, in a horizontal bar chart with a non-reversed axis. Without this (or flag=4), the center of the category interval is returned. This flag is ignored for non-bar-charts unless the flag=8 bit is set.
  • 4 = Return the "near" end of a categorical interval along the y-axis. Ignored for non-bar-charts except with the flag=8 bit is set.
  • 8 = Apply the flag=2 or flag=4 bit to non-bar charts. Without this, flag=2 or flag=4 apply only to bar charts.

Return values

It returns three values:

1. The horizontal coordinate of the point in pixel coordinates.
2. The vertical coordinate of the point in pixel coordinates.
3. True when the point is within the plot area (given the current axis scaling), False if it falls outside the current plot area.

To access the 2nd and 3rd return values, you must use the multiple-return-value capture syntax, which consists of placing parentheses around the local identifiers as follows:

Local (pixel_x, pixel_y, isVisible) := GraphToCanvasCoord(...)

See Also

• OnGraphDraw
• Drawing images