---
title: "Getting Started with grayleafspotr"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Getting Started with grayleafspotr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE,
                      fig.width = 7, fig.height = 4.5)
library(grayleafspotr)
```

## What is grayleafspotr?

`grayleafspotr` automates the quantitative phenotyping of gray leaf spot
(*Cercospora zeae-maydis*) fungal colonies grown on petri dishes. Given a
folder of plate photographs, the package:

- segments each colony with a bundled SmallUNet deep-learning model,
- extracts area, shape, texture, and crack-coverage features for each image,
- returns a tidy data frame ready for plotting and statistical analysis.

Python dependencies are handled automatically by `basilisk` — no manual setup
is needed.

---

## Quick start with bundled data

The package ships pre-computed results from three example images. Load them
with `example_grayleafspot_results()` to try the plotting functions
immediately:

```{r}
run <- example_grayleafspot_results()
```

### View the feature table

```{r}
run$results[, c("filename", "day", "area_mm2", "diameter_mm",
                "circularity", "crack_coverage_pct", "qc_status")]
```

### Template plots

```{r}
plot_colony_expansion(run)
```

```{r}
plot_growth_roughness(run)
```

```{r}
plot_stress_remodeling(run)
```

```{r}
plot_texture_organization(run)
```

```{r}
plot_shape_vs_stress(run)
```

```{r}
plot_feature_heatmap(run)
```

### Convert to a plain data frame

```{r}
df <- as_grayleafspot_growth_data(run)
df
```

---

## Analyze your own images

Point `grayleafspot_run()` at a folder of plate photographs. The pipeline
runs automatically — no Python configuration required.

```{r, eval=FALSE}
res <- grayleafspot_run(
  input_dir  = "path/to/images",   # folder of JPEG/PNG/TIFF plate photos
  output_dir = "outputs",
  run_name   = "my_experiment"
)

# Per-image feature table
res$results

# Run manifest (paths, timestamp)
res$run
```

For plotting support, use `grayleafspot_analyze()` instead:

```{r, eval=FALSE}
run <- grayleafspot_analyze(
  input_dir  = "path/to/images",
  output_dir = "outputs"
)
plot_colony_expansion(run)
```

### Reload saved results

Outputs are written to a timestamped folder and can be reloaded later:

```{r, eval=FALSE}
run <- read_grayleafspot_results("outputs/20260427T120000Z_localunet")
plot_colony_expansion(run)
```

---

## Next steps

See the **grayleafspotr Workflow** vignette for:

- a detailed description of all features extracted by the pipeline,
- a complete gallery of template plots with biological interpretation,
- guidance on image naming conventions and folder structure,
- instructions for saving publication-quality figures.

```r
vignette("grayleafspotr-workflow", package = "grayleafspotr")
```