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 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 tries to download the file from the test data server.

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 CTAPIPE_SVC_PATH (a colon-separated list of directories) and then in the download cache.

find_in_path(filename, searchpath[, url])

Search in searchpath for filename, returning full path.

get_bright_stars(time[, catalog, pointing, ...])

Get an astropy table of bright stars from the specified star catalog.

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).

get_file_type(path)

Determine the file type from its contents.

get_table_dataset(table_name[, role])

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

resource_file(filename)

Get the absolute path of ctapipe resource files.

Classes#

EventTypeFilter(*args, **kwargs)

Check that an event has one of the allowed types

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.

TableInterpolator(filename[, verbose])

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

UnstructuredInterpolator(keys, values[, ...])

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

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_star_catalog(catalog[, ...])

Utility function to download a star catalog for the get_bright_stars function.

get_bright_stars(time[, catalog, pointing, ...])

Get an astropy table of bright stars from the specified star catalog.

Classes#

StarCatalog(*values)

Enumeration of star catalogs with their respective metadata.

CatalogInfo(directory, coordinates, columns, ...)

ctapipe.utils.datasets Module#

Functions#

find_all_matching_datasets(pattern[, ...])

Returns a list of resource names (or substrings) matching the given pattern, searching first in CTAPIPE_SVC_PATH (a colon-separated list of directories) and then in the download cache.

find_in_path(filename, searchpath[, url])

Search in searchpath for filename, returning full path.

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).

get_default_url()

Get the default download url for datasets

get_file_type(path)

Determine the file type from its contents.

get_searchpath_dirs([searchpath, url])

returns a list of dirs in specified searchpath

get_structured_dataset(basename[, role])

find and return a YAML or JSON dataset as a dictionary

get_table_dataset(table_name[, role])

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

resource_file(filename)

Get the absolute path of ctapipe resource files.

try_filetypes(basename, role, file_types[, url])

Get the contents of dataset as an astropy.table.Table object from different file types if available.

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