# The Pipeline Mental Model

PhenoTypic processes plate images through a linear sequence of operations.
Understanding this model is essential for designing effective workflows.

## The Three-Stage Flow

Every analysis follows the same pattern:

1. **Enhance** — Improve `detect_mat` for better colony/background separation
2. **Detect** — Find colonies and write to `objmask` and `objmap`
3. **Measure** — Extract features from detected colonies into a DataFrame

```
Image → [Enhancers] → [Detector] → [Refiners] → [Measurements] → DataFrame
         modify          write        clean up      read
         detect_mat      objmask      objmask       objmap
                         objmap       objmap
```

Each stage reads from specific accessors and writes to others. This
separation means enhancers cannot corrupt detection results, and
measurements always see the final refined mask.

## What Each Stage Touches

| Stage | Reads | Writes | Leaves unchanged |
|-------|-------|--------|-----------------|
| Enhancer | `detect_mat` | `detect_mat` | `rgb`, `gray`, `objmask`, `objmap` |
| Detector | `detect_mat` | `objmask`, `objmap` | `rgb`, `gray`, `detect_mat` |
| Refiner | `objmask`, `objmap` | `objmask`, `objmap` | `rgb`, `gray`, `detect_mat` |
| Corrector | all components | all components | (transforms the entire image) |
| Measurement | `objmap`, `gray`/`rgb` | (none — returns DataFrame) | everything |

This contract is enforced by the abstract base classes. A custom enhancer
that accidentally writes to `objmap` would violate the contract and produce
unpredictable results.

## Immutability and Copies

By default, `pipeline.apply(image)` creates a copy of the input image. The
original is never modified. This makes it safe to apply multiple pipelines
to the same image for comparison.

Pass `inplace=True` to modify the image directly when memory is constrained.

## Serialization

Because each operation stores its configuration as simple parameters, the
entire pipeline can be serialized to JSON and reconstructed exactly. This
is the foundation of PhenoTypic's reproducibility model — the JSON file
captures everything needed to reproduce an analysis.

## References

[1] D. Procida, "Diataxis: A systematic framework for technical
documentation," 2023. [Online]. Available: https://diataxis.fr/