How To Overplot using a different axis range

*************************************************************************************************

NOTE:  With the IDL 8 Function Graphics, one can produce very similar results to the iTools procedure described in this help article. An example of this is shown in the code below:

pro axis_with_diff_data_ex

f1=findgen(100)
f2=sin(findgen(100))
data2=f2
nop=plot(data2, /nodata, axis_style=0)
p2=plot(f2, axis_style=0, /current, color='red')
p1=plot(f1, axis_style=1, /current)
a=axis('Y', location=[f1[-1]+1,0], tickdir=0,textpos=1, target=nop)

end

*************************************************************************************************

Occasions arise when iTools programmers need to overlay two variables of vastly different value ranges on the same plot. In a common scenario the X-axis data is the same for both variables, however the Y data is very different. For useful display of the plot lines two Y-axes of different ranges are called for. This Help Article is designed to demonstrate a programmatic approach for visualizing these different Y-axes in iTools. (The GUI approach will also be apparent from this Help Article, though it is not described in full.)

This is the kind of task that, in traditional Direct Graphics IDL PLOT's/OPLOT's, would be performed with the AXIS procedure and its SAVE keyword. It is not a completely trivial task in iPlot because iPlot's default behavior for its OVERPLOT keyword function is to rerange the original iPlot visualization so that all data sets fit in one set of axes and axes ranges. Thus, if you run the following commands:

IDL> x = findgen(100)
IDL> y1 = x ; Y range to 99
IDL> y2 = sqrt(x * 1600.) ; Y range to ~399
IDL> iplot, x, y1
IDL> iplot, x, y2, /OVERPLOT

the first call to IPLOT will show a Y-axis range of 0 - 99. The second call to IPLOT will rerange the same Y-axis and redraw 'y1' according to the new range 0 - 399. That is also the behavior of the iTools menu button 'Insert -> Visualization...'

The missing piece here is that the iTools display needs to have a second "Data Space" object, if it is going to display a second set of axis ranges. The "Data Space" is the object in iTools that maintains a mapping of data ranges to the display window pixels. Before we set out to do this programmatically, though, it is important to learn how it is done in the iTools GUI. Below is a method that assumes that the right Y-axis will be used to show the new dataspace range, while the left shows the original dataspace range.

1. Insert -> Data Space. This creates a new data space with new X- and Y-axes, all with default ranges 0.0 - 1.0.
2. Using the 'Window -> Visualization Browser...' dialog, select the new Data Space object and change its 'X maximum' property value to 99, its 'Y maximum' value to 399. Keep this Visualization Browser open for other "select object" steps below.
3. Run "iplot, x, y2, /OVERPLOT" from the IDL> command line or run the 'Insert -> Visualization...' utility to display the second data set in the iTools window.
4. Select the lower X-axis object (Axis 0) under the new Data Space object and hide it by changing its 'Show' property to False. Do the same to the upper X-axis object (Axis 2). We don't need two identically-ranged X-axes on display.
5. We now want to hide the new data space's left Y-axis (Axis 1) by selecting it and changing its 'Show' property to False. At the same time, we want to hide the original data space's right Y-axis (Axis 3 under the first Data Space object) using the same approach. This will leave the right Y-axis as the one axis from the new data space able to display its unique range.
6. To display this range, we need only set the 'Text show' property of this second Data Space's Axis 3 to True.

I would add to these steps steps to change the colors of the Plot object and the Y-axis associated with the overplotted 'y2' to some color that distinguishes them from the first data space's plot.

So, the above are the steps that we want to mimic programmatically. Using iTools querying methods like those shown in great detail in Help Article #3812 ("In iTools Synchronizing Annotation Layer Movement With Visualization Layer Movement") I was able to come up with the following list of code steps to perform the same actions:

x = findgen(100) ; Same data as above
y1 = x
y2 = sqrt(x * 1600.)
iplot, x, y1, XRANGE=[0., 100.], YRANGE=[0., 100.]
idTool = itgetcurrent(TOOL=oTool)
temp = oTool->FindIdentifiers('*DATA SPACE', /OPERATIONS)
idOpInsertDataSpace = temp[0]
; 'DoAction' does the same thing as pressing the menu button
success = oTool->DoAction(idOpInsertDataSpace)
; Not only overplots, but reranges the new dataspace as well
iplot, x, y2, /OVERPLOT, XRANGE=[0., 100.], YRANGE=[0., 400.]
; Turn off the display of unwanted axes
axisID = oTool->FindIdentifiers($
    '*DATA SPACE_1/AXES/AXIS0', /VISUALIZATIONS)
success = oTool->DoSetProperty(axisID[0], 'HIDE', 1)
axisID = oTool->FindIdentifiers($
    '*DATA SPACE_1/AXES/AXIS1', /VISUALIZATIONS)
success = oTool->DoSetProperty(axisID[0], 'HIDE', 1)
axisID = oTool->FindIdentifiers($
    '*DATA SPACE_1/AXES/AXIS2', /VISUALIZATIONS)
success = oTool->DoSetProperty(axisID[0], 'HIDE', 1)
axisID = oTool->FindIdentifiers($
    '*DATA SPACE/AXES/AXIS3', /VISUALIZATIONS)
success = oTool->DoSetProperty(axisID[0], 'HIDE', 1)
; Turn on the axis label text of the new data space
axisID = oTool->FindIdentifiers($
    '*DATA SPACE_1/AXES/AXIS3', /VISUALIZATIONS)
success = oTool->DoSetProperty(axisID[0], 'NOTEXT', 0)
; Color the Y2-associated objects red
success = oTool->DoSetProperty(axisID[0], 'COLOR', [255,0,0])
plotID = oTool->FindIdentifiers($
    '*DATA SPACE_1/PLOT', /VISUALIZATIONS)
success = oTool->DoSetProperty(plotID[0], 'COLOR', [255,0,0])
oTool->CommitActions