Search for coincidences between HiSPARC stations¶

Search for coincidences between HiSPARC stations

This module can be used to search for coincidences between several HiSPARC stations. To skip this and directly download coincidences use download_coincidences(), this is slightly less flexible because you can not choose the coincidence window.

For regular usage, download events from the ESD and use the CoincidencesESD class. Example usage:

import datetime

import tables

from sapphire import CoincidencesESD, download_data

STATIONS = [501, 503, 506]
START = datetime.datetime(2013, 1, 1)
END = datetime.datetime(2013, 1, 2)


if __name__ == '__main__':
    station_groups = ['/s%d' % u for u in STATIONS]

    data = tables.open_file('data.h5', 'w')
    for station, group in zip(STATIONS, station_groups):
        download_data(data, group, station, START, END)

    coin = CoincidencesESD(data, '/coincidences', station_groups)
    coin.search_and_store_coincidences()

class sapphire.analysis.coincidences.Coincidences(data, coincidence_group, station_groups, overwrite=False, progress=True)¶

Search for and store coincidences between HiSPARC stations.

Note

For better compatibility with other modules, such as reconstructions, it is recommended to use the subclass CoincidencesESD instead. This is an old class with a different way to store the results. It can be used, however, on raw data downloaded from the public database.

Suppose you want to search for coincidences between stations 501 and 503. First, download the data for these stations (with, or without traces, depending on your intentions). Suppose you stored the data in the ‘/s501’ and ‘/s503’ groups in the ‘data.h5’ file. Then:

>>> groups = ['/s501', '/s503']
>>> with Coincidences('data.h5', '/coincidences', groups) as coin:
...     coin.search_and_store_coincidences()

If you want a more manual method, replace the last line the separate methods which it calls:

>>> with Coincidences('data.h5', '/coincidences', groups) as coin:
...     coin.search_coincidences(window=50000)
...     coin.process_events()
...     coin.store_coincidences()

You can then provide different parameters to the individual methods. See the corresponding docstrings.

Once the coincidences are stored, there will be a coincidences table in the group. This table has multiple columns used for storing simulation inputs like shower direction and energy. At this point, they contain no information. They are only useful if the original event tables were created by simulations, instead of real detector data. The useful columns are:

id: the index of this coincidence. This index is identical for the coincidence and c_index tables.

timestamp: the timestamp of the event in seconds

nanoseconds: the subsecond part of the timestamp in nanoseconds

ext_timestamp: the timestamp of the event in nanoseconds (equal to timestamp * 1000000000 + nanoseconds)

N: the number of stations participating in this coincidence

s0, s1, …: whether the first (0), second (1) or other stations participated in the coincidence.

The coincidences group furthermore contains the table c_index to track down the individual events making up the coincidence. The c_index table gives indexes for the individual events inside the original event tables.

If you have obtained a particular coincidence from the coincidences table, the id is the index into all these tables. For example, looking up the source events making up the 40th coincidence:

>>> group = data.root.coincidences
>>> idx = 40
>>> group.coincidences[idx]

can be done in the following way (each row in the c_index table is a (station index, event index) pair):

>>> for event_idx in group.c_index[idx]:
...     event = group.observables[event_idx]

The event is one of the source events, processed to determine particle arrival times from the raw traces (if available). It has a station_id attribute which is an index into station_groups.

Initialize the class.

Parameters:

data – either a PyTables file or path to a HDF5 file.
coincidence_group – the destination group. If None the results can not be stored, but coincidences can still be searched for.
station_groups – a list of groups containing the station data.
overwrite – if True overwrite a previous coincidences group.
progress – if True show a progressbar while storing coincidences.

search_and_store_coincidences(window=10000)¶

Search, process and store coincidences.

This is a semi-automatic method to search for coincidences, process the events making up the coincidences and then store the results in the coincidences group.

If you want to make use of non-default parameters like time shifts or overwriting previously processed events, please call the individual methods. See the class docstring.

search_coincidences(window=10000, shifts=None, limit=None)¶

Search for coincidences.

Search all data in the station_groups for coincidences, and store rudimentary coincidence data in the coincidences group. This data might be useful, but is very basic. You can call the store_coincidences() method to store the coincidences in an easier format in the coincidences group.

If you want to process the preliminary results: they are stored in _src_c_index and _src_timestamps. The former is a list of coincidences, which each consist of a list with indexes into the timestamps array as a pointer to the events making up the coincidence. The latter is a list of tuples. Each tuple consists of a timestamp followed by an index into the stations list which designates the detector station which measured the event, and finally an index into that station’s event table.

Parameters:

window – the coincidence time window in nanoseconds. All events with delta t’s smaller than this window will be considered a coincidence.
shifts – optionally shift a station’s data in time. This can be useful if a station has a misconfigured GPS clock. Expects a list of shifts, one for each station, in seconds. Use ‘None’ for no shift.
limit – optionally limit the search for this number of events.

process_events(overwrite=None)¶

Process events using process_events

Events making up the coincidences are processed to obtain observables like number of particles and particle arrival times.

Parameters:: overwrite – if True, overwrite the events tables in the station groups.

store_coincidences()¶

Store the previously found coincidences.

After you have searched for coincidences, you can store the more user-friendly results in the coincidences group using this method.

class sapphire.analysis.coincidences.CoincidencesESD(data, coincidence_group, station_groups, overwrite=False, progress=True)¶

Store coincidences specifically using the ESD

This is a subclass of Coincidences. This subclass stores the paths to the station_groups that where used to look for coincidences in a lookup-table. The c_index stores the station and event id for each event in the coincidence, allowing you to find the original event row.

Suppose you want to search for coincidences between stations 501 and 503. First, download the data for these stations from the ESD. Suppose you stored the data in the ‘/s501’ and ‘/s503’ groups in the file ‘data.h5’. Then:

>>> groups = ['/s501', '/s503']
>>> with CoincidencesESD('data.h5', '/coincidences', groups) as coin:
...     coin.search_and_store_coincidences(station_numbers=[501, 503])

If you want a more manual method, replace the last line with, for example:

>>> with CoincidencesESD('data.h5', '/coincidences', groups) as coin:
...     coin.search_coincidences(5000, shifts=[None, 10], limit=100)
...     coin.store_coincidences(station_numbers=[501, 503])

You can then provide different parameters to the individual methods. See the corresponding docstrings for more details.

Once the coincidences are stored, there will be a coincidences table in the group. This table has multiple columns used for storing simulation inputs like shower direction and energy. At this point, they contain no information. They are only used if the event and coincidence tables were created by simulations, instead of real detector data. The useful columns are:

id: the index of this coincidence. This index is identical for the coincidence and c_index tables.

timestamp: the timestamp of the event in seconds

nanoseconds: the subsecond part of the timestamp in nanoseconds

ext_timestamp: the timestamp of the event in nanoseconds (equal to timestamp * 1000000000 + nanoseconds)

N: the number of stations participating in this coincidence

s501, s503, …: for each station indicate whether it participated in the coincidence.

The coincidences group furthermore contains the tables s_index and c_index to track down the individual events making up the coincidence. The s_index table contains a row for each station, pointing to the station’s event tables. The c_index table gives indexes for the individual events inside those tables.

If you have obtained a particular coincidence from the coincidences table, the id is the index into all these tables. For example, looking up the source events making up the 40th coincidence:

>>> group = data.root.coincidences
>>> idx = 40
>>> group.coincidences[idx]

can be done in the following way (each row in the c_index table is a (station index, event index) pair):

>>> for station_idx, event_idx in group.c_index[idx]:
...     station_path = group.s_index[station_idx]
...     event_group = data.get_node(station_path, 'events')
...     event = event_group[event_idx]

The event is one of the events in the coincidence.

Coincidences stored by this class can easily be searched by using a CoincidenceQuery object.

Initialize the class.

Parameters:

data – either a PyTables file or path to a HDF5 file.
coincidence_group – the destination group. If None the results can not be stored, but coincidences can still be searched for.
station_groups – a list of groups containing the station data.
overwrite – if True overwrite a previous coincidences group.
progress – if True show a progressbar while storing coincidences.

search_and_store_coincidences(window=10000, station_numbers=None)¶

Search and store coincidences.

This is a semi-automatic method to search for coincidences and then store the results in the coincidences group.

search_coincidences(window=10000, shifts=None, limit=None)¶

Search for coincidences.

Search all data in the station_groups for coincidences, and store rudimentary coincidence data in attributes. This data might be useful, but is very basic. You can call the store_coincidences() method to store the coincidences in an easier format in the coincidences group.

If you want to process the preliminary results: they are stored in the attributes _src_c_index and _src_timestamps. The former is a list of coincidences, which each consist of a list with indexes into the timestamps array as a pointer to the events making up the coincidence. The latter is a list of tuples. Each tuple consists of a timestamp followed by an index into the stations list which designates the detector station which measured the event, and finally an index into that station’s event table.

Parameters:

window – the coincidence time window. All events with delta t’s smaller than this window will be considered a coincidence.
shifts – optionally shift a station’s data in time. This can be useful if a station has a misconfigured GPS clock. Expects a list of shifts, one for each station.
limit – optionally limit the search for this number of events.

store_coincidences(station_numbers=None)¶

Store the previously found coincidences.

After having searched for coincidences, you can store the more user-friendly results in the coincidences group using this method. It also created a c_index and s_index table to find the source events.

Parameters:: station_numbers – optional list of station_numbers. If given these will be used to attach correct numbers to the station column names in the coincidences table. Otherwise they will simply be numbered by id. This list must be the same length as the station_groups.

sapphire.analysis.coincidences.get_events(data, stations, coincidence, timestamps, get_raw_traces=False)¶

Get event data of a coincidence

Return a list of events making up a coincidence.

Parameters:

data – the PyTables data file
stations – a list of HiSPARC event tables (normally from different stations, hence the name)
coincidence – a coincidence, as returned by search_coincidences().
timestamps – the list of timestamps, as returned by search_coincidences().
get_raw_traces – boolean. If true, return the raw ADC values instead of the baseline corrected traces.

Returns:

a list of tuples. Each tuple consists of (station, event, traces), where event is the event row from PyTables and traces is a list of the uncompressed traces.

Search for coincidences between HiSPARC stations¶

Table of Contents

Previous topic

Next topic