SubarrayDescription#

class ctapipe.instrument.subarray.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_ARRAY_ELEMENTS_IDENTIFIERS_VERSIONS`	Array element identifiers versions supported by `SubarrayDescription.from_service_data`
`COMPATIBLE_SERVICE_DATA_VERSIONS`	Service data versions supported by `SubarrayDescription.from_service_data`
`COMPATIBLE_SUBARRAY_IDENTIFIERS_VERSIONS`	Subarray identifiers versions supported by `SubarrayDescription.from_service_data`
`COMPATIBLE_VERSIONS`	Version numbers supported by `SubarrayDescription.from_hdf`
`CURRENT_ARRAY_ELEMENTS_IDENTIFIERS_VERSION`	Current version of the array element identifiers ("ctao.common.identifiers.array_elements") expected by `SubarrayDescription.from_service_data`
`CURRENT_SERVICE_DATA_VERSION`	Current version of the service data format expected by `SubarrayDescription.from_service_data`
`CURRENT_SUBARRAY_IDENTIFIERS_VERSION`	Current version of the subarray identifiers ("ctao.common.identifiers.subarrays") expected by `SubarrayDescription.from_service_data`
`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_earth_locations`	Telescope positions as `EarthLocation` objects.
`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])
`from_service_data`(subarray_id[, ...])	Create a SubarrayDescription from CTAO service data files.
`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_ARRAY_ELEMENTS_IDENTIFIERS_VERSIONS = {'2.0'}#: Array element identifiers versions supported by SubarrayDescription.from_service_data

COMPATIBLE_SERVICE_DATA_VERSIONS = {'1.0'}#: Service data versions supported by SubarrayDescription.from_service_data

COMPATIBLE_SUBARRAY_IDENTIFIERS_VERSIONS = {'2.0'}#: Subarray identifiers versions supported by SubarrayDescription.from_service_data

COMPATIBLE_VERSIONS = {'2.0'}#: Version numbers supported by SubarrayDescription.from_hdf

CURRENT_ARRAY_ELEMENTS_IDENTIFIERS_VERSION = '2.0'#: Current version of the array element identifiers (“ctao.common.identifiers.array_elements”) expected by SubarrayDescription.from_service_data

CURRENT_SERVICE_DATA_VERSION = '1.0'#: Current version of the service data format expected by SubarrayDescription.from_service_data

CURRENT_SUBARRAY_IDENTIFIERS_VERSION = '2.0'#: Current version of the subarray identifiers (“ctao.common.identifiers.subarrays”) expected by SubarrayDescription.from_service_data

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

Telescope positions as EarthLocation objects.

Returns:

dict[int, EarthLocation]: Dictionary mapping telescope IDs to their EarthLocation. This is cached to avoid expensive repeated conversions.

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

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

classmethod from_service_data(subarray_id, focal_length_choice=FocalLengthKind.EFFECTIVE)[source]#

Create a SubarrayDescription from CTAO service data files.

This method loads subarray definitions from the service data.

Expected directory structure:

instrument/
├── instrument.meta.json
├── array-element-ids.json
├── array-elements/
│   ├── LSTN/
│   │   ├── LSTN.camgeom.fits.gz
│   │   ├── LSTN.camreadout.fits.gz
│   │   └── LSTN.optics.ecsv
│   ├── MSTN/
│   │   ├── MSTN.camgeom.fits.gz
│   │   ├── MSTN.camreadout.fits.gz
│   │   └── MSTN.optics.ecsv
│   ├── 001/
│   │   ├── 001.optics.ecsv -> ../LSTN/LSTN.optics.ecsv
│   │   ├── 001.camgeom.fits.gz -> ../LSTN/LSTN.camgeom.fits.gz
│   │   └── 001.camreadout.fits.gz -> ../LSTN/LSTN.camreadout.fits.gz
│   ├── 002/
│   │   ├── 002.optics.ecsv -> ../LSTN/LSTN.optics.ecsv
│   │   ├── 002.camgeom.fits.gz -> ../LSTN/LSTN.camgeom.fits.gz
│   │   └── 002.camreadout.fits.gz -> ../LSTN/LSTN.camreadout.fits.gz
│   └── ...
├── positions/
│   ├── CTAO-North_ArrayElementPositions.ecsv
│   └── CTAO-South_ArrayElementPositions.ecsv
└── subarray-ids.json

Files:

instrument.meta.json: metadata about the service data version for backwards compatibility
array-element-ids.json: mapping of telescope IDs to names
subarray-ids.json: subarray definitions
positions/{site}_ArrayElementPositions.ecsv: ECSV files with telescope positions for each site
array-elements/{type}/: Shared telescope-type directories (e.g., LSTN, MSTN) containing instrument descriptions. Each directory contains optics.ecsv, camgeom.fits.gz, and camreadout.fits.gz files named with the type prefix.
array-elements/{ae_id:03d}/: Real directories for each array element, each containing per-file symlinks to the shared type files. Files are named with the ae_id prefix (e.g., 001.optics.ecsv) but point to the type directory.

Parameters:

subarray_idint: The subarray ID to load
focal_length_choiceFocalLengthKind: Whether to use the effective or equivalent focal length for the definition of the camera coordinate frame.

Returns:

SubarrayDescription: New SubarrayDescription instance

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', meta_convention='hdf')[source]#

export SubarrayDescription information as an astropy.table.Table

Parameters:

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