Help for package numspellR

Title:

Detection of Numeric Persistence and Rigidity Patterns

Version:

0.1.0

Description:

Tools for detecting numeric persistence ("spells") and rigidity patterns in time-ordered numeric data. The package identifies periods of stability, computes spell-based rigidity metrics, and provides plain-language interpretations suitable for policy and applied analysis.

License:

MIT + file LICENSE

Encoding:

UTF-8

Depends:

R (≥ 3.6.0)

Imports:

stats

Suggests:

testthat (≥ 3.0.0), knitr, rmarkdown

RoxygenNote:

7.3.3

Config/testthat/edition:

VignetteBuilder:

knitr

NeedsCompilation:

Packaged:

2026-02-03 07:48:07 UTC; BPS Prov Jawa Timur

Author:

Joko Ade Nursiyono

[aut, cre]

Maintainer:

Joko Ade Nursiyono <jokoadenursiyono@gmail.com>

Repository:

CRAN

Date/Publication:

2026-02-06 13:40:02 UTC

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.

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")