PhaseFinder Help

1. Overview

PhaseFinder's screen has three main areas:

• Sidebar (left) — drop zone for FCS files, the DNA-content channel selector, and the main action buttons (Plot Channel Events, Cell Cycle Modeling, Calculate Statistics).
• Plot panel (top of the workspace) — appears once you plot a channel; shows the overlaid event histogram, its controls, and (once modeling starts) the DJF fit overlay and results table.
• Metadata table panel (bottom of the workspace) — one row per loaded FCS file with editable annotations, sorting, filtering, and optional summary-statistics columns.

The header also has Load session and Save session buttons for saving your work to a file and restoring it later (see Saving & Loading Sessions).

2. Running PhaseFinder

PhaseFinder is a static site with no backend, install step, or account. Open index.html from a local web server (recommended) or directly from disk. A few features — the Dean–Jett–Fox curve-fitting libraries loaded from a CDN, and the background file-loading worker — are more reliable when served over http:// rather than opened as a file:// path.

If PhaseFinder cannot reach its two CDN-hosted math libraries (used only for curve fitting and peak detection), everything except Cell Cycle Modeling continues to work normally.

3. Loading FCS Files

Load one or more .fcs files by either:

• Dragging them onto the Drop FCS files here zone in the sidebar, or
• Clicking the drop zone to open a file picker.

PhaseFinder reads only each file's header and metadata (TEXT segment) at load time, so adding many files is fast — the actual event data for a channel is only read once you plot or compute statistics on it.

• Files that duplicate an already-loaded filename are rejected with a status message; nothing is re-loaded.
• Newly loaded files appear checked (included) in the metadata table by default — unless a plot already exists, in which case new files start unchecked so they don't unexpectedly change an existing plot.
• The sidebar shows a running Loaded FCS files (N) list once at least one file is loaded.
• A progress overlay reports read progress for larger batches of files.

If you collapse the sidebar (see Layout Controls), a compact icon rail still lets you drop or browse for more files, change the channel, and plot.

4. The Metadata Table

Every loaded file becomes one row in Table of Loaded FCS Samples. Each row has a checkbox; only checked rows are included the next time you plot. The filename column is read-only (shown without its .fcs extension); every other column is editable.

Editing annotations

Click into any annotation cell to type a value directly — strain, replicate, arrest status, timepoint, or whatever custom columns you've configured (see below). Edits are stored immediately and are included if you save a session or export the table.

Sorting & filtering

• Sort: click a column header's label to toggle ascending/descending, or click one of the small ▲ / ▼ arrows to jump straight to that direction. The Timepoint column sorts numerically even though it's stored as text.
• Filter: click the pill under a column header to open a checklist of that column's distinct values; check one or more values to show only matching rows. Clear the checkboxes to show all rows again.
• Filtering hides and deselects: a row hidden by a filter is automatically unchecked, so what's plotted always matches "visible ∩ checked". Removing the filter does not automatically re-check the row.
• The header checkbox selects or deselects every currently visible row (it shows an indeterminate dash when only some visible rows are checked).

Filename metadata wizard

Rather than guessing annotation values, PhaseFinder lets you derive metadata columns directly from each filename. The wizard opens automatically about a second after your first files load (only once per browser tab); you can reopen it any time via the ⌗ icon in the table's title bar (it's disabled until at least one file is loaded).

The wizard splits each filename (extension already stripped) into pieces using one or more split steps, applied in order to whatever text remains after the previous step:

• Delimiter — splits at the first occurrence of a fixed character or string, e.g. _.
• Fixed width — splits at a character position. Enter one or more comma/space-separated break positions, or type a column width into the small box and click Set to convert it into a break position automatically.
• Regex — splits using a JavaScript regular expression. If the pattern has a capture group, the captured text becomes the column value (useful for pulling a token out of the middle of a name); otherwise everything before the match becomes the value.

Every step (and the final Remainder, i.e. whatever text is left after all steps) gets its own column name and a Hide checkbox to exclude it from the table entirely. Use Add Step to add another split, or the step's Remove button to delete it (at least one step must remain). The Preview panel on the right shows how the first 20 loaded filenames would split with the current configuration, updating live as you edit.

• Apply commits the configured columns, replacing whatever custom columns exist. Values already typed for a column are kept if that column's field key is unchanged; values for genuinely new columns are filled in from the split.
• Filename Only clears all custom columns, leaving just the read-only Filename column.
• Cancel (or the Esc key) discards any unsaved edits in the wizard.

The last-applied split configuration is remembered in your browser (not tied to any one set of files) and is reapplied automatically to files you load later, and is also captured when you save a session.

Exporting to TSV

The ⇩ icon in the table's title bar exports exactly the currently visible rows (respecting active filters) as a tab-separated .tsv file, including every metadata column and any summary-statistics columns currently shown.

5. Choosing a Channel

The Select channel dropdown lists every parameter label seen across all loaded files (preferring each file's $PnS label, falling back to $PnN, then a generic P<n>). PhaseFinder guesses a likely DNA-content area channel automatically (looking for names containing patterns like DAPI_A, DNA_A, or ending in _A/AREA) and pre-selects it when possible — check that the suggestion is right before plotting.

Plot Channel Events stays disabled until at least one file is loaded and a channel is chosen.

If you change the channel after already plotting, PhaseFinder pre-loads the newly selected channel's data in the background (showing progress) without disturbing the currently visible plot; click Plot Channel Events again to switch the plot over to it.

6. Plotting Events

Click Plot Channel Events to load the selected channel's data for every checked row and draw an overlaid event histogram (x-axis: the chosen channel; y-axis: number of events). The plot panel title reports the number of plotted samples and total events.

The plot stays live afterward: checking or unchecking a row in the metadata table immediately adds or removes its curve — unchecking a row does not discard its already-loaded data, so re-checking it is instant. After the first plot, the button turns blue as a reminder that a channel is already plotted; click it again any time to refresh.

Color by, bins, corrections

• Color by — File gives every sample its own color; Strain groups samples sharing the same Strain annotation under one color.
• Bins — the histogram bin count (16–1024, default 512).
• Remove debris/background — before plotting (and fitting), builds a 256-bin histogram over the 0.2–99.8 percentile range, detects the G1/G2 peaks, estimates each peak's width, and keeps only events between roughly G1 − 4σ and G2 + 4σ (clamped to sane multiples of G1).
• Remove aggregates/doublets — when matching height and/or width channels can be linked to the selected area channel, removes events whose height/width ratio is far from the robust median (median ± 4 MAD-based sigma). If no matching height/width channel exists for a sample, that sample is left alone and PhaseFinder says so in the readout.

Both correction toggles apply to plotting and to cell-cycle modeling, and the readout below the controls reports how many events were removed (or that the required channels weren't available).

7. Cell Cycle Modeling (Dean–Jett–Fox)

Once a channel is plotted, the Cell Cycle Modeling button becomes enabled. Clicking it fits a Dean–Jett–Fox model (a G1 Gaussian, a G2 Gaussian pinned at roughly twice the G1 mean, and an S-phase bridge between them) to the first currently plotted sample and overlays the fitted total plus filled G1/S/G2 components.

Each sample's legend entry gains a small checkbox once modeling has started — check additional samples to fit and overlay them too (each gets an independent fit); uncheck to remove a fit without discarding the underlying data. A shared readout beneath the plot controls lists each shown fit's %G1 · %S · %G2.

Peak detection first looks for a matching G1/G2 peak pair around a 2× DNA-content ratio; when multiple samples are being modeled, PhaseFinder also estimates one shared "run G1" position so every sample's fit is anchored consistently.

Peak threshold

Tick Peak threshold to reveal a draggable grey line marking the minimum event count a histogram peak must reach to be considered during peak detection (default: 5% of the tallest shown bin). Drag it up to ignore small/noisy peaks, or down to include more candidate peaks; releasing the line re-detects peaks and refits every shown sample.

Fit results table

Every visible fit adds a group to the results table beside the plot: a title row with the sample name and its Strain/Replicate/Nocodazole Arrest/Timepoint annotations, followed by one row per phase (G1, S, G2) giving that phase's percent of events, fitted mean, and fitted standard deviation.

8. Summary Statistics

Calculate Statistics opens a modal where you can pick any loaded channel and one or more statistics — Mean, Std Dev, Median, Min, Max, or All — computed per file across every loaded sample (not just checked rows). Statistics already present for the selected channel are shown as disabled, already-checked boxes so you don't recompute them.

Results are added to the metadata table as new grouped columns (e.g. GFP/FITC-A Summary Statistics spanning Mean / Std Dev / …), and the table header switches to a two-row layout to accommodate them. A progress bar tracks the calculation, which loads each file's data as needed (a file already loaded for plotting reuses that cached data).

9. Saving & Loading Sessions

Because PhaseFinder keeps no server-side state, a session file (a human-readable .toml file) is how you resume work later or share a configured analysis with someone else.

Save session writes:

• The list of loaded filenames (not the file contents themselves — browsers don't expose real filesystem paths to web pages, so only names are stored).
• Every metadata column and its values, plus the active filename-splitting template.
• Table state: which rows are checked, the active sort, and active column filters.
• Plot settings: channel, color-by, bin count, both correction toggles, and the peak-threshold visibility.
• Any summary statistics you've computed (so they're recomputed automatically on load).
• Layout: sidebar/panel collapsed states, sidebar width, and panel heights.

Load session reads a session file back, restores all of the above, and then tries to relocate the original FCS files by name:

• Chrome / Edge / other Chromium browsers — prompts you to pick the folder containing the files once; the folder handle is remembered (in the browser's IndexedDB) so future loads of sessions from that folder only need a one-click permission re-grant, not a fresh folder pick.
• Firefox / Safari — opens a native folder picker each time, since these browsers don't expose a persistent folder-handle API.
• Files from the session that aren't found in the selected folder are reported by name so you can locate them manually.

10. Layout Controls

• Collapse the sidebar using the arrow icon in its title bar; a slim icon rail remains for uploading files, choosing a channel, and plotting.
• Resize the sidebar by dragging the vertical handle between the sidebar and the workspace.
• Resize the plot vs. table by dragging the horizontal handle between the plot panel and the metadata table panel (only draggable while both panels are expanded).
• Collapse the plot panel or the table panel independently using the minimize icon in each panel's title bar, to focus on the other.

All of the above are captured when you save a session, so a saved layout is restored along with your data.

11. Resetting the App

Click the PhaseFinder logo in the header to reload the page for a clean slate — this clears every loaded file, annotation, selection, filter, and plot. Save a session first if you want to keep your work.

12. Typical Workflow

1. Open PhaseFinder in a browser (ideally served over http://, not opened directly from disk).
2. Drop your .fcs files onto the drop zone, or click it to choose files.
3. Wait for metadata loading to finish; watch the progress overlay for large batches.
4. When the filename metadata wizard pops up, configure split steps so your filenames map cleanly onto Strain / Replicate / Nocodazole Arrest / Timepoint (or whatever columns make sense for your experiment), check the live preview, then click Apply.
5. Review and hand-edit any annotations the wizard couldn't infer, using the table's sort and filter controls to spot-check groups of samples.
6. Confirm (or change) the DNA-content channel in the sidebar.
7. Check the rows you want in the plot — unchecking removes a sample without losing its already-loaded data.
8. Click Plot Channel Events. Adjust Color by and Bins, and toggle the debris/doublet corrections if your data needs them.
9. Click Cell Cycle Modeling to fit the first plotted sample, then use each sample's legend checkbox to fit additional samples as needed. Tick Peak threshold if automatic peak detection needs a nudge.
10. Optionally, use Calculate Statistics to compute per-file summary statistics for any channel, and export the table to TSV for use elsewhere.
11. Click Save session before closing the tab so you (or a collaborator) can pick this exact analysis back up later.

13. Tips, Limits & Troubleshooting