Manual
How to use IRDME — concepts, methodology, tool guide, and site map. No prior knowledge of graph theory required.
Start here — which tool to use?
IRDME has five interconnected tools. Here is when to use each:
Use when: You have a graph and want a quick one-shot result right now.
Paste or upload a JSON graph. Get hub rankings, r values, archetypes, verdicts. No account needed. Result is not saved permanently.
Example: I want to see which protein is most central in my 12-node network.
Use when: You want to save a graph and reuse it across multiple analyses.
A named, versioned graph stored in your account. Any Investigation or Calculator run can load a dataset. Public datasets are shared with the community.
Example: I have a brain region connectivity graph I will run many experiments on.
Use when: You want to review past Calculator results.
Auto-saved snapshots of each Calculator run when you are logged in. Not a separate action — Experiments are created automatically. Think of it as your analysis history.
Example: I ran the Calculator three times last week and want to compare the r values.
Use when: You want a multi-step, chained analysis that builds on itself.
Step 1: run analysis on a dataset. Step 2: automatically derive a subgraph from the top hubs or most divergent nodes. Step 3: run again. Each step is saved. A Jaccard novelty guardrail blocks redundant steps (≥70 % hub overlap). Best for iterative scientific discovery.
Example: I want to analyse the full consciousness network, then zoom into the top 5 hubs, then analyse that subgraph.
Use when: You want to organise the ‘why’ behind your analyses — questions, hypotheses, goals.
A structured notebook of Questions, Hypotheses, Problems, Projects, Interpretations, and Goals. Nest them, share them, fork others’. Attach an Investigation to a Hypothesis to connect the idea to the evidence. This is where thinking lives; Investigations are where analysis runs.
Example: “Is consciousness a structural network property?” is a Question. Attach a Hypothesis under it. Attach an Investigation to the Hypothesis. The result is an auditable trail from idea to finding.
Use when: You want to find the true critical path in a project plan — beyond the Gantt chart.
Model your project as two layers: Gantt (schedule dependencies) and Risk (failure propagation). IRDME returns universal hubs (critical in both), hub shadows (high Gantt rank but low Risk rank — schedule illusions), and the law correlation r(Gantt ↔ Risk). Paste any JSON graph or use the Mars Mission example.
Example: I want to know which tasks in our product launch are structural risks, not just on the critical path.
Use when: You want to merge two existing datasets into a unified multilayer graph.
Select two datasets (A and B), name the inter-system layer, optionally provide cross-system edges, set per-dataset ID prefixes to avoid conflicts, and compose. The result is a new dataset with all nodes from A and B plus the inter-layer. Use it as input for any investigation or calculator run.
Example: I want to merge a protein interaction network and a gene expression network to see which proteins bridge both layers.
The typical flow for a new investigation:
- Create a Question in Research → create one now
- Add a Hypothesis as a child of that question
- Upload your graph as a Dataset → Datasets
- Create an Investigation and attach it to the Hypothesis → Investigations
- Run steps. The Calculator is available any time for quick one-off checks.
What is IRDME
IRDME is a structural analysis engine. You describe a system as a set of items (proteins, modules, companies, neurons, concepts — anything) connected by typed relations (imports, activates, co-occurs, reports-to). Relations of the same type form a layer. Most real systems have multiple layers — software has an import graph, a test coverage graph, and a co-change graph, all on the same set of modules.
IRDME answers: which items matter most, and do the different layers of your system agree on that? When layers agree, the important items are robustly central. When they disagree, you have discovered a structural anomaly — a hub shadow, a chameleon, a relay node.
What IRDME does not do:
- It does not read domain content — it reads graph structure only.
- It does not tell you why an item is central — it tells you that it is.
- It does not guarantee results are correct on small or malformed graphs.
- It does not replace domain expertise.
The three canonical layers (d1 / d2 / d3)
Every complex system — regardless of domain — decomposes into three kinds of coupling. IRDME calls these d1, d2, and d3:
What the system explicitly says it connects to. The contract. The architecture as written.
Inferred from shared structure — co-membership, shared dependencies, physical proximity.
What actually co-moves, co-activates, or co-changes — regardless of declared architecture.
The Functional Proximity Law states that r(d1 ↔ d2) > r(d1 ↔ d3) — confirmed 25x across 31 pre-registered experiments. Your layers do not need to be named d1/d2/d3; IRDME detects the pattern from any typed relation graph.
Node archetypes
After analysis, each item receives a structural role label based on how its hub rank compares across layers:
Consistently top-ranked across all layers. The load-bearing item.
Examples: TP53 (protein network) · build + client (Next.js) · mm (Linux kernel)
Action: Protect and optimize. This item is structurally load-bearing.
High behavioral rank (d3) but low declared rank (d1). Hidden risk — the system is more dependent on this item than its architecture admits.
Examples: post.php: co_change #4 but include_graph #19 (WordPress)
Action: Audit first. If in a codebase, split or document this coupling explicitly.
High rank in one layer, low in another. Structurally inconsistent — different measurement regimes see it differently.
Examples: AIG: equity/derivatives hub, mid-tier in credit · LLaMA: benchmark #1, citation #16
Action: Investigate why layers disagree. Often a sign of regime mismatch or intentional isolation.
Mid-rank across all layers. Structurally stable connector — not a hub, not peripheral.
Examples: server_app_render (Next.js App Router) — clean architecture produces relay nodes, not hub shadows
Action: Healthy architecture produces many relay nodes. If none exist, check for over-centralization.
Low rank across all layers. Structurally isolated.
Examples: Leaf nodes with single-layer low-degree connections
Action: May be candidates for pruning, or intentionally isolated (safe).
The Functional Proximity Law
The core finding: hub importance scores persist more strongly between layers that encode functionally similar relationships (e.g., structural coupling and declared coupling) than between layers that encode different ones (e.g., declared coupling and behavioral co-change).
The r value is the Pearson correlation between hub importance rank vectors across two layers. A high positive r means the same items are hubs in both layers. A negative r means the layers have inverted hub sets — items important in one layer are peripheral in the other.
See the full evidence table with 16 domains on the Paper page.
How to read results
CONFIRMED / DENIED / PARTIAL
These verdicts apply to pre-registered hypotheses only. CONFIRMED means the data matched the prediction. DENIED means it did not — and the reason why is the finding. PARTIAL means some conditions were met.
r value
Pearson correlation between hub rank vectors across two layers. Ranges from −1 (complete inversion) to +1 (perfect agreement). Values near 0 on a small graph may not be meaningful — check the p-value.
p-value
Permutation p-value from the null model. p < 0.05 means the correlation is unlikely to occur by chance. On graphs with n < 10 nodes, significance is hard to achieve — treat these results as exploratory.
Effect size
Cohen scale: negligible (<0.1), small (0.1–0.3), medium (0.3–0.5), large (≥0.5). Prefer large effect + p < 0.05 for any conclusion. A statistically significant small effect is not a strong finding.
Recommended workflow
- 1
Define your graph
List your items and the typed relations between them. You need at least 2 relation types (2 layers) and at least 8–10 items for meaningful results. Use the Calculator's YAML format or upload a JSON file.
Open Calculator → - 2
Run the law analysis
IRDME computes hub importance scores per layer and cross-layer r values. The law analysis tells you which layer pairs agree (high r) and which diverge (low/negative r).
- 3
Inspect the atlas
The structural role atlas assigns each item an archetype: universal hub, hub shadow, chameleon, relay, or peripheral. Hub shadows and chameleons are the highest-value findings.
- 4
Validate with the null model
Run a permutation test to confirm the pattern is not random. A law gradient with p > 0.05 is not significant. Compare against a random graph baseline.
- 5
Form a hypothesis and pre-register
If you find something interesting, pre-register a specific, falsifiable prediction before analyzing further. This keeps the finding credible.
- 6
Chain into an Investigation (optional)
Use the Investigations feature to build a multi-step analysis sequence. Each step derives its input from the previous result. A Jaccard novelty guardrail (≥ 70 % hub overlap → blocked) prevents circular analysis. Public investigations let other users contribute the next step.
Open Investigations →
Cross-domain transfer (role-vector comparison)
Once you have run IRDME on two different systems, you can ask: do the structural roles transfer?Which node in system B plays the same structural role as a given hub in system A? This is the cross-domain transfer method, introduced in F12b.
Every node in a multilayer graph has a role vector: its degree in each layer, in sorted layer order. Two nodes (even in different graphs, different domains, different sizes) are structurally analogous if their role vectors have high cosine similarity. PVCL in C. elegans (high in both chemical_synapse and gap_junction) is analogous to any Drosophila neuron that is also high in both its layers.
- Compare two organisms (C. elegans vs Drosophila — F12c experiment)
- Compare the same codebase at two points in time (hub drift across versions)
- Compare two independent datasets of the same system (multi-source trust check)
- Seed a synthetic graph from a real one (generative compression, F12b)
Metrics
avg_seed_cosineAverage cosine similarity between the top-N hubs in graph A and their best role-analogue in graph B. In F12b (C. elegans within-species reconstruction): 0.845. In F12c (cross-species target): threshold is 0.65.
rank_vector_cosineCosine similarity between the sorted degree distributions (per layer). Measures whether the hub distribution shape is conserved, independently of individual node identity. Requires matching layer names.
avg_rank_cosineAverage rank_vector_cosine across all matched layer pairs. The primary F12c confirmatory metric (threshold 0.65). Not sensitive to shared node IDs — works across species.
role_analogues listReturned by /transfer. For each top hub in graph A: its best structural match in graph B by cosine similarity. Labels, degrees, and similarity scores included.
API endpoint
{
"graph_a": { ...graph_object... },
"graph_b": { ...graph_object... },
"label_a": "C. elegans (F12)",
"label_b": "Drosophila larva (F13)",
"top_n": 15
}{
"role_analogues": [
{ "hub_a": "pvcl", "label_a": "PVCL",
"analogue_b": "11543212", "label_b": "11543212",
"cosine_similarity": 0.8710 },
...
],
"avg_seed_cosine": 0.7432,
"rank_vector_similarity": { "axon_to_dendrite": 0.812 },
"avg_rank_cosine": 0.756
}avg_seed_cosine reflects cross-graph cosine nearest-neighbour matching (padded role vectors), not same-node comparison. avg_rank_cosine requires matching layer names between the two graphs. Map layers explicitly before calling /transfer if the two graphs use different naming conventions.Research objects (the simple guide)
Imagine you have a notebook where you write down questions you want to answer. Each question can grow into more questions, ideas, and plans. That is what Research objects are — a structured notebook that lives on irdme.com.
Something you want to find out.
“Do proteins that talk a lot to each other also tend to break together?”
Your best guess — stated in a way that can be proven wrong.
“Hub proteins in the physical-binding layer will also be hubs in the co-expression layer (r > 0.5).”
A challenge you need to solve before you can answer the question.
“The STRING dataset has 15 000 proteins — I need to reduce it to the 30 most studied ones.”
A folder that holds related questions, hypotheses, and problems.
“Protein hub study — p53 network, May 2026”
What you think a result means — in plain words.
“The thalamus is structurally equivalent to TNF-α in the cytokine network — both are broadcast hubs that coordinate everything else.”
The destination you are trying to reach.
“Produce a pre-registered, peer-reviewable finding about structural risk in the 2026 financial network.”
How they connect
Any object can be a child of any other. A Question can have three Hypotheses under it. A Hypothesis can have a Problem under it. A Project can hold everything. There is no limit to how deep you can nest — the tree grows as your thinking grows.
Project: Protein hub study
Question: Do binding hubs = expression hubs?
Hypothesis: r(binding, co_expression) > 0.5
Problem: Filter STRING to 30 proteins
Interpretation: TP53 is a universal hub in all layers
Goal: Submit to PLOS Computational Biology
Visibility — who can see it?
Private
Only you can see it. Good for rough ideas.
Shared
Anyone with the link can see it. Good for collaborating with a specific person.
Public
Anyone on irdme.com can discover, read, and fork it.
Forking — build on someone else’s idea
If you see a public Question or Hypothesis that interests you, click Fork. IRDME copies it into your workspace as a private object. It keeps the original author’s name as attribution. You can now change it, add children to it, and attach your own Investigation — without affecting the original.
AI suggestions
On any object detail page, click Get AI suggestions. IRDME will suggest 3 structural next steps based on the object type — for example, a Hypothesis will suggest: attach an Investigation, add an alternative Hypothesis, or write an Interpretation of the result. You do not have to follow them.
Attaching an Investigation
An Investigation is the analysis engine — it runs IRDME step by step, checks novelty between steps, and converges when the structural signal flattens. Any Research object can have an Investigation attached to it. This is how an idea turns into evidence.
Start at Research feed → or create your first object at /research/new →
Project Risk Topology
The /project-risk tool takes a project plan modelled as a multilayer graph and identifies tasks that are structurally critical beyond what the schedule alone reveals.
Two required layers
- Gantt — schedule dependencies between tasks (edges = "must finish before")
- Risk — failure propagation paths (edges = "failure of A causes failure of B")
What the output means
- Universal hubs — high rank in both layers; true critical path items
- Hub shadows — high Gantt rank, low Risk rank (or vice versa); schedule illusions or hidden risks
- r(Gantt ↔ Risk) — WEAK means the two views of the project diverge significantly; that divergence is the finding
Use the Mars Mission example to explore a pre-built dataset, or paste your own JSON graph. Open Project Risk →
Compose Datasets
The /datasets/compose tool merges two existing datasets into a single multilayer graph with an optional inter-system layer connecting nodes from both sources.
When to use it
- Combining two protein networks from different databases
- Merging a codebase import graph with a runtime dependency graph
- Linking a social network with a co-authorship graph via shared edges
Node ID conflicts
If datasets A and B share node IDs, the compose endpoint returns a 422 with the conflicting IDs. Set prefixA and/or prefixB to namespace the nodes (e.g. prefixA="string_").
Inter-system layer
The optional interLayerName and interEdgesfields let you add cross-system edges — e.g. "gene_to_protein" bridging a gene regulation network and a protein interaction network. These edges form a third layer in the output dataset.
The composed dataset can immediately be loaded into Calculator, Investigations, or any API endpoint. Open Compose Datasets →
Site map
Upload or paste a graph. Run the full IRDME analysis: law, atlas, hub rankings, verdicts.
Browse example graphs across 19 domains. Load any dataset directly into the Calculator.
Your analysis history. Results saved per user. Requires login.
Chained analysis sequences. Run step N, derive a subgraph (top hubs / divergent nodes / custom), run step N+1. Convergence is tracked with a Jaccard novelty guardrail — if the hub sets between steps overlap ≥ 70 %, the step is blocked as redundant before it runs. Public investigations allow collaborative research.
Create questions, hypotheses, problems, projects, interpretations, and goals. Nest them, share them, fork others’, and get AI suggestions for what to do next.
Compare two datasets from independent sources. Returns trusted nodes (hub in both), boundary nodes (hub in one source only), Functional Proximity Law for each source, and a SHA-256 integrity certificate. Use when you have two datasets covering the same system.
Merge two datasets into a unified multilayer graph with a named inter-system layer. Resolve node-ID conflicts with per-dataset prefixes. The result is a new dataset ready for any analysis. Use when combining systems from different sources.
Model a project plan as Gantt + Risk layers. IRDME returns universal hubs (tasks critical in both), hub shadows (schedule illusions — high Gantt rank, low Risk rank or vice versa), and the law correlation r(Gantt ↔ Risk).
The Functional Proximity Law evidence table. 25 confirmed, 4 denied (named boundary conditions). Published arXiv:2604.23639.
One post per domain. Each post is a structural finding — AIG, post.php, C. elegans, LLaMA.
Applied walkthroughs: software audit, migration risk map, biological hub discovery.
What IRDME is, what it is not, alpha disclaimer, service model, integrity standards.
Questions, collaboration, or pilot inquiries.
FAQ
Do I need domain expertise to use IRDME?
No domain expertise is needed to run the analysis. The engine reads graph structure, not content. You do need domain expertise to interpret whether a finding is meaningful — topology is a signal, not a conclusion.
How large does my graph need to be?
At least 8–10 nodes per layer for the correlation statistics to be meaningful. Fewer than 8 nodes: use results as exploratory only. Graphs with 15–50 nodes produce the most interpretable results. Very large graphs (>200 nodes) may require subgraph extraction first.
What does it mean if r is negative?
A negative r between two layers means the items that are hubs in layer A tend to be peripheral in layer B, and vice versa. This is a layer inversion — one of the most interesting structural findings IRDME can produce. Finance DENIED (derivatives vs credit) and Internet AS topology (transit vs content delivery) both had negative r.
Is IRDME open source?
No. The analysis engine is closed source. The science (law statement, evidence table, pre-registered hypotheses) is published openly on arXiv:2604.23639. The pre-registration records are public at github.com/vladi160/preregistrations.
Can I use IRDME results in a paper?
Yes, with appropriate caveats. Cite the arXiv paper for the methodology. Note that this is alpha software. Any result should be independently validated for your domain before publication. IRDME findings are structural observations — peer review requires domain-level interpretation.
What is an Investigation?
An Investigation is a chained analysis sequence. You run an initial analysis on a graph, then derive a subgraph from the result (top hubs, most divergent nodes, or a custom selection), then run another analysis on that subgraph. Each step is an immutable checkpoint. A Jaccard novelty guardrail checks whether the hub sets between consecutive steps overlap ≥ 70% — if so, the next step is blocked as redundant (you would just be re-analysing the same structural space). Public investigations allow any logged-in user to contribute the next step, enabling collaborative structural research.
What is a pre-registered experiment?
A pre-registered experiment commits specific, falsifiable hypotheses to a public repository before running any analysis. The SHA-256 hash of the hypothesis statements proves they were not modified after seeing results. This is the same standard as clinical trial registration. All CONFIRMED/DENIED verdicts on this platform with a pre-reg hash follow this protocol.