Source code for ctlearn.tools.predict_LST1
"""
Predict the gammaness, energy and arrival direction from lstchain DL1 data.
"""
__all__ = ["LST1PredictionTool"]
import atexit
import numpy as np
import tables
from astropy import units as u
from astropy.coordinates import AltAz, SkyCoord
from astropy.table import Table, join, setdiff, vstack
from astropy.time import Time
from ctapipe.containers import (
ParticleClassificationContainer,
ReconstructedEnergyContainer,
ReconstructedGeometryContainer,
)
from ctapipe.coordinates import CameraFrame
from ctapipe.core import Tool
from ctapipe.core.tool import ToolConfigurationError
from ctapipe.core.traits import (
Bool,
CaselessStrEnum,
ComponentName,
Dict,
Int,
List,
Path,
UseEnum,
classes_with_traits,
flag,
)
from ctapipe.instrument.optics import FocalLengthKind
from ctapipe.io import read_table, write_table
from ctapipe.io.hdf5dataformat import (
DL1_SUBARRAY_TRIGGER_TABLE,
DL1_TEL_GROUP,
DL1_TEL_PARAMETERS_GROUP,
DL1_TEL_POINTING_GROUP,
DL1_TEL_TRIGGER_TABLE,
DL2_SUBARRAY_ENERGY_GROUP,
DL2_SUBARRAY_GEOMETRY_GROUP,
DL2_SUBARRAY_PARTICLETYPE_GROUP,
DL2_TEL_ENERGY_GROUP,
DL2_TEL_GEOMETRY_GROUP,
DL2_TEL_PARTICLETYPE_GROUP,
)
from ctapipe.reco.utils import add_defaults_and_meta
from dl1_data_handler.image_mapper import ImageMapper
from dl1_data_handler.reader import (
TableQualityQuery,
get_unmapped_image,
)
from ctlearn import __version__ as ctlearn_version
from ctlearn.tools.utils import (
FrameworkType,
get_lst1_subarray_description,
model_conv_backend,
setup_framework,
validate_conv_backend,
validate_trait_dict,
)
SUBARRAY_EVENT_KEYS = ["obs_id", "event_id"]
TELESCOPE_EVENT_KEYS = ["obs_id", "event_id", "tel_id"]
[docs]
class LST1PredictionTool(Tool):
"""
Tool to predict the gammaness, energy and arrival direction from lstchain DL1 data.
This tool is used to predict the gammaness, energy and arrival direction
from pixel-wise image data in lstchain format. The tool loads the trained models
from the specified paths and performs inference on the input data. The
input data is expected to be in the DL1 format of lstchain and the output data is
stored in the DL2 format of ctapipe. Besides the DL2 predictions, the tool creates
the SubarrayDescription of the LST-1 telescope and stores it in the output file.
In addition, the tool also creates the trigger, pointing and DL1 parameters tables
and stores them in the output file.
CAUTION: The tool is designed to work with the DL1 data format of lstchain only.
"""
name = "ctlearn-predict-LST1"
description = __doc__
examples = """
To predict from DL1 lstchain data using trained CTLearn models:
> ctlearn-predict-LST1 \
--input_url input.subrun.lstchain.dl1.h5 \
--LST1PredictionTool.batch_size=64 \
--LST1PredictionTool.channels=cleaned_image \
--LST1PredictionTool.channels=cleaned_relative_peak_time \
--LST1PredictionTool.image_mapper_type=BilinearMapper \
--type_model="/path/to/your/type/ctlearn_model(.keras/.pth)" \
--energy_model="/path/to/your/energy/ctlearn_model(.keras/.pth)" \
--cameradirection_model="/path/to/your/direction/ctlearn_model(.keras/.pth)" \
--output output.dl2.h5 \
--overwrite \
"""
input_url = Path(
help="Input LST-1 HDF5 files including pixel-wise image data",
allow_none=True,
exists=True,
directory_ok=False,
file_ok=True,
).tag(config=True)
dl1_features = Bool(
default_value=False,
allow_none=False,
help="Set whether to include the dl1 feature vectors in the output file.",
).tag(config=True)
dl2_telescope = Bool(
default_value=False,
allow_none=False,
help="Set whether to include dl2 telescope-event-wise data in the output file.",
).tag(config=True)
dl2_subarray = Bool(
default_value=True,
allow_none=False,
help="Set whether to include dl2 subarray-event-wise data in the output file.",
).tag(config=True)
prefixes = Dict(
default_value={
"type": "CTLearnClassifier",
"energy": "CTLearnRegressor",
"cameradirection": "CTLearnCameraReconstructor",
"all": "CTLearn",
},
allow_none=False,
help=(
"Name of the reconstruction algorithm used "
"to generate the dl2 data for each task."
),
).tag(config=True)
load_type_model_from = Path(
default_value=None,
help=(
"Path to a Keras model file (Keras3) "
"for the classification of the primary particle type."
),
allow_none=True,
exists=True,
directory_ok=True,
file_ok=True,
).tag(config=True)
load_energy_model_from = Path(
default_value=None,
help=(
"Path to a Keras model file (Keras3) "
"for the regression of the primary particle energy."
),
allow_none=True,
exists=True,
directory_ok=True,
file_ok=True,
).tag(config=True)
load_cameradirection_model_from = Path(
default_value=None,
help=(
"Path to a Keras model file (Keras3) "
"for the regression of the primary particle arrival direction "
"based on the camera coordinate offsets."
),
allow_none=True,
exists=True,
directory_ok=True,
file_ok=True,
).tag(config=True)
batch_size = Int(
default_value=64,
allow_none=False,
help="Size of the batch to perform inference of the neural network.",
).tag(config=True)
channels = List(
trait=CaselessStrEnum(
[
"image",
"cleaned_image",
"peak_time",
"relative_peak_time",
"cleaned_peak_time",
"cleaned_relative_peak_time",
]
),
default_value=["cleaned_image", "cleaned_relative_peak_time"],
allow_none=False,
help=(
"Set the input channels to be loaded from the DL1 event data. "
"image: integrated charges, "
"cleaned_image: integrated charges cleaned with the DL1 cleaning mask, "
"peak_time: extracted peak arrival times, "
"relative_peak_time: extracted relative peak arrival times, "
"cleaned_peak_time: extracted peak arrival times cleaned with the DL1 cleaning mask, "
"cleaned_relative_peak_time: extracted relative peak arrival times cleaned with the DL1 cleaning mask."
),
).tag(config=True)
image_mapper_type = ComponentName(ImageMapper, default_value="BilinearMapper").tag(
config=True
)
focal_length_choice = UseEnum(
FocalLengthKind,
default_value=FocalLengthKind.EFFECTIVE,
help=(
"If both nominal and effective focal lengths are available, "
" which one to use for the `~ctapipe.coordinates.CameraFrame` attached"
" to the `~ctapipe.instrument.CameraGeometry` instances in the"
" `~ctapipe.instrument.SubarrayDescription` which will be used in"
" CameraFrame to TelescopeFrame coordinate transforms."
" The 'nominal' focal length is the one used during "
" the simulation, the 'effective' focal length is computed using specialized "
" ray-tracing from a point light source"
),
).tag(config=True)
override_obs_id = Int(
default_value=None,
allow_none=True,
help=(
"Use the given obs_id instead of the default one. "
"Needed to merge subruns later with ctapipe-merge."
),
).tag(config=True)
output_path = Path(
default_value="./output.dl2.h5",
allow_none=False,
help="Output path to save the dl2 prediction results",
).tag(config=True)
overwrite = Bool(help="Overwrite output file if it exists").tag(config=True)
aliases = {
("i", "input_url"): "LST1PredictionTool.input_url",
("t", "type_model"): "LST1PredictionTool.load_type_model_from",
("e", "energy_model"): "LST1PredictionTool.load_energy_model_from",
(
"d",
"cameradirection_model",
): "LST1PredictionTool.load_cameradirection_model_from",
("o", "output"): "LST1PredictionTool.output_path",
}
flags = {
"overwrite": (
{"LST1PredictionTool": {"overwrite": True}},
"Overwrite existing files",
),
}
flags = {
**flag(
"dl1-features",
"LST1PredictionTool.dl1_features",
"Include dl1 features",
"Exclude dl1 features",
),
**flag(
"dl2-telescope",
"LST1PredictionTool.dl2_telescope",
"Include dl2 telescope-event-wise data in the output file",
"Exclude dl2 telescope-event-wise data in the output file",
),
**flag(
"dl2-subarray",
"LST1PredictionTool.dl2_subarray",
"Include dl2 subarray-event-wise data in the output file",
"Exclude dl2 subarray-event-wise data in the output file",
),
}
classes = classes_with_traits(ImageMapper)
[docs]
def setup(self):
"""
Initialize the tool configuration, validate parameters, and setup data handlers.
This method is the first part of the tool execution lifecycle. It validates input arguments,
sets up the configuration dictionary, configures the output file, and prepares the DataReader
to ensure everything is ready before the core processing begins.
"""
self.log.info("ctlearn version %s", ctlearn_version)
# Validate the prefixes trait dictionary
validate_trait_dict(self.prefixes, ["type", "energy", "cameradirection", "all"])
# Save dl1 image and parameters tree schemas and tel id for easy access
self.image_table_path = "/dl1/event/telescope/image/LST_LSTCam"
self.parameter_table_name = "/dl1/event/telescope/parameters/LST_LSTCam"
self.tel_id = 1
# Collect all configured model path attributes
model_paths = [
self.load_type_model_from,
self.load_energy_model_from,
self.load_cameradirection_model_from,
]
# Reads the model paths and set up the Keras or PyTorch framework
self.framework_type, self.num_devices, self.strategy, self.device = (
setup_framework(model_paths)
)
self.log.info("Framework selected: %s", self.framework_type.value)
if self.framework_type == FrameworkType.KERAS:
atexit.register(self.strategy._extended._collective_ops._lock.locked) # type: ignore
self.log.info(
"Using Keras MirroredStrategy with %d replica(s).", self.num_devices
)
elif self.framework_type == FrameworkType.PYTORCH:
import torch
if self.device == torch.device("cpu"):
self.log.info("Using PyTorch CPU device.")
else:
self.log.info(
"Using PyTorch GPU device(s). Count: %d", self.num_devices
)
# Load the models from the specified paths
input_shape_type, self.backbone_type, self.head_type = self._load_model(
self.load_type_model_from
)
input_shape_energy, self.backbone_energy, self.head_energy = self._load_model(
self.load_energy_model_from
)
input_shape_direction, self.backbone_direction, self.head_direction = (
self._load_model(self.load_cameradirection_model_from)
)
# Get the number of rows in the table
with tables.open_file(self.input_url) as input_file:
self.table_length = len(input_file.get_node(self.image_table_path))
# Get the SubarrayDescription of the LST-1 telescope
self.subarray = get_lst1_subarray_description(
focal_length_choice=self.focal_length_choice
)
# Write the SubarrayDescription to the output file
self.subarray.to_hdf(self.output_path, overwrite=self.overwrite)
self.log.info("SubarrayDescription was stored in '%s'", self.output_path)
# Initialize the Table data quality query
self.quality_query = TableQualityQuery(parent=self)
# Copy the pixel rotation of the camera geometry of the subarray in a variable
# since the ImageMapper will be derotated the pixels. The pixel rotation
# is needed to create a rotated camera frame in order to transform the
# predicted camera coordinate offsets back to the correct Alt/Az coordinates.
self.pix_rotation = self.subarray.tel[self.tel_id].camera.geometry.pix_rotation
# Create the ImageMapper
self.image_mapper = ImageMapper.from_name(
name=self.image_mapper_type,
geometry=self.subarray.tel[self.tel_id].camera.geometry,
subarray=self.subarray,
parent=self,
)
# Check if the input shape of the model matches the image shape of the ImageMapper
for input_shape in [
input_shape_type,
input_shape_energy,
input_shape_direction,
]:
if (
input_shape is not None
and input_shape[0] != self.image_mapper.image_shape
):
raise ToolConfigurationError(
f"The input shape of the model ('{input_shape[0]}') does not match "
f"the image shape of the ImageMapper ('{self.image_mapper.image_shape}'). "
f"Use e.g. '--BilinearMapper.interpolation_image_shape={input_shape[0]}' ."
)
# Validate that the ImageMapper and each loaded model's conv backend agree
image_mappers = {self.image_mapper_type: self.image_mapper}
for loaded_model in (
self.backbone_type if self.load_type_model_from is not None else None,
self.backbone_energy if self.load_energy_model_from is not None else None,
self.backbone_direction
if self.load_cameradirection_model_from is not None
else None,
):
if loaded_model is not None:
validate_conv_backend(image_mappers, model_conv_backend(loaded_model))
# Get offset and scaling of images
self.transforms = {}
self.transforms["image_scale"] = 0.0
self.transforms["image_offset"] = 0
self.transforms["peak_time_scale"] = 0.0
self.transforms["peak_time_offset"] = 0
# Get the number of rows in the table
with tables.open_file(self.input_url) as input_file:
img_table_v_attrs = input_file.get_node(self.image_table_path)._v_attrs
# Check transform values while the input file is still open.
if "CTAFIELD_3_TRANSFORM_SCALE" in img_table_v_attrs:
self.transforms["image_scale"] = img_table_v_attrs[
"CTAFIELD_3_TRANSFORM_SCALE"
]
self.transforms["image_offset"] = img_table_v_attrs[
"CTAFIELD_3_TRANSFORM_OFFSET"
]
if "CTAFIELD_4_TRANSFORM_SCALE" in img_table_v_attrs:
self.transforms["peak_time_scale"] = img_table_v_attrs[
"CTAFIELD_4_TRANSFORM_SCALE"
]
self.transforms["peak_time_offset"] = img_table_v_attrs[
"CTAFIELD_4_TRANSFORM_OFFSET"
]
[docs]
def start(self):
"""
Execute the core logic of the tool.
Depending on the tool, this method either orchestrates the training and validation
loops across epochs, or it iterates through the input dataset to generate
and save model predictions to the output file.
"""
all_identifiers = read_table(self.input_url, self.parameter_table_name)
all_identifiers.meta = {}
if self.override_obs_id is not None:
all_identifiers["obs_id"] = self.override_obs_id
self.obs_id = all_identifiers["obs_id"][0]
parameter_table = all_identifiers.copy()
tel_az = u.Quantity(parameter_table["az_tel"], unit=u.rad)
tel_alt = u.Quantity(parameter_table["alt_tel"], unit=u.rad)
event_type = parameter_table["event_type"]
time = Time(parameter_table["dragon_time"] * u.s, format="unix")
# Create the pointing table
# This table is used to store the telescope pointing per event
pointing_table = Table(
{
"time": time,
"azimuth": tel_az,
"altitude": tel_alt,
}
)
write_table(
pointing_table,
self.output_path,
f"{DL1_TEL_POINTING_GROUP}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL1 telescope pointing table was stored in '%s' under '%s'",
self.output_path,
f"{DL1_TEL_POINTING_GROUP}/tel_{self.tel_id:03d}",
)
# Set the time format to MJD since in the other table we store the time in MJD
time.format = "mjd"
# Keep only the necessary columns for the creation of tables
all_identifiers.keep_columns(TELESCOPE_EVENT_KEYS)
# Create the dl1 telescope trigger table
trigger_table = all_identifiers.copy()
trigger_table.add_column(time, name="time")
trigger_table.add_column(-1, name="n_trigger_pixels")
write_table(
trigger_table,
self.output_path,
DL1_TEL_TRIGGER_TABLE,
overwrite=self.overwrite,
)
self.log.info(
"DL1 telescope trigger table was stored in '%s' under '%s'",
self.output_path,
DL1_TEL_TRIGGER_TABLE,
)
trigger_table.keep_columns(["obs_id", "event_id", "time"])
trigger_table.add_column(
np.ones((len(trigger_table), 1), dtype=bool), name="tel_with_trigger"
)
trigger_table.add_column(event_type, name="event_type")
# Save the dl1 subrray trigger table to the output file
write_table(
trigger_table,
self.output_path,
DL1_SUBARRAY_TRIGGER_TABLE,
overwrite=self.overwrite,
)
self.log.info(
"DL1 subarray trigger table was stored in '%s' under '%s'",
self.output_path,
DL1_SUBARRAY_TRIGGER_TABLE,
)
# Create the dl1 parameters table
parameter_table.rename_column("intensity", "hillas_intensity")
parameter_table.rename_column("x", "hillas_x")
parameter_table.rename_column("y", "hillas_y")
parameter_table.rename_column("phi", "hillas_phi")
parameter_table.rename_column("psi", "hillas_psi")
parameter_table.rename_column("length", "hillas_length")
parameter_table.rename_column("length_uncertainty", "hillas_length_uncertainty")
parameter_table.rename_column("width", "hillas_width")
parameter_table.rename_column("width_uncertainty", "hillas_width_uncertainty")
parameter_table.rename_column("skewness", "hillas_skewness")
parameter_table.rename_column("kurtosis", "hillas_kurtosis")
parameter_table.rename_column("time_gradient", "timing_deviation")
parameter_table.rename_column("intercept", "timing_intercept")
parameter_table.rename_column("n_pixels", "morphology_n_pixels")
parameter_table.rename_column("n_islands", "morphology_n_islands")
parameter_table.keep_columns(
[
"obs_id",
"event_id",
"hillas_intensity",
"hillas_x",
"hillas_y",
"hillas_phi",
"hillas_psi",
"hillas_length",
"hillas_length_uncertainty",
"hillas_width",
"hillas_width_uncertainty",
"hillas_skewness",
"hillas_kurtosis",
"timing_deviation",
"timing_intercept",
"morphology_n_pixels",
"morphology_n_islands",
]
)
parameter_table.add_column(self.tel_id, name="tel_id", index=2)
# Save the dl1 parameters table to the output file
write_table(
parameter_table,
self.output_path,
f"{DL1_TEL_PARAMETERS_GROUP}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL1 parameters table was stored in '%s' under '%s'",
self.output_path,
f"{DL1_TEL_PARAMETERS_GROUP}/tel_{self.tel_id:03d}",
)
# Add additional columns to the parameter table
# which are not present in the originl DL1 parameter table.
# They are needed for applying the quality selection.
parameter_table.add_column(event_type, name="event_type")
parameter_table.add_column(tel_az, name="tel_az")
parameter_table.add_column(tel_alt, name="tel_alt")
# Only select cosmic events for the prediction
parameter_table = parameter_table[parameter_table["event_type"] == 32]
self.log.info("Starting the prediction...")
event_id, tel_azimuth, tel_altitude, trigger_time = [], [], [], []
prediction, energy, cam_coord_offset_x, cam_coord_offset_y = [], [], [], []
classification_fvs, energy_fvs, direction_fvs = [], [], []
# Iterate over the data in chunks based on the batch size
for start in range(0, self.table_length, self.batch_size):
stop = min(start + self.batch_size, self.table_length)
self.log.debug("Processing chunk from '%d' to '%d'.", start, stop - 1)
# Read the data
dl1_table = read_table(
self.input_url, self.image_table_path, start=start, stop=stop
)
# Join the dl1 table with the parameter table to perform quality selection
dl1_table = join(
left=dl1_table,
right=parameter_table,
keys=["event_id"],
)
dl1_table = join(
left=dl1_table,
right=trigger_table,
keys=["event_id"],
)
# Initialize a boolean mask to True for all events in the sliced dl1 table
passes_quality_checks = np.ones(len(dl1_table), dtype=bool)
# Quality selection based on the dl1b parameter
if self.quality_query:
passes_quality_checks = self.quality_query.get_table_mask(dl1_table)
# Apply the mask to filter events that are not fulfilling the quality criteria
dl1_table = dl1_table[passes_quality_checks]
if len(dl1_table) == 0:
self.log.debug("No events passed the quality selection.")
continue
data = []
for event in dl1_table:
# Get the unmapped image
image = get_unmapped_image(event, self.channels, self.transforms)
data.append(self.image_mapper.map_image(image))
input_data = np.array(data)
event_id.extend(dl1_table["event_id"].data)
tel_azimuth.extend(dl1_table["tel_az"].data)
tel_altitude.extend(dl1_table["tel_alt"].data)
trigger_time.extend(dl1_table["time"].mjd)
if self.load_type_model_from is not None:
fvs, preds = self._predict_batch(
self.backbone_type, self.head_type, input_data
)
if self.framework_type == FrameworkType.PYTORCH:
from scipy.special import softmax
preds = softmax(preds, axis=1)
classification_fvs.extend(fvs)
prediction.extend(preds[:, 1])
if self.load_energy_model_from is not None:
fvs, preds = self._predict_batch(
self.backbone_energy, self.head_energy, input_data
)
energy_fvs.extend(fvs)
energy.extend(preds[:, 0])
if self.load_cameradirection_model_from is not None:
fvs, preds = self._predict_batch(
self.backbone_direction, self.head_direction, input_data
)
direction_fvs.extend(fvs)
cam_coord_offset_x.extend(preds[:, 0])
cam_coord_offset_y.extend(preds[:, 1])
# Create the prediction tables
example_identifiers = Table(
{
"obs_id": np.full(len(event_id), self.obs_id, dtype=int),
"event_id": event_id,
"tel_id": np.full(len(event_id), self.tel_id, dtype=int),
}
)
nonexample_identifiers = setdiff(
all_identifiers, example_identifiers, keys=TELESCOPE_EVENT_KEYS
)
if len(nonexample_identifiers) > 0:
nonexample_identifiers.sort(TELESCOPE_EVENT_KEYS)
# Create the feature vector table
feature_vector_table = example_identifiers.copy()
fvs_columns_list, fvs_shapes_list = [], []
if self.load_type_model_from is not None:
classification_tel_table = example_identifiers.copy()
classification_tel_table.add_column(
prediction, name=f"{self.prefixes['type']}_tel_prediction"
)
# Produce output table with NaNs for missing predictions
if len(nonexample_identifiers) > 0:
nan_table = self._create_nan_table(
nonexample_identifiers,
columns=[f"{self.prefixes['type']}_tel_prediction"],
shapes=[(len(nonexample_identifiers),)],
)
classification_tel_table = vstack([classification_tel_table, nan_table])
classification_tel_table.sort(TELESCOPE_EVENT_KEYS)
classification_is_valid = ~np.isnan(
classification_tel_table[
f"{self.prefixes['type']}_tel_prediction"
].data,
dtype=bool,
)
classification_tel_table.add_column(
classification_is_valid,
name=f"{self.prefixes['type']}_tel_is_valid",
)
# Add the default values and meta data to the table
add_defaults_and_meta(
classification_tel_table,
ParticleClassificationContainer,
prefix=self.prefixes["type"],
add_tel_prefix=True,
)
# Save the prediction to the output file
if self.dl2_telescope:
write_table(
classification_tel_table,
self.output_path,
f"{DL2_TEL_PARTICLETYPE_GROUP}/{self.prefixes['type']}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_TEL_PARTICLETYPE_GROUP}/{self.prefixes['type']}/tel_{self.tel_id:03d}",
)
# Write the mono telescope prediction to the subarray prediction table
if self.dl2_subarray:
classification_subarray_table = classification_tel_table.copy()
classification_subarray_table.remove_column("tel_id")
for colname in classification_subarray_table.colnames:
if "_tel_" in colname:
classification_subarray_table.rename_column(
colname, colname.replace("_tel", "")
)
classification_subarray_table.add_column(
[[val] for val in classification_is_valid],
name=f"{self.prefixes['type']}_telescopes",
)
# Save the prediction to the output file
write_table(
classification_subarray_table,
self.output_path,
f"{DL2_SUBARRAY_PARTICLETYPE_GROUP}/{self.prefixes['type']}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_SUBARRAY_PARTICLETYPE_GROUP}/{self.prefixes['type']}",
)
# Adding the feature vectors for the classification
if self.dl1_features:
is_valid_col = ~np.isnan(np.min(classification_fvs, axis=1), dtype=bool)
feature_vector_table.add_column(
classification_fvs,
name=f"{self.prefixes['all']}_tel_particletype_feature_vectors",
)
if nonexample_identifiers is not None:
fvs_columns_list.append(
f"{self.prefixes['all']}_tel_particletype_feature_vectors"
)
fvs_shapes_list.append(
(
len(nonexample_identifiers),
classification_fvs[0].shape[0],
)
)
if self.load_energy_model_from is not None:
energy_tel_table = example_identifiers.copy()
# Convert the reconstructed energy from log10(TeV) to TeV
reco_energy = u.Quantity(np.power(10, np.squeeze(energy)), unit=u.TeV)
# Add the reconstructed energy to the prediction table
energy_tel_table.add_column(
reco_energy, name=f"{self.prefixes['energy']}_tel_energy"
)
# Produce output table with NaNs for missing predictions
if len(nonexample_identifiers) > 0:
nan_table = self._create_nan_table(
nonexample_identifiers,
columns=[f"{self.prefixes['energy']}_tel_energy"],
shapes=[(len(nonexample_identifiers),)],
)
energy_tel_table = vstack([energy_tel_table, nan_table])
energy_tel_table.sort(TELESCOPE_EVENT_KEYS)
energy_is_valid = ~np.isnan(
energy_tel_table[f"{self.prefixes['energy']}_tel_energy"].data,
dtype=bool,
)
energy_tel_table.add_column(
energy_is_valid,
name=f"{self.prefixes['energy']}_tel_is_valid",
)
# Add the default values and meta data to the table
add_defaults_and_meta(
energy_tel_table,
ReconstructedEnergyContainer,
prefix=self.prefixes["energy"],
add_tel_prefix=True,
)
# Save the prediction to the output file
if self.dl2_telescope:
write_table(
energy_tel_table,
self.output_path,
f"{DL2_TEL_ENERGY_GROUP}/{self.prefixes['energy']}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_TEL_ENERGY_GROUP}/{self.prefixes['energy']}/tel_{self.tel_id:03d}",
)
# Write the mono telescope prediction to the subarray prediction table
if self.dl2_subarray:
energy_subarray_table = energy_tel_table.copy()
energy_subarray_table.remove_column("tel_id")
for colname in energy_subarray_table.colnames:
if "_tel_" in colname:
energy_subarray_table.rename_column(
colname, colname.replace("_tel", "")
)
energy_subarray_table.add_column(
[[val] for val in energy_is_valid],
name=f"{self.prefixes['energy']}_telescopes",
)
# Save the prediction to the output file
write_table(
energy_subarray_table,
self.output_path,
f"{DL2_SUBARRAY_ENERGY_GROUP}/{self.prefixes['energy']}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_SUBARRAY_ENERGY_GROUP}/{self.prefixes['energy']}",
)
# Adding the feature vectors for the energy regression
if self.dl1_features:
is_valid_col = ~np.isnan(np.min(energy_fvs, axis=1), dtype=bool)
feature_vector_table.add_column(
energy_fvs,
name=f"{self.prefixes['all']}_tel_energy_feature_vectors",
)
if nonexample_identifiers is not None:
fvs_columns_list.append(
f"{self.prefixes['all']}_tel_energy_feature_vectors"
)
fvs_shapes_list.append(
(
len(nonexample_identifiers),
energy_fvs[0].shape[0],
)
)
if self.load_cameradirection_model_from is not None:
direction_tel_table = example_identifiers.copy()
# Set the telescope position
tel_ground_frame = self.subarray.tel_coords[
self.subarray.tel_ids_to_indices(self.tel_id)
]
# Set the telescope pointing with the trigger timestamp and the telescope position
trigger_time = Time(trigger_time, format="mjd")
altaz = AltAz(
location=tel_ground_frame.to_earth_location(),
obstime=trigger_time,
)
# Set the telescope pointing
tel_pointing = SkyCoord(
az=u.Quantity(tel_azimuth, unit=u.rad),
alt=u.Quantity(tel_altitude, unit=u.rad),
frame=altaz,
)
# Set a new camera frame with the pixel rotation of the camera
camera_frame = CameraFrame(
focal_length=self.subarray.tel[
self.tel_id
].camera.geometry.frame.focal_length,
rotation=self.pix_rotation,
telescope_pointing=tel_pointing,
)
# Set the camera coordinate offset
cam_coord_offset = SkyCoord(
x=u.Quantity(cam_coord_offset_x, unit=u.m),
y=u.Quantity(cam_coord_offset_y, unit=u.m),
frame=camera_frame,
)
# Transform the true Alt/Az coordinates to camera coordinates
reco_direction = cam_coord_offset.transform_to(altaz)
# Add the reconstructed direction (az, alt) to the prediction table
direction_tel_table.add_column(
reco_direction.az.to(u.deg),
name=f"{self.prefixes['cameradirection']}_tel_az",
)
direction_tel_table.add_column(
reco_direction.alt.to(u.deg),
name=f"{self.prefixes['cameradirection']}_tel_alt",
)
# Produce output table with NaNs for missing predictions
if len(nonexample_identifiers) > 0:
nan_table = self._create_nan_table(
nonexample_identifiers,
columns=[
f"{self.prefixes['cameradirection']}_tel_az",
f"{self.prefixes['cameradirection']}_tel_alt",
],
shapes=[
(len(nonexample_identifiers),),
(len(nonexample_identifiers),),
],
)
direction_tel_table = vstack([direction_tel_table, nan_table])
direction_tel_table.keep_columns(
TELESCOPE_EVENT_KEYS
+ [
f"{self.prefixes['cameradirection']}_tel_az",
f"{self.prefixes['cameradirection']}_tel_alt",
]
)
direction_tel_table.sort(TELESCOPE_EVENT_KEYS)
direction_is_valid = ~np.isnan(
direction_tel_table[f"{self.prefixes['cameradirection']}_tel_az"].data,
dtype=bool,
)
direction_tel_table.add_column(
direction_is_valid,
name=f"{self.prefixes['cameradirection']}_tel_is_valid",
)
# Add the default values and meta data to the table
add_defaults_and_meta(
direction_tel_table,
ReconstructedGeometryContainer,
prefix=self.prefixes["cameradirection"],
add_tel_prefix=True,
)
# Save the prediction to the output file
if self.dl2_telescope:
write_table(
direction_tel_table,
self.output_path,
f"{DL2_TEL_GEOMETRY_GROUP}/{self.prefixes['cameradirection']}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_TEL_GEOMETRY_GROUP}/{self.prefixes['cameradirection']}/tel_{self.tel_id:03d}",
)
# Write the mono telescope prediction to the subarray prediction table
if self.dl2_subarray:
direction_subarray_table = direction_tel_table.copy()
direction_subarray_table.remove_column("tel_id")
for colname in direction_subarray_table.colnames:
if "_tel_" in colname:
direction_subarray_table.rename_column(
colname, colname.replace("_tel", "")
)
direction_subarray_table.add_column(
[[val] for val in direction_is_valid],
name=f"{self.prefixes['cameradirection']}_telescopes",
)
# Save the prediction to the output file
write_table(
direction_subarray_table,
self.output_path,
f"{DL2_SUBARRAY_GEOMETRY_GROUP}/{self.prefixes['cameradirection']}",
overwrite=self.overwrite,
)
self.log.info(
"DL2 prediction data was stored in '%s' under '%s'",
self.output_path,
f"{DL2_SUBARRAY_GEOMETRY_GROUP}/{self.prefixes['cameradirection']}",
)
# Adding the feature vectors for the arrival direction regression
if self.dl1_features:
is_valid_col = ~np.isnan(np.min(direction_fvs, axis=1), dtype=bool)
feature_vector_table.add_column(
direction_fvs,
name=f"{self.prefixes['all']}_tel_geometry_feature_vectors",
)
if nonexample_identifiers is not None:
fvs_columns_list.append(
f"{self.prefixes['all']}_tel_geometry_feature_vectors"
)
fvs_shapes_list.append(
(
len(nonexample_identifiers),
direction_fvs[0].shape[0],
)
)
# Produce output table with NaNs for missing predictions
if self.dl1_features:
if nonexample_identifiers is not None:
if len(nonexample_identifiers) > 0:
nan_table = self._create_nan_table(
nonexample_identifiers,
columns=fvs_columns_list,
shapes=fvs_shapes_list,
)
feature_vector_table = vstack([feature_vector_table, nan_table])
is_valid_col = np.concatenate(
(
is_valid_col,
np.zeros(len(nonexample_identifiers), dtype=bool),
)
)
# Add is_valid column to the feature vector table
feature_vector_table.add_column(
is_valid_col,
name=f"{self.prefixes['all']}_tel_is_valid",
)
# Save the prediction to the output file
write_table(
feature_vector_table,
self.output_path,
f"{DL1_TEL_GROUP}/features/{self.prefixes['all']}/tel_{self.tel_id:03d}",
overwrite=self.overwrite,
)
self.log.info(
"DL1 feature vectors was stored in '%s' under '%s'",
self.output_path,
f"{DL1_TEL_GROUP}/features/{self.prefixes['all']}/tel_{self.tel_id:03d}",
)
[docs]
def finish(self):
"""
Perform final cleanup and save metadata after the core logic completes.
This method writes provenance data (such as configuration and execution context)
to the output file, finalizes tables, and ensures all file handlers are safely closed.
"""
self.log.info("Tool is shutting down")
def _predict_batch(self, backbone, head, input_data):
"""
Run batch inference through a backbone and head model using Keras or PyTorch.
Dispatches model execution based on ``self.framework_type``. For PyTorch,
converts input data to Tensors, transposes to channels-first format (NCHW),
places inputs on the targeted device, runs inference without gradient tracking
(``torch.no_grad()``), and returns NumPy outputs on CPU.
Parameters
----------
backbone : keras.Model or torch.nn.Module
The feature extractor network that processes raw input data into
feature representations.
head : keras.Model or torch.nn.Module
The task-specific head network that computes final predictions
from feature vectors.
input_data : np.ndarray
Batch of image data following the Keras convention.
Returns
-------
fvs : np.ndarray
Extracted feature vectors for the batch.
preds : np.ndarray
Model output predictions for the batch.
"""
if self.framework_type == FrameworkType.KERAS:
fvs = backbone.predict_on_batch(input_data)
preds = head.predict_on_batch(fvs)
return fvs, preds
if self.framework_type == FrameworkType.PYTORCH:
import torch
tensor_data = torch.from_numpy(input_data).float()
# Convert Channels-Last (N, H, W, C) to Channels-First (N, C, H, W)
if tensor_data.ndim == 4:
tensor_data = tensor_data.permute(0, 3, 1, 2)
tensor_data = tensor_data.to(self.device)
def _to_numpy(val):
"""
Convert Astropy columns or arrays to native NumPy format for prediction.
"""
if isinstance(val, dict):
# Extract the tensor value from the dictionary (e.g., {'energy': tensor(...)})
val = next(iter(val.values()))
if isinstance(val, torch.Tensor):
return val.cpu().numpy()
return np.asarray(val)
with torch.no_grad():
fvs = backbone(tensor_data)
preds = head(fvs)
return fvs.cpu().numpy(), _to_numpy(preds)
def _load_model(self, path):
"""
Load a trained model and extract its input shape, backbone, and head.
Supports both Keras and PyTorch frameworks based on ``self.framework_type``.
For PyTorch models, the model is set to evaluation mode (``.eval()``) and its
``backbone`` and ``head`` submodules are extracted.
Parameters
----------
path : str, pathlib.Path, or None
Path to the saved model file. If ``None``, the function immediately returns ``None`` elements.
Returns
-------
input_shape : tuple of int or None
Input feature tensor shape (excluding batch dimension), or ``None`` if ``path``
is ``None`` or framework is PyTorch.
backbone : keras.Model, torch.nn.Module, or None
Feature extraction backbone of the model, or ``None`` if ``path`` is ``None``.
head : keras.Model, torch.nn.Module, or None
Output prediction head of the model, or ``None`` if ``path`` is ``None``.
Raises
------
TypeError
If the loaded PyTorch object is not an instance of ``torch.nn.Module``
(e.g., when a ``state_dict`` is loaded instead of the full model).
"""
if path is None:
return None, None, None
self.log.info("Loading the model from %s.", path)
def _split_keras_model(model):
"""Split the Keras model into backbone and head."""
import keras
# Get the backbone model which is the second layer of the model
backbone = model.get_layer(index=1)
# Create a new head model with the same layers as the original model.
# The output of the backbone model is the input of the head model.
backbone_output_shape = keras.Input(model.layers[2].input.shape[1:])
x = backbone_output_shape
for layer in model.layers[2:]:
x = layer(x)
head = keras.Model(inputs=backbone_output_shape, outputs=x)
return backbone, head
if self.framework_type == FrameworkType.KERAS:
import keras
model = keras.saving.load_model(path)
input_shape = model.input_shape[1:]
backbone, head = _split_keras_model(model)
return input_shape, backbone, head
if self.framework_type == FrameworkType.PYTORCH:
import torch
import torch.nn as nn
model = torch.load(path, map_location=self.device, weights_only=False)
# Extract model and check config if it's a checkpoint dictionary
if isinstance(model, dict) and "model" in model:
saved_config = model.get("ctlearn_config", {})
current_config = dict(self.config) if self.config else {}
if "DLDataReader" in saved_config and "DLDataReader" in current_config:
for key, saved_val in saved_config["DLDataReader"].items():
current_val = current_config["DLDataReader"].get(key)
if current_val is not None and current_val != saved_val:
raise ValueError(
f"Configuration mismatch: The model was trained with DLDataReader.{key}={saved_val}, "
f"but you are trying to predict with {key}={current_val}. "
"Adjust the prediction configuration to match."
)
model = model["model"]
if not isinstance(model, nn.Module):
raise TypeError(
f"Expected a PyTorch 'nn.Module' object at '{path}', "
f"but got '{type(model).__name__}'. "
"Ensure the model was saved via 'torch.save(model, path)' "
"rather than 'torch.save(model.state_dict(), path)'."
)
model.eval()
backbone, head = model.backbone, model.head
if self.num_devices > 1:
backbone = nn.DataParallel(backbone)
head = nn.DataParallel(head)
return None, backbone, head
def _create_nan_table(self, nonexample_identifiers, columns, shapes):
"""
Create a table with NaNs for missing predictions.
This method creates a table with NaNs for missing predictions for the non-example identifiers.
Parameters:
-----------
nonexample_identifiers : astropy.table.Table
Table containing the non-example identifiers.
columns : list of str
List of column names to create in the table.
shapes : list of shapes
List of shapes for the columns to create in the table.
Returns:
--------
nan_table : astropy.table.Table
Table containing NaNs for missing predictions.
"""
# Create a table with NaNs for missing predictions
nan_table = nonexample_identifiers.copy()
for column_name, shape in zip(columns, shapes):
nan_table.add_column(np.full(shape, np.nan), name=column_name)
return nan_table
def main():
"""
Main entry point for the command-line tool.
This function instantiates the Tool class and invokes its `run()` method,
which sequentially executes the `setup()`, `start()`, and `finish()` methods.
"""
# Run the tool
tool = LST1PredictionTool()
tool.run()
if __name__ == "__main__":
main()