SubarrayDescription

class ctapipe.instrument.subarray.SubarrayDescription(name, tel_positions, tel_descriptions, reference_location)

Bases: object

Collects the TelescopeDescription of all telescopes along with their positions on the ground.

Attributes:

name: str

name of subarray

tel_coords: ctapipe.coordinates.GroundFrame

coordinates of all telescopes

tels:

dict of TelescopeDescription for each telescope in the subarray

Attributes Summary

COMPATIBLE_VERSIONS	Version numbers supported by SubarrayDescription.from_hdf
CURRENT_TAB_VERSION	Current version number of the format written by SubarrayDescription.to_hdf
camera_types	Tuple of unique camera types in the array
footprint	area of smallest circle containing array on ground
n_tels	number of telescopes in this subarray
optics_types	Tuple of unique optics types in the array
tel	Dictionary mapping tel_ids to TelescopeDescriptions
tel_coords	Telescope positions in GroundFrame
tel_ids	Array of telescope ids in order of telescope indices
tel_index_array	Array of telescope indices that can be indexed by telescope id
tel_indices	dictionary mapping telescope ids to telescope index
telescope_types	Tuple of unique telescope types in the array

Methods Summary

check_matching_subarrays(subarray_list)	Check if subarrays are matching
from_hdf(path[, focal_length_choice])
get_tel_ids(telescopes)	Convert a list of telescope ids and telescope descriptions to a list of unique telescope ids.
get_tel_ids_for_type(tel_type)	return tuple of tel_ids that have the given tel_type
get_tel_indices_for_type(tel_type)	return tuple of telescope indices that have the given tel_type
info([printer])	print descriptive info about subarray
multiplicity(tel_mask[, tel_type])	Compute multiplicity from a telescope mask
peek([ax])	Draw a quick matplotlib plot of the array
read(path, **kwargs)	Read subarray from path
select_subarray(tel_ids[, name])	return a new SubarrayDescription that is a sub-array of this one
tel_ids_to_indices(tel_ids)	maps a telescope id (or array of them) to flat indices
tel_ids_to_mask(tel_ids)	Convert a list of telescope ids to a boolean mask of length n_tels where the index of the telescope is set to True for each tel_id in tel_ids
tel_mask_to_tel_ids(tel_mask)	Convert a boolean mask of selected telescopes to a list of tel_ids.
to_hdf(h5file[, overwrite, mode])	write the SubarrayDescription
to_table([kind, meta_convention])	export SubarrayDescription information as an astropy.table.Table

Attributes Documentation

COMPATIBLE_VERSIONS = {'2.0'}

Version numbers supported by SubarrayDescription.from_hdf

CURRENT_TAB_VERSION = '2.0'

Current version number of the format written by SubarrayDescription.to_hdf

camera_types

Tuple of unique camera types in the array

The entries are ordered by camera name to be deterministic but the order should not be relied on.

footprint

area of smallest circle containing array on ground

n_tels

number of telescopes in this subarray

optics_types

Tuple of unique optics types in the array

The entries are ordered by optics name to be deterministic but the order should not be relied on.

tel

Dictionary mapping tel_ids to TelescopeDescriptions

tel_coords

Telescope positions in GroundFrame

tel_ids

Array of telescope ids in order of telescope indices

tel_index_array

Array of telescope indices that can be indexed by telescope id

I.e. for a given telescope, this array maps the tel_id to a flat index starting at 0 for the first telescope. tel_index = subarray.tel_index_array[tel_id]

If the tel_ids are not contiguous, gaps will be filled in by int minval. For a more compact representation use the tel_indices

tel_indices

dictionary mapping telescope ids to telescope index

telescope_types

Tuple of unique telescope types in the array

The entries are ordered by telescope name to be deterministic but the order should not be relied on.

Methods Documentation

static check_matching_subarrays(subarray_list: list) → bool

Check if subarrays are matching

Currently only checks if the tel_ids are the same in all subarrays. More checks can be added if needed.

classmethod from_hdf(path, focal_length_choice=FocalLengthKind.EFFECTIVE)

get_tel_ids(telescopes: Iterable[int | str | TelescopeDescription]) → tuple[int]

Convert a list of telescope ids and telescope descriptions to a list of unique telescope ids.

Parameters:

telescopes: List[Union[int, str, TelescopeDescription]]

List of Telescope IDs and descriptions. Supported inputs for telescope descriptions are instances of TelescopeDescription as well as their string representation.

Returns:

tel_ids: List[int]

List of unique telescope ids matching telescopes

get_tel_ids_for_type(tel_type) → tuple[int]

return tuple of tel_ids that have the given tel_type

Parameters:

tel_type: str or TelescopeDescription

telescope type string (e.g. ‘MST_MST_NectarCam’)

get_tel_indices_for_type(tel_type)

return tuple of telescope indices that have the given tel_type

Parameters:

tel_type: str or TelescopeDescription

telescope type string (e.g. ‘MST_MST_NectarCam’)

info(printer=<built-in function print>)

print descriptive info about subarray

multiplicity(tel_mask, tel_type=None)

Compute multiplicity from a telescope mask

Parameters:

tel_masknp.ndarray

Boolean array with last dimension of size n_telescopes

tel_typeNone, str or TelescopeDescription

If not given, compute multiplicity from all telescopes. If given, the multiplicity of the given telescope type will be computed.

Returns:

multiplicityint or np.ndarray

Number of true values for given telescope mask and telescope type

peek(ax=None)

Draw a quick matplotlib plot of the array

Parameters:

axmatplotlib.axes.Axes or None

If given, the subarray will be plotted into this ax.

static read(path, **kwargs)

Read subarray from path

This uses the EventSource mechanism, so it should be able to read a subarray from any file supported by ctapipe or an installed io plugin.

kwargs are passed to the event source

select_subarray(tel_ids, name=None) → SubarrayDescription

return a new SubarrayDescription that is a sub-array of this one

Parameters:

tel_ids: list(int)

list of telescope IDs to include in the new subarray

name: str

name of new sub-selection

Returns

——-

SubarrayDescription

tel_ids_to_indices(tel_ids)

maps a telescope id (or array of them) to flat indices

Parameters:

tel_idsint or List[int]

array of tel IDs

Returns:

np.array:

array of corresponding tel indices

tel_ids_to_mask(tel_ids)

Convert a list of telescope ids to a boolean mask of length n_tels where the index of the telescope is set to True for each tel_id in tel_ids

Parameters:

tel_idsint or List[int]

array of tel IDs

Returns:

np.array[dtype=bool]:

Boolean array of length n_tels with indices of the telescopes in tel_ids set to True.

tel_mask_to_tel_ids(tel_mask)

Convert a boolean mask of selected telescopes to a list of tel_ids.

Parameters:

tel_mask: array-like

Boolean array of length n_tels with indices of the telescopes in tel_ids set to True.

Returns

——-

np.array:

Array of selected tel_ids

to_hdf(h5file, overwrite=False, mode='a')

write the SubarrayDescription

Parameters:

h5filestr, bytes, path or tables.File

Path or already opened tables.File with write permission

overwriteFalse

If the output path already contains a subarray, by default an error will be raised. Set overwrite=True to overwrite an existing subarray. This does not affect other content of the file. Use mode="w" to completely overwrite the output path.

modestr

If h5file is not an already opened file, the output file will be opened with the given mode. Must be a mode that enables writing.

to_table(kind='subarray', meta_convention='hdf')

export SubarrayDescription information as an astropy.table.Table

Parameters:

kind: str

which table to generate (subarray or optics)