HiSPARC API¶

Access the HiSPARC public database API.

This provides easy classes and functions to access the HiSPARC publicdb API. This takes care of the url retrieval and conversion from JSON to Python dictionaries.

Example usage:

>>> from sapphire import Station
>>> stations = [5, 3102, 504, 7101, 8008, 13005]
>>> clusters = [Station(station).cluster for station in stations]
>>> for station, cluster in zip(stations, clusters):
...     print('Station %d is in cluster %s.' % (station, cluster))
Station 5 is in cluster Amsterdam.
Station 3102 is in cluster Leiden.
Station 504 is in cluster Amsterdam.
Station 7101 is in cluster Enschede.
Station 8008 is in cluster Eindhoven.
Station 13005 is in cluster Bristol.

sapphire.api.get_api_base()¶

sapphire.api.get_src_base()¶

class sapphire.api.API(force_fresh=False, force_stale=False)¶

Base API class

This provided the methods to retrieve data from the API. The results are converted from JSON data to Python objects (dict/list/etc). Support is also provided for the retrieval of Source TSV data, which is returned as NumPy arrays.

Initialize API class

Parameters:: force_fresh,force_stale – if either of these is set to True the data must either loaded from server or from local data. Be default fresh data is preferred, but falls back to local data.

urls = {'clusters': 'clusters/', 'clusters_in_country': 'countries/{country_number}/', 'configuration': 'station/{station_number}/config/{year}/{month}/{day}/', 'countries': 'countries/', 'event_trace': 'station/{station_number}/trace/{ext_timestamp}/', 'has_data': 'station/{station_number}/data/{year}/{month}/{day}/', 'has_weather': 'station/{station_number}/weather/{year}/{month}/{day}/', 'number_of_events': 'station/{station_number}/num_events/{year}/{month}/{day}/{hour}/', 'station_info': 'station/{station_number}/', 'stations': 'stations/', 'stations_in_subcluster': 'subclusters/{subcluster_number}/', 'stations_with_data': 'stations/data/{year}/{month}/{day}/', 'stations_with_weather': 'stations/weather/{year}/{month}/{day}/', 'subclusters': 'subclusters/', 'subclusters_in_cluster': 'clusters/{cluster_number}/'}¶

src_urls = {'azimuth': 'azimuth/{station_number}/{year}/{month}/{day}/', 'barometer': 'barometer/{station_number}/{year}/{month}/{day}/', 'coincidencenumber': 'coincidencenumber/{year}/{month}/{day}/', 'coincidencetime': 'coincidencetime/{year}/{month}/{day}/', 'current': 'current/{station_number}/', 'detector_timing_offsets': 'detector_timing_offsets/{station_number}/', 'electronics': 'electronics/{station_number}/', 'eventtime': 'eventtime/{station_number}/{year}/{month}/{day}/', 'gps': 'gps/{station_number}/', 'integral': 'pulseintegral/{station_number}/{year}/{month}/{day}/', 'layout': 'layout/{station_number}/', 'pulseheight': 'pulseheight/{station_number}/{year}/{month}/{day}/', 'station_timing_offsets': 'station_timing_offsets/{station_1}/{station_2}/', 'temperature': 'temperature/{station_number}/{year}/{month}/{day}/', 'trigger': 'trigger/{station_number}/', 'voltage': 'voltage/{station_number}/', 'zenith': 'zenith/{station_number}/{year}/{month}/{day}/'}¶

static check_connection()¶

Open the API man page URL to test the connection

Returns:: boolean indicating the internet status

static validate_partial_date(year='', month='', day='', hour='')¶

class sapphire.api.Network(force_fresh=False, force_stale=False)¶

Get info about the network (countries/clusters/subclusters/stations)

Initialize API class

Parameters:: force_fresh,force_stale – if either of these is set to True the data must either loaded from server or from local data. Be default fresh data is preferred, but falls back to local data.

countries()¶

Get a list of countries

Returns:: all countries in the region

country_numbers()¶: Same as countries but only returns a list of country numbers

clusters(country=None)¶

Get a list of clusters

Parameters:: country – the number of the country for which to get all clusters.
Returns:: all clusters in the region

cluster_numbers(country=None)¶: Same as clusters but only returns a list of cluster numbers

subclusters(country=None, cluster=None)¶

Get a list of subclusters

Parameters:: country,cluster – the number of the region for which to get the subclusters it contains, only one or none should be specified.
Returns:: all subclusters in the region

subcluster_numbers(country=None, cluster=None)¶: Same as subclusters but only returns a list of subcluster numbers

stations(country=None, cluster=None, subcluster=None)¶

Get a list of stations

Parameters:: country,cluster,subcluster – the number of the region for which to get all stations, only one or none should be specified.
Returns:: all stations in the region

station_numbers(country=None, cluster=None, subcluster=None)¶: Same as stations but only returns a list of station numbers

nested_network()¶: Get a nested list of the full network

stations_with_data(year='', month='', day='')¶

Get a list of stations with data on the specified date

Parameters:: year,month,day – the date for which to check. It is possible to be less specific.
Returns:: all stations with data.

stations_with_weather(year='', month='', day='')¶

Get a list of stations with weather data on the specified date

Parameters:: year,month,day – the date for which to check. It is possible to be less specific.
Returns:: all stations with weather data.

coincidence_time(year, month, day)¶

Get the coincidences per hour histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

coincidence_number(year, month, day)¶

Get the number of stations in coincidence histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

static validate_numbers(country=None, cluster=None, subcluster=None)¶

uptime(stations, start=None, end=None)¶

Get number of hours for which the given stations have been simultaneously active

Using hourly eventrate data the number of hours in which the given stations all had data is determined. Only hours in which each station had a reasonable eventrate are counted, to exclude likely bad data.

Parameters:

stations – station number or a list of station numbers.
start,end – start, end timestamp.

Returns:

number of hours with simultaneous data.

class sapphire.api.Station(station, force_fresh=False, force_stale=False)¶

Access data about a single station

Initialize station

Parameters:

station – station number.
force_fresh – set to True to require data to be fresh from the server.
force_stale – set to True to require data to be taken from local data, not valid for all methods.

property info¶: Get general station info

country()¶

cluster()¶

subcluster()¶

n_detectors()¶: Get the number of detectors in this station

config(date=None)¶

Get station config

Retrieve either the latest, or a config for a specific date.

Parameters:: date – date object for which to get the config
Returns:: the full config for the station

n_events(year='', month='', day='', hour='')¶

Get number of events

Note that it is possible to give only the year to get the total number of events in that year. If both year and month are given, the total events in that month are returned.

Parameters:: year,month,day,hour – the date and time for which to get the number. It is possible to be less specific.
Returns:: the number of events recorded by the station on date.

has_data(year='', month='', day='')¶

Check for HiSPARC data

Parameters:: year,month,day – the date for which to check. It is possible to be less specific.
Returns:: boolean, indicating whether the station had air shower data on the date.

has_weather(year='', month='', day='')¶

Check for weather data

Parameters:: year,month,day – the date for which to check. It is possible to be less specific.
Returns:: boolean, indicating whether the station had weather data on the date.

event_trace(timestamp, nanoseconds, raw=False)¶

Get the traces for a specific event

The exact timestamp and nanoseconds for the event have to be given.

Parameters:

timestamp,nanoseconds – the extended timestamp for which to get the traces.
raw – get the raw trace, without the subtracted baselines.

Returns:

an array with the traces for each detector in ADCcounts

event_time(year='', month='', day='')¶

Get the number of events per hour histogram

If no date is given the full event time histogram for this station will be returned. That means for the entire time this station has collected data.

This data (the full histogram) can made available locally using the extend_local_data command.

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

pulse_height(year, month, day)¶

Get the pulseheight histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

pulse_integral(year, month, day)¶

Get the pulseintegral histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

azimuth(year, month, day)¶

Get the azimuth histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

zenith(year, month, day)¶

Get the zenith histogram

Parameters:: year,month,day – the date for which to get the histogram.
Returns:: array of bins and counts.

barometer(year, month, day)¶

Get the barometer dataset

Parameters:: year,month,day – the date for which to get the dataset.
Returns:: array of timestamps and values.

temperature(year, month, day)¶

Get the temperature dataset

Parameters:: year,month,day – the date for which to get the dataset.
Returns:: array of timestamps and values.

property electronics¶

Get the electronics version data

Returns:: array of timestamps and values.

electronic(timestamp=None)¶

Get electronics version data for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: list of values for given timestamp.

property voltages¶

Get the PMT voltage data

Returns:: array of timestamps and values.

voltage(timestamp=None)¶

Get PMT voltage data for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: list of values for given timestamp.

property currents¶

Get the PMT current data

Returns:: array of timestamps and values.

current(timestamp=None)¶

Get PMT current data for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: list of values for given timestamp.

property gps_locations¶

Get the GPS location data

Returns:: array of timestamps and values.

gps_location(timestamp=None)¶

Get GPS location for specific timestamp

Parameters:: timestamp – optional timestamp or datetime object for which the values are valid.
Returns:: dictionary with the values for given timestamp.

property triggers¶

Get the trigger config data

Returns:: array of timestamps and values.

trigger(timestamp=None)¶

Get trigger config for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: thresholds and trigger values for given timestamp.

property station_layouts¶

Get the station layout data

Returns:: array of timestamps and values.

station_layout(timestamp=None)¶

Get station layout data for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: list of coordinates for given timestamp.

property detector_timing_offsets¶

Get the detector timing offsets data

Returns:: array of timestamps and values.

detector_timing_offset(timestamp=None)¶

Get detector timing offset data for specific timestamp

Parameters:: timestamp – timestamp for which the values are valid.
Returns:: list of values for given timestamp.

station_timing_offsets(reference_station)¶

Get the station timing offset relative to reference_station

Parameters:: reference_station – reference station
Returns:: array of timestamps and values.

station_timing_offset(reference_station, timestamp=None)¶

Get station timing offset data for specific timestamp

Parameters:

reference_station – reference station
timestamp – timestamp for which the value is valid.

Returns:

the offset and error for given timestamp.

HiSPARC API¶

Table of Contents

Previous topic

Next topic