plot_most_frequent_sequences()

plot_most_frequent_sequences() draws the Top-N most common full sequences in your data (e.g., the 10 most frequently observed state paths). Each horizontal bar represents one sequence pattern across time; the bar’s height equals that sequence’s percentage in the whole dataset. Colors follow your SequenceData state color map so segments match your legend.

This is similar to TraMineR::seqfplot().

Function Usage

plot_most_frequent_sequences(
    seqdata,
    top_n=10,         # how many sequences to show
    save_as=None,     # e.g., "top_sequences.png"
    dpi=200
)

Entry Parameters

Parameter	Required	Type	Description
seqdata	✓	SequenceData	Your sequence dataset created with SequenceData. Colors and legend come from this object.
top_n	✗	int	Number of most frequent sequences to display. Default = 10.
save_as	✗	str	File path to save the figure (e.g., "top_sequences.png"). If not set, the plot is just shown on screen.
dpi	✗	int	Resolution when saving the image. Default = 200. Use 300+ for publications if your machine can handle it.

What It Does

• Counts how often each unique full sequence appears.

• Selects the Top-N sequences and computes their share (percentage of all sequences).

• Draws each sequence as a stacked horizontal bar: one colored block per time point.

• Labels the x-axis as time and the y-axis as cumulative percentage so you can see:

  • the top sequence’s percentage,
  • the cumulative share covered by the Top-N sequences.

Returns

None. The function draws the figure on screen, and writes it to disk when save_as is provided.

Key Features

• Clear, compact view of the most typical trajectories in your data.
• Colors and legend automatically match SequenceData (no manual color work).
• Scales to different top_n values without changing your workflow.
• Ready for export with save_as and dpi.

Examples

1. Show the default Top 10 sequences

plot_most_frequent_sequences(seqdata)

2. Show Top 5 sequences with higher resolution

plot_most_frequent_sequences(
    seqdata,
    top_n=5,
    dpi=300
)

3. Save the figure to a file

plot_most_frequent_sequences(
    seqdata,
    top_n=15,
    save_as="top15_sequences.png"
)

This saves top15_sequences.png in your current working directory (or the folder you specify).

R Counterpart

• Closest R function: TraMineR::seqfplot()
• Mapping note: Closest match: display top frequent sequences and their frequencies.

Notes

• Bars are stacked along time so you can read the sequence pattern left → right.
• The y-axis shows percentages. The top tick equals the cumulative share of the Top-N sequences (so the bars fill up to that value, not necessarily to 100%).
• The legend is pulled from SequenceData to ensure state-color consistency across plots.

See Also

• How to Read Sequence Plots explains how to interpret and choose plot types.
• Visualization Gallery shows all plots with code.
• Visualization Tools documents shared parameters.

Authors

Code: Yuqi Liang

Documentation: Yuqi Liang

Edited by: Yuqi Liang