Figure options

Every keyword the figure builders take: the default it renders with, the render flag that sets it on the command line, and what it does. The sections follow the app's plot rail.

import scanpath_studio as sps

words, fixations = sps.load_sample_data()
fig = sps.plot_scanpath(
    words,
    fixations,
    "l7_1090",
    "l7_1090_2_1_1_Ele_r0",
    show_heatmap=True,  # any option below, as a keyword
    heatmap_norm="log",
    fixation_color="#D55E00",
)

• Builders. plot_scanpath, animate_scanpath and compare_scanpaths take every option, unless its description ends by naming the builders that do (Plot and compare only.). A keyword a builder does not take raises a TypeError that names the closest valid ones.
• Fixed values. An option with a fixed set of values lists them. Case, spaces, - and _ are ignored, so the CLI's log and mark-border work; any other value raises a ValueError.
• Descriptions are the render flag's own help. A --no-… flag describes an option that is on by default.
• In code, figure_options() returns the same defaults, and figure_options(choices=True) adds the values.

Fixations

Option and render flag	Default	Description
show_fixations --no-fixations	True	Hide fixation markers. Plot and compare only.
fixation_color --fixation-color	'#0072B2'	Flat fixation marker color used when --color-by is (uniform).
color_by --color-by	'(uniform)'	Fixation column to color by, e.g. duration_ms, or 'line' to color each fixation by its text line (same as --color-by-line). Default: '(uniform)', one flat color, since marker size already shows duration.
color_by_line --color-by-line	False	Color each fixation by the text line it lands on (lines inferred from the word boxes); overrides --color-by. Same as --color-by line.
fixation_colorscale --fixation-colorscale	'Blues'	Color scale for --color-by, e.g. Viridis.
fixation_color_range --fixation-color-range	None	Pin the --color-by color scale to LO..HI instead of the trial's own range, so several figures share one scale.
fixation_opacity --fixation-opacity	0.7	Fixation marker opacity, 0.1–1.0.
fixation_symbol --fixation-symbol	'circle'	Fixation marker shape. Unlike color, shape survives a grayscale print. One of 'circle', 'square', 'diamond', 'triangle-up', 'cross', 'x', 'star', 'hexagon', 'heart'.
hollow_fixations --hollow-fixations	False	Draw the fixations as outlines instead of filled markers.
fixation_outline_color --fixation-outline-color	'#111111'	Color of that outline.
fixation_outline_width --fixation-outline-width	0.5	Outline round each filled fixation marker, 0–5 px; 0 draws none.
marker_size_scale --marker-size-scale	'sqrt'	How duration sets marker size. sqrt / linear / log map --marker-duration-range onto --marker-size-range the same way for every figure, so one duration is one size across trials, comparisons and replays; sqrt makes marker area grow with duration. relative stretches each figure from its own shortest to longest fixation. One of 'sqrt', 'linear', 'log', 'relative'.
marker_size_range --marker-size-range	(8, 24)	Min/max fixation marker size in px, e.g. 4 12. Smaller ranges suit small thumbnails.
marker_duration_range --marker-duration-range	(50, 600)	Durations in ms given the smallest and largest marker on a fixed scale. Shorter and longer fixations clamp to them.
show_order --no-fixation-index --fixation-index	False	Number the fixations in reading order.
order_font_size --order-font-size	10	Fixation index label size.
order_font_color --order-font-color	'#111111'	Fixation index label color.
fixation_flags --fixation-flag	None	The app's Filters & highlights for fixations, repeatable. SPEC is CATEGORY=MODE[,threshold_ms=N][,symbol=S][,color=#RRGGBB] with CATEGORY one of short, long, oob (outside every word box), blink and MODE one of off, highlight, discard — e.g. --fixation-flag short=discard,threshold_ms=80. discard drops those fixations from the drawing only; measures and exports are untouched. threshold_ms applies to short/long only.
fixation_snap_to_line --snap-fixations	False	Move each fixation up or down onto its text line (its word's, else the nearest); it keeps its x. --snap-position says where on the line. Plot and compare only.
fixation_snap_position --snap-position	-0.5	Where on its line a snapped fixation sits, in line heights from the line's middle: 0 centers it, -0.5 is the top edge, 0.5 the bottom edge. Used with --snap-fixations. Plot and compare only.

Saccades

Option and render flag	Default	Description
show_saccades --no-saccades	True	Hide saccade lines.
saccade_color --saccade-color	'#CC79A7'	Saccade line/arrow color, hex or CSS name.
saccade_style --saccade-style	'solid'	Saccade line dash style. One of 'solid', 'dash', 'dot', 'dashdot'.
saccade_width --saccade-width	2.0	Saccade line width in px, 0.5–10.
saccade_opacity --saccade-opacity	1.0	Opacity of the saccade lines and direction arrows, 0.1–1.0. A comparison's two scanpaths share it.
show_saccade_arrows --saccade-arrows	False	Draw saccade direction arrowheads.
saccade_arrow_size --saccade-arrow-size	12.0	Size of the --saccade-arrows arrowheads, 4–40 px.
saccade_render_mode --saccade-arcs	'Straight'	Draw saccades as upward arcs (the linear-reading diagram) instead of straight connectors. One of 'Straight', 'Arc'. Plot and compare only.
saccade_color_mode --saccade-color-by-type --saccade-color-by-direction	'Uniform'	Color each saccade by its reading type (forward / skip / refixation / return sweep / regression) instead of one uniform color. One of 'Uniform', 'Forward / regression', 'By type'. Plot and compare only.
saccade_class_colors --saccade-type-color	None	Override a reading-type color, e.g. --saccade-type-color regression=#000000 (repeatable; classes: forward, skip, refixation, return_sweep, regression). Implies --saccade-color-by-type, unless --saccade-color-by-direction is given — then it recolors that two-way split (its forward and regression colors). Plot and compare only.
saccade_classes --saccade-classes	list, see figure_options()	Draw only these reading classes, comma-separated, e.g. --saccade-classes regression,return_sweep (classes: forward, skip, refixation, return_sweep, regression, other). Hidden classes lose their line and their direction arrow. Default: all. Plot and compare only.

Text and stimulus

Option and render flag	Default	Description
show_word_labels --no-text	True	Hide the reading text.
text_color --text-color	'#000000'	Reading-text color.
line_spacing --line-spacing	3.0	How far apart the lines are, in font sizes: the reading text is the distance between lines ÷ N.
scale_text_to_boxes --no-scale-text-to-boxes	True	Draw the reading text at --font-size instead of sizing it from the word boxes.
highlight_column --highlight-column	'is_in_aspan'	Boolean words column marking the text to highlight — the critical span. Pass --highlight-column '' to highlight nothing. How it is drawn is --critical-span-style.
highlight_text_color --highlight-text-color	'#D55E00'	Color of the --highlight-column words under --critical-span-style mark-text.
critical_span_style --critical-span-style	'Mark text'	How the --highlight-column words are marked: mark-text recolors them, mark-border outlines their boxes, none draws neither. One of 'Mark text', 'Mark border', 'None'. Plot and compare only.
span_border_color --span-border-color	'#000000'	Box color under --critical-span-style mark-border. Plot and compare only.
show_stimulus_image --show-stimulus-image	False	Draw each trial's own stimulus page under the scanpath: the image_path its rows carry (from --image-root, or a dataset that ships its pages, like --sample), placed at its image_x / image_y. --stimulus-image PATH wins.
background_image --stimulus-image	None	Draw an image (PNG/JPG) as the stimulus background under the scanpath. By default it's stretched to the image's own pixel size (PNG) or the canvas; set --stimulus-image-size / -origin to place a crop precisely in fixation coordinates.
background_image_size --stimulus-image-size	None	Stimulus-image size in px, e.g. 1310x991. Use with --stimulus-image.
background_image_origin --stimulus-image-origin	None	Top-left of the stimulus image in monitor px, e.g. 305,44. Use with --stimulus-image to align a centered crop to the fixation coordinates.
background_image_opacity --stimulus-image-opacity	1.0	Stimulus-image opacity 0.1–1.0. Lower it to dim a busy image so the fixations / saccades / word boxes read over it.

Word boxes

Option and render flag	Default	Description
show_words --no-word-boxes --word-boxes	False	Draw the word boxes.
word_box_color --word-box-color	'#6c757d'	Word-box outline color. A comparison outlines each scanpath's boxes in its own color instead.
word_box_line_opacity --word-box-line-opacity	1.0	Word-box outline opacity, 0–1; 0 draws the fill only. Below 1 the outline color must be #rrggbb, #rgb or rgb(r, g, b).
word_box_fill_color --word-box-fill-color	'#646464'	Word-box fill color, drawn at --word-box-fill-opacity: #rrggbb, #rgb or rgb(r, g, b).
word_box_fill_opacity --word-box-fill-opacity	0.05	Word-box fill opacity, 0–1; 0 draws outlines only.

Heatmap

Option and render flag	Default	Description
show_heatmap --no-heatmap --heatmap	False	Draw the heatmap. Plot and compare only.
heatmap_style --heatmap-style	'Word boxes'	Heatmap geometry. One of 'Word boxes', 'Interpolated'. Plot and compare only.
heatmap_metric --heatmap-metric	'duration_ms'	Heatmap weighting: the fixation duration column — under your file's name or as duration_ms (the default) — or counts. Plot and compare only.
heatmap_colorscale --heatmap-colorscale	'Blues'	Heatmap color scale, e.g. Greens. Plot and compare only.
heatmap_norm --heatmap-norm	'Linear'	Heatmap color scaling: linear (default) or log — log compresses heavy-tailed dwell times so a few hot words don't wash out the rest. One of 'Linear', 'Log'. Plot and compare only.
heatmap_range --heatmap-range	None	Pin the heatmap's color scale to LO..HI instead of the trial's own range. Plot and compare only.
heatmap_opacity --heatmap-opacity	None	Heatmap opacity, 0.05–1.0. Plot and compare only.
heatmap_sigma_px --heatmap-sigma	None	Gaussian σ in px for --heatmap-style interpolated. Plot and compare only.
word_heatmap_col --word-heatmap-col	None	For a words-only dataset (no fixations): tint each word box by this numeric words column — e.g. gpt2_surprisal — instead of its dwell time. Plot and compare only.
word_heatmap_title --word-heatmap-title	None	Color-bar title for --word-heatmap-col. Plot and compare only.

Raw gaze

Option and render flag	Default	Description
show_raw_gaze --raw-gaze --no-raw-gaze	False	Raw (sample-level) gaze table(s) to draw under the fixations, columns auto-detected like --fixations (same formats; several paths or a quoted glob concatenate). Static figures and --compare-with comparisons, where each scanpath's samples take its color (not --animate). On its own (no other input) it is the dataset: its trials are listed and drawn as recorded — no fixations are detected from the samples. Plot and compare only.
raw_gaze_color --raw-gaze-color	'#888888'	Raw-gaze sample color. A comparison draws each scanpath's samples in its own color instead.
raw_gaze_marker_size --raw-gaze-marker-size	4.0	Raw-gaze sample size, 1–12.
raw_gaze_opacity --raw-gaze-opacity	0.6	Raw-gaze sample opacity, 0.1–1.0.

Legends and color bars

Option and render flag	Default	Description
legend_layout --legend	None	Place one legend, repeatable. SPEC is KIND=POSITION[,ARRANGEMENT][,SIZE] with KIND one of compare, saccades, colors (the fixation colour categories), size-key, highlight (the highlighted-words note); POSITION auto or SPOT-outside / SPOT-inside with SPOT one of top-left, top-center, top-right, left, right, bottom-left, bottom-center, bottom-right (outside grows the figure; left and right run down the side); ARRANGEMENT stacked or side-by-side; SIZE the text size in px — e.g. --legend saccades=right-outside,stacked,14. Whether a legend is drawn at all is still its own switch.
show_color_legend --no-color-legend	True	Hide the fixation-colour legend: the categories of a categorical --color-by and the highlighted fixations' entries (the markers still draw). Shows by default.
show_highlight_legend --no-highlight-legend	True	Hide the note naming the highlighted words (the words stay marked). Shows by default; --legend highlight=SPEC places it.
saccade_type_legend --no-saccade-type-legend	True	With --saccade-color-by-type: hide the saccade-type color key on the figure (the colored lines still draw). Legend shows by default. Plot and compare only.
duration_size_legend --no-duration-size-legend	True	Hide the duration-size key (reference circles labelled in ms) drawn on a fixed --marker-size-scale.
show_fixation_colorbar --no-fixation-colorbar	True	Leave out --color-by's color bar.
fixation_colorbar_orientation --fixation-colorbar-orientation	'Vertical'	Fixation color bar: beside the plot (vertical, default) or below it. One of 'Vertical', 'Horizontal'.
fixation_colorbar_length --fixation-colorbar-length	None	Fixation color bar: length as a share of the plot's side, 0.1–1.0.
fixation_colorbar_thickness --fixation-colorbar-thickness	14	Fixation color bar: thickness, 4–40 px.
fixation_colorbar_tickangle --fixation-colorbar-tickangle	0	Fixation color bar: tick-label angle, -90–90.
fixation_colorbar_tickfont_size --fixation-colorbar-tickfont-size	12	Fixation color bar: tick-label size.
show_heatmap_colorbar --no-heatmap-colorbar	True	Leave out the heatmap's color bar.
heatmap_colorbar_orientation --heatmap-colorbar-orientation	'Vertical'	Heatmap color bar: beside the plot (vertical, default) or below it. One of 'Vertical', 'Horizontal'.
heatmap_colorbar_length --heatmap-colorbar-length	None	Heatmap color bar: length as a share of the plot's side, 0.1–1.0.
heatmap_colorbar_thickness --heatmap-colorbar-thickness	14	Heatmap color bar: thickness, 4–40 px.
heatmap_colorbar_tickangle --heatmap-colorbar-tickangle	0	Heatmap color bar: tick-label angle, -90–90.
heatmap_colorbar_tickfont_size --heatmap-colorbar-tickfont-size	12	Heatmap color bar: tick-label size.

Figure and canvas

Option and render flag	Default	Description
fit_to_monitor --no-full-monitor	True	Frame the axes on the data instead of the whole --canvas monitor (the app's Crop to data).
crop_margin --crop-margin	None	The margin around the data, in screen px, when cropping to it. Implies --crop-to-data.
background_color --background-color	'#ffffff'	Plot background color.
show_plot_frame --no-plot-frame	True	Leave out the border round the plot area.
plot_frame_color --plot-frame-color	'#000000'	Color of the border round the plot area.
show_coordinate_grid --coordinate-grid	False	Overlay a monitor-pixel X/Y grid on the scanpath.
coordinate_grid_spacing --coordinate-grid-spacing	None	Pin the major coordinate-grid interval in pixels. Implies --coordinate-grid; omit for automatic 1/2/5×10ⁿ spacing.
coordinate_grid_font_size --coordinate-grid-font-size	18	Size of the coordinate grid's labels, 6–36 px.
x_field --x-field	'x'	Fixation column on the x axis. A non-spatial one draws a chart of the fixations instead of the scanpath. Plot and compare only.
y_field --y-field	'y'	Fixation column on the y axis. Plot and compare only.

Title and caption

Option and render flag	Default	Description
title_font_size --title-size	20	Size of the --title text, 8–48 px.
caption_font_size --caption-size	13	Size of the --caption text, 6–36 px.
caption_color --caption-color	'#555555'	Color of the --caption text.

Hover

Option and render flag	Default	Description
word_hover_fields --word-hover-fields	list, see figure_options()	Comma-separated word columns shown on hover (e.g. text,word_id,gpt2_surprisal).
word_hover_measure --word-hover-measure	'total_fixation_duration_ms'	The reading measure a word's hover shows.
fixation_hover_fields --fixation-hover-fields	list, see figure_options()	Comma-separated fixation columns shown on hover (e.g. order_in_trial,duration_ms,eye).

Illustration

Option and render flag	Default	Description
illustration_text --illustration-text	''	The Illustration label's text.
illustration_reasons	None	Why the figure is labelled an illustration. The builder works it out from illustration_label; pass it only to word the label yourself. Plot and compare only.

Comparison

Option and render flag	Default	Description
label_a --label-a	'Scanpath A'	Name for the FIRST scanpath in the legend and hover, instead of the default. Applies to the comparison figure and the --animate co-animation. Requires --label-b. Animate only.
label_b --label-b	'Scanpath B'	Name for the SECOND scanpath in the legend and hover, instead of the default. Requires --label-a. Animate only.
style_a --style-a	None	Styling for the FIRST scanpath, repeatable: KEY=VALUE[,...]. Colors (#RRGGBB): fix_color, saccade_color, box_color (word-box outline; default fix_color), box_fill_color (default --word-box-fill-color), raw_gaze_color (default fix_color). Also heatmap_colorscale (default --heatmap-colorscale, on the shared range), saccade_style (solid|dash|dot|dashdot), saccade_width (px), marker_size_range (MIN:MAX), opacity (0.1–1), box_line_opacity / box_fill_opacity (0–1; default --word-box-line-opacity / --word-box-fill-opacity), hollow (true|false). E.g. --style-a fix_color=#D55E00,opacity=0.5. --animate uses them too, except box_color, box_fill_color, the box opacities and raw_gaze_color. Animate and compare only.
style_b --style-b	None	Styling for the SECOND scanpath, repeatable: KEY=VALUE[,...]. Colors (#RRGGBB): fix_color, saccade_color, box_color (word-box outline; default fix_color), box_fill_color (default --word-box-fill-color), raw_gaze_color (default fix_color). Also heatmap_colorscale (default --heatmap-colorscale, on the shared range), saccade_style (solid|dash|dot|dashdot), saccade_width (px), marker_size_range (MIN:MAX), opacity (0.1–1), box_line_opacity / box_fill_opacity (0–1; default --word-box-line-opacity / --word-box-fill-opacity), hollow (true|false). E.g. --style-b fix_color=#D55E00,opacity=0.5. --animate uses them too, except box_color, box_fill_color, the box opacities and raw_gaze_color. Animate and compare only.
show_legend --no-compare-legend	True	Draw the legend naming the two scanpaths (the app's A/B legend; on by default, as in the app). Applies to the --animate co-animation too. Animate and compare only.
compare_stimulus --compare-stimulus	'both'	On an overlay, whose word boxes and text to draw. Two datasets' word boxes coincide only when the text is identical. One of 'both', 'a', 'b'. Animate only.
words_b	None	Scanpath B's word table, for a replay of two scanpaths. Animate only.
fixations_b	None	Scanpath B's fixation table, for a replay of two scanpaths. Animate only.
fixation_flags_b --compare-fixation-flag	None	Filters & highlights for the SECOND scanpath only, repeatable; same SPEC as --fixation-flag, e.g. --compare-fixation-flag short=discard,threshold_ms=80. Replaces --fixation-flag for B. Animate only.
background_image_b --stimulus-image-b	None	The SECOND scanpath's stimulus image, for a side-by-side or stacked comparison across two datasets (each panel draws its own page). Sized and placed like --stimulus-image. Compare only.
background_image_size_b --stimulus-image-size-b	None	Size of --stimulus-image-b in px. Compare only.
background_image_origin_b --stimulus-image-origin-b	None	Top-left of --stimulus-image-b in the second screen's px. Compare only.

Replay

Option and render flag	Default	Description
anim_grid_step_ms --anim-grid-step-ms	None	With --animate: emit a frame every MS of reading time. Smaller is smoother and larger to export. Animate only.
anim_max_frames --anim-max-frames	None	With --animate: at most N frames, the first included. A trial too long for that many at --anim-grid-step-ms gets a wider step instead. Animate only.