makeLabelSheet.m

function makeLabelSheet(timepointFolder, nCellsOrFraction, perPage)

%% OFFLINE GROUND-TRUTH LABEL SHEET (headless-safe alternative to captureGroundTruth)
% Renders a random subset of cells to PNG montage pages you can open in any
% image viewer, so labelling does NOT depend on MATLAB's interactive figure
% backend (which throws a web-figure error in some R2026a setups). You count
% the real transients per cell by eye, then pass the counts to
% saveGroundTruthCounts to write the groundTruth_<tag>.mat that
% tuneCalciumParameters expects.
%
% USAGE:
%   makeLabelSheet(folder)            % 40 cells, 12 per page
%   makeLabelSheet(folder, 60)        % 60 specific cells
%   makeLabelSheet(folder, 0.15)      % 15% of cells (fraction < 1)
%
% Writes, INTO the timepoint folder:
%   labelsheet_<tag>_p*.png   the montage pages (cell # in each title)
%   labelsel_<tag>.mat        the exact cells chosen (order = labelling order)

    if nargin < 1 || isempty(timepointFolder), error('Give a timepoint folder path.'); end
    if nargin < 2 || isempty(nCellsOrFraction), nCellsOrFraction = 40; end
    if nargin < 3 || isempty(perPage), perPage = 12; end

    thisDir = fileparts(mfilename('fullpath'));
    settings = load(fullfile(thisDir, 'preprocessing_settings.mat'));
    duration = settings.analysisDurationSeconds;
    nSmooth  = settings.n;

    fp = fullfile(timepointFolder, 'fdata.mat');
    if ~isfile(fp), error('No fdata.mat in %s', timepointFolder); end
    S = load(fp); fn = fieldnames(S); fdata_original = S.(fn{1});

    si = ProcessNeuroCa(fdata_original, duration);
    ss = smoothCalciumSignals(si, nSmooth);
    numCells = size(ss, 1);
    if numCells == 0, error('No cells to label after processing.'); end
    frames = size(ss, 2);
    fps = si.fps;

    if nCellsOrFraction < 1
        numCheck = max(1, round(nCellsOrFraction * numCells));
    else
        numCheck = min(numCells, round(nCellsOrFraction));
    end

    rng(7);   % reproducible selection (also saved below)
    sel = sort(randperm(numCells, numCheck));

    [~, tag] = fileparts(timepointFolder);
    labelsel = struct('tag', tag, 'selectedCells', sel(:), 'n_atLabeling', nSmooth, ...
                      'analysisDurationSeconds', duration, 'numCellsTotalProcessed', numCells);
    save(fullfile(timepointFolder, ['labelsel_' tag '.mat']), 'labelsel');

    tsec = (1:frames) / fps;
    nPages = ceil(numCheck / perPage);
    for p = 1:nPages
        idx = (p-1)*perPage + (1:perPage);
        idx = idx(idx <= numCheck);
        fig = figure('Visible', 'off', 'Position', [10 10 1680 1050]);
        tl = tiledlayout(fig, 3, 4, 'Padding', 'compact', 'TileSpacing', 'compact');
        title(tl, sprintf('%s   page %d/%d   (n=%d)   -- count REAL transients per cell (0 = noise only)', ...
            tag, p, nPages, nSmooth), 'FontWeight', 'bold');
        for q = 1:numel(idx)
            c = sel(idx(q));
            ax = nexttile(tl);
            plot(ax, tsec, si.fdata(c, 1:frames), '-', 'Color', [0.75 0.75 0.75]); hold(ax, 'on');
            plot(ax, tsec, ss(c, :), 'b', 'LineWidth', 1.4); hold(ax, 'off');
            grid(ax, 'on');
            title(ax, sprintf('Cell %d      (#%d)', c, idx(q)), 'FontSize', 10);
            xlabel(ax, 'Time (s)');
        end
        outPng = fullfile(timepointFolder, sprintf('labelsheet_%s_p%d.png', tag, p));
        exportgraphics(fig, outPng, 'Resolution', 110);
        close(fig);
        fprintf('wrote %s\n', outPng);
    end

    fprintf('\nSelected %d cells. Titles show "Cell <realIndex>  (#<orderPosition>)".\n', numCheck);
    fprintf('Open labelsheet_%s_p*.png, count transients, then run:\n', tag);
    fprintf('  saveGroundTruthCounts(''%s'', [ ... %d counts in #1..#%d order ... ])\n', ...
        timepointFolder, numCheck, numCheck);
end