Package 'STMotif'

CSA Datamining Process

Description

Performs the complete Combined Series Approach (CSA) workflow: normalization with SAX encoding, motif discovery, and ranking. This is a convenience wrapper around NormSAX, SearchSTMotifs, and RankSTMotifs.

Usage

CSAMiningProcess(D, DS, w, a, sb, tb, si, ka)

Arguments

D	Dataset containing numeric values.
DS	Dataset containing SAX encoded values (recomputed internally; this parameter is kept for backward compatibility).
w	Word size (motif length in SAX symbols).
a	Number of letters in the SAX alphabet.
sb	Spatial block size (number of columns per block).
tb	Temporal block size (number of rows per block).
si	Minimum number of occurrences inside each block (sigma).
ka	Minimum number of spatial series with occurrences inside each block (kappa).

Value

A list of ranked motifs. Each motif contains:

isaxcode

Motif sequence in character format.

recmatrix

Matrix indicating which blocks contain this motif.

vecst

Data frame with columns s (spatial) and t (temporal) giving the start positions of the motif in the original dataset.

rank

List with ranking components: dist, word, qtd, proj.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
rmotif <- CSAMiningProcess(D, DS, 4, 5, 4, 10, 2, 2)

---

Plot Heatmap with Highlighted Motifs

Description

Displays the dataset as a heatmap (encoded via SAX binning) and overlays colored markers at the positions where the selected motifs occur.

Usage

display_motifsDataset(dataset, rstmotifs, alpha)

Arguments

dataset	Data frame or matrix containing numeric values. Each column represents a spatial series, each row a time point.
rstmotifs	List of ranked motifs, as returned by RankSTMotifs or CSAMiningProcess.
alpha	Integer. The cardinality of the SAX alphabet (number of discretization levels).

Value

A ggplot object showing the heatmap with motif positions highlighted as colored squares.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)
display_motifsDataset(
  dataset = STMotif::example_dataset,
  rstmotifs[c(1:4)],
  5
)

---

Plot Spatial-Time Series with Highlighted Motifs

Description

Displays the selected spatial-time series and highlights the segments corresponding to the discovered motifs using distinct colors.

Usage

display_motifsSTSeries(dataset, rstmotifs, space = seq_len(ncol(dataset)))

Arguments

dataset	Data frame or matrix containing numeric values. Each column represents a spatial series, each row a time point.
rstmotifs	List of ranked motifs, as returned by RankSTMotifs or CSAMiningProcess.
space	Integer vector specifying which columns (spatial series) to display. Defaults to all columns.

Value

A ggplot object showing the time series with motif occurrences highlighted in color.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)
display_motifsSTSeries(
  dataset = STMotif::example_dataset,
  rstmotifs[c(1:4)],
  space = c(1:4, 10:12)
)

---

Example Spatial-Time Series Dataset

Description

A synthetic toy dataset containing 12 spatial-time series, each with 20 time points. Used to demonstrate the motif discovery functions in this package.

Usage

example_dataset

Format

A data frame with 20 rows and 12 columns. Each column represents a spatial-time series and each row represents a time point. All values are numeric.

Source

Synthetic data generated for demonstration purposes.

Examples

data(example_dataset)
dim(example_dataset)
# [1] 20 12

---

Normalize and SAX Encode a Dataset

Description

Applies z-score normalization to the entire dataset and encodes the values using the Symbolic Aggregate approXimation (SAX) with an alphabet of size a.

Usage

NormSAX(D, a)

Arguments

D	Dataset containing numeric values.
a	Number of letters in the SAX alphabet.

Value

A data frame with the same dimensions as D, containing SAX letter encodings (characters from a to the a-th letter of the alphabet).

Examples

DS <- NormSAX(STMotif::example_dataset, 5)

---

Rank Spatial-Time Motifs

Description

Ranks the discovered motifs by computing a composite quality score that balances spatial-temporal proximity of occurrences, entropy of the SAX encoding, and quantity of occurrences.

Usage

RankSTMotifs(stmotifs)

Arguments

stmotifs

List of identified motifs (as returned by SearchSTMotifs).

Value

A list of motifs sorted by decreasing quality score. Each motif gains a rank component with dist, word, qtd, and proj values.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)
rstmotifs <- RankSTMotifs(stmotifs)

---

Search for Spatial-Time Motifs

Description

Discovers motifs in the spatio-temporal blocks of the dataset, validates occurrence constraints, and groups motifs from neighboring blocks.

Usage

SearchSTMotifs(D, DS, w, a, sb, tb, si = 3, ka = 3)

Arguments

D	Dataset containing numeric values.
DS	Dataset containing SAX encoded values (as returned by NormSAX).
w	Word size (motif length in SAX symbols).
a	Number of letters in the SAX alphabet.
sb	Spatial block size (number of columns per block).
tb	Temporal block size (number of rows per block).
si	Minimum number of occurrences inside each block (sigma). Default: 3.
ka	Minimum number of spatial series with occurrences inside each block (kappa). Default: 3.

Value

A list of identified motifs. Each motif contains:

isaxcode

Motif sequence in character format.

recmatrix

Matrix indicating which blocks contain this motif.

vecst

Data frame with columns s and t giving the start positions in the original dataset.

Examples

D  <- STMotif::example_dataset
DS <- NormSAX(STMotif::example_dataset, 5)
stmotifs <- SearchSTMotifs(D, DS, 4, 5, 4, 10, 2, 2)

---

Adjust a Dataset

Description

Adjusts the dimensions of a dataset so that it can be evenly divided into spatio-temporal blocks of size tb x sb.

Usage

STSADatasetAdjust(D, tb, sb)

Arguments

D	Dataset containing numeric values.
tb	Temporal block size (number of rows per block).
sb	Spatial block size (number of columns per block).

Value

Dataset with rows and columns trimmed to be divisible by tb and sb, respectively.

Examples

D <- STSADatasetAdjust(STMotif::example_dataset, 20, 12)

---