EventSource#

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

Bases: 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, regardless 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) 

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_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 simulation, or a measurement 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 overridden by sources needing a cleanup-step

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