Implement integrated CMS Combine backend

[captainvogon]

Overview

This PR transitions the Combine statistical backend integration from a standalone YAML parser to a fully integrated, object-oriented Python framework.

Key Changes

• Object-Oriented Configs: Replaced YAML-based configs with a Pythonic Fit class (see examples/fcc_ee_zh_mumu_bb.py). Users now define channels, processes, and systematics natively in Python.
• Backend Integration (python/combine.py): Built the wrapper to dynamically load the user's fit script, instantiate the Fit class, and validate inputs.
• Datacard Generation: Implemented the logic to translate the Fit object into a production-ready Combine datacard.txt.
• Automated Testing: Added robust integration tests (test_combine_backend.py) that verify config sanitization, datacard generation, and isolated combine tool execution while gracefully handling CI environment limits.

Status

All framework integration tests and CI pipelines are passing successfully.

[Copilot]

Pull request overview

This PR introduces an object-oriented Python interface for defining Combine fits, adds a new fccanalysis fit subcommand to generate datacards (and optionally execute Combine), and wires an integration test into CTest to validate end-to-end behavior.

Changes:

• Added python/combine.py for loading user Fit scripts, validating configs, and writing Combine text datacards.
• Added python/fit.py and CLI plumbing (python/parsers.py, bin/fccanalysis) for the new fit subcommand with optional backend execution.
• Added an example OOP fit configuration and a CTest-driven Python integration test.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/python/test_combine_backend.py	Adds a Python integration test that runs fccanalysis fit and validates datacard generation / execution behavior.
tests/CMakeLists.txt	Registers the new Python integration test with CTest.
python/parsers.py	Adds a new fit subcommand parser and arguments.
python/fit.py	Implements the fccanalysis fit subcommand entry point and Combine execution wrapper.
python/combine.py	Implements Fit script loading, config sanitization/validation, and datacard writing.
examples/fcc_ee_zh_mumu_bb.py	Provides an example Fit class config for the new backend.
bin/fccanalysis	Wires the new fit command into the main CLI dispatcher.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[kjvbrt]

Hi @captainvogon, looks good. One thing to think about is how possible next step (plotting) will interact with the combine products. In the current state of the framework, the following step always require input directory, which is produced as output of the previous step.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (4)

python/combine.py:28

• jmax is computed from the first channel only, which can produce an incorrect header when different channels have different numbers of background processes. This can lead to invalid/inconsistent Combine datacards.

    def _get_metadata(self) -> Dict[str, int]:
        imax = len(self.channels)
        jmax = 0
        if self.channels:
            first_channel = list(self.channels.values())[0]

python/fit.py:28

• The CLI allows --backend pyhf, but run_fit() only handles combine. For pyhf, the command exits successfully without generating output or reporting an error.

    if backend == 'combine':
        from combine import generate_datacard
        generate_datacard(anapath, output_path)

python/combine.py:234

• The shape-systematics validation block references proc_name before it is defined when selecting mapping_rule, which raises NameError for any shape systematic. Additionally, the validation currently assumes variations are named by appending _{syst}{Up/Down} to the nominal template, ignoring the $SYSTEMATIC template token when provided.

                # Extract the ROOT file path (assumes space-separated path and inner structure mapping)
                root_file_path = mapping_rule.split()[0]

                if not os.path.isfile(root_file_path):

tests/CMakeLists.txt:36

• set_tests_properties(... DEPENDS get_test_inputs) references a CTest test named get_test_inputs, but input downloading is performed at CMake configure time (top-level CMakeLists.txt) and there is no such CTest test. This dependency will be ignored and may emit CTest warnings.

    # Ensure test data assets are fully downloaded via CI before running this test
    set_tests_properties(test_combine_fit_backend PROPERTIES DEPENDS get_test_inputs)
endif()

[kjvbrt]

if user provides --out as well on the command line, who's --out wins?