Batch¶

Summary¶

Batch is the main processed object for folder-backed PyFLASH analysis. It combines one or more experiments under the same group list, builds merged summary tables, keeps output paths, and provides Excel and CSV export methods.

Most users get a Batch from create_batch or load_state. Direct construction is possible, but it expects pre-built experiment objects.

How To Create It¶

Preferred path:

from PyFLASH import GroupBuilder, create_batch

groups = (
    GroupBuilder("Diagnosis")
    .add("Control", short="Control", color="grey")
    .add("AD", short="AD", color="red")
    .compare("Control", "AD")
    .build()
)

batch = create_batch(
    name="example-batch",
    conditions=groups,  # current create_batch parameter; pass a groupList
    batch_path="/path/to/output-folder",
    experiments="/path/to/experiment-parent-folder",
    import_images=False,
)

Direct construction:

from PyFLASH import Batch, Experiment

experiments = [
    Experiment("exp-1", "/path/to/experiment-1"),
    Experiment("exp-2", "/path/to/experiment-2"),
]

batch = Batch("example-batch", experiments, groups, "/path/to/output-folder")
batch.processData(import_images=False)

create_batch can also take experiments as a dictionary of {name: path}, a list of pre-built experiment objects, a parent folder path, or None to search inside batch_path.

Important Attributes¶

Attribute	Meaning
`name`	Batch name. `create_batch` also uses this as the default pickle filename when `pickle_path` is supplied.
`experiment_list`	Ordered list of `Experiment`-like objects in the batch. Iterating over `batch` iterates over this list.
`condition_list`	The ordered `conditionList` or `groupList` used for group order, colors, styles, factors, and planned comparisons.
`conditions`	Flattened list of single group objects, set by `set_condition_list`. Crossed designs flatten into their component groups here.
`factor`	List of factor names, such as `["Diagnosis"]` or `["Diagnosis", "Sex"]`.
`factorDict`	Mapping from factor name to the group objects for that factor.
`summary`	Backward-compatible primary summary table. It returns the `SCN` table when available, otherwise the first table in `summaries`.
`summaries`	Dictionary of subject-level summary tables keyed by region of interest base, such as `"SCN"`.
`data`	Dictionary of imported marker or attribute tables. Each value has a `.df` DataFrame.
`markers`	Set of imported marker names gathered from all experiments.
`images`	Image metadata table when images were imported. `None` when image import was skipped.
`imagesDict`	Lookup dictionary built from `images`; regenerated after pickle loading.
`aliases`	Path/name aliases auto-generated by `create_batch` from conditions and `Config.ALIASES`. Direct `Batch(...)` construction does not create this automatically.
`filePath`	Batch output root.
`export_path`	Base folder for Excel exports, usually `<filePath>/Exports`.
`fig_path`	Base folder for saved figures, usually `<filePath>/Results/Python Figures`.
`image_fig_path`	Saved image-panel figure folder under `fig_path`.
`representative_path`	Folder for representative image outputs.
`legend_path`	Folder for standalone legends and condition keys.
`data_path`	Folder for saved statistics and data outputs.
`csv_path`, `column_path`, `attribute_path`	Folders used by CSV exports.

Common Methods¶

Method	Use
`processData(import_images=True, progress=True)`	Process each experiment, apply conditions, merge data and summaries, configure output paths, optionally import images, and assign regions.
`createSavePaths()`	Populate output path attributes. It does not create every folder immediately.
`importImages(progress=True)`	Build a combined image metadata table from the experiments.
`getImageTable(include_summary=True)`	Return the image metadata table, optionally merged with summary metadata.
`getDisplaySummary(roi_base=None)`	Inherited helper that returns a display-only summary with readable column labels.
`getRegionDict(roi_base=None)`	Return the condition to animal to region mapping used by iteration.
`save_csvs()`	Ask each experiment to write its CSV outputs.
`export_excel(...)`	Write the standard Excel export set.
`export_all_excel(...)`	Alias for `export_excel(...)`.
`export_extended_data_excel(...)`	Write extended immunofluorescence data workbooks.
`export_IF_summary_excel(...)`	Write summary immunofluorescence workbooks.
`export_extra_summary_excel(...)`	Write summary columns not covered by standard IF export maps.
`export_unregistered_summary_excel(...)`	Underlying method used by `export_extra_summary_excel`.
`export_behavior_summary_excel(...)`	Write behavior summary workbooks when a `Behaviour` table is present.

Accepted By¶

Batch is accepted by most plotting functions, pipeline functions, exclusion helpers, formatting helpers, export workflows, and modelling functions. It is the most complete PyFLASH input object because it can provide summary data, marker-level tables, image metadata, condition metadata, and output paths.

Returned By¶

create_batch
load_state, when the saved pickle contains a Batch

Examples¶

Inspect the primary summary table:

print(batch.summary.head())
print(batch.summary[["AnimalName", "Condition"]].head())

List experiments and marker tables:

print([exp.name for exp in batch])
print(sorted(batch.data))

gfap = batch.data["GFAP"].df
print(gfap.head())

Export Excel workbooks to the default export folder:

batch.export_all_excel()

Export only extra unregistered summary columns to a chosen folder:

batch.export_extra_summary_excel(
    save_path="/path/to/exports",
    include=["Intensity|Patchiness"],
    save_name="Extra_Metrics",
)

Save and load a processed batch:

from PyFLASH import load_state, save_state

save_state(batch, "/path/to/example-batch.pkl")
batch = load_state("/path/to/example-batch.pkl")

Notes¶

Batch subclasses Experiment, so several methods are inherited.
summary is a convenience view. Use summaries when you need a specific region of interest base.
Missing measurements from experiments where an animal was not present are filled with the NOT_INCLUDED_IN_EXPERIMENT sentinel during batch summary merging.
Set import_images=False in create_batch when you only need summary plots and want faster processing.
Batch does not expose an experiments attribute in source. Use batch.experiment_list or iterate over batch.