[SHA Metrics] Extend silence metrics for structural preservation analysis #2820
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
❌ Deploy Preview for stunning-zabaione-f1f1ef failed. Why did it fail? →
|
…e tests Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>
…ases Co-authored-by: fermga <203334638+fermga@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Add extended SHA preservation metrics
[SHA Metrics] Extend silence metrics for structural preservation analysis
Nov 8, 2025
There was a problem hiding this comment.
Pull Request Overview
This PR adds extended metrics functionality to the SHA (Silence) operator to enable deep analysis of structural preservation effectiveness. The enhancements provide insights into EPI stability, preservation quality, reactivation readiness, and collapse risk prediction.
Key Changes
- Four new helper functions to compute extended silence metrics (EPI variance, preservation integrity, reactivation readiness, time-to-collapse)
- Enhanced
silence_metrics()function to include extended metrics alongside core metrics - Comprehensive test suite covering all helper functions and integration scenarios
- Demo file showcasing real-world use cases (biomedical, cognitive, social domains)
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/tnfr/operators/metrics.py |
Added four private helper functions and updated silence_metrics() to compute and return extended metrics for deeper preservation analysis |
tests/unit/operators/test_sha_extended_metrics.py |
Comprehensive test suite with unit tests for each helper function, integration tests for the extended metrics, and domain-specific use case tests |
examples/sha_extended_metrics_demo.py |
Interactive demo showcasing extended SHA metrics across biomedical (sleep consolidation), cognitive (memory consolidation), social (conflict pause), and failure detection scenarios |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+1030
to
+1033
| _compute_epi_variance : EPI variance computation | ||
| _compute_preservation_integrity : Preservation quality metric | ||
| _compute_reactivation_readiness : Reactivation readiness score | ||
| _estimate_time_to_collapse : Collapse time estimation |
There was a problem hiding this comment.
The docstring references private helper functions in the "See Also" section. Since these functions are private (prefixed with _), they should not be part of the public API documentation.
If these functions are meant to remain private implementation details, remove them from the "See Also" section. If they should be part of the public API, remove the _ prefix and add them to __all__.
Suggested change
| _compute_epi_variance : EPI variance computation | |
| _compute_preservation_integrity : Preservation quality metric | |
| _compute_reactivation_readiness : Reactivation readiness score | |
| _estimate_time_to_collapse : Collapse time estimation |
| "preservation_integrity": ( | ||
| _compute_preservation_integrity(preserved_epi, epi_after) | ||
| if preserved_epi is not None | ||
| else 1.0 - abs(epi_after - epi_before) |
There was a problem hiding this comment.
The fallback calculation for preservation_integrity when preserved_epi is None uses 1.0 - abs(epi_after - epi_before), which can produce negative values if the absolute difference is greater than 1.0. This differs from the behavior of _compute_preservation_integrity() which clamps negative values to 0.0.
For consistency, this should be:
max(0.0, 1.0 - abs(epi_after - epi_before))This ensures the metric always stays in the [0, 1] range as documented.
Suggested change
| else 1.0 - abs(epi_after - epi_before) | |
| else max(0.0, 1.0 - abs(epi_after - epi_before)) |
Comment on lines
+20
to
+65
| _compute_epi_variance, | ||
| _compute_preservation_integrity, | ||
| _compute_reactivation_readiness, | ||
| _estimate_time_to_collapse, | ||
| ) | ||
| from tnfr.alias import set_attr | ||
| from tnfr.constants.aliases import ALIAS_VF, ALIAS_EPI | ||
|
|
||
|
|
||
| class TestComputeEPIVariance: | ||
| """Test _compute_epi_variance helper function.""" | ||
|
|
||
| def test_no_history_returns_zero(self): | ||
| """Empty history should return 0.0 variance.""" | ||
| G, node = create_nfr("test", epi=0.5, vf=1.0) | ||
| # No epi_history_during_silence attribute | ||
| variance = _compute_epi_variance(G, node) | ||
| assert variance == 0.0 | ||
|
|
||
| def test_single_value_returns_zero(self): | ||
| """Single value in history should return 0.0 variance.""" | ||
| G, node = create_nfr("test", epi=0.5, vf=1.0) | ||
| G.nodes[node]["epi_history_during_silence"] = [0.5] | ||
| variance = _compute_epi_variance(G, node) | ||
| assert variance == 0.0 | ||
|
|
||
| def test_constant_values_returns_zero(self): | ||
| """Constant values should return 0.0 variance.""" | ||
| G, node = create_nfr("test", epi=0.5, vf=1.0) | ||
| G.nodes[node]["epi_history_during_silence"] = [0.5, 0.5, 0.5, 0.5] | ||
| variance = _compute_epi_variance(G, node) | ||
| assert variance == pytest.approx(0.0, abs=1e-10) | ||
|
|
||
| def test_varying_values_returns_positive_variance(self): | ||
| """Varying values should return positive variance.""" | ||
| G, node = create_nfr("test", epi=0.5, vf=1.0) | ||
| G.nodes[node]["epi_history_during_silence"] = [0.5, 0.6, 0.4, 0.55] | ||
| variance = _compute_epi_variance(G, node) | ||
| assert variance > 0.0 | ||
| # Verify it's reasonable (should be around 0.07 for these values) | ||
| assert 0.05 < variance < 0.1 | ||
|
|
||
|
|
||
| class TestComputePreservationIntegrity: | ||
| """Test _compute_preservation_integrity helper function.""" | ||
|
|
There was a problem hiding this comment.
The test file imports private helper functions (prefixed with _) that are not exported in the __all__ list of src/tnfr/operators/metrics.py. This violates API design principles as private functions should not be part of the public API and should not be directly tested by importing them.
Consider either:
- Making these functions public by removing the
_prefix and adding them to__all__, OR - Testing them indirectly through
silence_metrics()which uses these functions internally
If these are intended to be internal implementation details, they should only be tested through the public API.
Suggested change
| _compute_epi_variance, | |
| _compute_preservation_integrity, | |
| _compute_reactivation_readiness, | |
| _estimate_time_to_collapse, | |
| ) | |
| from tnfr.alias import set_attr | |
| from tnfr.constants.aliases import ALIAS_VF, ALIAS_EPI | |
| class TestComputeEPIVariance: | |
| """Test _compute_epi_variance helper function.""" | |
| def test_no_history_returns_zero(self): | |
| """Empty history should return 0.0 variance.""" | |
| G, node = create_nfr("test", epi=0.5, vf=1.0) | |
| # No epi_history_during_silence attribute | |
| variance = _compute_epi_variance(G, node) | |
| assert variance == 0.0 | |
| def test_single_value_returns_zero(self): | |
| """Single value in history should return 0.0 variance.""" | |
| G, node = create_nfr("test", epi=0.5, vf=1.0) | |
| G.nodes[node]["epi_history_during_silence"] = [0.5] | |
| variance = _compute_epi_variance(G, node) | |
| assert variance == 0.0 | |
| def test_constant_values_returns_zero(self): | |
| """Constant values should return 0.0 variance.""" | |
| G, node = create_nfr("test", epi=0.5, vf=1.0) | |
| G.nodes[node]["epi_history_during_silence"] = [0.5, 0.5, 0.5, 0.5] | |
| variance = _compute_epi_variance(G, node) | |
| assert variance == pytest.approx(0.0, abs=1e-10) | |
| def test_varying_values_returns_positive_variance(self): | |
| """Varying values should return positive variance.""" | |
| G, node = create_nfr("test", epi=0.5, vf=1.0) | |
| G.nodes[node]["epi_history_during_silence"] = [0.5, 0.6, 0.4, 0.55] | |
| variance = _compute_epi_variance(G, node) | |
| assert variance > 0.0 | |
| # Verify it's reasonable (should be around 0.07 for these values) | |
| assert 0.05 < variance < 0.1 | |
| class TestComputePreservationIntegrity: | |
| """Test _compute_preservation_integrity helper function.""" | |
| ) | |
| from tnfr.alias import set_attr | |
| from tnfr.constants.aliases import ALIAS_VF, ALIAS_EPI |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request: Extend SHA Metrics for Preservation Analysis
🎯 Intent
Enable quantitative assessment of structural preservation effectiveness during silence states. Adds deep telemetry for detection of degradation, reactivation timing, and collapse prediction across biomedical, cognitive, and social domains.
🔧 Changes
Type of Change:
Implementation:
Added 4 helper functions to
operators/metrics.py:_compute_epi_variance()- σ(EPI) during silence (0.0 = perfect stability)_compute_preservation_integrity()- Quality ratio [0,1] where <0.8 = failure_compute_reactivation_readiness()- Multi-factor score: νf, EPI, duration, network support_estimate_time_to_collapse()- Based onepi_drift_rate; returns ∞ if stableExtended
silence_metrics()return dict with 4 new fields while preserving all existing behavior.Example Usage:
🔬 Structural Impact
Operators Involved:
SHA (Silence)
Affected Invariants:
None violated. Extension only - adds telemetry without modifying operator semantics.
Metrics Impact:
✅ Quality Checklist
Code Quality:
.pyistub files generated/updatedTNFR Canonical Requirements:
Testing:
Documentation:
docs/changelog.d/)Security (if applicable):
make security-audit)🧪 Testing Evidence
Test Coverage:
Health Metrics (if applicable):
🔗 Related Issues
Closes #2714 (depends on latency state management - preserved_epi, silence_duration attributes)
📋 Additional Context
Design Decisions:
_(internal use, not exported in__all__)time_to_collapsereturnsfloat('inf')when no drift detected (notNone)preservation_integrityuses absolute value for preserved_epi to handle sign changesCross-Domain Applicability:
🎨 Visual Changes (if applicable)
N/A - Metrics only, no visualization changes
Reviewer Notes
Implementation is additive only. Zero breaking changes. All existing SHA behavior preserved. New metrics are optional - code using old metrics continues to work unchanged.
Original prompt
This section details on the original issue you should resolve
<issue_title>[SHA Metrics] Ampliar métricas de preservación estructural</issue_title>
<issue_description>## Contexto
Las métricas actuales de SHA en
metrics.pyson correctas pero básicas. Para análisis profundos de efectividad de preservación, se propone ampliarlas con tracking temporal, varianza e integridad estructural.Métricas Actuales (Funcionales)
Métricas Extendidas Propuestas
1. Duración de Silencio (
silence_duration)Definición: Tiempo total en estado latente (en steps o tiempo estructural)
Utilidad:
Implementación:
2. Varianza de EPI Durante Silencio (
epi_variance)Definición: Desviación estándar de EPI durante periodo de silencio
Utilidad:
Implementación:
3. Integridad de Preservación (
preservation_integrity)Definición: Ratio de cambio estructural relativo
[
\text{integrity} = 1 - \frac{|\text{EPI}{\text{after}} - \text{EPI}{\text{preserved}}|}{\text{EPI}_{\text{preserved}}}
]
Interpretación:
integrity = 1.0: Preservación perfectaintegrity < 0.95: Degradación significativaintegrity < 0.8: Fallo de preservaciónImplementación:
4. Capacidad de Reactivación (
reactivation_readiness)Definición: Score que evalúa si el nodo puede reactivarse efectivamente
Factores:
Implementación:
5. Tiempo Hasta Colapso (
time_to_collapse)Definición: Estimación de cuánto tiempo puede mantenerse el silencio antes de colapso nodal
Modelo:
[
t_{\text{collapse}} \approx \frac{\text{EPI}_{\text{preserved}}}{|\text{DRIFT_RATE}|}
]
Donde DRIFT_RATE es la tasa de degradación estructural observada.
Actualización Completa de
silence_metrics