Add event-level comparison tool for productions

docs/changes/2181.feature.md

@@ -0,0 +1 @@
+Add an event-level production comparison application with multi-production trigger-distribution plots.

docs/source/api-reference/index.md

@@ -25,6 +25,7 @@ reporting
 runners
 sim_events
 sim_telarray
+statistics
 simulators
 testing
 trigger

docs/source/api-reference/sim_events.md

@@ -49,3 +49,12 @@ Provide tools for reading, writing, and processing simulated shower and telescop
 .. automodule:: simtools.sim_events.output_validator
    :members:
 ```
+
+## Production comparison
+
+(sim_events_production_comparison-1)=
+
+```{eval-rst}
+.. automodule:: simtools.sim_events.production_comparison
+   :members:
+```

docs/source/api-reference/statistics.md

@@ -0,0 +1,14 @@
+(statistics)=
+
+# Statistics
+
+Statistical helper functions for comparing distributions and aligned histograms.
+
+## statistics
+
+(statisticsmodule)=
+
+```{eval-rst}
+.. automodule:: simtools.statistics
+   :members:
+```

docs/source/api-reference/visualization.md

@@ -114,3 +114,10 @@ the visualization module.
 .. automodule:: visualization.camera_plot_utils
    :members:
 ```
+
+## plot_event_level_production_comparison
+
+```{eval-rst}
+.. automodule:: visualization.plot_event_level_production_comparison
+   :members:
+```

docs/source/conf.py

@@ -85,6 +85,7 @@ def get_python_version_from_pyproject():
 nitpick_ignore = [
     ("py:class", "astropy.table.table.Table"),
     ("py:class", "astropy.units.quantity.Quantity"),
+    ("py:class", "collections.Counter"),
     ("py:class", "logging.Logger"),
     ("py:class", "numpy.float64"),
     ("py:class", "numpy.ndarray"),

docs/source/user-guide/applications.md

@@ -49,6 +49,7 @@ Parameters with the same functionality are named consistently the same among all
 :glob: true
 :maxdepth: 1
 
+simtools-compare-productions <applications/simtools-compare-productions>
 simtools-convert-all-model-parameters-from-simtel <applications/simtools-convert-all-model-parameters-from-simtel>
 simtools-convert-geo-coordinates-of-array-elements <applications/simtools-convert-geo-coordinates-of-array-elements>
 simtools-convert-model-parameter-from-simtel <applications/simtools-convert-model-parameter-from-simtel>

docs/source/user-guide/applications/simtools-compare-productions.rst

@@ -0,0 +1,6 @@
+
+simtools-compare-productions
+============================
+
+.. automodule:: compare_productions
+   :members:

pyproject.toml

@@ -73,6 +73,7 @@ optional-dependencies.tests = [
 urls."bug tracker" = "https://github.com/gammasim/simtools/issues"
 urls.documentation = "https://gammasim.github.io/simtools/"
 urls.repository = "https://github.com/gammasim/simtools"
+scripts.simtools-compare-productions = "simtools.applications.compare_productions:main"
 scripts.simtools-convert-all-model-parameters-from-simtel = "simtools.applications.convert_all_model_parameters_from_simtel:main"
 scripts.simtools-convert-geo-coordinates-of-array-elements = "simtools.applications.convert_geo_coordinates_of_array_elements:main"
 scripts.simtools-convert-model-parameter-from-simtel = "simtools.applications.convert_model_parameter_from_simtel:main"

src/simtools/applications/compare_productions.py

@@ -0,0 +1,75 @@
+#!/usr/bin/python3
+
+r"""Compare simulation productions at different comparison levels.
+
+The application accepts repeated production descriptors and dispatches to
+comparison-level specific implementations.
+
+Command line arguments
+----------------------
+production (repeated, required)
+    Production descriptor in two fields:
+    1) label
+    2) comma-separated event data file patterns
+comparison_level (str, optional)
+    Comparison level selector. Supported values are:
+    - events
+    - signals
+    - compute
+output_path (str, required)
+    Output directory for generated comparison plots.
+"""
+
+from simtools.application_control import build_application
+from simtools.sim_events.production_comparison import (
+    collect_production_metrics,
+    parse_production_arguments,
+)
+from simtools.visualization import plot_event_level_production_comparison
+
+
+def _add_arguments(parser):
+    """Register application-specific command line arguments."""
+    parser.initialize_application_arguments(["output_path"])
+    parser.add_argument(
+        "--production",
+        action="append",
+        nargs="+",
+        metavar=("LABEL", "EVENT_DATA_FILES"),
+        required=True,
+        help=(
+            "Production descriptor. "
+            "Use as: --production <label> <comma-separated file patterns>. "
+            "Repeat this argument as needed for multiple productions."
+        ),
+    )
+    parser.add_argument(
+        "--comparison_level",
+        choices=["events", "signals", "compute"],
+        default="events",
+        help="Comparison level to execute.",
+    )
+
+
+def main():
+    """See CLI description."""
+    app_context = build_application(
+        initialization_kwargs={"db_config": False, "output": True},
+    )
+
+    output_directory = app_context.io_handler.get_output_directory()
+    production_descriptors = parse_production_arguments(app_context.args["production"])
+
+    comparison_level = app_context.args["comparison_level"]
+    if comparison_level == "events":
+        metrics_per_production = collect_production_metrics(production_descriptors)
+        plot_event_level_production_comparison.plot(
+            metrics_per_production,
+            output_path=output_directory,
+        )
+    else:
+        raise NotImplementedError(f"Comparison level '{comparison_level}' is not implemented yet.")
+
+
+if __name__ == "__main__":
+    main()