markov-null-design

Scaffolds Markov null model permutation tests for trajectory TDA pipelines.

1|Updated Dec 13, 2025
One-click install
npx skills add https://github.com/ZK-Theory/TDL --skill markov-null-design-zk-theory
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: markov-null-design
Source: https://github.com/ZK-Theory/TDL/tree/main/.agents/skills/markov-null-design
Command: npx skills add https://github.com/ZK-Theory/TDL --skill markov-null-design-zk-theory

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Designing a correctly-specified Markov null model for topological data analysis is error-prone: researchers omit the Markov order, under-power permutation counts, or choose statistics that are invariant under the null, invalidating p-values. This Skill enforces the P01-B mandate that Markov order k is always explicit and generates a complete, correctly-parameterized permutation test scaffold. ## Core Features & Use Cases - Null Model Scaffolding: Generates the full permutation_test_trajectories call with explicit markov_order, statistic, permutation count, landmarks, and seed parameters. - Memory Ladder Guidance: Maps the five-rung null hierarchy (label_shuffle, order_shuffle, markov k=1, markov k=2, stratified_markov1) so batteries include proper negative controls. - Design Error Detection: Flags common mistakes such as missing markov_order, under-powered permutation counts, landmark reuse, and statistics centered on the null's sufficient statistic. - Use Case: A researcher testing whether trajectory topology exceeds second-order Markov prediction runs /markov-null-design markov 2 to get the complete function call, results file naming convention, and Computational-Log logging stub. ## Quick Start Ask the assistant to scaffold a Markov-2 null model permutation test for your trajectory TDA pipeline with explicit seed and permutation count.

Frequently Asked Questions about markov-null-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a Markov null model permutation test for trajectory TDA?

Call permutation_test_trajectories with null_type="markov", an explicit markov_order, your embeddings and trajectories, a statistic such as total_persistence, and at least 200 permutations. Always record the seed for the Computational-Log before running.

What Markov order should I use for a permutation null model?

The memory ladder defines rungs: Markov-1 tests whether topology exceeds first-order prediction, and Markov-2 tests second-order. Minimum batteries include label_shuffle and order_shuffle as negative controls; publication quality requires rungs 0 through 3.

How many permutations are needed for a publication-quality null test?

Use at least 200 permutations for publication results, and 500 or more when the statistic is Wasserstein distance. Development runs can use 100 permutations with 2000 landmarks, scaling to 5000 landmarks for publication.

Why does my Markov null test return p-values near 0.5?

This happens when the statistic is a function of the same sufficient statistic the null is fit from, such as a transition-count-matrix feature tested against a Markov-1 null. The null is centered on the observed statistic by construction; add a lower rung or use a richer statistic.

When should I use stratified_markov1 instead of a standard Markov null?

Use stratified_markov1 when testing whether within-regime topology exceeds regime-level Markov-1 prediction. It requires metadata containing regime_labels and raises a ValueError if they are missing.