plotting-with-vplot

When to use

Use this skill any time a task involves:

• Producing a .vpl file — Madagascar's portable vector/raster plot format.
• Calling sfgrey, sfgraph, sfwiggle, sfcontour, sfdots, or sfbargraph from an SConstruct or at the command line.
• Debugging a blank, mis-scaled, or mis-labeled plot.
• Composing multiple plots into an overlay, side-by-side panel, or animation.
• Writing axis labels that require subscripts, superscripts, or Greek letters.
• Controlling color schemes, clip levels, or scalebars.

This skill does not cover converting .vpl to PDF/PNG (use sfpen options or vppen), or 3D surface plots (sfgrey3, sfsurf).

---

Mental model

What vplot is

Vplot is Madagascar's internal plot language — a compact binary stream describing lines, rasters, text, and color tables. Every visualization program (sfgrey, sfgraph, etc.) reads an RSF file and writes a .vpl stream. The .vpl file can be:

• Displayed on screen with sfpen (wraps the xtpen or pspen driver).
• Composed with other .vpl files using vppen.
• Converted to PostScript with pspen.

Programs vs. the pipeline

Every vplot program is a standard Madagascar filter:

< data.rsf sfgrey color=j clip=1 title="My data" > out.vpl

At the command line, output goes to stdout. In SConstruct, SCons manages the filenames.

Plot vs. Result in SConstruct

Plot and Result are the two SConstruct functions that produce .vpl files.

Rules of thumb:

• Use Plot for any image you intend to overlay or combine.
• Use Result for any image that is a deliverable on its own.
• A Result with a composition string is both — it reads Plot-produced .vpl files and writes a final composed .vpl to Fig/.

How parameters reach the vplot program

In SConstruct, the second argument to Plot or Result is either:

1. A flow string — the vplot program call with its parameters:

   Result('img', 'grey title="My plot" color=j clip=2')
   

2. A source list plus a composition keyword:

   Result('combined', 'img1 img2', 'Overlay')
   

Parameters follow the same key=value syntax as any sf program. String values with spaces must be quoted.

Universal parameter inheritance

All vplot programs call sfstdplot internally (see sfdoc stdplot). This means axis labels, title, min/max, grid, screen size, and layout parameters are available to every vplot program, not just the one documented in its own sfdoc entry.

---

Core program catalog

---

Universal plot parameters

These parameters come from sfstdplot (run sfdoc stdplot) and are accepted by every vplot program.

---

Program-specific parameters

sfgrey — 2D raster/density plot

sfdoc sfgrey | source: plot/main/grey.c

Defaults: transp=y yreverse=y xreverse=n. With these defaults, axis 1 runs vertically (time, depth), axis 2 runs horizontally (trace, offset). This is the standard seismic display convention.

clip vs. pclip: pclip=99 (default) estimates clip from the 99th percentile. Set clip= explicitly for reproducible cross-panel display. gainpanel=a normalizes across all 3D frames; gainpanel=e per frame. For strictly positive data (envelopes, migration images) use allpos=y color=j.

---

sfgraph — 1D line plot

sfdoc sfgraph | source: plot/main/graph.c

Default: transp=n. Plots each column (n2 traces) as a curve, with axis 1 values on the vertical axis and axis 2 index on the horizontal.

Overlay alignment: Both plots must share axis ranges. With sfgrey transp=y (default), axis 1 is vertical and min1/max1 control vertical range. With sfgraph transp=y yreverse=y, the curve values map to the vertical axis via min2/max2. Always use wantaxis=n wanttitle=n pad=n on the overlay graph.

---

sfwiggle — seismic trace display

sfdoc sfwiggle | source: plot/main/wiggle.c

Draws each trace as an oscillating waveform. Positive excursions can be filled (polygon mode).

Note on clip: sfwiggle requires an explicit positive clip to work properly. Either set clip=<value> directly, or rely on pclip=98 (the default) which estimates the clip from the data percentile. Setting clip=0 with no pclip produces no display.

---

sfcontour — contour plot

sfdoc sfcontour | source: plot/main/contour.c

Draws iso-value lines on a 2D scalar field. Defaults: transp=y allpos=y.

Gotcha: Unlike other vplot programs, sfcontour's scalebar also requires barlabel=... to activate. scalebar=y without a non-empty barlabel= silently produces no colorbar. (Source: plot/main/contour.c lines 97-99, which checks both scalebar and barlabel before enabling the bar.)

Contour overlay on grey: A common pattern is to overlay contours on a raster image:

Plot('raster', 'grey color=j')
Plot('lines',  'contour nc=20 wantaxis=n wanttitle=n')
Result('both', 'raster lines', 'Overlay')

---

sfdots — lollipop/impulse display

sfdoc sfdots | source: plot/main/dots.c

Plots each sample as a vertical stick with a ball. Good for sparse signals and filter coefficients. Key parameters: dots= (1=balloon, 0=stick only), strings=y (draw sticks), connect= (1=diagonal, 2=bar), gaineach=y (per-trace normalization), clip= (-1=no clip), overlap=0.9 (trace width fraction), transp=, yreverse=, seemean=. Note: the axis is drawn only when label1= is present.

---

sfbargraph — bar chart

sfdoc sfbargraph | source: plot/main/bargraph.c

Plots each column as a group of bars. Key parameters: width=0.8 (bar width fraction), stack=y (stack vs. side-by-side), transp=n (horizontal bars if y). Inherits all sfstdplot parameters for labels, title, and axes.

---

Color schemes (color=)

The color= parameter in sfgrey (default i) and sfgraph (default j) selects a color table. These codes are defined in plot/lib/coltab.c. An uppercase letter reverses the table; appending C clips out-of-range values in a highlight color.

Custom color tables: You can also pass a filename (path to a CSV file with R,G,B triples, one per line, values in [0,1]) as the color= value. Madagascar looks in $RSFROOT/include/<name>.csv if the name is not a single letter.

Clipping highlight suffix C: Appending C to any color code (e.g. color=jC) marks values that fall outside the clip range with a red highlight color (configurable via cliprgb=). Useful for diagnosing saturation.

---

Label escape codes

Vplot interprets \ as an escape character in text strings (titles, axis labels). This lets you add subscripts, superscripts, font switches, and size changes directly in label strings.

Complete escape reference

All escapes that do not take an argument:

Escapes that take an integer argument followed by a required space:

Key font numbers: 0=Pen, 1=Roman Simplex, 3=Roman Complex, 5=Italic Complex, 9=Greek Simplex (α β γ), 10=Greek Complex, 15=Mathematics. -1 restores the default font.

The Python backslash problem

Python interprets \s, \F, \_, \^ as string escapes. This means you need to double the backslash or use raw strings:

# Wrong — Python eats the backslash before vplot sees it:
Result('bad', 'grey title="v\_NMO"')

# Correct option 1 — double the backslash:
Result('ok1', 'grey title="v\\_NMO"')

# Correct option 2 — raw string (preferred for readability):
Result('ok2', r'grey title="v\_NMO"')

# In a triple-quoted string, doubling still works:
Result('ok3',
       '''
       grey title="v\\_\s75 NMO\s100 "
       ''')

The NMO tutorial in the book (book/rsf/tutorials/nmo/SConstruct) uses the doubling convention:

title="v\\_\\s75 NMO\\s100 \\^ Profile"

Common recipes: r"v\_NMO" → v subscript NMO; r"x\^2\_ " → x superscript 2 (back to baseline); r"\F9 b\F-1 " → Greek beta (font 9, restore with -1); r"v\\_\\s75 NMO\\s100 " → NMO at 75% size (doubling convention from the book).

---

Composition

Madagascar's rsf.proj defines eight composition modes for combining .vpl files. These are invoked as the flow string in Result or Plot when the source is a list of names.

All eight modes at a glance

(Source: framework/rsf/proj.py lines 255-264.)

Overlay

Stacks multiple plots in registration (Z-order, last source on top).

Plot('background', 'grey ...')
Plot('foreground', 'graph wantaxis=n wanttitle=n pad=n ...')
Result('combined', 'background foreground', 'Overlay')

Internally: vppen erase=o vpstyle=n source1.vpl source2.vpl > out.vpl

The first source defines the coordinate frame. All subsequent sources must use compatible axis ranges to align correctly.

SideBySideAniso

Places N plots side by side, each keeping its own aspect ratio. Good for heterogeneous panels (e.g., a narrow velocity panel next to a wide gather).

Result('comparison', 'img1 img2 img3', 'SideBySideAniso')
# Extra vppen flags via keyword argument:
Result('out', 'img1 img2', 'SideBySideAniso', vppen='txscale=1.5')

OverUnderAniso

Places N plots stacked vertically, each keeping its own aspect ratio. Use when the panels have different data types or shapes that should not be forced to a common scale.

Result('stacked', 'top bottom', 'OverUnderAniso')

SideBySideIso

Places N plots side by side with matched aspect ratios — good when panels show the same data type.

Result('panels', 'imgA imgB', 'SideBySideIso')

OverUnderIso

Places N plots stacked vertically with matched aspect ratios. Use when you want a column of comparable panels (e.g., the same section at different stages of processing).

Result('column', 'before after', 'OverUnderIso')

TwoRows

Arranges N panels into two rows with isotropic scaling (gridnum=ceil(N/2), 2). Convenient for even numbers of panels that should read left-to-right across two rows.

Result('grid', 'p1 p2 p3 p4', 'TwoRows')

TwoColumns

Arranges N panels into two columns with isotropic scaling (gridnum=2, ceil(N/2)). Stacks pairs of panels in two vertical columns.

Result('twocol', 'p1 p2 p3 p4', 'TwoColumns')

Movie

Assembles multiple frames into a flipbook animation. sfpen cycles through them on display.

for iframe in range(nframes):
    Plot('frame%d' % iframe, 'slice%d' % iframe, 'grey ...')
Result('movie', ['frame%d' % i for i in range(nframes)], 'Movie')

Internally: vppen vpstyle=n frame0.vpl frame1.vpl ...

---

Frame and layout

screenratio= (height/width) controls figure aspect: 0.5=wide landscape, 0.75=typical landscape, 1.0=square, 1.5=portrait.

For manual panel placement, use xll=/yll=/xur=/yur= in inches from the paper's bottom-left corner:

Plot('left',  'grey ... xll=1.0 yll=1.5 xur=4.0 yur=6.5')
Plot('right', 'grey ... xll=4.5 yll=1.5 xur=7.5 yur=6.5')
Result('both', 'left right', 'Overlay')

crowd= (default 0.75) controls what fraction of the frame the plot area occupies. crowd1=/crowd2= set axes independently.

---

Debugging plots

Empty or all-black plot

Symptom: sfgrey produces a .vpl that shows as solid black or solid white.

Causes and fixes:

1. Data is all zeros — check with sfattr < data.rsf. If max = 0, the flow that produced the data failed silently.
2. clip= was set to a value much larger than the data range — the entire range falls in one color. Check sfattr for actual min/max and set clip= accordingly, or remove it and let pclip estimate.
3. pclip= is very low (e.g. pclip=1) — almost all data is clipped. Increase to 99.

Wrong aspect ratio

Symptom: Plot looks squashed or stretched.

Fix: Set screenratio= explicitly. Remember that sfgrey with transp=y (default) swaps n1 and n2 roles — if your data is 1000×50 samples, the display is 50 wide and 1000 tall without aspect correction.

Missing or mangled labels

Symptom: Label appears with a literal backslash and letter instead of a formatted escape.

Fix: Python ate the backslash. Use raw strings (r"...") or double the backslash ("\\_").

Symptom: Label is absent entirely.

Fix: wantaxis=n is set, or the header fields label1/label2 were not set in the RSF file and no explicit label1=/label2= was passed.

Misaligned overlay

Symptom: Overlay curve appears at the wrong position on the background image.

Cause: Axis range mismatch between the two plots.

Diagnosis:

• sfgrey with transp=y (default): axis 1 is on the vertical axis, axis 2 on the horizontal. min1/max1 control the vertical range; min2/max2 control the horizontal.
• sfgraph with transp=y: axis 1 values are the independent axis (horizontal after transposing... actually vertical after transp=y yreverse=y), and the data values are on axis 2 (min2/max2).

Fix: Both plots must share identical min1/max1 and min2/max2. Also use pad=n on the overlay sfgraph to suppress the automatic padding that would shift the curve.

Scalebar out of range

Set minval= and maxval= explicitly (from sfattr) to control scalebar labels independently of clip range.

Wiggle traces invisible

clip=0 with no pclip estimates zero clip — nothing shows. Use pclip=98 (default) or an explicit clip= from sfattr.

Overlay Z-order

In vppen erase=o, sources are drawn left to right — the last source is on top. Put foreground elements last in the source list:

Result('out', 'raster_below curve_on_top', 'Overlay')

---

Examples

Example 1 — basic grey plot

File: skills/plotting-with-vplot/references/example-grey.SConstruct

from rsf.proj import *

Flow('synth', None,
     '''
     spike n1=200 n2=100 k1=50,100,150 nsp=3 mag=1,0.8,0.6 |
     ricker1 frequency=40 |
     noise seed=2025 var=0.005
     ''')

Result('synth',
       '''
       grey title="Synthetic gather"
            label1="Time" unit1="s" label2="Trace" unit2=""
            color=j scalebar=y
       ''')

End()

Stage by stage:

1. sfspike creates a 200-sample × 100-trace array with three spikes at samples 50, 100, 150. nsp=3 is required — sfspike does not infer it from the length of the k1 list.

2. sfricker1 frequency=40 convolves each trace with a 40 Hz Ricker wavelet, turning the spikes into wavelets.

3. sfnoise adds Gaussian noise (variance 0.005, reproducible with seed 2025) to simulate real data.

4. sfgrey displays the result. Key choices:

   • color=j — jet colormap shows the gather with blue–green–yellow–red mapping. Good for seeing both amplitude and polarity.
   • scalebar=y — draws a colorbar on the right showing the amplitude-to-color mapping.
   • label1/unit1/label2/unit2 — explicit labels override whatever is in the RSF header.
   • transp=y yreverse=y (defaults) — time (axis 1) runs vertically top-to-bottom, traces (axis 2) run left-to-right.

Output: Fig/synth.vpl — a seismic-style display of a synthetic gather.

---

Example 2 — overlay with a velocity curve

File: skills/plotting-with-vplot/references/example-overlay.SConstruct

from rsf.proj import *

Flow('cmp', None,
     '''
     spike n1=400 n2=60 k1=80,180,300 nsp=3 mag=1,0.7,0.5 |
     ricker1 frequency=30
     ''')
Plot('cmp', 'grey title="CMP" label1=Time unit1=s label2=Offset unit2=m')

Flow('vcurve', None,
     '''
     math n1=60 output="1500+x1*10" d1=1 o1=0
     ''')
Plot('vcurve',
     '''
     graph transp=y yreverse=y min2=0 max2=2000
           wantaxis=n wanttitle=n plotcol=2 plotfat=3 pad=n
     ''')

Result('cmp-with-vcurve', 'cmp vcurve', 'Overlay')

Stage by stage:

1. cmp is a 400-sample × 60-trace synthetic gather. Plot (not Result) is used because it is an intermediate that feeds the overlay.

2. vcurve is a 60-sample 1D array where sample i has value 1500 + i*10, representing a velocity that increases linearly from 1500 to 2090 m/s across 60 offset positions. sfmath is used because there is no input file — n1=60 d1=1 o1=0 defines the grid, and output= gives the analytic formula.

3. The sfgraph call for vcurve uses:

   • transp=y yreverse=y — makes the curve plot in the same orientation as the grey background (vertical time axis).
   • min2=0 max2=2000 — the velocity curve values (1500–2090) are mapped onto the horizontal axis range 0–2000. This must match what sfgrey uses for its horizontal axis. Here sfgrey uses label2=Offset unit2=m with the default axis range from the data (0 to 59 for the 60 traces). There is a conceptual mismatch here — in a real workflow you would align min2/max2 precisely with the offset range. For demonstration purposes, the curve is plotted within the displayed frame.
   • wantaxis=n wanttitle=n — suppress the graph's own axes; the background cmp image provides the axis frame.
   • plotcol=2 — red curve.
   • plotfat=3 — thick curve for visibility.
   • pad=n — no extra padding; ensures the curve aligns with the raster plot coordinate frame.

4. Result('cmp-with-vcurve', 'cmp vcurve', 'Overlay') — vppen draws cmp.vpl first (background), then vcurve.vpl on top.

Output: Fig/cmp-with-vcurve.vpl — the gather with a red velocity curve overlaid.

---

Example 3 — wiggle trace display

File: skills/plotting-with-vplot/references/example-wiggle.SConstruct

from rsf.proj import *

Flow('traces', None,
     '''
     spike n1=500 n2=15 k1=100,300 nsp=2 mag=1,0.6 |
     ricker1 frequency=25
     ''')

Result('traces',
       '''
       wiggle clip=0.8 title="Wiggle display"
              label1=Time unit1=s label2=Trace unit2=""
              poly=y zplot=1.5
       ''')

Stage by stage:

1. sfspike generates 500 samples × 15 traces with two wavelets per trace (at samples 100 and 300). nsp=2 is required explicitly.

2. sfricker1 frequency=25 creates 25 Hz Ricker wavelets — lower frequency than example 1, producing broader, more clearly visible wiggles.

3. sfwiggle displays with:

   • clip=0.8 — explicit clip at 80% of the spike amplitude. Wiggle traces are clipped to this value to control how wide the excursions can get. Without an explicit clip, the pclip=98 default would estimate one.
   • poly=y — fills positive excursions with black polygons (standard seismic wiggle style).
   • zplot=1.5 — traces are spaced at 1.5× the default separation, so they overlap slightly. This emphasizes the waveform shape. Values > 1 cause overlap; values < 1 leave gaps between traces.
   • Default transp=n for sfwiggle puts axis 1 (time) on the vertical axis and traces on the horizontal.

Output: Fig/traces.vpl — a 15-trace wiggle display with filled positive excursions.