10. The example research project
10. The example research project
How does a mother’s exposure to heat during pregnancy relate to her baby’s birthweight, and does that relationship vary with maternal age? This question connects the following chapters. An agent can help develop it, examine the evidence, and build an analysis whose results can be checked and reproduced.
The example uses 1,200 synthetic birth records. Each record contains the mother’s age and smoking status, the number of hot days she experienced during the third trimester, and the baby’s birthweight in grams. You can inspect the saved files without installing additional software.
Download the complete synthetic research project
Develop the research question
An agent can help you compare ways to frame a research question. For this study, you might examine average birthweight or the probability of low birthweight, and measure heat exposure across the third trimester or during a brief heatwave. Ask the agent to explain what each approach would estimate and what data it would require. Chapter 11: Find and assess research literature explains how to find evidence that supports or challenges these choices.
These are research decisions, not details for the agent to settle while coding. A different outcome or exposure window may answer a different question. You decide which question to pursue; the agent can make the alternatives, assumptions, and unresolved issues easier to examine.
Using the research question, available data, and constraints below, compare plausible analysis approaches. Explain what each would estimate, the assumptions it requires, and what evidence supports or challenges it. Separate verified sources from suggestions to investigate. Identify decisions needed from me before turning the chosen approach into an analysis specification.
Write the scientific specification
The analysis specification tells the agent what to estimate, how to estimate it, and what results to save. For the synthetic birthweight study, these decisions are recorded in SPECIFICATION.md and summarized below.
| Item | Specification |
|---|---|
| Question | What is the mean birthweight difference between 10 and 5 hot days, and how does it vary with maternal age? |
| Primary estimand | The 10-minus-5-day mean difference, standardized over this synthetic sample’s age and smoking distribution. |
| Secondary estimands | The same contrast at maternal ages 22, 28, and 36, using the sample’s smoking distribution. |
| Estimator | Least squares with quadratic age, a hot-days-by-age interaction, and smoking; counterfactual predictions supply the contrasts. |
| Uncertainty | 95% confidence intervals from an HC3 heteroskedasticity-robust covariance estimate and a normal reference distribution. |
| Outputs | A contrast table and figure, simulation results, an independent comparison, and a manuscript passage. |
The exposure coefficient alone does not supply the requested average contrast when exposure interacts with age. Specifying the estimand prevents an agent from silently reporting that coefficient instead.
A real study would also need a target population and defensible assumptions about confounding, measurement, selection, and support for the exposure comparison.
Write
SPECIFICATION.mdfrom my research decisions: estimands, target population and analysis sample, comparisons, estimator, sample rules, inputs, uncertainty, and outputs. State any averaging or standardization explicitly. Include prescribed checks and tolerances. Flag unresolved choices for my review before fitting.
Keep the project files together
The download follows the organization introduced in Chapter 6: Organize your research projects. It contains the original synthetic records and data dictionary, their generator, independent R and Python implementations, saved results, software records, and verification reports. Its README explains how to run the project and records which checks have been completed.
Record the prescribed analysis in SPECIFICATION.md. The completed example states the sample, contrasts, estimator, and required outputs. Its METHODOLOGY.md explains the documented choices and the later reorganization; it identifies retrospective entries rather than inventing a decision history. The original specification supplied to the independent implementations is preserved separately, so readers can see exactly what those runs received.
The simulation specification defines distinct simulated scenarios with known relationships among the study variables. Chapter 14: Test the analysis against known truth uses these scenarios to assess the estimator. Keeping the simulation specification, code, and results together helps distinguish checks specified in advance from explanations developed after seeing the results.
Follow the work, including its revisions
Research rarely proceeds once through a fixed sequence. A literature finding may change the exposure definition; a data limitation may narrow the research question. Failed checks can reveal a coding error or an inadequate method. Writing can expose a claim the analysis has not addressed.
The agent can investigate these problems and propose responses. Before changing the scientific approach, agree what should change and record why. Preserve the earlier specification and results so that the revision can be understood.