numspellr: Detect Numeric Persistence and Spell Patterns

In numspellR: Detection of Numeric Persistence and Rigidity Patterns

Detect Numeric Persistence and Spell Patterns

Description

numspellr() is a universal numeric persistence detector designed to identify prolonged stability ("spells") and rigidity patterns in numeric data. The function automatically detects numeric variables from various data structures (numeric vectors or data frames) and computes persistence metrics commonly used in rigidity and stickiness analysis.

The output includes interpretable measures such as average spell length, stability ratio, elasticity, and adjustment frequency, accompanied by plain-language interpretations suitable for policy and applied analysis.

Usage

numspellr(data, lang = c("indonesia", "english"), min_spell = 2, tol = NULL)

Arguments

data	A numeric vector or a data.frame/tibble containing one or more numeric variables. Non-numeric columns are ignored automatically.
lang	Language for persistence status labels and interpretation text. Must be either "indonesia" or "english".
min_spell	Minimum length (in periods) required for a sequence to be considered a persistence spell. Default is 2.
tol	Optional numeric tolerance threshold for detecting stability. If NULL (default), tolerance is determined automatically based on variability of first differences.

Details

The function identifies persistence spells as consecutive periods where absolute changes fall below a tolerance threshold.

Metrics computed include:

• avg_spell: average duration of stable periods.

• median_spell: median duration of stability.

• max_spell: longest observed stable period.

• stability_ratio: proportion of observations belonging to spells.

• elasticity_index: average relative magnitude of changes.

• adjustment_frequency: share of periods with meaningful changes.

• spell_concentration: dominance of long spells over short ones.

Persistence status is classified into qualitative categories ranging from highly flexible to highly rigid, with labels adapted to the selected language.

Value

A data.frame with one row per numeric variable containing:

structure

Detected data structure type.

id

Variable identifier.

variable

Variable name.

avg_spell

Average persistence spell length.

median_spell

Median persistence spell length.

max_spell

Maximum persistence spell length.

stability_ratio

Share of observations in stable spells.

elasticity_index

Average relative change magnitude.

adjustment_frequency

Frequency of meaningful adjustments.

spell_concentration

Concentration index of persistence spells.

persistence_status

Qualitative persistence category.

interpretation

Plain-language interpretation suitable for policy analysis.

Author(s)

Joko Nursiyono

References

Caballero, R. J., & Engel, E. M. R. A. (1993). Microeconomic adjustment hazards and aggregate dynamics. Quarterly Journal of Economics, 108(2), 359–383.

Nakamura, E., & Steinsson, J. (2008). Five facts about prices: A reevaluation of menu cost models. Quarterly Journal of Economics, 123(4), 1415–1464.

See Also

diff, rle

Examples

x <- c(10, 10, 10, 11, 11, 11, 11, 12)
numspellr(x, lang = "english")

df <- data.frame(
  time = 1:8,
  value = c(5, 5, 5, 5, 6, 6, 6, 7)
)
numspellr(df, lang = "indonesia")

numspellR documentation built on Feb. 6, 2026, 5:08 p.m.