---
title: "Contiguous Motif Workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Contiguous Motif Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4.5
)
```

## Scope

This article demonstrates the restricted contiguous-motif workflow in
`gp3sequences`. The workflow accepts ordinary long-format data frames and does
not require Gazepoint software, hardware, exports, or `gp3tools`.

The functions describe recurring state windows and their locations. They do not
infer attention, cognition, emotion, intention, psychological state, or causal
mechanisms.

## Synthetic ordered-state data

The example contains three sequences and one preserved grouping variable.

```{r data}
library(gp3sequences)

sequence_data <- data.frame(
  sequence = c(
    rep("s1", 5L),
    rep("s2", 4L),
    rep("s3", 3L)
  ),
  order = c(1:5, 1:4, 1:3),
  state = c(
    "A", "B", "A", "B", "C",
    "A", "B", "C", "B",
    "B", "A", "B"
  ),
  group = c(
    rep("g1", 5L),
    rep("g1", 4L),
    rep("g2", 3L)
  ),
  stringsAsFactors = FALSE
)

sequence_data
```

## Extract contiguous motifs

`extract_sequence_ngrams()` enumerates contiguous state windows only. Minimum
and maximum motif lengths and the overlapping-occurrence policy are explicit.

```{r extract}
extracted <- extract_sequence_ngrams(
  sequence_data,
  sequence_id_col = "sequence",
  order_col = "order",
  state_col = "state",
  metadata_cols = "group",
  min_length = 2L,
  max_length = 3L,
  overlap = "allow"
)

head(extracted$occurrences)
```

## Summarise, filter, and format motifs

Sequence prevalence uses every validated sequence as its denominator. Filtering
is deterministic and retains explicit thresholds and tie handling.

```{r summarise-filter-format}
motif_summary <- summarise_sequence_motifs(extracted)

motif_filter <- filter_sequence_motifs(
  motif_summary,
  min_occurrences = 2L,
  min_sequences = 2L,
  min_prevalence = 0.50,
  motif_lengths = c(2L, 3L),
  top_n = 10L,
  rank_by = "sequence_prevalence",
  ties = "include"
)

motif_table <- format_sequence_motifs(
  motif_filter,
  prevalence = "percent",
  digits = 1L
)

motif_table$table
```

## Summarise motif positions

Positions may represent the start, centre, or end of each motif occurrence.
Absolute positions use one-based state indices. Relative positions range from 0
to 1 across each sequence.

```{r position-summary}
position_summary <- summarise_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative",
  by = "group"
)

position_summary$summary
```

`format_sequence_motif_positions()` changes display precision and units without
modifying the underlying analytical object.

```{r position-format}
position_table <- format_sequence_motif_positions(
  position_summary,
  digits = 1L,
  position_units = "percent",
  include_rank = TRUE
)

position_table$table
```

## Plot motif prevalence

`plot_sequence_motifs()` uses base R graphics. The returned data frame contains
the exact motifs and values used in the plot.

```{r motif-plot, fig.cap="Sequence prevalence for the most frequent contiguous motifs."}
plotted_motifs <- plot_sequence_motifs(
  motif_summary,
  metric = "sequence_prevalence",
  top_n = 8L,
  motif_lengths = c(2L, 3L),
  ties = "include",
  horizontal = TRUE
)

plotted_motifs[
  c("plot_rank", "motif", "motif_length", "plot_value")
]
```

## Plot motif locations

The strip display shows individual occurrence positions with deterministic
stacking. No random jitter is used.

```{r position-strip, fig.cap="Relative centre positions of selected motif occurrences."}
strip_data <- plot_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative",
  top_n = 5L,
  display = "strip"
)

head(
  strip_data[
    c(
      "sequence_id",
      "motif",
      "position_value",
      "plot_rank"
    )
  ]
)
```

The distribution display provides a compact base-R summary for the same
structural positions.

```{r position-distribution, fig.cap="Distributions of relative motif centre positions."}
plot_sequence_motif_positions(
  extracted,
  position = "centre",
  scale = "relative",
  top_n = 5L,
  display = "distribution"
)
```

## Interpretation boundary

The reported counts, prevalence values, and positions describe the supplied
ordered states under the declared preparation, motif-length, overlap, filtering,
and position rules. Any substantive interpretation belongs to the research
design and cannot be inferred automatically from motif structure alone.