# 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:

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) 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) Search in searchpath for filename, returning full path. 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. CutFlow([name]) a class that keeps track of e.g. PureCountingCut UndefinedCut 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.

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