entitycreation

Context: concepts

Synopsis

Managing the creation of all levels of the object hierarchy.

Description

ChIPS uses a hierarchical approach to constructing plots. Any number of windows may exist, and each window may contain zero or more frames. The frames contain plots. The plots contain any axes, curves, images, contours, histograms and annotations, such as regions, lines, points, labels, and color bars. Graphically, the layout looks like:

WINDOWS--------------------------+
|   FRAMES-------------------+   |
|   |   PLOTS -----------+   |   |
|   |   |   AXES         |   |   |
|   |   |   COLORBARS    |   |   |
|   |   |   CONTOURS     |   |   |
|   |   |   CURVES       |   |   |
|   |   |   HISTOGRAMS   |   |   |
|   |   |   IMAGES       |   |   |
|   |   |   LABELS       |   |   |
|   |   |   LINES        |   |   |
|   |   |   POINTS       |   |   |
|   |   |   REGIONS      |   |   |
|   |   +----------------+   |   |
|   +------------------------+   |
+--------------------------------+

In order to display a curve, ChIPS must have a window which contains a frame. The frame must contain a plot, and the plot in turn contains a pair of axes and the curve. ChIPS will automatically create those objects that are needed, but you can also generate them manually if required (e.g. for fine control). The two sets of commands below create the same visualization - a curve of the data in the xdat and ydat arrays, but the second version overrides the default values for a number of options, such as the size of the window, the background color of the frame, and the position of the plot within the frame.

chips> xdat = np.arange(-np.pi, np.pi, 0.1)
chips> ydat = np.sin(xdat) * np.cos(xdat * 1.5)

chips> clear()
chips> id1 = ChipsId()
chips> add_curve(id1, xdat, ydat)

chips> clear()
chips> add_window()
chips> add_frame()
chips> add_plot()
chips> add_axis(XY_AXIS, 0, 0, 1)
chips> id2 = ChipsId()
chips> add_curve(id2, xdat, ydat)

The objects created by either version of commands can be seen using the info command:

chips> print(info())
Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Curve [crv1]

The difference can be seen in the items created by each add_curve call, as recorded in the fields of the ChipsId object:

chips> for aname in id1.attributes:
              aval = getattr(id1, aname)
              if aval != None:
                  print("{} = {}".format(aname, aval))

window = win1
frame = frm1
plot = plot1
xaxis = ax1
yaxis = ay1
curve = crv1
coord = ds0.0.0.3
coord_sys = 3
chips> for aname in id2.attributes:
    aval = getattr(id2, aname)
    if aval != None:
        print("{} = {}".format(aname, aval))

xaxis = ax1
yaxis = ay1
curve = crv1
coord_sys = 0

The second ChipsId structure does not have the window, frame, and plot fields set because they were already created. The xaxis, yaxis, and coord_sys fields are set to indicate what data system the curve has been added to.

Examples

Example 1

chips> add_window(10, 10, "cm")
chips> add_frame("bgcolor=navy")
chips> add_plot()
chips> add_axis(XY_AXIS, 0, 0, 1, "ticklabel.color=gold")
chips> add_histogram([1,4,5,0.4,3], "dropline=true")

These commands explicitly create each object which must exist to display a histogram. The output is a 10 cm by 10 cm window with a navy frame background that has a histogram displayed in a plot with gold axis ticklabels.

Example 2

chips> attrs = { 'window.units': 'cm', 'window.height': 10,
'window.width': 10 }
chips> attrs['frame.bgcolor'] = 'navy'
chips> attrs['axis.ticklabel.color'] = 'gold'
chips> attrs['dropline'] = True
chips> add_histogram([1,4,5,0.4,3], attrs)

If no windows exist, this command will create output identical to the previous example.

Bugs

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.