Package 'DCIi1'

I1 Mean-Change Testing and DCI Candidate Detection

Description

Adaptive mean contrasts, the I1 statistic, localized scaling, descriptive DCI candidate detection and segmentation covering metrics.

Details

Start with i1_test for the 100-observation independent Gaussian reference test, or i1_stt for statistic-only analysis. Use dcii1 for descriptive candidate locations. DCI does not perform significance testing. See the package vignettes for examples.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

---

Extract Refined Candidate Locations

Description

Sort and deduplicate refined locations from a DCI candidate result.

Usage

change_points(x)

Arguments

x	A data frame returned by dcii1, with finite numeric etavec and a Flag column.

Details

This function performs no significance filtering or refitting. Returned values are candidate locations, not statistically accepted changes. Each location denotes the last observation before a candidate boundary. The alpha argument from development version 0.1.0 is not supported.

Value

Sorted unique numeric candidate locations; numeric(0) for no candidates.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

Examples

set.seed(14)
y <- rnorm(100) + rep(c(0, 3), each = 50)
change_points(dcii1(y))

---

Weighted and Unweighted Segmentation Covering

Description

Compare a true segmentation with an estimated segmentation using best matching Jaccard overlaps, as in the manuscript's simulation criteria.

Usage

covering_metric(Tl, actual_cps, est_cps)
covering_metric_unwtd(Tl, actual_cps, est_cps)

Arguments

Tl	Positive integer series length.
actual_cps	Numeric vector of actual last-observation-before-change indices, integers in 1 through Tl-1. Use numeric(0) for no changes.
est_cps	Estimated indices with the same restrictions.

Details

For each actual segment, find the largest intersection-over-union score with any estimated segment. The weighted metric averages these scores with actual segment lengths as weights. The unweighted metric assigns equal weight to each distinct actual segment. Both functions sort and deduplicate input locations; this corrects the original unweighted denominator for repeated locations. Invalid indices are rejected. The metrics are directional, need not be symmetric, and are not tests or p-values. Endpoints are computed by interval arithmetic, without allocating observation-index sets.

Value

A numeric value between 0 and 1; 1 means identical segmentations.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

Examples

covering_metric(100, c(30, 60), c(32, 58))
covering_metric_unwtd(100, c(30, 60), c(32, 58))
covering_metric(100, numeric(0), numeric(0))

---

Generate and Refine DCI Candidate Change Locations

Description

Flag candidate mean changes with localized IQR exceedances, then calculate the I1 statistic and a refined location in each neighboring window. This is descriptive candidate detection, without significance testing.

Usage

dcii1(y, r1 = 0, nbrhudfracleni1 = 1, i1ar = 0,
  w1 = 22, il_cutoff = 0, flag_method = c("legacy", "runs"))

Arguments

y	Finite numeric vector, subject to the length and scale restrictions of i1_test. Each local IQR must be positive.
r1	Nonnegative minimum absolute flag weight. Positive weights exactly equal to r1 are retained for reference compatibility.
nbrhudfracleni1	Localization fraction in (0,1]. Scaling-window length is round((length(y)-1)*nbrhudfracleni1), at least 2.
i1ar	0 for independent-noise standardization; 1 for the manuscript WD scale in local statistic calculations. Neither setting produces DCI p-values.
w1	Full-window parameter; see i1_test.
il_cutoff	Nonnegative exceedance threshold applied before summing weights.
flag_method	"legacy" preserves original run selection and centroid conventions with negative-terminal indexing repaired. "runs" uses every maximal nonzero same-sign run and its rounded arithmetic midpoint.

Details

Apply adaptive contrasts to y. Within each scaling window, subtract the upper quartile for observations above it or the lower quartile below it, and divide by the window IQR; observations inside the quartiles contribute zero. Average transformed values across all windows containing each contrast. The manuscript's Hankel row count is p = length(y) - round((length(y)-1)*nbrhudfracleni1).

Legacy centroids are run_end - round(run_length/2); its counter rule omits some interfacing runs or the first singleton. The runs option is a separate explicit convention. Flag weights are signed; Direction need not agree with the sign of the subsequently fitted Magnitude.

Prune flags from left to right until each neighboring pair of segments has enough observations. The source length check uses length(y)-1 as the terminal boundary; local evaluation uses length(y). Evaluate each retained flag using its initial neighbors, with statistic-only I1 calculations. Refined locations can coincide or appear out of order. No hypothesis is accepted or rejected, and no sequential significance filtering is performed. The reference I1 calibration is not applied to data-selected DCI windows, even when a window happens to have length 100. Candidate locations can occur in noise-only data.

Undefined local scales or inadmissible WD dependence estimates cause an error identifying the affected flag. No artificial jitter or fallback distribution is introduced. The alpha, output, evaluation and calibration arguments from development version 0.1.0 are not part of this interface.

Value

Data frame with the original six column names:

Flag	Numeric preliminary last-observation-before-change index.
Direction	Character flag sign, +ve or -ve.
pvalue	Always NA_real_: retained as a structural compatibility column.
istatistic	Local I1 statistic rounded to four decimals.
etavec	Refined global candidate location.
Magnitude	Signed local contrast in that window's standardized units.

Empty results have zero rows and the same column types. The settings attribute explicitly identifies candidate-only inference.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

See Also

i1_test, change_points

Examples

set.seed(21)
y <- rnorm(160) + rep(c(0, 4, -3, 1), c(50, 15, 15, 80))
candidates <- dcii1(y)
candidates
change_points(candidates)
dcii1(y, nbrhudfracleni1 = .5)

---

Compute the Unrounded I1 Statistic Without Calibration

Description

Compute the reference adaptive I1 statistic independently of the empirical calibration repository.

Usage

i1_stt(y, archeck = 0, w1 = 22)

Arguments

y	Finite numeric vector with the length and scaling restrictions of i1_test.
archeck	0 for differenced-IQR scaling; 1 to estimate dependence.
w1	Integer full-window parameter, at least 4, with half-width round(w1 / 2) and at least twice that half-width observations.

Details

Uses adaptive contrasts and symmetric aggregation as described in i1_test. No p-value, critical value or significance decision is available here. WD scaling follows Appendix B.1 and the supplied script. Estimated dependence must lie strictly in (-1,1), and no p-value is assigned. Undefined scaling and non-finite inputs produce errors.

Value

One unrounded nonnegative numeric statistic.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

See Also

i1_test

Examples

set.seed(13)
y <- rnorm(100)
i1_stt(y)
i1_stt(y, w1 = 10)
i1_stt(y, archeck = 1)

---

I1 Mean-Change Test or Statistic-Only Analysis

Description

Compute an adaptive mean-change statistic. Reference p-values are available only for independent Gaussian series of length 100 with w1 = 22.

Usage

i1_test(y, archeck = 0, w1 = 22, calibration = c("reference", "none"))

Arguments

y	Finite numeric vector or univariate time series. At least max(w1, 2 * round(w1 / 2)) observations are required. Missing, infinite, complex and matrix inputs are rejected.
archeck	0 for independent-noise standardization; 1 for the manuscript's WD scale. WD mode requires calibration = "none".
w1	Integer full-window parameter, at least 4. Each side uses at most w = round(w1 / 2) observations; R rounds ties to even.
calibration	"reference" requires length 100, w1 = 22 and archeck = 0. It assumes independent Gaussian noise. "none" returns NA for pvalue and allows other supported lengths, windows and WD standardization.

Details

Center the data and divide by $\mathrm{IQR}(\Delta y)/[-2\sqrt{2}\Phi^{-1}(0.25)]$. For boundary t, subtract the preceding min(w,t) observation mean from the following min(w,n-t) observation mean. Sum these contrasts from t-w+1 through t+w-1; maximize the absolute aggregate over t = w,...,n-w, choosing the first maximum. This preserves the original script's adaptive implementation; the theoretical interior-only index set is different.

WD estimates $\hat\rho=1+2\mathrm{cor}(\Delta y_{1:(n-2)},\Delta y_{2:(n-1)})$ and uses $\mathrm{IQR}(\Delta y)/[-2\sqrt{2}(1-\hat\rho)\Phi^{-1}(0.25)]$, as in Appendix B.1. The radical covers 2 only. The dependence identity is appropriate for stationary AR(1) noise, not arbitrary serial dependence. Non-finite estimates or estimates outside (-1,1), zero IQR and arithmetic overflow cause descriptive errors. WD results are statistics, not calibrated tests.

Reference p-values sum the supplied zero-correlation density ordinates at or above the unrounded statistic, multiply by grid spacing, bound to [0,1] and round to four decimals. A zero is a finite-grid tail approximation, not proof of zero probability. The null is a constant mean with independent Gaussian noise. Distributional assumptions are the user's responsibility; they cannot be established from input length alone. The method is not a general test for variance changes, trends, or arbitrary dependent noise.

In 10000 independent Gaussian null validation series of length 100, rejection rates at nominal .01, .05 and .10 were .0086, .0415 and .0857. Thus the retained calibration is approximate and was conservative at these levels in this study. These results do not establish exact size at every significance level. There is no multiplicity adjustment or asymptotic p-value substitution.

Value

One-row data frame with numeric columns:

pvalue	Approximate reference upper-tail probability; NA for statistic-only mode.
i1	Absolute maximum aggregate, rounded to four decimals.
etahat	Estimated last observation before the change, between w and n-w, even when the test is not significant.
cpmag	Signed right-minus-left contrast in standardized units. Multiply by the diagnostics sigma to express it in the original data units.

The diagnostics attribute records scale, dependence estimate, calibration mode, reference length, selected key, unrounded statistic and inference scope.

References

Waychal, N., Laha, A. K. and Sinha, A. (2026). Closely spaced change-point detection with an application to geopolitical shocks in oil and gas markets. doi:10.48550/arXiv.2610.23476.

See Also

i1_stt, dcii1

Examples

set.seed(12)
y <- rnorm(100) + rep(c(0, 3), each = 50)
result <- i1_test(y)
result
attr(result, "diagnostics")
i1_test(y, w1 = 16, calibration = "none")
i1_test(y, archeck = 1, calibration = "none")

---