Systems Framing & Modelling (agsy-systems-framing-and-modeling)
This is the distinctive core of an Agricultural Systems paper. AgSy expects an explicit system
(boundaries, components, hierarchical levels, feedbacks) and a model that is described, justified, and
calibrated — not a black box. Frame the system first, then make the model reproducible enough that a
reader could re-implement it.
When to trigger
- Defining the system boundary, components, and what counts as inside vs. outside
- Choosing a modelling approach and justifying it against alternatives
- Writing the model-description (methods) section
- A reviewer asked "what is the system?", "why this model?", or "how was it calibrated?"
Step 1 — Frame the system
- Boundary. State what is inside the system and what is an external driver (climate, prices,
policy). Justify the boundary by the question.
- Components & interactions. Name the components (crop, soil, water, livestock, labour, economics)
and the interactions that matter — AgSy is about interactions, so make them explicit.
- Hierarchical levels. Field → farm → landscape → region → food system: say which levels you
model and how processes at one level aggregate or constrain another.
- Feedbacks & emergence. Identify feedback loops and any emergent behavior the system can produce.
A conceptual diagram (boxes/arrows) is usually expected.
Step 2 — Choose and justify the model
- Match model to question. Process/simulation (APSIM/DSSAT/STICS/DNDC) for biophysical dynamics;
whole-farm models for resource flows and trade-offs; bio-economic / mathematical programming
for farmer decisions under constraints; agent-based for heterogeneity and emergence; integrated
assessment for regional/food-system scenarios. (See
resources/external_tools.md.)
- Justify the choice against the standard alternatives — what does this model represent that others
cannot, and what does it omit?
Step 3 — Describe the model so it can be reproduced
- Version & provenance. Exact model and version; any modifications you made.
- Equations / structure. Key state variables, processes, and (for ABM) the ODD protocol.
- Parameters & inputs. Sources for parameters and driving data; what is fixed vs. estimated.
- Calibration. What was calibrated, against which data, by what procedure — and what was held out
for evaluation (hand off to
agsy-data-and-model-evaluation).
- Assumptions. State the load-bearing assumptions and their plausible range.
The "interaction or it isn't AgSy" test
Write one sentence: "The result arises because component A interacts with component B such that ___;
absent that interaction the system would behave like ___." If you cannot, you have a single-factor
study, not a systems analysis — reframe (back to agsy-topic-selection).
Anti-patterns
- An undefined system boundary ("the farm" with no components or interactions specified)
- A model used as a black box: no version, equations, parameters, or calibration described
- Calibrating and evaluating on the same data (no independent evaluation)
- Choosing a model out of familiarity without justifying it against alternatives
- Hiding assumptions that drive the headline result
Worked micro-example: framing one system (illustrative)
A study asks how feed-price shocks reshape a mixed crop–livestock farm's land allocation (illustrative).
- Boundary. Inside: cropping, the dairy herd, feed and manure flows, gross margin. External drivers:
climate, feed-grain and milk prices, N regulation.
- Interactions. The load-bearing loop is feed price → herd feeding strategy → manure N → crop rotation
→ on-farm feed supply, so a bio-economic whole-farm model is chosen over a crop-only simulator.
- Interaction test passes: the result arises because the herd–manure–rotation loop couples feed price
to land use; absent it the farm would behave like two independent enterprises.
Referee pushback → the AgSy-specific fix
- "What exactly is the system?" → Add a boundary statement, a component-and-interaction list, and a
conceptual diagram; name the hierarchical levels modelled.
- "Why this model and not the standard one?" → State what your model represents that the alternative
cannot, and what it omits.
- "The system boundary is too narrow." → Show the interaction the boundary would cut (the
manure–rotation feedback) and widen it, or justify the cut.
Calibration anchors (hedged where uncertain)
- Model choice is judged by referees against the question, not fixed by the journal — justify it.
- The ODD protocol is the community standard for agent-based model description, not a journal format.
Output format
【System boundary】inside vs. external drivers
【Components & interactions】the interactions that matter
【Hierarchical levels】modelled + how they link/aggregate
【Model & version】+ why this model vs. alternatives
【Calibration】what, against which data, what was held out
【Key assumptions】load-bearing ones + plausible range
【Next】agsy-data-and-model-evaluation
Supplementary resources
Source: brycewang-stanford/Awesome-Journal-Skills → Agricultural-Systems-Skills/skills/agsy-systems-framing-and-modeling/SKILL.md
1---2name: agsy-systems-framing-and-modeling3description: Use when framing the system and describing the model for an Agricultural Systems (AgSy) manuscript — defining system boundaries, components, hierarchical levels, and feedbacks, then choosing, describing, and calibrating the model (process/simulation, whole-farm, bio-economic, agent-based, or integrated assessment). This is the distinctive core of an AgSy paper. Structures the model and system; it does not run code for you.4---5
6
7# Systems Framing & Modelling (agsy-systems-framing-and-modeling)
8
9This is the **distinctive core** of an Agricultural Systems paper. AgSy expects an explicit **system**
10(boundaries, components, hierarchical levels, feedbacks) and a model that is **described, justified, and
11calibrated** — not a black box. Frame the system first, then make the model reproducible enough that a
12reader could re-implement it.
13
14## When to trigger
15
16- Defining the system boundary, components, and what counts as inside vs. outside
17- Choosing a modelling approach and justifying it against alternatives
18- Writing the model-description (methods) section
19- A reviewer asked "what is the system?", "why this model?", or "how was it calibrated?"
20
21## Step 1 — Frame the system
22
231. **Boundary.** State what is inside the system and what is an external driver (climate, prices,
24 policy). Justify the boundary by the question.
252. **Components & interactions.** Name the components (crop, soil, water, livestock, labour, economics)
26 and the **interactions** that matter — AgSy is about interactions, so make them explicit.
273. **Hierarchical levels.** Field → farm → landscape → region → food system: say which levels you
28 model and how processes at one level **aggregate or constrain** another.
294. **Feedbacks & emergence.** Identify feedback loops and any emergent behavior the system can produce.
30 A conceptual diagram (boxes/arrows) is usually expected.
31
32## Step 2 — Choose and justify the model
33
34- **Match model to question.** Process/simulation (APSIM/DSSAT/STICS/DNDC) for biophysical dynamics;
35 **whole-farm** models for resource flows and trade-offs; **bio-economic / mathematical programming**
36 for farmer decisions under constraints; **agent-based** for heterogeneity and emergence; **integrated
37 assessment** for regional/food-system scenarios. (See `resources/external_tools.md`.)
38- **Justify the choice** against the standard alternatives — what does this model represent that others
39 cannot, and what does it omit?
40
41## Step 3 — Describe the model so it can be reproduced
42
43- **Version & provenance.** Exact model and version; any modifications you made.
44- **Equations / structure.** Key state variables, processes, and (for ABM) the **ODD protocol**.
45- **Parameters & inputs.** Sources for parameters and driving data; what is fixed vs. estimated.
46- **Calibration.** What was calibrated, against which data, by what procedure — and what was held out
47 for evaluation (hand off to `agsy-data-and-model-evaluation`).
48- **Assumptions.** State the load-bearing assumptions and their plausible range.
49
50## The "interaction or it isn't AgSy" test
51
52Write one sentence: *"The result arises because component A interacts with component B such that ___;
53absent that interaction the system would behave like ___."* If you cannot, you have a single-factor
54study, not a systems analysis — reframe (back to `agsy-topic-selection`).
55
56## Anti-patterns
57
58- An undefined system boundary ("the farm" with no components or interactions specified)
59- A model used as a black box: no version, equations, parameters, or calibration described
60- Calibrating and evaluating on the **same** data (no independent evaluation)
61- Choosing a model out of familiarity without justifying it against alternatives
62- Hiding assumptions that drive the headline result
63
64## Worked micro-example: framing one system (illustrative)
65
66A study asks how feed-price shocks reshape a mixed crop–livestock farm's land allocation (illustrative).
67
68- *Boundary.* Inside: cropping, the dairy herd, feed and manure flows, gross margin. External drivers:
69 climate, feed-grain and milk prices, N regulation.
70- *Interactions.* The load-bearing loop is feed price → herd feeding strategy → manure N → crop rotation
71 → on-farm feed supply, so a bio-economic whole-farm model is chosen over a crop-only simulator.
72- *Interaction test passes:* the result arises because the herd–manure–rotation loop couples feed price
73 to land use; absent it the farm would behave like two independent enterprises.
74
75## Referee pushback → the AgSy-specific fix
76
77- *"What exactly is the system?"* → Add a boundary statement, a component-and-interaction list, and a
78 conceptual diagram; name the hierarchical levels modelled.
79- *"Why this model and not the standard one?"* → State what your model represents that the alternative
80 cannot, and what it omits.
81- *"The system boundary is too narrow."* → Show the interaction the boundary would cut (the
82 manure–rotation feedback) and widen it, or justify the cut.
83
84## Calibration anchors (hedged where uncertain)
85
86- Model choice is judged by referees against the question, not fixed by the journal — justify it.
87- The ODD protocol is the community standard for agent-based model description, not a journal format.
88
89## Output format
90
91```
92【System boundary】inside vs. external drivers
93【Components & interactions】the interactions that matter
94【Hierarchical levels】modelled + how they link/aggregate
95【Model & version】+ why this model vs. alternatives
96【Calibration】what, against which data, what was held out
97【Key assumptions】load-bearing ones + plausible range
98【Next】agsy-data-and-model-evaluation
99```
100
101## Supplementary resources
102
103- [`../../resources/external_tools.md`](../../resources/external_tools.md) — process, whole-farm, bio-economic, ABM, and integrated-assessment models; ODD protocol
104- [`../../resources/official-source-map.md`](../../resources/official-source-map.md) — AgSy's interaction- and modelling-centered scope
105
106---
107
108**Source:** [`brycewang-stanford/Awesome-Journal-Skills`](https://github.com/brycewang-stanford/Awesome-Journal-Skills) → `Agricultural-Systems-Skills/skills/agsy-systems-framing-and-modeling/SKILL.md`
thedixitjain