Type:	Package
Title:	Detection and Analysis of Dormant Patterns in Data
Version:	0.1.0
Description:	A novel framework for detecting, quantifying, and analyzing dormant patterns in multivariate data. Dormant patterns are statistical relationships that exist in data but remain inactive until specific trigger conditions emerge. This concept, inspired by biological dormancy (seeds, pathogens) and geological phenomena (dormant faults), provides tools to identify latent risks, hidden correlations, and potential phase transitions in complex systems. The package introduces methods for quantifying dormancy depth, trigger sensitivity, and awakening risk - enabling analysts to discover patterns that conventional methods miss because they focus only on currently active relationships.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.0.0)
Imports:	stats, utils, grDevices, graphics, Rcpp (≥ 1.0.0)
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, ggplot2, covr
LinkingTo:	Rcpp
VignetteBuilder:	knitr
URL:	https://github.com/danymukesha/dormancy/, https://danymukesha.github.io/dormancy/
BugReports:	https://github.com/danymukesha/dormancy/issues/
NeedsCompilation:	yes
Packaged:	2026-03-09 20:30:00 UTC; dany.mukesha
Author:	Dany Mukesha [aut, cre]
Maintainer:	Dany Mukesha <danymukesha@gmail.com>
Repository:	CRAN
Date/Publication:	2026-03-16 16:00:33 UTC

dormancy: Detection and Analysis of Dormant Patterns in Data

Description

A novel framework for detecting, quantifying, and analyzing dormant patterns in multivariate data. Dormant patterns are statistical relationships that exist in data but remain inactive until specific trigger conditions emerge. This concept, inspired by biological dormancy (seeds, pathogens) and geological phenomena (dormant faults), provides tools to identify latent risks, hidden correlations, and potential phase transitions in complex systems. The package introduces methods for quantifying dormancy depth, trigger sensitivity, and awakening risk - enabling analysts to discover patterns that conventional methods miss because they focus only on currently active relationships.

Author(s)

Maintainer: Dany Mukesha danymukesha@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/danymukesha/dormancy/

• https://danymukesha.github.io/dormancy/

• Report bugs at https://github.com/danymukesha/dormancy/issues/

Simulate Awakening of Dormant Patterns

Description

Simulates what would happen if a dormant pattern were to "awaken" - i.e., become active. This function allows exploration of potential future states and scenario analysis without waiting for actual pattern activation.

Usage

awaken(
  dormancy_result,
  pattern_id = 1,
  intensity = 1,
  n_sim = 100,
  return_data = FALSE,
  verbose = FALSE
)

Arguments

Details

Awakening simulation is valuable for:

• Scenario planning and stress testing

• Understanding potential system behaviors

• Preparing for pattern activation events

• Testing the robustness of current strategies

The simulation works by:

1. Identifying the dormant pattern's trigger conditions

2. Simulating data where those conditions are met

3. Applying the pattern's relationship to the simulated data

4. Measuring the resulting effects on the system

Value

A list containing:

• awakening_effects - Data frame describing the effects of awakening

• simulated_stats - Summary statistics from simulations

• cascade_effects - Effects on other patterns (if any)

• simulated_data - If return_data = TRUE, simulated datasets

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
z <- sample(c(0, 1), n, replace = TRUE)
y <- ifelse(z == 1, 0.8 * x + rnorm(sum(z), 0, 0.3), rnorm(n))
data <- data.frame(x = x, y = y, z = factor(z))

result <- dormancy_detect(data, method = "conditional")
awakening <- awaken(result, pattern_id = 1, n_sim = 50)
print(awakening)

Categorize risk level

Description

Categorize risk level

Usage

categorize_risk(risk_score, tolerance)

Compute cascade potential

Description

Compute cascade potential

Usage

compute_cascade_potential(pattern_idx, patterns, data)

Compute dormancy potential at a grid point

Description

Compute dormancy potential at a grid point

Usage

compute_dormancy_potential(x, y, x_center, y_center, method)

Compute energy-based depth

Description

Compute energy-based depth

Usage

compute_energy_depth(x, y, pattern, data)

Compute entropy-based depth

Description

Compute entropy-based depth

Usage

compute_entropy_depth(x, y, pattern, data)

Compute impact magnitude

Description

Compute impact magnitude

Usage

compute_impact_magnitude(x, y, pattern, data)

Compute local entropy

Description

Compute local entropy

Usage

compute_local_entropy(x, y)

Compute stability-based depth

Description

Compute stability-based depth

Usage

compute_stability_depth(x, y, pattern, data)

Create risk matrix

Description

Create risk matrix

Usage

create_risk_matrix(risk_scores)

Detect cascade-ready dormancy

Description

Detect cascade-ready dormancy

Usage

detect_cascade_dormancy(x, y, v1, v2, num_data, min_cluster, overall_cor)

Detect conditional dormancy

Description

Detect conditional dormancy

Usage

detect_conditional_dormancy(
  x,
  y,
  v1,
  v2,
  data,
  numeric_cols,
  n_bins,
  min_cluster,
  overall_cor
)

Detect phase-based dormancy

Description

Detect phase-based dormancy

Usage

detect_phase_dormancy(x, y, v1, v2, n_bins, min_cluster, overall_cor)

Detect self-conditional dormancy (when no other variables available)

Description

Detect self-conditional dormancy (when no other variables available)

Usage

detect_self_conditional(x, y, v1, v2, n_bins, min_cluster, overall_cor)

Detect threshold-based dormancy

Description

Detect threshold-based dormancy

Usage

detect_threshold_dormancy(x, y, v1, v2, n_bins, min_cluster, overall_cor)

Determine impact direction

Description

Determine impact direction

Usage

determine_impact_direction(x, y, pattern, data)

Determine the type of trigger

Description

Determine the type of trigger

Usage

determine_trigger_type(pattern, method)

Measure the Depth of Dormancy in Patterns

Description

Quantifies how "deeply asleep" a dormant pattern is - measuring the energy required to activate it and the stability of its dormant state. Deeper dormancy implies greater resistance to activation but potentially larger effects when awakened.

Usage

dormancy_depth(
  dormancy_result,
  method = "combined",
  normalize = TRUE,
  verbose = FALSE
)

Arguments

Details

Dormancy depth is a novel concept in statistical analysis, inspired by:

• Physics: Potential energy barriers in phase transitions

• Biology: Depth of seed dormancy (stratification requirements)

• Geology: Locked fault segments and earthquake potential

A deeply dormant pattern:

• Requires significant change in conditions to activate

• Is stable against minor perturbations

• May have a larger effect when finally awakened

• Represents accumulated "potential energy" in the system

The depth measurement helps prioritize which patterns to monitor and what magnitude of change would be required to awaken them.

Value

A list containing:

• depths - Data frame with depth measurements for each pattern

• depth_distribution - Summary statistics of depth distribution

• awakening_effort - Estimated effort required to activate each pattern

• stability_index - Stability measure for each pattern's dormant state

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
# Create a deeply dormant pattern (only active in extreme conditions)
z <- ifelse(abs(x) > 2, 1, 0)
y <- ifelse(z == 1, 0.9 * x + rnorm(sum(z), 0, 0.1), rnorm(n))
data <- data.frame(x = x, y = y)

result <- dormancy_detect(data, method = "threshold")
depths <- dormancy_depth(result)
print(depths)

Detect Dormant Patterns in Multivariate Data

Description

Identifies dormant patterns in multivariate data - statistical relationships that exist but are currently inactive. Dormant patterns only manifest when specific trigger conditions emerge in the data.

Usage

dormancy_detect(
  data,
  threshold = 0.3,
  method = "conditional",
  n_bins = 10,
  min_cluster = 0.05,
  parallel = FALSE,
  verbose = FALSE
)

Arguments

Details

Dormant patterns are fundamentally different from weak or spurious correlations. A dormant pattern is a genuine relationship that is currently suppressed by prevailing conditions in the data. The key insight is that:

1. The pattern exists (verified through subset analysis)

2. The pattern is currently inactive (not visible in aggregate statistics)

3. The pattern can "awaken" when conditions change

The detection algorithm works by:

1. Segmenting the data space into regions

2. Computing pairwise relationships in each region

3. Identifying relationships that vary significantly across regions

4. Flagging relationships that are strong in some regions but weak overall

5. Estimating the conditions under which dormant patterns would activate

Value

A list of class "dormancy" containing:

• patterns - A data frame of detected dormant patterns with columns: variables, dormancy_score, trigger_variable, trigger_region, activation_risk

• data - The input data

• method - The detection method used

• threshold - The threshold used

• conditional_regions - List of regions where patterns are dormant

• metadata - Additional information about the detection process

See Also

dormancy_trigger for identifying activation triggers, dormancy_depth for measuring dormancy depth, awaken for simulating pattern activation

Examples

# Create data with a dormant pattern
set.seed(42)
n <- 1000
x <- rnorm(n)
z <- sample(c(0, 1), n, replace = TRUE)
# Relationship between x and y only exists when z == 1
y <- ifelse(z == 1, 0.8 * x + rnorm(n, 0, 0.3), rnorm(n))
data <- data.frame(x = x, y = y, z = factor(z))

# Detect dormant patterns
result <- dormancy_detect(data, method = "conditional")
print(result)

Assess Risk of Dormant Pattern Activation

Description

Quantifies the risk associated with dormant patterns, including the probability of activation, potential impact, and uncertainty in risk estimates. This function provides actionable risk metrics for decision-making and monitoring priorities.

Usage

dormancy_risk(
  dormancy_result,
  depth_result = NULL,
  impact_weights = NULL,
  time_horizon = 1,
  risk_tolerance = 0.3,
  verbose = FALSE
)

Arguments

Details

Risk assessment for dormant patterns considers multiple dimensions:

• Activation Probability: Likelihood that trigger conditions will be met in the given time horizon

• Impact Magnitude: Expected effect size if the pattern activates

• Impact Direction: Whether activation would be beneficial, harmful, or neutral

• Cascade Potential: Risk of triggering other patterns

• Uncertainty: Confidence in risk estimates

The risk score combines these dimensions into an actionable metric:

Risk = P(activation) \times Impact \times CascadeFactor \times (1 + Uncertainty)

Value

A list containing:

• risk_scores - Data frame with risk metrics for each pattern

• risk_matrix - Matrix of activation probability x impact

• priorities - Ordered list of patterns by risk priority

• recommendations - Risk management recommendations

• summary - Overall risk summary statistics

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
z <- sample(c(0, 1), n, replace = TRUE)
y <- ifelse(z == 1, 0.8 * x + rnorm(sum(z), 0, 0.3), rnorm(n))
data <- data.frame(x = x, y = y, z = factor(z))

result <- dormancy_detect(data, method = "conditional")
risk <- dormancy_risk(result, time_horizon = 2)
print(risk)

Scout for Dormant Pattern Regions in Data

Description

Systematically scans the data space to identify regions where dormant patterns might emerge. Unlike dormancy_detect which identifies specific patterns, dormancy_scout maps the "terrain" of dormancy potential.

Usage

dormancy_scout(
  data,
  grid_resolution = 20,
  scout_method = "density",
  return_map = TRUE,
  verbose = FALSE
)

Arguments

Details

Scout analysis is useful for:

• Identifying regions to monitor for future pattern emergence

• Understanding the "geography" of your data's pattern space

• Finding data regions that are underexplored or anomalous

• Planning targeted data collection in high-potential regions

The scout creates a map of "dormancy potential" - not actual patterns, but locations where patterns are more likely to exist or emerge.

Value

A list containing:

• scout_results - Data frame with coordinates and dormancy potential

• hotspots - Regions with highest dormancy potential

• dormancy_map - If return_map = TRUE, a matrix representing the dormancy landscape

• summary - Summary statistics of the scan

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
y <- rnorm(n)
# Create a region with hidden pattern
z <- ifelse(x > 1 & y > 1, 0.9 * x + rnorm(sum(x > 1 & y > 1), 0, 0.1), y)
data <- data.frame(x = x, y = z)

scout <- dormancy_scout(data, grid_resolution = 15)
print(scout)

Identify Trigger Conditions for Dormant Patterns

Description

Analyzes detected dormant patterns to identify the specific conditions under which they would activate. This function goes beyond detection to characterize the precise trigger mechanisms and their sensitivity.

Usage

dormancy_trigger(
  dormancy_result,
  sensitivity = 0.5,
  n_bootstrap = 100,
  verbose = FALSE
)

Arguments

Details

Trigger identification is crucial for risk management and early warning systems. A dormant pattern might be triggered by:

• Threshold triggers: When a variable crosses a specific value

• Region triggers: When observations fall within specific data regions

• Categorical triggers: When a categorical condition is met

• Compound triggers: When multiple conditions align

• Temporal triggers: When time-dependent patterns emerge

The function uses bootstrap resampling to provide confidence intervals around trigger estimates, ensuring robust identification even with limited data.

Value

A list containing:

• triggers - A data frame with trigger details: pattern_id, trigger_variable, trigger_type, threshold_value, sensitivity_score, confidence_lower, confidence_upper

• trigger_map - A matrix showing trigger relationships

• recommendations - Character vector of actionable insights

See Also

dormancy_detect, dormancy_risk

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
z <- sample(c(0, 1), n, replace = TRUE)
y <- ifelse(z == 1, 0.8 * x + rnorm(n, 0, 0.3), rnorm(n))
data <- data.frame(x = x, y = y, z = factor(z))

result <- dormancy_detect(data, method = "conditional")
triggers <- dormancy_trigger(result)
print(triggers)

Fast Conditional Correlation

Description

Compute correlation conditioned on a third variable being in a range.

Usage

fast_conditional_cor(x, y, z, z_min, z_max)

Arguments

Value

Correlation coefficient

Fast 2D Entropy

Description

Compute entropy of a 2D binned distribution.

Usage

fast_entropy_2d(x, y, n_bins)

Arguments

Value

Normalized entropy value

Fast Mutual Information

Description

Estimate mutual information between two variables.

Usage

fast_mutual_info(x, y, n_bins)

Arguments

Value

Mutual information estimate

Fast Rolling Correlation

Description

Compute rolling correlation between two vectors efficiently.

Usage

fast_rolling_cor(x, y, window_size)

Arguments

Value

Numeric vector of rolling correlations

Fast Threshold Detection

Description

Find optimal threshold where correlation changes most.

Usage

fast_threshold_detect(x, y, n_thresholds)

Arguments

Value

List with threshold value and correlation difference

Generate risk recommendations

Description

Generate risk recommendations

Usage

generate_risk_recommendations(risk_scores, tolerance)

Generate actionable recommendations from trigger analysis

Description

Generate actionable recommendations from trigger analysis

Usage

generate_trigger_recommendations(triggers_df, sensitivity)

Identify Patterns That Have Become Dormant Over Time

Description

Analyzes time series or sequential data to identify patterns that were once active but have become dormant. This is the inverse problem from dormancy_detect - finding patterns that "went to sleep" rather than patterns that are currently dormant.

Usage

hibernate(
  data,
  time_var = NULL,
  window_size = 0.2,
  threshold = 0.3,
  min_observations = 30,
  verbose = FALSE
)

Arguments

Details

Hibernation detection is important for:

• Understanding system evolution and regime changes

• Identifying lost relationships that might return

• Detecting structural breaks in relationships

• Monitoring degradation of system components

A pattern is considered to have "hibernated" if:

1. It was strong in an earlier time window

2. It has weakened significantly in recent windows

3. The weakening is not due to noise or reduced sample size

Value

A list containing:

• hibernated_patterns - Patterns that have become dormant

• timeline - When patterns transitioned to dormancy

• hibernation_depth - How deeply patterns have hibernated

• revival_potential - Likelihood patterns could reawaken

Examples

set.seed(42)
n <- 500
time <- 1:n
x <- rnorm(n)
# Relationship that fades over time
effect_strength <- exp(-time / 200)
y <- effect_strength * 0.8 * x + (1 - effect_strength) * rnorm(n)
data <- data.frame(time = time, x = x, y = y)

hib <- hibernate(data, time_var = "time", window_size = 0.15)
print(hib)

Plot Methods for Dormancy Objects

Description

Visualization methods for dormancy analysis results. Creates informative plots showing dormant patterns, trigger regions, and risk landscapes.

Usage

## S3 method for class 'dormancy'
plot(x, type = "overview", ...)

## S3 method for class 'dormancy_map'
plot(x, type = "overview", ...)

Arguments

Value

Invisibly returns the plot data.

Examples

set.seed(42)
n <- 500
x <- rnorm(n)
z <- sample(c(0, 1), n, replace = TRUE)
y <- ifelse(z == 1, 0.8 * x + rnorm(sum(z), 0, 0.3), rnorm(n))
data <- data.frame(x = x, y = y, z = factor(z))

result <- dormancy_detect(data, method = "conditional")
plot(result)

Plot dormancy overview

Description

Plot dormancy overview

Usage

plot_dormancy_overview(x, ...)

Plot dormancy patterns

Description

Plot dormancy patterns

Usage

plot_dormancy_patterns(x, ...)

Plot dormancy risk

Description

Plot dormancy risk

Usage

plot_dormancy_risk(x, ...)

Plot dormancy timeline

Description

Plot dormancy timeline

Usage

plot_dormancy_timeline(x, ...)