Jungfraujoch/image_analysis/scale_merge/SearchSpaceGroup.h

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

#pragma once

#include <optional>
#include <string>
#include <vector>

#include "Merge.h"
#include "gemmi/symmetry.hpp"

struct SpaceGroupOperatorScore {
    std::string op_triplet_hkl;
    double cc = 0.0;
    int compared = 0;
    bool accepted = false;
};

struct SpaceGroupAbsenceBinScore {
    double d_min_A = 0.0;
    double d_max_A = 0.0;
    int absent_reflections = 0;
    int allowed_reflections = 0;
    double mean_absent_i_over_sigma = 0.0;
    double mean_allowed_i_over_sigma = 0.0;
    double absent_to_allowed_ratio = 0.0;
    bool used_for_decision = false;
    bool accepted = true;
};

struct SpaceGroupAbsenceScore {
    int absent_reflections = 0;
    int allowed_reflections = 0;
    int compared_bins = 0;
    int accepted_bins = 0;
    double mean_absent_i_over_sigma = 0.0;
    double mean_allowed_i_over_sigma = 0.0;
    double weighted_absent_to_allowed_ratio = 0.0;
    double worst_absent_to_allowed_ratio = 0.0;
    bool accepted = true;
    std::vector<SpaceGroupAbsenceBinScore> bins;
};

struct SpaceGroupCandidateScore {
    gemmi::SpaceGroup space_group;
    double mean_cc = 0.0;
    double min_cc = 0.0;
    int compared_total = 0;
    int accepted_operators = 0;
    int tested_operators = 0;
    bool accepted = false;
    SpaceGroupAbsenceScore absence_score;
    std::vector<SpaceGroupOperatorScore> operator_scores;
};

struct SearchSpaceGroupOptions {
    // If not set, search all crystal systems.
    std::optional<gemmi::CrystalSystem> crystal_system;

    // '\0' means: search all centerings compatible with the candidate system.
    char centering = '\0';

    // If true, Friedel mates are treated as equivalent when matching HKLs.
    bool merge_friedel = true;

    // Ignore reflections beyond this resolution (higher-resolution means smaller d).
    // Set to 0 to disable the cutoff.
    double d_min_limit_A = 0.0;

    // Optional I/sigma filter on merged reflections.
    double min_i_over_sigma = 0.0;

    // Acceptance thresholds for each tested rotational operator.
    double min_operator_cc = 0.80;
    int min_pairs_per_operator = 20;

    // Minimum total number of compared reflection pairs for a candidate SG.
    int min_total_compared = 100;

    // Test systematic absences from centering / screws / glides.
    bool test_systematic_absences = true;

    // Number of resolution bins used for absence-vs-allowed comparison.
    int absence_resolution_bins = 10;

    // Minimum counts in a bin before it contributes to the decision.
    int min_absent_reflections_per_bin = 5;
    int min_allowed_reflections_per_bin = 10;

    // Acceptance thresholds for absent/allowed <I/sig> ratios.
    double max_absent_to_allowed_i_over_sigma_ratio = 0.20;
    double max_absent_to_allowed_i_over_sigma_ratio_in_any_bin = 0.50;
};

struct SearchSpaceGroupResult {
    std::optional<gemmi::SpaceGroup> best_space_group;
    std::vector<SpaceGroupCandidateScore> candidates;
};

SearchSpaceGroupResult SearchSpaceGroup(
    const std::vector<MergedReflection>& merged,
    const SearchSpaceGroupOptions& opt = {});

std::string SearchSpaceGroupResultToText(
    const SearchSpaceGroupResult& result,
    size_t max_candidates_to_print = 20);