SubarrayDescription#

class ctapipe.instrument.SubarrayDescription(name, tel_positions, tel_descriptions, reference_location)[source]#

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

`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])	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

classmethod from_hdf(path, focal_length_choice=FocalLengthKind.EFFECTIVE)[source]#

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

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][source]#

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)[source]#

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>)[source]#: print descriptive info about subarray

multiplicity(tel_mask, tel_type=None)[source]#

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)[source]#

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)[source]#

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[source]#

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)[source]#

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)[source]#

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)[source]#

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')[source]#

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')[source]#

export SubarrayDescription information as an astropy.table.Table

Parameters:

kind: str: which table to generate (subarray or optics)