EventSource¶

class ctapipe.io.EventSource(input_url=traitlets.Undefined, config=None, parent=None, **kwargs)[source]¶

Bases: ctapipe.core.component.Component

Parent class for EventSources.

EventSources read input files and generate ArrayEventContainer instances when iterated over.

A new EventSource should be created for each type of event file read into ctapipe, e.g. sim_telarray files are read by the SimTelEventSource.

EventSource provides a common high-level interface for accessing event information from different data sources (simulation or different camera file formats). Creating an EventSource for a new file format or other event source ensures that data can be accessed in a common way, irregardless of the file format or data origin.

EventSource itself is an abstract class, but will create an appropriate subclass if a compatible source is found for the given input_url.

>>> EventSource(input_url="dataset://gamma_prod5.simtel.zst")
<ctapipe.io.simteleventsource.SimTelEventSource ...>

An EventSource can also be created through the configuration system, by passing config or parent as appropriate. E.g. if using EventSource inside of a Tool, you would do: >>> self.source = EventSource(parent=self) # doctest: +SKIP

To loop through the events in a file: >>> source = EventSource(input_url=”dataset://gamma_prod5.simtel.zst”, max_events=2) >>> for event in source: … print(event.count) 0 1

NOTE: Every time a new loop is started through the source, it tries to restart from the first event, which might not be supported by the event source.

It is encouraged to use EventSource in a context manager to ensure the correct cleanups are performed when you are finished with the source:

>>> with EventSource(input_url="dataset://gamma_prod5.simtel.zst", max_events=2) as source:
...    for event in source:
...        print(event.count)
0
1

NOTE: EventSource implementations should not reuse the same ArrayEventContainer, as these are mutable and may lead to errors when analyzing multiple events.

Attributes

input_urlstr: Path to the input event file.
max_eventsint: Maximum number of events to loop through in generator
allowed_tels: Set or None: Ids of the telescopes to be included in the data. If given, only this subset of telescopes will be present in the generated events. If None, all available telescopes are used.

Attributes Summary

`allowed_tels`	list of allowed tel_ids, others will be ignored.
`atmosphere_density_profile`	atmosphere density profile that can be integrated to convert between h_max and X_max.
`datalevels`	The datalevels provided by this event source
`input_url`	Path to the input file containing events.
`is_simulation`	Whether the currently opened file is simulated
`is_stream`	Bool indicating if input is a stream.
`max_events`	Maximum number of events that will be read from the file
`obs_ids`	The observation ids of the runs located in the file Unmerged files should only contain a single obs id.
`observation_blocks`	Obtain the ObservationConfigurations from the EventSource, indexed by obs_id
`plugin_entry_point`	ctapipe_io entry points may provide EventSource implementations
`scheduling_blocks`	Obtain the ObservationConfigurations from the EventSource, indexed by obs_id
`simulation_config`	The simulation configurations of all observations provided by the EventSource, or None if the source does not provide simulated data
`subarray`	Obtain the subarray from the EventSource

Methods Summary

`close`()	Close this event source.
`from_config`([config, parent])	Find compatible EventSource for the EventSource.input_url traitlet specified via the config.
`from_url`(input_url, **kwargs)	Find compatible EventSource for input_url via the `is_compatible` method of the EventSource
`has_any_datalevel`(datalevels)	Check if any of `datalevels` is in self.datalevels
`is_compatible`(file_path)	Abstract method to be defined in child class.

Attributes Documentation

allowed_tels¶: list of allowed tel_ids, others will be ignored. If None, all telescopes in the input stream will be included

atmosphere_density_profile¶

atmosphere density profile that can be integrated to convert between h_max and X_max. This should correspond either to what was used in a simualtion, or a measurment for use with observed data.

Returns

AtmosphereDensityProfile:: profile to be used

datalevels¶

The datalevels provided by this event source

Returns

tuple[ctapipe.io.DataLevel]

input_url¶: Path to the input file containing events.

is_simulation¶

Whether the currently opened file is simulated

Returns

bool

is_stream¶

Bool indicating if input is a stream. If it is then it is incompatible with ctapipe.io.eventseeker.EventSeeker.

TODO: Define a method to detect if it is a stream

Returns

bool: If True, then input is a stream.

max_events¶: Maximum number of events that will be read from the file

obs_ids¶

The observation ids of the runs located in the file Unmerged files should only contain a single obs id.

Returns

list[int]

observation_blocks¶: Obtain the ObservationConfigurations from the EventSource, indexed by obs_id

plugin_entry_point = 'ctapipe_io'¶: ctapipe_io entry points may provide EventSource implementations

scheduling_blocks¶: Obtain the ObservationConfigurations from the EventSource, indexed by obs_id

simulation_config¶

The simulation configurations of all observations provided by the EventSource, or None if the source does not provide simulated data

Returns

Dict[int,ctapipe.containers.SimulationConfigContainer] | None

subarray¶

Obtain the subarray from the EventSource

Returns

ctapipe.instrument.SubarrayDecription

Methods Documentation

close()[source]¶

Close this event source.

No-op by default. Should be overriden by sources needing a cleanup-step

classmethod from_config(config=None, parent=None, **kwargs)[source]¶

Find compatible EventSource for the EventSource.input_url traitlet specified via the config.

This method is typically used in Tools, where the input_url is chosen via the command line using the traitlet configuration system.

Parameters

configtraitlets.config.loader.Config: Configuration created in the Tool
kwargs: Named arguments for the EventSource

Returns

instance: Instance of a compatible EventSource subclass

classmethod from_url(input_url, **kwargs)[source]¶

Find compatible EventSource for input_url via the is_compatible method of the EventSource

Parameters

input_urlstr: Filename or URL pointing to an event file
kwargs: Named arguments for the EventSource

Returns

instance: Instance of a compatible EventSource subclass

has_any_datalevel(datalevels) → bool [source]¶

Check if any of datalevels is in self.datalevels

Parameters

datalevels: Iterable: Iterable of datalevels

abstract static is_compatible(file_path)[source]¶

Abstract method to be defined in child class.

Perform a set of checks to see if the input file is compatible with this file event_source.

Parameters

file_pathstr: File path to the event file.

Returns

compatiblebool: True if file is compatible, False if it is incompatible