Utilities (utils)

Introduction

ctapipe.utils contains a variety of low-level functionality used by other modules that are not part of the ctapipe.core package. Classes in this package may eventually move to ctapipe.core if they have a stable enough API and are more widely used.

It currently provides:

  • ND Histogramming (see Histogram)

  • ND table interpolation (see TableInterpolator)

  • access to service datasets

  • linear algebra helpers

  • dynamic class access

  • json conversion

Access to Service Data files

The get_dataset_path() function provides a common way to load CTA “SVC” data (e.g. required lookups, example data, etc). It returns the full directory path to the requested file. It currently works as follows:

  1. it checks all directories in the CTA_SVC_PATH environment variable (which should be a colon-separated list of directories, like PATH)

  2. if it doesn’t find it there, it checks the ctapipe_resources module (which should be installed already in the package ctapipe-extra), which contains defaults.

Tabular data can be accessed automatically using get_table_dataset(basename), where the basename is the filename without the extension. Several tabular formats will be searched and when the file is found it will be opened and read as an astropy.table.Table object. For example:

from ctapipe.utils import get_table_dataset

optics = get_table_dataset('optics')
print(optics)

Reference/API

ctapipe.utils Package

Functions

find_all_matching_datasets(pattern[, …])

Returns a list of resource names (or substrings) matching the given pattern, searching first in searchpath (a colon-separated list of directories) and then in the ctapipe_resources module)

get_table_dataset(table_name[, role])

get a tabular dataset as an astropy.table.Table object

get_dataset_path(filename[, url])

Returns the full file path to an auxiliary dataset needed by ctapipe, given the dataset’s full name (filename with no directory).

find_in_path(filename, searchpath[, url])

Search in searchpath for filename, returning full path.

resource_file(filename)

Get the absoulte path of ctapipe resource files.

get_bright_stars([pointing, radius, …])

Returns an astropy table containing star positions above a given magnitude within a given radius around a position in the sky, using the Yale bright star catalog which needs to be present in the ctapipe-extra package.

Classes

Histogram(nbins, ranges[, name, axis_names])

An N-D histogram class with FITS image I/O.

TableInterpolator(filename[, verbose])

This is a simple class for loading lookup tables from a fits file and interpolating between them

UnstructuredInterpolator(interpolation_points)

This class performs linear interpolation between an unstructured set of data points.

IndexFinder(values)

Helper class to find the index of the closest matching value in an array/list/…, used to locate the pointing of an event based on the trigger time.

EventTypeFilter(**kwargs)

Check that an event has one of the allowed types

ctapipe.utils.astro Module

This module is intended to contain astronomy-related helper tools which are not provided by external packages and/or to satisfy particular needs of usage within ctapipe.

Functions

get_bright_stars([pointing, radius, …])

Returns an astropy table containing star positions above a given magnitude within a given radius around a position in the sky, using the Yale bright star catalog which needs to be present in the ctapipe-extra package.

ctapipe.utils.datasets Module

Functions

get_dataset_path(filename[, url])

Returns the full file path to an auxiliary dataset needed by ctapipe, given the dataset’s full name (filename with no directory).

find_in_path(filename, searchpath[, url])

Search in searchpath for filename, returning full path.

find_all_matching_datasets(pattern[, …])

Returns a list of resource names (or substrings) matching the given pattern, searching first in searchpath (a colon-separated list of directories) and then in the ctapipe_resources module)

get_default_url()

Get the default download url for datasets

ctapipe.utils.download Module

Functions

download_file(url, path[, auth, chunk_size, …])

Download a file.

download_cached(url[, cache_name, auth, …])

download_file_cached(name[, cache_name, …])

Downloads a file from a dataserver and caches the result locally in $HOME/.cache/<cache_name>.

ctapipe.utils.linalg Module

Functions

rotation_matrix_2d(angle)

construct a 2D rotation matrix as a numpy NDArray that rotates a vector clockwise.

length(vec)

returns the length/norm of a numpy array as the square root of the inner product with itself

normalise(vec)

Sets the length of the vector to 1

angle(v1, v2)

computes the angle between two vectors