---
title: "Getting Started with grayleafspotr"
output:
  BiocStyle::html_document:
    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)

# Gate the pipeline chunks with a presence check. If an external basilisk
# cache is configured, it must exist before the live examples can run. Live
# Python examples are not run on Bioconductor build machines.
is_bioc_build <- identical(Sys.getenv("IS_BIOC_BUILD_MACHINE"), "true")
basilisk_dir <- Sys.getenv("BASILISK_EXTERNAL_DIR", unset = "")
py_ok <- !is_bioc_build &&
  (!nzchar(basilisk_dir) || dir.exists(basilisk_dir)) &&
  tryCatch(
    grayleafspot_python_available(engine_model = "localunet"),
    error = function(e) FALSE
  )
```

## What is grayleafspotr?

`grayleafspotr` automates the quantitative phenotyping of gray leaf spot
(*Magnaporthe oryzae*) 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.

`basilisk` handles Python dependencies automatically, so you do not need to
set up Python yourself. For visual quality control, `plot_grayleafspot_overlay()`
uses the Bioconductor `EBImage` package to draw the detected dish boundary, colony
outline, and crack segments directly on the source photograph, so automated
segmentation results can be checked against the original image rather than
trusted as an opaque summary statistic.

---

## 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 load-example-run}
run <- example_grayleafspot_results()
```

### View the feature table

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

### Template plots

```{r plot-colony-expansion}
plot_colony_expansion(run)
```

```{r plot-growth-roughness}
plot_growth_roughness(run)
```

```{r plot-stress-remodeling}
plot_stress_remodeling(run)
```

```{r plot-texture-organization}
plot_texture_organization(run)
```

```{r plot-shape-vs-stress}
plot_shape_vs_stress(run)
```

```{r plot-feature-heatmap}
plot_feature_heatmap(run)
```

### Convert to a plain data frame

```{r convert-tidy-data}
df <- as_grayleafspot_growth_data(run)
df
```

---

## Analyze your own images

Point `grayleafspot_run()` at a folder of plate photographs. The pipeline
uses the basilisk-managed Python environment. The chunks below run
the real pipeline against the three bundled 06FEB test images
(`inst/extdata/testdata/06FEB/`) so this vignette demonstrates the full,
working code path rather than a snippet you can't execute.

```{r run-own-images, eval=py_ok}
img_dir <- system.file("extdata", "testdata", "06FEB", package = "grayleafspotr")
out_dir <- file.path(tempdir(), "grayleafspotr-run-demo")

res <- grayleafspot_run(input_dir = img_dir, output_dir = out_dir, run_name = "demo")

# Per-image feature table
res$results

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

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

```{r analyze-own-images, eval=py_ok}
run_own <- grayleafspot_analyze(
  input_dir = img_dir, output_dir = out_dir,
  run_name = "demo-analyze", verbose = FALSE
)
plot_colony_expansion(run_own)
```

### Visualize detected regions of interest

`plot_grayleafspot_overlay()` draws the detected dish boundary (yellow),
colony outline (red), and crack segments (cyan) on top of the original
image, using `EBImage`:

```{r visualize-overlay, eval=py_ok}
image_file <- list.files(img_dir, full.names = TRUE)[1]
plot_grayleafspot_overlay(run_own, image_path = image_file)
```

### Reload saved results

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

```{r reload-saved-results, eval=py_ok}
saved_dir <- run_own$run$output_dir
reloaded <- read_grayleafspot_results(saved_dir)
plot_colony_expansion(reloaded)
```

---

## 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")
```

## Session information {-}

```{r session-info}
sessionInfo()
```