+ BioFile Finder (BFF) is a web-based application + designed to enable researchers to explore and manage large-scale + biological imaging datasets and associated files in a consistent and + streamlined way. It enables users to query structured metadata and + seamlessly connect results to associated image assets. +
++ Built to handle complex, high-volume data, BioFile Finder supports + advanced search, filtering, and sorting—making it easier to access, + curate, collaborate on, and share datasets. The intuitive interface + requires no coding, allowing users to quickly preview data through + thumbnails, open files in common industry tools, or visualize them in + the companion web-based 3D volume viewer, Vol-E. +
+ + ), + }, + { + heading: "Publication & citation", + body: ( + <> ++ + Read the BFF publication in Nature Methods. + +
+
+ Meharry, S.L., Borensztejn, A., Gaudreault, N. et al. Search, organize,
+ aggregate and share image data with BioFile Finder (BFF). Nat Methods
+ (2026).
+
+ https://doi.org/10.1038/s41592-026-03130-w
+
+ BFF is designed for anyone who needs to explore and manage large + collections of biological files, especially those associated with + imaging datasets. It is particularly useful for: +
++ + Read detailed scenarios and use cases + +
+ + ), + }, + { + heading: "What makes BFF unique?", + body: ( + <> ++ A number of thoughtful features set BFF apart from other similar tools. + Key differentiators include: +
++ BioFile Finder is interoperable with many different tools and data + repositories. The following table compares BFF amongst some data + repositories, but is intended to be used as a companion to these rather + than outright replacement. For more information on how BFF can be used + with a data repository, see{" "} + + Cloud storage examples + + . +
+| Feature | +BioFile Finder (BFF) | +OMERO | +IDR | +SSBD | +Zarrcade | +BioImage Archive (BIA) | +Quilt | +Cytomine | +BisQue | +
|---|---|---|---|---|---|---|---|---|---|
| + Cost + | +Free | +Free, but deployment may cost | +Free | +Free | +Free | +Free | +Free, but deployment may cost | +Free | +Free | +
| + Deployment + | ++ Available at bff.allencell.org or can be self-hosted + | +Self-hosted | +Available at idr.openmicroscopy.org | +Available at ssbd.riken.jp | +Self-hosted | +Available at ebi.ac.uk/bioimage-archive | ++ Available at quiltdata.com or can be self-hosted + | +Self-hosted | +Self-hosted | +
| + File Format Support + | +Any file type; Parquet, CSV, JSON metadata | +150+ microscopy formats via Bio-Formats | +Same as OMERO | +OME-Zarr, BD5/HDF5 | +OME-Zarr only | +Any bioimaging format | +Any file type | +TIFF, whole-slide images | +Many image formats | +
| + Metadata Source + | +User-supplied files (Parquet/CSV) | +Separately managed database | +Separately managed database | +Separately managed database | +User-supplied files (Parquet/CSV) | +Separately managed database | +User-supplied files (Parquet/CSV) | +Separately managed database | +Separately managed database | +
| + File Source + | +Local, network, cloud, or public repositories | +Internal data store | +Internal data store | +Internal data store | +Internal data store | +Internal data store | +S3 | +Internal data store | +Internal data store | +
| + Dynamic Querying / Filtering + | ++ Yes — in-browser SQL via DuckDB; filter, sort, group + by any column + | +Yes — HQL/API queries; filter by tag/key-value | +Limited — browse by study, screen, gene | +Limited — browse by organism/study | +No — browse/list only | +Limited — search by study/accession | +Limited — search by package name | +Yes — ontology-based spatial queries | +Yes — tag-based queries | +
| + Annotation Hierarchy / Grouping + | ++ Yes — user-defined nested grouping by any annotation + | +Partial — tag groups, datasets, projects | +No | +No | +No | +No | +No | +Partial — project/folder hierarchy | +Partial — tag hierarchy | +
| + Shareable URLs / Copy-Paste Sharing + | +Yes — query state encoded in URL | ++ Partial — links to images/datasets, requires server + access + | +Yes — public stable URLs per study | +Yes — public DOI-based URLs | +Yes — public URLs to Zarr stores | +Yes — accession-based URLs | +Yes — versioned package URLs | +Partial — project links, requires login | +Partial — resource links, requires server | +
| + Works Without a Server + | ++ Yes — runs entirely in-browser or as desktop app + | +No — requires OMERO.server | +N/A (hosted service) | +N/A (hosted service) | +Yes — static site | +N/A (hosted service) | +No (SaaS) | +No — requires server | +No — requires server | +
| + Cloud / Remote Data + | +Yes — S3, HTTP/HTTPS URLs | +Yes — via OMERO.server with S3 backend | +N/A | +N/A | +Yes — any HTTP-hosted Zarr | +N/A | +Yes — S3-backed | +Limited | +Limited | +
| + Data Scale + | +Tested to 10M+ rows; limited by browser memory | +Millions of images (server-dependent) | +~50 TB across studies | +Moderate (curated datasets) | +Unlimited (just a catalog) | +Petabyte-scale archive | +Package-size dependent | +Large histopathology images | +Moderate | +
| + Image Viewing + | +Thumbnails; delegates to external viewers | ++ Built-in multi-dimensional viewer (OMERO.web, + OMERO.figure) + | +Built-in viewer (idr.openmicroscopy.org) | +Built-in 3D/4D viewer | +Links to external Zarr viewers (e.g. Vizarr) | +Links to BioStudies viewer | +Built-in preview for some types | +Built-in annotation/viewer | +Built-in multi-dim viewer | +
| + User Annotations / Editing + | +Yes — add/edit metadata columns in-browser | +Yes — key-value pairs, tags, ratings, ROIs | +No (read-only) | +No (read-only) | +No (read-only) | +No (submission-based) | +Yes — package metadata | +Yes — spatial annotations, ontology terms | +Yes — tags, gobjects | +
| + Programmatic API + | +DuckDB SQL in-browser; no REST API needed | ++ Full REST + JSON API; Python (omero-py), Java, CLI + | +REST API (same as OMERO) | +REST API | +None (static JSON) | +REST API (BioStudies) | +Python SDK, REST API | +REST API, Python client | +REST API, Python/MATLAB | +
| + Multi-User / Auth + | +No — single-user local tool | +Yes — LDAP, groups, permissions | +Public (no auth) | +Public (no auth) | +Public (no auth) | +Submission requires login | +Yes — teams, RBAC | +Yes — LDAP, project roles | +Yes — user/group permissions | +
| + Primary Use Case + | ++ Explore & filter large tabular file metadata; + share queries via URL + | ++ Manage, view & annotate microscopy data for a + lab/institute + | +Publish & browse reference image datasets | +Share quantitative bio-dynamics data | +Discover & link to OME-Zarr datasets | +Archive & publish bioimaging data | +Version & share data packages | ++ Collaborative image annotation (pathology, etc.) + | +Manage & analyze diverse bio-images | +
| + License + | +MIT | +AGPL v3 | +N/A (hosted) | +N/A (hosted) | +MIT | +N/A (hosted) | +Apache 2.0 | +Apache 2.0 | +BSD | +
+ BFF uses{" "}
+
+ DuckDB
+ Group files by any combination of metadata columns to create a navigable + folder-like hierarchy — without moving or reorganizing your actual + files. Switch grouping strategies instantly to explore different + dimensions of your dataset. +
++ Sharing is one of BFF's most powerful and distinctive features. + Every filter, sort, grouping, and column layout you configure is encoded + directly into the URL. Copy the link and share it — anyone who opens it + sees exactly the same view of the data, without re-running any queries, + sending files, or setting anything up. +
++ This makes BFF uniquely suited for collaborative research and open + science: +
++ Most tools in this space either require server access to share data or + only link to a static dataset. BFF shares the exact filtered, sorted, + grouped view — making it a powerful tool for transparent and + reproducible science. +
++ BFF renders thumbnail previews for files in your dataset so you can + visually scan your data without opening each file individually. + Thumbnails appear inline in the file list and update dynamically as you + filter and group. +
+Thumbnail column
+ in your dataset — useful for large or complex files where
+ auto-generation isn't possible
+ + BFF connects directly to a variety of image viewers — web-based and + desktop. Select any file and open it in the viewer best suited for its + format and your workflow. +
++ + See the image viewer comparison table + +
+ + ), + }, + ], + }, +]; diff --git a/packages/web/src/components/UserGuide/content/app-information.tsx b/packages/web/src/components/UserGuide/content/app-information.tsx new file mode 100644 index 000000000..b487acded --- /dev/null +++ b/packages/web/src/components/UserGuide/content/app-information.tsx @@ -0,0 +1,391 @@ +import { Icon } from "@fluentui/react"; +import * as React from "react"; + +import { Page, PageSlug, SectionHeading } from "./types"; + +export const APP_INFORMATION_CONTENT: Page[] = [ + { + slug: PageSlug.Specifications, + title: "Specifications", + intro: "Technical specifications for BioFile Finder (BFF).", + sections: [ + { + heading: "File size and format compatibility", + body: ( + <> ++ BFF ingests metadata about biological files (a dataset), not the files + themselves. This metadata is intended to be tabular and can be stored as + the following formats: +
++ Information on file size limitations coming soon. +
++ Limitations around the files tracked within BFF are imposed by the + applications BFF links to for that given file. For example, FIJI will + only work with the files that it supports. BFF itself is agnostic to the + file types and sizes referenced in a dataset. +
+ + ), + }, + { + heading: "Browser and device compatibility", + body: ( + <> ++ For best performance and compatibility, we recommend using the latest + versions of the following browsers: +
++ BFF is optimized for desktop use and is not currently designed for + mobile devices. +
+ + ), + }, + { + heading: "Open source", + body: ( +
+ BioFile Finder is open-source and free to use. You can find the code, report
+ issues, and contribute on{" "}
+
+ GitHub
+ File format will heavily limit viewer options, but when multiple options + are feasible, the following information may help guide your decision. +
++ The following table offers comparisons between various supported + viewers. +
+| Feature | +Vol-E | +AGAVE | +FIJI / ImageJ | +Neuroglancer | +OME NGFF Validator | +Browser (web) | +Simularium | +VolView | +
|---|---|---|---|---|---|---|---|---|
| + Type + | +Web-based 3D volume viewer | +Desktop GPU-accelerated volume renderer | +Desktop image analysis suite | +Web-based volumetric viewer | +Web-based validation tool | +Native file preview | +Web-based simulation viewer | +Web-based 3D volume viewer | +
| + Platform + | +Web app (browser) | +Desktop (Windows, macOS, Linux) | +Desktop (Windows, macOS, Linux) | +Web app (browser) | +Web app (browser) | +Desktop (OS-native) | +Web app (browser) | +Web app (browser) | +
| + Installation required + | +No | +Yes (standalone app) | +Yes (Java-based) | +No | +No | +No (built into OS) | +No | +No | +
| + Cost + | +Free / open-source | +Free / open-source | +Free / open-source | +Free / open-source | +Free / open-source | +Free (bundled with OS) | +Free / open-source | +Free / open-source | +
| + Primary use case + | ++ Interactive 3D volume rendering of microscopy data + | ++ High-quality cinematic 3D rendering and path tracing + | ++ General-purpose image analysis, measurement, and + processing + | ++ Explore large-scale connectomics / volumetric neuro + datasets + | ++ Validate OME-Zarr/NGFF file structure and metadata + compliance + | +Quick preview of standard image/video files | ++ Visualize agent-based biological simulations over + time + | ++ Clinical and research DICOM/volume visualization + | +
| + Supported formats + | +OME-Zarr, TIFF, OME-TIFF | ++ OME-TIFF, TIFF, CZI, LIF, and other microscopy + formats + | +100+ formats via Bio-Formats | +Precomputed, N5, Zarr, NIFTI | +OME-Zarr (NGFF) only | +JPEG, PNG, TIFF, MP4, PDF (OS-dependent) | +Simularium, CytoSim, ReaDDy, Smoldyn | +DICOM, NIFTI, MHA, VTI, NRRD, Zarr | +
| + 3D volume rendering + | +Yes — real-time ray marching | +Yes — GPU path tracing, cinematic quality | +Limited — 3D Viewer plugin | +Yes — multi-scale, GPU-accelerated | +No | +No | +Yes — 3D agent trajectories and meshes | +Yes — GPU-accelerated ray casting | +
| + Multi-channel support + | +Yes | +Yes | +Yes | +Yes | +Validates channel metadata | +No | +N/A | +Yes | +
| + Time series / 4D + | +Yes | +Yes | +Yes | +Limited | +Validates time dimension metadata | +No | +Yes — primary feature | +Limited | +
| + Large data / streaming + | +Yes — streams OME-Zarr from cloud/HTTP | +No — loads full volume into GPU memory | +Limited | +Yes — designed for petascale | +Validates metadata only | +No | +Streams from URL | +Yes — progressive loading | +
| + Cloud / remote data + | +Yes — HTTP/S3 URLs | +No — local files only | +Limited | +Yes — GCS, S3, HTTP | +Yes — validates remote URLs | +No | +Yes | +Yes | +
| + Collaborative / sharing + | +Shareable URL with view state | +No | +No | +Yes — URL encodes full view state | +Shareable validation URL | +No | +Shareable URL | +Shareable URL via hosted instance | +
| + Best for + | ++ Quick interactive exploration of cloud-hosted + OME-Zarr volumes + | ++ High-quality figures and movies of 3D microscopy + data + | +Comprehensive image analysis and scripting | ++ Browsing terabyte+ volumetric datasets in the cloud + | +Checking OME-Zarr files before sharing | +Quickly previewing a standard image file | ++ Viewing and sharing spatiotemporal biological + simulations + | ++ Medical/research volumes with clinical-style tools + | +
| + Limitations + | +No analysis tools; limited format support | +Requires dedicated GPU; local files only | ++ Basic 3D rendering; struggles with very large + datasets + | ++ Steep learning curve; specific pre-tiled formats + only + | +Validation only; OME-Zarr only | +No scientific image capabilities | +Simulation data only | +Limited microscopy format support | +
| + {headerCell == null ? "" : String(headerCell)} + | + ))} +
|---|
| + {cell == null ? "" : String(cell)} + | + ))} +
+ Prepare a metadata file describing the files in your dataset. The + metadata file can be provided as CSV, Parquet, or JSON. Each row + typically represents a file, while columns contain metadata such as: +
++ See:{" "} + + Creating a metadata file + + ,{" "} + + Metadata guidance + +
+ ++ Your metadata file must include file paths or URLs pointing to the files + you want BFF to access. Those files can live: +
++ BFF is storage agnostic and does not require files to be moved into a + proprietary system. +
++ See:{" "} + + Storage options + + ,{" "} + + Viewer compatibility + +
+ +Open BFF and either:
++ Once loaded, BFF allows you to filter and search metadata, group files + dynamically, preview and open files in compatible viewers, and share + exact dataset views via URL. +
+ + ), + }, + { + heading: "Minimum requirements", + body: ( + <> +To use BFF, you only need:
+No backend, database, or server infrastructure is required.
+ + ), + }, + { + heading: "Common workflows", + body: ( +| Goal | +Typical setup | +
|---|---|
| Personal / local exploration | +Local dataset + local files | +
| Shared lab dataset | +Hosted dataset + shared storage | +
| Public publication companion | +Hosted dataset + public cloud storage | +
| Large-scale datasets | +Parquet + cloud storage | +
| Metadata validation / QC | +Dataset + metadata descriptor file | +
| File lineage / relationship tracking | +Dataset + provenance file | +
+ If data is intended to be publicly shared — like in a publication — + store the dataset and files referenced in the dataset in{" "} + + cloud storage + {" "} + to enable readers to explore the dataset and its files via a sharable + BFF link (URL). +
++ Note: You can use BFF as a way to circumvent having to publish all files + by publishing only the metadata file and instructing readers to request + files directly. This allows viewers to see metadata about every file in + the dataset without you paying for full cloud storage of each file. + Building on this approach, you can host thumbnails of each file so + readers can get a preview without you paying for full-resolution images + to live in the cloud. +
+ ++ A metadata file is organized as a table where each row typically + represents a file in your dataset and each column represents a metadata + field describing that file, such as a file path, experimental condition, + sample identifier, or other annotation. The structure is flexible—aside + from the required columns, you can define metadata fields that best + support your workflow. +
++ + See Specifications + {" "} + for more details. +
+ + ), + }, + { + heading: "Rows and columns", + body: ( + <> ++ Each row typically represents a file you want BioFile Finder to explore. + Files can be stored locally, on network-attached storage, in cloud + storage, or in public repositories. +
++ Advanced workflows may reference multiple files from a single row or + reference the same file across multiple rows. +
++ Columns can be anything that describes metadata fields relevant to your + workflow. The only exceptions are the required column described below, + and a few special optional columns that, if provided, enable special + features in BFF. +
+ + ), + }, + { + heading: "Required columns", + body: ( + <> +This column is required for BFF to locate and open your files.
+These optional columns enable specific features in BFF when provided.
++ Each row is a file. Columns can be anything meaningful to your workflow + — here a well position, gene target, and fluorophore. +
+ {renderUgTable(BASIC_METADATA_EXAMPLE_ROWS)} +
+
+ Download this example as CSV{" "}
+
+ Browse open-source datasets +
++ Visit{" "} + + Metadata guidance + {" "} + for a full description of recommended metadata practices, including more + CSV examples and templates. +
+ + ), + }, + { + heading: "Advanced capabilities (optional)", + body: ( + <> +BFF supports:
+
+ REMBI (Recommended Metadata for Biological Images), published in{" "}
+
+ Nature Methods in 2021{" "}
+
+
+ Download REMBI-based template{" "}
+
+ The following interpretation of the{" "}
+
+ FoundingGIDE{" "}
+
+ Fields included: Metadata Field, Study Description, Authors, + Organization, Publication, License, Release Date, Imaging Method, Cell + Line, Organism, Gene, Compound, Antibody, Channel — Content, Channel — + Biological Entity, Instrument, Dimension, Pixel/Voxel Size / Time + resolution, Study Unique ID, Dataset Unique ID, Pathology/Disease, + Phenotype, Organ, Analyzed Data. +
+
+
+ Download FoundingGIDE template CSV{" "}
+
+ See example descriptions for these fields in{" "} + + Describing columns in your dataset + + . +
+ + ), + }, + ], + }, + + { + slug: PageSlug.DescribingColumns, + title: "Describing columns in your dataset", + intro: + "Providing descriptions for columns in your datasets helps collaborators and readers understand the meaning of each column, especially when column names are abbreviated or use internal lab terminology.", + sections: [ + { + heading: "Providing column descriptions", + body: ( + <> ++ BFF can display tooltips that describe the columns in your dataset if + provided an additional file, referenced as a{" "} + “metadata descriptor file” in the app. This + file must contain three columns: +
+Open file link, which tells BFF the column represents a
+ link that can be opened with the “Open with…”
+ button. This is useful for pointing to alternative viewers or
+ related resources — for example, a column containing a direct link
+ to open a file in a specific tool.
+
+
+ Download this example as CSV{" "}
+
+ Traditional flat metadata tables work well when each file has a single + value for each attribute. But many experiments produce files associated + with several related values — for example, a plate image taken under + multiple drug doses, or a segmentation file linked to multiple cell + lines. Repeating those values across separate rows (one row per + condition) means losing the file-level grouping. Putting all values in a + single comma-separated string in one column makes filtering and sorting + unreliable. +
+Nested metadata columns solve both problems by letting you:
+Well.Dose without losing the surrounding well context).
+ BFF supports two kinds of nested columns:
+Microscope column with sub-fields{" "}
+ Model and Objective.
+ Well column where each file can be associated with
+ several wells, each described by Position,{" "}
+ Dose, and Cell Line.
+
+ Sub-fields appear in BFF as dotted annotation names —{" "}
+ Well.Dose or Microscope.Objective. You can
+ filter, sort, and group on any sub-field, and the full nested structure
+ is preserved when you download a metadata manifest.
+
+ Parquet is the recommended format for nested metadata because it + natively stores STRUCT and STRUCT[] columns with full type information. + No additional configuration is needed — BFF reads the schema + automatically. +
+
+ The following Python example (using{" "}
+
+ pandas
+ {" "}
+ and{" "}
+
+ pyarrow
+
+ ) creates a dataset with a STRUCT column (Microscope) and a
+ STRUCT[] column (Well):
+
+ {`import pandas as pd
+import pyarrow as pa
+import pyarrow.parquet as pq
+
+# Each row is a file.
+# "Microscope" is a plain STRUCT (one value per row).
+# "Well" is a STRUCT[] (multiple wells per row).
+data = [
+ {
+ "File Path": "/data/img_001.tif",
+ "Microscope": {"Model": "Zeiss LSM 980", "Objective": "40x"},
+ "Well": [
+ {"Position": "B3", "Dose": 0.5, "Cell Line": "HeLa"},
+ {"Position": "B4", "Dose": 1.0, "Cell Line": "HeLa"},
+ ],
+ },
+ {
+ "File Path": "/data/img_002.tif",
+ "Microscope": {"Model": "Leica SP8", "Objective": "63x"},
+ "Well": [
+ {"Position": "G9", "Dose": 2.0, "Cell Line": "U2OS"},
+ ],
+ },
+]
+
+# Define the explicit Parquet schema
+schema = pa.schema([
+ pa.field("File Path", pa.string()),
+ pa.field("Microscope", pa.struct([
+ pa.field("Model", pa.string()),
+ pa.field("Objective", pa.string()),
+ ])),
+ pa.field("Well", pa.list_(pa.struct([
+ pa.field("Position", pa.string()),
+ pa.field("Dose", pa.float64()),
+ pa.field("Cell Line", pa.string()),
+ ]))),
+])
+
+table = pa.Table.from_pylist(data, schema=schema)
+pq.write_table(table, "dataset.parquet")`}
+
+
+ Once loaded into BFF, annotations like Well.Position,{" "}
+ Well.Dose, and Microscope.Objective will
+ appear in the annotation picker and can be used for filtering, grouping,
+ and sorting.
+
+ In JSON, nested columns are expressed as objects (for STRUCT) or arrays + of objects (for STRUCT[]) within each row. The structure of the example + above expressed in JSON: +
+
+ {`[
+ {
+ "File Path": "/data/img_001.tif",
+ "Microscope": { "Model": "Zeiss LSM 980", "Objective": "40x" },
+ "Well": [
+ { "Position": "B3", "Dose": 0.5, "Cell Line": "HeLa" },
+ { "Position": "B4", "Dose": 1.0, "Cell Line": "HeLa" }
+ ]
+ },
+ {
+ "File Path": "/data/img_002.tif",
+ "Microscope": { "Model": "Leica SP8", "Objective": "63x" },
+ "Well": [
+ { "Position": "G9", "Dose": 2.0, "Cell Line": "U2OS" }
+ ]
+ }
+]`}
+
+
+ BFF infers the schema from the JSON structure. Rows where a nested field
+ is absent or null will have no value for that annotation.
+
+ CSV does not natively support nested or repeated values. If your source + data is in CSV and you need nested metadata, convert it to Parquet or + JSON first (for example, using pandas as shown above). +
++ If you load a CSV that was originally exported from BFF with nested + columns, the nested values will be serialized as strings. BFF will treat + those as plain text and will not reconstruct the nested structure. +
+ + ), + }, + { + heading: "Date and datetime sub-fields", + body: ( +
+ Date and datetime values inside nested columns are fully supported. Store
+ them as pa.date32() or{" "}
+ pa.timestamp("ms") in Parquet, or as ISO 8601 strings
+ (e.g., "2025-01-10") in JSON. BFF will recognize the
+ type from the schema and enable date-range filters on those sub-fields.
+
Experiment.Run.Channel),
+ very deep hierarchies can make the annotation picker harder to navigate.
+ + In BFF, open the data source panel by clicking the dataset name at the top + of the app. At the bottom of that panel you will find an optional field + labeled "Provenance file". Paste the URL or drag + in the file there to load it alongside your dataset. +
+ ), + }, + { + heading: "Provenance file format", + body: ( + <> +The provenance file should contain 6 columns:
+pointer, this should be the name of a dataset column
+ that encodes the relationship.
+ file if the child is a
+ file in the dataset; entity if it is metadata.
+ file if the parent is a
+ file; entity if it is metadata.
+ pointer if the
+ relationship is defined via a dataset column.
+
+
+ Download this example{" "}
+
+ Provenance is especially important in microscopy workflows that span + multiple levels of biological organization, such as plates, wells, and + individual image files. Without clear provenance linking each + segmentation file back to its original image, well, and plate context, + it becomes difficult to trace results back to the experimental setup. + Capturing these relationships ensures that derived data products remain + connected to their biological source, enabling validation, + troubleshooting, and reproducibility. +
++ In BFF, once a provenance file is loaded, each file row in the file list + will show a relationship indicator. Expanding a row reveals its linked + parent or child entities — for example, given the provenance schema + defined above, clicking a segmentation image will show the colony image + it was derived from and the well it originated in. +
++ Provenance is also critical when a single publication draws on images + from multiple datasets. If the origin of each image is not clearly + documented — which dataset it came from, how it was selected, whether it + was processed consistently — readers and collaborators may struggle to + interpret how comparable those images truly are. By maintaining + provenance across datasets, researchers can clearly communicate how + figures were constructed and allow others to navigate back to the full + underlying data for verification or reuse. +
+ + ), + }, + ], + }, +]; diff --git a/packages/web/src/components/UserGuide/content/index.ts b/packages/web/src/components/UserGuide/content/index.ts index e4ea9d777..f1f7bbecf 100644 --- a/packages/web/src/components/UserGuide/content/index.ts +++ b/packages/web/src/components/UserGuide/content/index.ts @@ -1,9 +1,36 @@ +// Content is split into per-section files to keep each file focused and reviewable. +// To add a new page: add its entry to the relevant section file. + export type { NavigationGroup, Page } from "./types"; +import { ABOUT_CONTENT } from "./about"; +import { APP_INFORMATION_CONTENT } from "./app-information"; +import { GETTING_STARTED_CONTENT } from "./getting-started"; import { OTHER_RESOURCES_CONTENT } from "./other-resources"; +import { REAL_WORLD_USE_CASES_CONTENT } from "./real-world-use-cases"; import { GroupSlug, NavigationGroup } from "./types"; export const CONTENT: NavigationGroup[] = [ + { + slug: GroupSlug.About, + title: "About", + pages: ABOUT_CONTENT, + }, + { + slug: GroupSlug.RealWorldUseCases, + title: "Real world use", + pages: REAL_WORLD_USE_CASES_CONTENT, + }, + { + slug: GroupSlug.AppInformation, + title: "App information", + pages: APP_INFORMATION_CONTENT, + }, + { + slug: GroupSlug.GettingStarted, + title: "Getting started", + pages: GETTING_STARTED_CONTENT, + }, { slug: GroupSlug.OtherResources, title: "Other resources", diff --git a/packages/web/src/components/UserGuide/content/real-world-use-cases.tsx b/packages/web/src/components/UserGuide/content/real-world-use-cases.tsx new file mode 100644 index 000000000..d0f0b7e7c --- /dev/null +++ b/packages/web/src/components/UserGuide/content/real-world-use-cases.tsx @@ -0,0 +1,634 @@ +import { Icon } from "@fluentui/react"; +import { kebabCase } from "lodash"; +import * as React from "react"; + +import { Page, PageSlug, SectionHeading } from "./types"; + +export const REAL_WORLD_USE_CASES_CONTENT: Page[] = [ + { + slug: PageSlug.UseCasesAndScenarios, + title: "Use cases & scenarios", + intro: + "BioFile Finder (BFF) is flexible enough to fit many different workflows and contexts. This page highlights common use cases observed across research labs, core facilities, and data teams — along with real-world scenarios showing how different types of users leverage BFF in their work.", + sections: [ + { + heading: "How people use BFF", + body: ( + <> ++ This table is a summary of known use cases. Read detailed descriptions + below. +
+| Use case | +Key BFF actions | +Problem BFF solves | +
|---|---|---|
| + + + {SectionHeading.ExploreScreeningResults} + + + | ++ Group by plate/treatment; filter by phenotype; share URL + | +Hours of scripting per query | +
| + + {SectionHeading.ValidateMetadata} + + | ++ Filter for blanks/duplicates; group to check counts; export + errors + | +Days of spreadsheet auditing | +
| + + {SectionHeading.InspectSubsetsOfImages} + + | ++ Multi-filter to exact subset; open in viewer; arrow-key + navigation + | +Hunting through folders by hand | +
| + + {SectionHeading.PerformQCOnDatasets} + + | ++ Aggregate counts per group; filter for anomalies; + cross-validate columns + | +Custom scripts per dataset | +
| + + {SectionHeading.ManageImageInventory} + + | ++ Host metadata file; browse by any column; shareable filtered + URLs + | +Building and maintaining a web portal | +
| + Compare across experimental dimensions + | ++ Pivot/group across multiple metadata axes (e.g., cell line × + staining × condition); rapidly switch views + | +Rewriting analysis scripts per comparison | +
| + Collaborative data exploration + | ++ Share filtered views; maintain consistent dataset state + across users; parallel exploration + | +Back-and-forth file exchange and re-alignment | +
| + Publish interactive datasets + | ++ Share public BFF links tied to figures; enable readers to + explore full datasets in-browser + | +Building custom portals or static supplements | +
+ A high-content screening run produces tens of thousands of images across + hundreds of wells, multiple plates, and several time points. The + pipeline outputs a Parquet or CSV manifest linking each image file to + its well position, compound treatment, concentration, cell line, and + measured phenotype scores. +
++ Load the manifest into BFF and immediately group files by Plate > + Treatment > Concentration to see how many images exist at each + condition. Filter to a specific compound and sort by phenotype score to + surface the most interesting wells. Click into a well to see thumbnails + of every image at that position. Share the filtered view with a + colleague by copying the URL — they see exactly the same subset without + re-running any queries. +
++ A genomics core runs CRISPR screens and outputs per-guide results as a + CSV. Researchers load it into BFF to filter by gene target, sort by + effect size, and quickly identify which guides to follow up on — without + writing R or Python code. +
+ + ), + }, + /* "Validate metadata" section — temporarily hidden + { + heading: SectionHeading.ValidateMetadata, + level: 3, + body: ( + <> ++ Before publishing a dataset or submitting to a repository, you need to + confirm that every file has complete, consistent metadata — no missing + cell lines, no mislabeled plates, no blank file paths. +
++ Load your metadata file and use BFF's filters to find gaps. Group + by "Cell Line" and look for a blank or "(No value)" + group — those are your missing entries. Sort by "File Path" to + spot duplicates or malformed paths. Filter for rows where + "Treatment" is empty to find unlabeled conditions. Use the + aggregate count at each folder level to verify expected file counts per + condition (e.g., "I should have 96 images per plate — any plate + with fewer has missing data"). Export the problematic subset as a + CSV for correction. +
++ A museum digitization team loads their specimen catalog CSV into BFF to + check for records missing accession numbers, blank taxonomic + classifications, or broken file paths to scans — catching errors before + ingesting into their collection management system. +
+ + ), + }, + */ + { + heading: SectionHeading.InspectSubsetsOfImages, + level: 3, + body: ( + <> ++ You don't want to look at all 50,000 images. You want to look at a + very specific slice — maybe failed QC images, or images from a + particular experimental condition, or everything captured on a specific + date. +
++ Apply filters to narrow down to exactly the subset you care about: + "Cell Line = iPSC" AND "Plate = 007" AND "QC + Status = Failed". The file list updates instantly to show only + matching files. Click any file to see its full metadata in the detail + panel. Open the image directly in your preferred viewer (FIJI, AGAVE, + Neuroglancer, or the browser) to visually inspect it. Navigate through + the filtered list with arrow keys to quickly scan through the subset + one-by-one. +
++ A pathology lab filters their slide inventory to all H&E-stained + tissue sections from a specific patient cohort and date range, then + opens each in their whole-slide viewer to confirm stain quality before + analysis. +
+ + ), + }, + { + heading: SectionHeading.PerformQCOnDatasets, + level: 3, + body: ( + <> ++ Quality control means checking that your data is complete and correct + before you build on it — the right number of files, sensible values, + nothing blank, corrupted, or mislabeled. If you've tried to do this + by scrolling through a huge spreadsheet, you know it gets unmanageable + fast — and you shouldn't have to write code or formulas to catch + these problems. +
++ Drop your metadata file into BFF and let it do the checking for you — no + scripts, no coding. The aggregate info bar shows your total file count + at a glance. Group by "Plate," then "Well," to see + how many images are in each — any group with fewer than expected jumps + right out. Filter for files where "File Size" is 0 to find + empty or broken files. Sort by "Date Acquired" to make sure + nothing's out of sequence. Group by "Instrument" to + confirm everything came from the microscope you expected. You can even + stack filters to catch labeling mistakes — for example, show only + "Control" plates that aren't labeled "DMSO" — + all by pointing and clicking instead of programming. +
++ A lab manager preparing a dataset for publication receives images and a + metadata spreadsheet from a student. Rather than asking a programmer to + write a validation script, they open it in BFF to look for duplicate + sample names, spot rows missing a file path or a label, and confirm + every expected experiment is present — finding and fixing the mistakes + themselves before the data goes out. +
+ + ), + }, + { + heading: SectionHeading.ManageImageInventory, + level: 3, + body: ( + <> ++ You or your team have accumulated a large collection of files over + months or years. They live across local drives, shared network storage, + or cloud buckets. You have metadata about them — maybe a database + export, maybe a painstakingly maintained spreadsheet — and you need an + easy way to browse, search, and share access to this inventory without + maintaining a server. +
++ Export your inventory as a Parquet file (or maintain it as a CSV) with + columns for file path, file name, and any annotations that matter to + your team (project, investigator, organism, imaging modality, date, + etc.). Host the file on a web server, S3 bucket, or just keep it local. + Point BFF at it. Your entire team can now browse the inventory by any + column, search for specific files, and open them directly. Add a source + metadata file to provide human-readable descriptions for each column. + When someone asks "do we have any confocal images of iPSC-derived + cardiomyocytes from 2024?", the answer is three clicks away instead + of a Slack thread. +
++ A natural history museum has 200,000 digitized specimen records in a CSV + exported from their collection database. They host a BFF instance on + their website so visiting researchers can browse specimens by taxonomy, + collection site, and date — filtering to exactly the subset relevant to + their study and downloading a manifest of matching file paths. +
+ + ), + }, + { + heading: "Real-world scenarios", + body: ( + <> ++ + I have thousands of images and I just want to find the right ones. + +
++ You ran a plate screen last week and now need to find every image from + Well A3 treated with Drug X. Your files are scattered across folders, + drives, or cloud storage, with no easy way to search by experimental + conditions. BFF lets you load a spreadsheet of your file metadata and + instantly filter, sort, and group by any column—cell line, treatment, + plate, date, or anything else you need. No coding, no databases, no IT + tickets. Just drag, drop, and find your files. +
++ + I want to query millions of files without writing a pipeline to do + it. + +
++ You have a Parquet manifest with 10 million rows of imaging metadata. + You need to pull a specific subset for your next analysis run. BFF runs + full SQL queries in your browser via DuckDB—no server, no cluster, no + credentials. Filter by any combination of annotations, copy out the file + paths you need, and get back to your actual work. Share your exact query + with a collaborator by copying the URL. +
++ + I want to give users self-service data access without building a + portal. + +
++ Your team maintains the imaging pipeline. Scientists keep asking you to + "just pull all the files where..." and it turns into a JIRA + ticket every time. BFF is a zero-infrastructure frontend: point it at a + Parquet file on S3 or a CSV on a web server and your users can explore, + filter, and export on their own. No backend to deploy, no API to + maintain, no accounts to manage. Host a static web page and you're + done. +
++ I need to make my shared data actually usable. +
++ You run a core imaging facility or oversee a lab generating terabytes of + data. Your shared drive has 50,000 files and a naming convention that + made sense two years ago. BFF turns any metadata spreadsheet into a + searchable, filterable, shareable interface. Publish a dataset with a + BFF link and reviewers, collaborators, or new lab members can explore it + immediately—no software to install, no accounts to create. +
++ I want to make my collection metadata interactive. +
++ You have a CSV with 200,000 digitized specimens, each with accession + numbers, taxonomic classifications, collection dates, and file paths to + high-resolution scans. BFF turns that spreadsheet into a browsable, + filterable, groupable interface—right in the browser. Let researchers + explore your collection by species, date range, or geographic origin. + Share a filtered view as a URL. No web developer needed. +
+ + ), + }, + ], + }, + + { + slug: PageSlug.ExampleAICS, + title: "The cell science accelerator at Allen Institute", + intro: + "BioFile Finder (BFF) was used in publication by the cell science accelerator at Allen Institute.", + sections: [ + { + heading: "", + body: ( + <> +
+
+ Open publication{" "}
+
+
+ View dataset in BFF{" "}
+
+ In this study on epithelial-to-mesenchymal transition (EMT), the authors + generated a large-scale microscopy dataset consisting of 3,538 3D + Z-stack datasets across 37 experimental conditions, 8 cell lines, and 9 + antibody stainings. BioFile Finder (BFF) was used to organize and + explore this complex dataset without relying on a fixed folder + hierarchy. Instead, BFF enabled dynamic filtering, grouping, and + navigation based on metadata, allowing users to analyze the data across + multiple dimensions (e.g., comparing stainings across cell lines) + without duplicating files. This approach improved collaboration between + experimental and computational researchers, supported parallel analysis + workflows, and reduced friction in large-scale data exploration. + Additionally, BFF was used to share the dataset publicly, enabling + readers to directly access figure-associated data, explore full 3D + timelapse datasets in the browser, and interact with the dataset using + the same flexible metadata-driven framework. +
+++ + ), + }, + ], + }, + + { + slug: PageSlug.ExampleAIBS, + title: "The brain science accelerator at Allen Institute", + intro: + "BioFile Finder (BFF) was used in publication by the brain science accelerator at Allen Institute.", + sections: [ + { + heading: "", + body: ( + <> ++ “Every organizational choice comes at the cost of another. In + other words, every choice is a bad choice.” — Antoine + Borensztejn, author +
++ “BioFile Finder (BFF) allowed us to break away from this + constraint entirely.” — Antoine Borensztejn,{" "} + author +
++ “We believe this approach sets a new standard for FAIR data + sharing, and will significantly improve the accessibility, + transparency, and reuse of complex biological datasets.” + — Antoine Borensztejn, author +
+
+
+ Open publication{" "}
+
{" "}
+
+ View dataset in BFF{" "}
+
+ Yoav Ben-Simon from the Allen Institute for Brain Science describes + using BioFile Finder (BFF) as a flexible data management and sharing + platform for imaging datasets related to viral vector targeting in the + brain. BFF was used to organize datasets in a spreadsheet-like + interface, enabling intuitive querying, filtering, and restructuring of + data without requiring custom software development. The tool allowed + users to quickly create and curate datasets, organize them + hierarchically based on relevant features, and visualize grouped image + sets with thumbnails. This significantly lowered the barrier to entry + for data management and sharing, enabling non-engineers to deploy and + share datasets via simple links rather than building dedicated web + interfaces. Additionally, BFF facilitated collaboration by allowing + teams to interact with shared datasets dynamically and supported reuse + across different domains, extending from cell imaging to brain section + and genomic data visualization. +
+++ + ), + }, + { + heading: "Video", + body: ( + <> ++ “BioFile Finder is a data management tool… like a fancy + spreadsheet so that you can interact with it in multiple different + ways.” — Yoav Ben-Simon, author +
++ “I can create and curate data sets in two or three clicks of a + button.” +
++ “It doesn't require exchanging of files—it just + requires exchanging of links.” — Yoav Ben-Simon,{" "} + author +
++ “It was really easy for us to repurpose it… from + looking at individual cells to looking at images of brain sections + and genomic data.” — Yoav Ben-Simon, author +
+
+ Check out this short video from the Allen Institute on how they and + AMBIOM at ISAS used BFF to organize and share their datasets. +
+ + + ), + }, + ], + }, + + { + slug: PageSlug.ExampleAMBIOM, + title: "AMBIOM at ISAS", + sections: [ + { + heading: "", + body: ( + <> ++ AMBIOM develops AI methods for very large microscopy datasets. Copying + petabyte-scale image collections into another repository is often + impractical. BioFile Finder (BFF) instead indexes metadata while leaving + pixel data where it already resides—on institutional servers, cloud + object storage, or local storage. Researchers continue using their + existing storage infrastructure and permissions while gaining a unified + interface for discovery and curation. +
+ + ), + }, + { + heading: "BFF - an extensible ecosystem", + body: ( + <> ++ AMBIOM developed an "Uploader" tool that is compatible with + BFF. The BFF Uploader demonstrates the extensibility of the BFF + ecosystem. Rather than modifying BFF's core approach of operating + on metadata catalogs, ISAS built an external ingestion layer that + automates metadata generation and standardization. This extension + enables researchers to move from raw microscopy files to searchable BFF + datasets with minimal manual effort while preserving BFF's + decentralized architecture, where image data remains in its original + storage locations and only metadata is indexed for discovery and reuse. +
+
+
+ Watch a video about the ISAS BFF Uploader{" "}
+
+ Check out this short video from the Allen Institute on how they and + AMBIOM at ISAS used BFF to organize and share their datasets. +
+ + + ), + }, + ], + }, +]; diff --git a/packages/web/webpack/webpack.config.js b/packages/web/webpack/webpack.config.js index 53976a64d..87bc9a3bd 100644 --- a/packages/web/webpack/webpack.config.js +++ b/packages/web/webpack/webpack.config.js @@ -87,7 +87,7 @@ module.exports = ({ analyze, production } = {}) => ({ ], }, { - test: /\.png/, + test: /\.(png|jpe?g)/, type: "asset/resource", }, ],