Production Configuration#
Modules provide functionality to configure a simulation production. This includes the derivation of energy, viewcone radius, and core scatter ranges and the calculation of the number of events to be simulated given a pre-determined metric.
calculate_statistical_uncertainties_grid_point#
Evaluate statistical uncertainties from DL2 MC event files.
- class production_configuration.calculate_statistical_uncertainties_grid_point.StatisticalUncertaintyEvaluator(file_path: str, metrics: dict[str, float], grid_point: tuple[float, float, float, float, float] | None = None)[source]#
Evaluate statistical uncertainties for a metric at a point in the observational parameter grid.
- Parameters:
- file_pathstr
Path to the DL2 MC event file.
- metricsdict
Dictionary of metrics to evaluate.
- grid_pointtuple, optional
Grid point (energy, azimuth, zenith, NSB, offset).
- calculate_energy_estimate()[source]#
Calculate the uncertainties in energy estimation.
- Returns:
- float
The calculated uncertainty for energy estimation.
- calculate_energy_threshold(requested_eff_area_fraction=0.1)[source]#
Calculate the energy threshold where the effective area exceeds 10% of its maximum value.
- Returns:
- float
Energy threshold value.
- calculate_max_error_for_effective_area()[source]#
Calculate the maximum relative uncertainty for effective area within the validity range.
- Returns:
- max_errorfloat
Maximum relative error.
- calculate_metrics()[source]#
Calculate all defined metrics as specified in self.metrics and store results.
- calculate_overall_metric(metric='average')[source]#
Calculate an overall metric for the statistical uncertainties.
- Parameters:
- metricstr
The metric to calculate (‘average’, ‘maximum’).
- Returns:
- float
The overall metric value.
- calculate_uncertainty_effective_area()[source]#
Calculate the uncertainties on the effective collection area.
- Returns:
- dict
Dictionary with uncertainties for the file.
- compute_efficiency_and_uncertainties(reconstructed_event_counts, simulated_event_counts)[source]#
Compute reconstructed event efficiency and its uncertainty assuming binomial distribution.
- Parameters:
- reconstructed_event_countsarray with units
Histogram counts of reconstructed events.
- simulated_event_countsarray with units
Histogram counts of simulated events.
- Returns:
- efficienciesarray
Array of calculated efficiencies.
- relative_uncertaintiesarray
Array of relative uncertainties.
- compute_reconstructed_event_histogram(event_energies_reco, bin_edges)[source]#
Compute histogram of events as function of reconstructed energy.
- Parameters:
- event_energies_recoarray
Array of reconstructed energy per event.
- bin_edgesarray
Array of energy bin edges.
- Returns:
- reconstructed_event_histogramarray
Histogram of reconstructed events.
corsika_limit_calculator#
Calculate CORSIKA thresholds for energy, radial distance, and viewcone.
- class production_configuration.corsika_limit_calculator.LimitCalculator(event_data_file, array_name=None, telescope_list=None)[source]#
Compute limits for CORSIKA configuration for energy, radial distance, and viewcone.
Event data is read from the reduced MC event data file.
- Parameters:
- event_data_filestr
Path to the event-data file.
- array_namestr, optional
Name of the telescope array configuration (default is None).
- telescope_listlist, optional
List of telescope IDs to filter the events (default is None).
- compute_limits(loss_fraction)[source]#
Compute the limits for energy, radial distance, and viewcone.
- Parameters:
- loss_fractionfloat
Fraction of events to be lost.
- Returns:
- dict
Dictionary containing the computed limits.
- compute_lower_energy_limit(loss_fraction)[source]#
Compute the lower energy limit in TeV based on the event loss fraction.
- Parameters:
- loss_fractionfloat
Fraction of events to be lost.
- Returns:
- astropy.units.Quantity
Lower energy limit.
- compute_upper_radius_limit(loss_fraction)[source]#
Compute the upper radial distance based on the event loss fraction.
- Parameters:
- loss_fractionfloat
Fraction of events to be lost.
- Returns:
- astropy.units.Quantity
Upper radial distance in m.
- compute_viewcone(loss_fraction)[source]#
Compute the viewcone based on the event loss fraction.
The shower IDs of triggered events are used to create a mask for the azimuth and altitude of the triggered events. A mapping is created between the triggered events and the simulated events using the shower IDs.
- Parameters:
- loss_fractionfloat
Fraction of events to be lost.
- Returns:
- astropy.units.Quantity
Viewcone radius in degrees.
- property core_distance_bins#
Return bins for the core distance histogram.
- property energy_bins#
Return bins for the energy histogram.
- plot_data(output_path=None, rebin_factor=2)[source]#
Histogram plotting.
- Parameters:
- output_path: Path or str, optional
Directory to save plots. If None, plots will be displayed.
- rebin_factor: int, optional
Factor by which to reduce the number of bins in 2D histograms for rebinned plots. Default is 2 (merge every 2 bins). Set to 0 or 1 to disable rebinning.
- property view_cone_bins#
Return bins for the viewcone histogram.
derive_corsika_limits#
Derive CORSIKA limits from a reduced event data file.
derive_production_statistics#
Calculate the event production statistics based on metrics.
Module for calculating the production event statistics based on statistical error metrics.
Contains the ProductionStatisticsDerivator
class, which derives the number of events for
both the entire dataset and specific grid points. Event statistic is calculated using error
metrics and the evaluator’s results.
- class production_configuration.derive_production_statistics.ProductionStatisticsDerivator(evaluator, metrics: dict)[source]#
Derives the production statistics based on statistical error metrics.
Supports deriving statistics for both the entire dataset and specific grid points like energy values.
- calculate_production_statistics_at_grid_point(grid_point: tuple) Quantity [source]#
Derive the production statistics for a specific energy grid point.
- Parameters:
- grid_pointtuple
The grid point specifying energy, azimuth, zenith, NSB, and offset.
- Returns:
- float
The derived production statistics at the specified grid point (energy).
- derive_statistics(return_sum: bool = True) Quantity [source]#
Derive the production statistics based on statistical error metrics.
- Parameters:
- return_sumbool, optional
If True, returns the sum of production statistics for the entire set of MC events. If False, returns the production statistics for each grid point along the energy axis. Default is True.
- Returns:
- u.Quantity
If ‘return_sum’ is True, returns the total derived production statistics as a u.Quantity. If ‘return_sum’ is False, returns an array of production statistics along the energy axis as a u.Quantity.
derive_production_statistics_handler#
Derives the required statistics for a requested set of production parameters through interpolation.
This module provides the ProductionStatisticsHandler
class, which manages the workflow for
derivation of required number of events for a simulation production using pre-defined metrics.
The module includes functionality to: - Initialize evaluators for statistical uncertainty calculations based on input parameters. - Perform interpolation using the initialized evaluators to estimate production statistics at a query point. - Write the results of the interpolation to an output file.
- class production_configuration.derive_production_statistics_handler.ProductionStatisticsHandler(args_dict, output_path)[source]#
Handles the workflow for deriving production statistics.
This class manages the evaluation of statistical uncertainties from DL2 MC event files and performs interpolation to estimate the required number of events for a simulation production at a specified query point.
generate_production_grid#
Module defines the GridGeneration
class.
Used to generate a grid of simulation points based on flexible axes definitions such azimuth, zenith angle, night-sky background, and camera offset. The module handles axis binning, scaling and interpolation of energy thresholds, viewcone, and radius limits from a lookup table. Additionally, it allows for converting between Altitude/Azimuth and Right Ascension Declination coordinates. The resulting grid points are saved to a file.
- class production_configuration.generate_production_grid.GridGeneration(axes: dict, coordinate_system: str = 'zenith_azimuth', observing_location=None, observing_time=None, lookup_table: str | None = None, telescope_ids: list | None = None)[source]#
Defines and generates a grid of simulation points based on flexible axes definitions.
This class generates a grid of points for a simulation based on parameters such as azimuth, zenith angle, night-sky background, and camera offset, taking into account axis definitions, scaling, and units and interpolating values for simulations from a lookup table.
- convert_altaz_to_radec(alt, az)[source]#
Convert Altitude/Azimuth (AltAz) coordinates to Right Ascension/Declination (RA/Dec).
- Parameters:
- altfloat
Altitude angle in degrees.
- azfloat
Azimuth angle in degrees.
- Returns:
- SkyCoord
SkyCoord object containing the RA/Dec coordinates.
- Raises:
- ValueError
If observing_time is not set.
- convert_coordinates(grid_points: list[dict]) list[dict] [source]#
Convert the grid points to RA/Dec coordinates if necessary.
- Parameters:
- grid_pointslist of dict
- List of grid points, each represented as a dictionary with axis
names as keys and values.
- Returns:
- list of dict
The grid points with converted RA/Dec coordinates.
- create_circular_binning(azimuth_range, num_bins)[source]#
Create bin centers for azimuth angles, handling circular wraparound (0 deg to 360 deg).
- Parameters:
- azimuth_rangetuple
(min_azimuth, max_azimuth), can wrap around 0 deg.
- num_binsint
Number of bins.
- Returns:
- np.ndarray
Array of bin centers.
- generate_grid() list[dict] [source]#
Generate the grid based on the required axes and include interpolated limits.
Takes energy threshold, viewcone, and radius from the interpolated lookup table.
- Returns:
- list of dict
A list of grid points, each represented as a dictionary with axis names as keys and axis values as values. Axis values may include units where defined.
interpolation_handler#
Handle interpolation between multiple StatisticalUncertaintyEvaluator instances.
- class production_configuration.interpolation_handler.InterpolationHandler(evaluators, metrics: dict, grid_points_production: list)[source]#
Calculate the required events for production via interpolation from a grid.
This class provides methods to interpolate production statistics across a grid of parameter values (azimuth, zenith, NSB, offset) and energy.
- build_grid_points_no_energy()[source]#
Build grid points without energy dimension.
- Returns:
- tuple
(production_statistics, grid_points_no_energy)
- interpolate() ndarray [source]#
Interpolate production statistics at the grid points specified in grid_points_production.
This method performs two types of interpolation: 1. Energy-independent interpolation using the sum of production statistics 2. Energy-dependent interpolation for each energy bin
- Returns:
- np.ndarray
Interpolated values at the query points.
merge_corsika_limits#
Class for merging CORSIKA limit tables and checking grid completeness.
- class production_configuration.merge_corsika_limits.CorsikaMergeLimits(output_dir=None)[source]#
Class for merging CORSIKA limit tables and checking grid completeness.
- check_grid_completeness(merged_table, grid_definition)[source]#
Check if the grid is complete by verifying all expected combinations exist.
This function checks whether all combinations of zenith, azimuth, nsb_level, and array_name specified in the grid_definition are present in the merged_table.
- Parameters:
- merged_tableastropy.table.Table
The merged table containing CORSIKA limit data.
- grid_definitiondict
Dictionary defining the grid dimensions with keys: ‘zenith’: list of zenith angles, ‘azimuth’: list of azimuth angles, ‘nsb_level’: list of NSB levels, ‘array_name’: list of array name
- Returns:
- tuple
A tuple containing: is_complete (bool) that is True if all expected combinations are found in the table, and info_dict (dict) with detailed information about the completeness check including expected points, found points, and missing combinations.
- merge_tables(input_files)[source]#
Merge multiple CORSIKA limit tables into a single table.
This function reads and merges CORSIKA limit tables from multiple files, handling duplicate grid points by checking for consistency and raising an error if inconsistent duplicates are found. It also converts the loss_fraction value from metadata to a table column and logs a message if multiple loss_fraction values are found.
- Parameters:
- input_fileslist of Path or str
List of paths to CORSIKA limit table files to merge.
- Returns:
- astropy.table.Table
The merged table with duplicates removed, containing all rows from input files. The table will be sorted by array_name, zenith, azimuth, and nsb_level.
- Raises:
- ValueError
If inconsistent duplicate grid points are found.
- plot_grid_coverage(merged_table, grid_definition)[source]#
Generate plots showing grid coverage for each combination of NSB level and array name.
Creates a series of heatmap plots showing which grid points (combinations of zenith and azimuth angles) are present or missing in the merged table, for each combination of NSB level and array name.
- Parameters:
- merged_tableastropy.table.Table
The merged table containing CORSIKA limit data.
- grid_definitiondict
Dictionary defining the grid dimensions with keys: ‘zenith’: list of zenith angles, ‘azimuth’: list of azimuth angles, ‘nsb_level’: list of NSB levels, ‘array_name’: list of array names
- Returns:
- list
List of Path objects pointing to the saved plot files.
- plot_limits(merged_table)[source]#
Create plots showing the derived limits for each combination of array_name and azimuth.
Creates plots showing the lower energy limit, upper radius limit, and viewcone radius versus zenith angle for each combination of array_name and azimuth angle. Each plot has lines for different NSB levels.
- Parameters:
- merged_tableastropy.table.Table
The merged table containing CORSIKA limit data.
- Returns:
- list
List of Path objects pointing to the saved plot files.
- read_file_list(file_list_path)[source]#
Read a list of input files from a text file.
The text file should contain one file path per line. Lines starting with ‘#’ are treated as comments and ignored. Empty lines are also ignored.
- Parameters:
- file_list_pathPath or str
Path to the text file containing the list of input files.
- Returns:
- list
List of Path objects for the input files.
- Raises:
- FileNotFoundError
If the file list does not exist.
- write_merged_table(merged_table, output_file, input_files, grid_completeness)[source]#
Write the merged table to file and save metadata.
Writes the merged table to the specified output file in ECSV format and saves relevant metadata about the merge process, including input files, grid completeness statistics, and row count.
- Parameters:
- merged_tableastropy.table.Table
The merged table to write to file.
- output_filePath or str
Path where the merged table will be written.
- input_fileslist of Path or str
List of input files used to create the merged table.
- grid_completenessdict
Dictionary with grid completeness information from check_grid_completeness.
- Returns:
- Path or str
The path to the written file (same as output_file).