Common utility functions


The module contains some commonly functions and classes.

sapphire.utils.ERR = [-1, -999]

Error values used to indicate missing or bad data. Code -999 is used if the reconstruction of a quantity failed. Code -1 is used if that detector/sensor is not present.

sapphire.utils.c = 0.299792458

Speed of light in vacuum in m / ns.


Get the HiSPARC Public Database base URL

This can be configured by setting the PUBLICDB_BASE environment variable to the desired URL.

sapphire.utils.pbar(iterable, length=None, show=True, **kwargs)

Get a new progressbar with our default widgets

  • iterable – the iterable over which will be looped.

  • length – in case iterable is a generator, this should be its expected length.

  • show – boolean, if False simply return the iterable.


a new iterable which iterates over the same elements as the input, but shows a progressbar if possible.

sapphire.utils.ceil_in_base(value, base)

Get nearest multiple of base above the value

sapphire.utils.floor_in_base(value, base)

Get nearest multiple of base below the value

sapphire.utils.round_in_base(value, base)

Get nearest multiple of base to the value

sapphire.utils.closest_in_list(value, items)

Get nearest item from a list of items to the value

sapphire.utils.get_active_index(values, value)

Get the index where the value fits.

  • values – sorted list of values (e.g. list of timestamps).

  • value – value for which to find the position (e.g. a timestamp).


index into the values list.

sapphire.utils.gauss(x, n, mu, sigma)

Gaussian distribution

To be used for fitting where the integral is not 1.


Normalize an angle to the range [-pi, pi)

We use the range from -pi upto but not including pi to represent angles.

sapphire.utils.angle_between(zenith1, azimuth1, zenith2, azimuth2)

Calculate the angle between two (zenith, azimuth) coordinates

Using the haversine formula, from:

  • zenith# – Zenith parts of the coordinates, in radians (0, pi/2).

  • azimuth# – Azimuth parts of the coordinates, in radians (-pi, pi).


Angle between the two coordinates.

sapphire.utils.vector_length(x, y, z=0)

Length of a vector given by (x, y, z) coordinates


x,y,z – vector components.


length of vector.

sapphire.utils.distance_between(x1, y1, x2, y2)

Calculate the distance between two (x, y) coordinates

  • x# – x parts of the coordinates.

  • y# – y parts of the coordinates.


distance between the two coordinates.


Make first element the origin and make rest relative to it.


Check if a command line program is available

An Exception is raised if the program is not available.


program – name or program to check for, e.g. ‘wget’.


Memoisation cache decorator