6.6 Plot and Read Routines

These are the main user written routines. NOTHING is prescribed here, you can read your data any which way you want, and pass it to your plot routine any which way you want. PaPCo will simply call your plot routine when it processes your panel after the DRAW button has been pressed: it calls the interface routine draw_plot_type from your papcoadd_plot_type.pro file. In that file your data is also read, so you can pass parameters to your plot routine locally through command line parameters, or globally through common blocks, which is the preferred method, as other routines (e.g. slices) can then use that data without having to read it again.

One thing is needed though. In your plot routine you need to call a PaPCo routine called panelset . This routine sets the viewport for your plot, i.e. the position of the panel. You can of course substitute your own routine for this, if the default PaPCo behavior does not suit you. In the Los Alamos module I have used a different routine which allows space for an extra x-axis to be plotted for each panel, even if it is not the bottom panel - to plot the local time for the data.

However, for your module to work well with all the other modules so that the output ``looks good'', it makes sense to stick to the PaPCo plotting and reading philosophy as described in Chapter 5.

All the plot and read templates reside in
papco_XX/papco/papco_modules/plot_type/plot_read.

6.6.1 Platform independence

Your read routine is the part of your module that interacts with your computer's operating system. As modules are written in order for many people to use them, you will need to pay some attention to making your read routine work under different operating systems and/or architectures.

PaPCo core has been written to be platform independent, by resolving all platform dependent calls using a set of PaPCo operating system routines. These routines are all collected in the file papco_opsys.pro, and are documented there. If you use only these routines, then any updates to new operating systems will become transparent to your module. Should you need routines that are not available, let me know and I'll add them to papco_opsys.pro.

Things you need to pay attention to are mainly filenames and file I/O. Also, if your data format is NOT one of the intrinsically portable ones (like ASCII, CDF, IDL savesets) then you need to be worried about things such as byte-swapping between Dec and SUN. You can use the IDL system variable !version to find out what system/architecture you are on, and take action accordingly.

help,!version,/stru
** Structure !VERSION, 4 tags, length=32:
   ARCH            STRING    'sparc'
   OS              STRING    'sunos'
   OS_FAMILY       STRING    'unix'
   RELEASE         STRING    '4.0'

6.6.2 Read-routine

Read-routines used are very much up to the user to supply as outlined in Section 1.6.1 and 5.6. To guide the user, a template read-routine is supplied which implements the expected error checking that allows PaPCo to continue should there be a problem with reading the data. It also gives an example of how to write a generic read routine that can construct data arrays that span several files, and it uses the remote get data facility. The actual techniques used for reading the data are not prescribed. However, a very effective method is using the IDL SAVE and RESTORE commands.

To use the template (r_plot_type.pro), this is what you do:

1.

Rename all occurrences of plot_type in the file name and in the file to the actual name.

2.

Include a common block for your data (common plot_type_data).

3.

Adjust the error messages to your taste.

4.

Write some code that constructs the file name(s) needed from the start and end times in common mjdt, mjdt_start, mjdt_end.

5.

Write your specific file I/O.

6.

Test the read-routine by setting the time common block from the command line. Use the routines in papco_XX/papco_lib/convert.pro to make some suitable MJDT times and load these into mjdt_start and mjdt_end before calling your read-routine. Make sure to also test correct error-handling.

The error common block is used by PaPCo to check if a valid read was done. If get_err_no is not zero then an empty panel is plotted which only contains the error message contained in get_err_msg.

The documentation in the template will lead you through what you need to do (Section B.2.1). If your system has the GNU program ``wGeT'' then you can use PaPCo 's remote data-get facility. See Section C.2 and B.2.4 for more details.

6.6.3 Plot routines

Once you have a panel editor, a read-routine and the papcoadd routines, you're ready to write the plot routine or adapt an old one. It might be easier to use the plot routine templates provided instead of adding your own routine, since the templates support all of the PaPCo functionality, and are designed to ``stack'' nicely. But the choice is yours. The procedure outlined here applies to both templates (p_plot_type_line.pro and p_plot_type_spec.pro), for line plots and for color plots.

1.

Rename all occurrences of plot_type in the file name and in the file to the actual name.

2.

Include a common block for your data.

3.

If you intend to use time routines from PaPCo (for labeling x-axis), then change your time base to mjdt using PaPCo conversion routines
(can be found in papco_XX/papco_lib\convert.pro).

4.

Change axis labeling, titles etc. to suit yourself.

5.

Test the routine using either dummy or actual data by calling it from the command line. To get a full page plot set the following panel_vector:[0,1,1], and set the common time block to contain some time.

6.

Once the basic plotting works, you can use PaPCo for further testing. Set the correct plot- and read-call in the draw procedure in papcoadd. From PaPCo, make yourself a product with some samples of your plot as panels (trying out all options), select a time for which you have test or real data, and save this product (if PaPCo crashes while testing, you don't have to remake the product). Now try out your plot. If you need to make editing changes to your plot routine (assuming it hasn't crashed) use the STOP button in PaPCo. Edit you routine, compile, type .con and redraw your product from PaPCo.

The documentation in the templates will lead you through what you need to do (Section B.2.2 and B.2.3).