A 5-minute guide

What ResearchArchitect does, in the order you'll actually do it — from a research question to a set of hypotheses that know their own limits.

What you're building

An influence network: the variables that bear on your research question, and the links between them. It is not a finished analysis — it is the design you would otherwise carry around implicitly, made explicit enough to argue with.

One boundary worth stating up front. What you get back is pattern synthesis — plausible structure recalled from prior research — not causal discovery, and not evidence about the world. Building the graph does not search anything; only the literature-review actions go and look. Treat every proposed link as a claim to check.

The workflow

Six steps. You can stop after any of them, and you can loop back at any point — the graph is saved as you go and every action is recorded.

1

Describe the study

On the setup card, give your research question. That is the only required field. If you already know your data and your scope — the area, the time window, the resolution — add them now; if not, add them later and re-run.

Why it matters: scope and data are what later steps judge everything against. A graph with no scope can still be built, but the scope and coverage assessments will have nothing to measure against.
2

Generate the first network

Generate causal graph

You get a first network of variables and directed links. Expect it to be too broad and partly wrong — that is the point. It is faster to delete a bad variable than to think of a missing one.

How to judge it: look for the mechanisms you know should be there. What's missing tells you more than what's present.
3

Argue with it

Refine graph

Say what is wrong in your own words — a variable that conflates two things, a link pointing the wrong way, a mechanism nobody in your field would accept. You can also add and delete nodes directly, or ask a question in the chat panel without changing anything.

This is the main loop. Most of the value comes from here, not from step 2. Refine first; the analyses below are only worth running on a graph you believe.
4

Ask what kind of link each one is

Edge importance

Every link gets classified by the kind of role it plays — necessary, driving, or modifying — and the graph is redrawn accordingly. See reading the graph below.

Re-run it after adding nodes. New edges start unclassified; re-running covers them and reports how many were left unclassified.
5

Ask what your study can actually see

Scope assessment Data coverage

Two different questions, often confused. Scope asks whether a variable will even move inside your observation window and act within your study area. Coverage asks whether you can measure it with the data you have. A variable can be perfectly measurable and still useless, because it is constant across everything you sampled.

What to do with an out-of-scope variable: not delete it. State it as a boundary condition of the study — or widen the window, or change the sampling unit.
6

Turn the design into claims you can test

Feedback loops Generate hypotheses

Check for cycles first — a feedback loop changes which hypotheses are even statable, because a variable inside one cannot be treated as simply upstream of the outcome. Then generate hypotheses, each tied to the variables and links it depends on.

Selecting a hypothesis highlights its subgraph. Press Esc or the release button to let go of the highlight.

Reading the graph

Three encodings, each answering a different question. They are independent — an edge can be necessary and out of scope and uncovered.

Line colour and style — what kind of link is this?

Necessary
The target cannot occur without this factor.
Example: Mosquito larvae cannot develop without an aquatic habitat.
So what: A precondition. Removing it eliminates the outcome, so it bounds where the outcome can exist at all — but it usually explains little of the variation where it is already present.
Driving
Changes in this factor substantially control or explain changes in the target.
Example: During the dry season, water persistence may drive differences in mosquito productivity among habitats.
So what: Explains variation. These are the levers for intervention and the variables most worth measuring precisely.
Modifying
This factor alters the probability, magnitude, timing, or form of the target but is not required for it to occur.
Example: Shade may modify water temperature, evaporation, and larval survival, but shaded conditions are not required for every mosquito habitat.
So what: Context and effect modification. Often the reason effects differ between settings, and a common source of confounding or interaction terms.

Scope status — can this vary inside your study?

In scope
The factor varies meaningfully inside your observation window and its influence operates within your study area, so it can carry signal you are able to detect.
So what: This is where your inferential leverage lives. Worth measuring precisely, and legitimate to use as a predictor, exposure or treatment.
Partial
The factor passes one of the two axes and fails the other: it varies but not here, it acts here but barely varies, or its effect arrives after your window closes.
So what: Detectable but attenuated. Keep it as a covariate or a stated background condition rather than a headline estimate — or extend the window, or change the sampling unit.
Out of scope
The factor is static across your study period AND its influence originates beyond your study area, so within this design it is effectively a constant.
So what: This is NOT a claim that the factor is non-causal or unimportant. It means your design cannot see it, so state it as a boundary condition of the study rather than trying to estimate it.

Evidence levels — what job does a citation do?

A literature review is not a web search with citations attached. Every source a review cites is tagged with the role it plays for your study, and the reference list is ordered by it.

Foundation
The upstream theory, method or enabling technology this study rests on. If it advances or is overturned, the research question has to be reframed rather than simply re-run.
Example: A study that inventories water bodies from satellite imagery rests on computer-vision object detection. A step change in detection accuracy would not just improve the estimates — it would change which questions are worth asking, because habitats previously invisible become measurable.
So what: This is the study's dependency and its obsolescence risk. Cite it to justify that the link belongs in the model, and watch it: it tells you which of your design choices are contingent on the current state of the art rather than on the science.
Similar research
Studies and projects close enough in location, period, scale, method or data source that their design decisions, instruments and results transfer to this study.
Example: A study estimating larval habitat from sub-metre imagery in another East African city — different site, same measurement problem, and its sampling design and failure modes carry straight across.
So what: Where the design leverage is, and the main source of inspiration. It tells you what effect size is plausible, which confounders bit in practice, what sample size sufficed, which measurement approaches already failed, and what a comparable team chose to do next.
Boundary
Work that qualifies, bounds or contests the claim: null and contradictory results, effect modification, findings that fail to transfer across settings, and critiques of how the thing is usually measured.
Example: A study finding no association between rainfall and larval abundance in a piped-water city, showing the relationship depends on how water is stored rather than how much rain falls.
So what: The most useful level for stating limitations honestly, and the one a search-style review omits most often — negative results are cited less and surface lower.
Quick or comprehensive. A quick review is one pass and takes about a minute — the default. A comprehensive review runs a separate searching agent for each level above and then synthesises them, which is how the upstream dependencies and the contradictory results actually get found. It costs several times as much and takes a few minutes.

Transparency — is there data for this?

Solid
Covered — your stated data can measure this variable.
Faded
Partially covered — a proxy exists, or the resolution is wrong.
Very faint
Not covered — nothing in your data measures it.
Coverage changes opacity only, never colour, so it can be read at the same time as the link type.

What each action costs

Actions that call out to a model cost credits. Editing, deleting, exporting, and asking a question in the chat panel are free.

ActionWhat it producesCredits
Generate causal graph Turn a research question into a structured causal DAG. 5
Refine graph Iteratively improve nodes and edges based on your feedback. 3
Data coverage Find which variables have data and which need collection. 4
Edge importance Score each causal relationship by strength and evidence. 4
Scope assessment Evaluate the boundaries and assumptions of your model. 4
Generate hypotheses Discover testable hypotheses from the graph + literature. 8
Detect feedback loops Identify system dynamics and reinforcing cycles. 5
Literature review Edge-by-edge literature evidence with citations. 6

Common questions

The things people ask in the first session.

Do I have to know my scope and data before I start?
No. The research question is the only required field. Scope and data can be added later from the same setup card, and you can re-run the scope and coverage assessments as often as you like — the graph keeps its history.
I added a node. Do I need to re-run the analyses?
Yes, for anything you want it included in. New edges start unclassified; re-running Edge importance picks them up and tells you how many remain unclassified. The same applies to scope and coverage.
What is the difference between scope and data coverage?
Scope asks whether a variable will move within your observation window and act within your study area. Coverage asks whether you can measure it. They fail independently: a satellite product might measure land surface temperature perfectly (covered) while temperature barely varies across your five sites in one week (out of scope).
Something is out of scope. Should I delete it?
Usually not. Out of scope is a statement about your design, not about the world — it means this study cannot see the factor. The honest move is to keep it and state it as a boundary condition, so a reader knows it was considered rather than overlooked.
Is my work saved?
Yes. Graphs, analysis results, literature reviews and every input you typed are stored with the study and are there when you come back. Changes that rewrite the graph create an entry in Version History so you can roll back.
Can I get the graph out of the app?
Yes — export to a standalone interactive HTML page that keeps the app's layout and symbology, or to GraphML for use in other network tools.
Should I trust what it proposes?
No more than you would trust a well-read colleague thinking out loud. Recalling patterns from prior research makes it good at breadth, and good at surfacing mechanisms from outside your own field — and leaves it unable to tell you what is true. The design is yours; the judgement has to be yours too.

Start from a real study

These open in the workspace with everything already run, so you can see the finished shape before building your own.

Aedes aegypti indoor resting height factors · 20 nodes Carlton County housing labor factors · 51 nodes Dry season Anopheles stephensi larval productivity factors · 34 nodes
Open the workspace →