Clipper

Clipper (Compact and LIteral Pulse ProgrammE Representation) is a tool to create diagrams of pulse sequences directly from Bruker AVANCE series pulse programs.

The first aim of Clipper is to make diagrams that provide a very precise representation of the pulse program, maintaining a very close one-to-one correspondence with the actual text of the pulse program. At the same time it provides a view of the pulse program that, compared to the raw pulse program text, is much easier to compare with a typical publication quality diagram. It is the correspondence of each feature in the diagram with the text of the pulse program that makes this tool different to those provided in xwinnmr.

Clipper is implemented in awk and creates a postcript file as output. Thus installation is trivial, clipper is very portable, and hardcopy output is (?) guaranteed to be the same as you see on screen (in a postscript viewer). In my view a hardcopy of pulse program diagrams is much easier to 'think through' than an on-screen representation, except for trivial things. It was developed on SGI machines running IRIX, but has also been used less extensively under LINUX. A decent postscript viewer is very handy, especally one that makes zooming in easy (we use gv 3.5.8) as the font size is by necessity small to get the diagram to fit onto A4 paper.

Clipper makes it much easier to

get an overview of what a pulse program does
work out which line needs altering to alter a particular part of the sequence
see where gradients, power level switches, etc come in the sequence
see what phase cycling is employed
debug pulse programs.
compare two implementations of a pulse sequence by different authors

Clipper works on a PULSE PROGRAM, and NOT on a dataset, i.e. it does not read any parameter files such as acqu. This is deliberate because it is meant to, for instance, show you where a power level change is made (and is enough time left for it ?), rather than trying to show that subsequent pulses occur at that power level. The aim is to try to keep the task of getting the syntax and logic of the pulse program correct distinct from the task of setting the parameters correctly for it on a particular spectrometer. However, as noted below, there are a number of 'qualifiers' that can be used to express the intent of the pulse programmer, particularly which pulses are 180 degree pulses.

Disclaimer

No responsibility can be accepted for any spectrometer damage or other loss arising from any innacuracy in the clipper representation of a pulse program. Observe the usual extreme caution.

.. but

However it seems to be pretty robust, but be especially aware of the 'precompile' limitation (see 'Known limitations' below).

Feedback

I would appreciate any comments (positive and negative), suggestions, bug reports etc, to c.j.craven@shef.ac.uk. If you try it out and it fails abysmally on a particular program, I would be grateful for a copy of the pulse program, output etc before you give up.

Download clipper tar file (which also includes a copy of this page)

Quickstart

In its most basic form, clipper requires a command as simple as

clipper $PP/zgpr > temp.ps

(The $PP specifies the pulse program directory, so you can run clipper from a suitable directory of YOUR OWN!)

This creates a postscript file which can be viewed with any postscript viewer.

Clipper makes NO initial assumptions about the usage of parameters. However, the command can include qualifiers that will make the output more clear.

In particular you can specify

Which pulses are 180 degree pulses (e.g. p180=p2,p22,p14). By default all pulses are marked as 90 degree pulses (N.B. If the pulse program uses p1*2 as the 180 pulse you can specify p180=p1x2. Note the substitution of 'x' for '*' to avoid problems with the shell trying to match '*' with filenames)
Which pulses are off resonance (e.g. offres=sp5). These pulses are marked by barred lines.
Which phases are trivial (e.g. constant x ) and which should not be explicitly marked (e.g. nophase=ph1)

Thus you could have

clipper p180=p2,p14,p22 offres=sp5 nophase=ph1 $PP/hncags3d > temp.ps

(this example is expected to operate on the current standard Bruker release hncags3d pulse program).

I suggest you have a clipper directory where you keep a README file of previous commands. That way it is easy to reproduce diagrams. Faced with a unfamiliar pulse program, the usual method would be to run clipper first with no qualifiers, and then use that diagram to work out which pulses are intended to be 180s, off-resonance etc, and thus refine the diagram. By placing these things in a 'autoclipper' statement (see below) this effort is then useable by other users of the pulse program.

Other options

Other more esoteric qualifiers are

ignoreshefpar=1 ; this allows suppression of a local header system which otherwise makes the program rather long

number_lines=1; this will number each line with its actual line number within the pulse program file.

nodelay=4u,20u,d11; this replaces the specified delays by capital delta symbols (i.e. triangles). In some pulse programs this helps remove clutter so you can see the important delays.

gradfull=1; this causes the gradients to be labelled according to their 'gp' labels.

scale=0.8; currently very long pulse programs will fall off the bottom of the page. 'scale' is a way to reduce the size of the diagram. It may be better to edit out part of the pulse program instead in a temporary file.

Depiction of pulse program

An example is usually the best way to understand something ... so that is all you get here.

example.pp is a dummy pulse program which does not implement a real pulse sequence but uses as many different bits of the pulse programming language as possible, with sample commands annotated.

This was turned into a clipper diagram via the command:

clipper p180=p2 nophase=ph10 test.pp> example.ps

The file example.ps can be clicked on to view it, or print it out using the right mouse button to save it to a file first. (N.B. The program assumes A4 sized paper, and not all viewers will automatically assume this, so the viewer may clip the diagram unless you reset the page size, but it should print OK)

The annotations should allow you to understand the way various pulse program events are depicted.

Autoclipper

You can put clipper directives directly in the pulse program so that making a diagram of a particular sequence is made even easier. Simply put a line (anywhere) that starts ';clipper' followed by the clipper options you want,

e.g. in the hnca example above you would insert

;clipper p180=p2,p14,p22 offres=sp5 nophase=ph1

Then to make the diagram type

autoclipper filename > output.ps

Of course such a line gets copied from version to version of a pulse program and may become an invalid and misleading 'hangover' after a while, in the same way that comments can.

Known limitations

Because clipper tries to keep a one to one correspondence with the main pulse program file, it does not precompile the pulse program. Thus code which is contained in #include files is not depicted. However, clipper does scan include files for declarations of user defined delays and pulses, so that these can be properly displayed. If a pulse program contains crucial executable statments in #include or #define code, then clipper should be run on the precompiled file (e.g. the file pulseprogram that appears in the data directory when you type zg). I would like to think of an ergonomic way to display #defined statements in the diagram. In most fairly standard pulse programs the only executables in #define statements are the lock hold statements.

Currently clipper does not flag up any unrecognised pulse program commands.

If you mistype part of the clipper command qualifiers you will be warned that the qualifier is not recognised. However, there are some qualifiers that ARE legal and that will ALSO give an error. You can ignore these if the required effect is still obtained. (It is just that the list of legal qualifiers is not always as up to date as options that it really understands).

Clipper does not flag up illegal syntax, such as a power level change behind no delay, and may generate a misleading diagram. It is best to check a new pulse program against xwinnmr first, e.g. ased or pulsdisp to check that the xwinnmr compiler is happy with it.

As noted above, very long pulse programs may fall off the bottom of the page. Currently there is no fix for this, except editing out part of the pulse program into a temporary file.

The components (in case you are curious)

There are four stages to the creation of the final output file.

First the actual clipper command is a front end command that does some reformatting and checking of the typed command before passing the action to clipper_pp_parse. This converts the pulse program into a more computer-readable list of events, with due account of 'parallel' commands. The output from this stage can be saved by specifying debug=1 as an extra argument to the clipper command, in which case the output will be saved as a file called clipper_parsed_pp. clipper_parsed2diag then turns this output into a postscript diagram. Finally a (rather long) postscript header is added by clipper_jplot2ps which makes the output into a fully functional postscript file. This header contains definitions of a lot of graphics functions that I wrote originally (and extensively use) as graph plotting commands. Only a subset of them are actually used by the pulse program diagram but it is easier for me to leave the whole lot in. The postscript produced appears to be robust to a variety of postscript interpreters.