Jungfraujoch/image_analysis/scale_merge/RfreeFlags.h

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only

#pragma once

#include <cstddef>
#include <cstdint>
#include <optional>
#include <vector>

#include "../../common/Reflection.h"
#include "../../common/UnitCell.h"
#include "gemmi/symmetry.hpp"

// Assign R-free (test-set) flags to merged reflections. With the cell given, the flag is a pure
// function of the reflection's orbit under the LATTICE HOLOHEDRY (the metric symmetry of the cell,
// which contains the merging group); without one, or when the cell does not carry the merging group,
// of its Friedel-merged (Laue) ASU key in space_group. That gives four properties:
//  - all symmetry- and Friedel-equivalent reflections share one flag, so a Bijvoet pair I(+)/I(-)
//    is never split across the work and free sets;
//  - with the cell, twin-law mates share one too, and every file of one crystal - whatever space
//    group it is merged in - carries the same free set;
//  - the assignment is reproducible run-to-run and independent of merge/call order;
//  - it depends only on the reflection index, not on the dataset's resolution range or contents, so
//    every dataset of one crystal form gets the SAME free set (needed for multi-dataset campaigns:
//    ensemble refinement, PanDDA). A uniform hash draws ~rfree_fraction of the distinct reflections.
//
// min_free_reflections floors the test-set size: on small data, where rfree_fraction would give too
// few test reflections for a statistically stable R-free (Brunger's ~500-2000 rule), the fraction is
// lifted so ~min_free_reflections distinct reflections are free - but never above 10% (a large test
// set steals working data for no gain). For ordinary data (rfree_fraction already clears the floor)
// this is inactive and the fraction stays flat, so the cross-dataset-identical property above holds;
// the floor only lifts the fraction on genuinely small datasets, where per-dataset R-free stability
// matters more than cross-dataset identity (and a shared reference/ApplyReferenceFreeFlags is the way
// to keep exact identity there). Pass 0 to disable the floor.
void AssignRfreeFlags(std::vector<MergedReflection> &merged, const gemmi::SpaceGroup &space_group,
                      double rfree_fraction, int min_free_reflections = 500,
                      const std::optional<UnitCell> &cell = std::nullopt, size_t nthreads = 1);

// Override the R-free flags on `merged` from a reference set (e.g. a reference MTZ's FreeR_flag
// column), so an entire campaign shares one test set. A merged reflection whose Friedel-merged
// (Laue) ASU key matches a reference reflection takes the reference's flag; reflections with no
// match keep the flag they already carry (the deterministic per-hkl hash from AssignRfreeFlags).
// Returns the number of merged reflections matched to the reference (for logging).
size_t ApplyReferenceFreeFlags(std::vector<MergedReflection> &merged, const gemmi::SpaceGroup &space_group,
                               const std::vector<MergedReflection> &reference);