Command-line Tools (tools)#

Introduction#

ctapipe.tools contains the command line tools that use the ctapipe framework. All commandline tools inherit from ctapipe.core.Tool which provides a common user-interface experience, complete with command-line and configuration file handling, logging, and provenance features. See ctapipe.core documentation for examples.

Getting Started#

You can find out what ctapipe tools are installed using the ctapipe-info command-line tool:

ctapipe-info --tools        # list all tools
ctapipe-info --version      # show ctapipe version
ctapipe-info --dependencies # list dependencies

To find out more about a specific tool, use it’s --help command-line option

Common Tool Functionality#

  • High-level command-line options can be seen with --help

  • Low-level (Component) options can be seen with --help-all

  • You can either specify options on the command-line, or in a config file (so far in JSON or python format, see the documentation for traitlets.config). Specify this configuration file using the --config=FILENAME option.

  • You can set the logging level of a tool using --log_level to a value or name in the list [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL']. By default, only warning messages are shown, but if you specify DEBUG you will get everything.

Developing a New Tool#

To create a new command-line Tool, follow the following procedure:

  1. make a subclass of ctapipe.core.Tool

  2. define any user-configurable parameters of the tool

  3. register all configurable ctapipe.core.Component classes that you want to be configured via the Tool via its classes attribute

  4. use the aliases attribute to promote any parameters from one of the sub-Components to a high-level a command-line parameter (they can still be specified using the advanced command-line command syntax or via a config file if you do not do this, but if the parameter is commonly changed by the user, having it be high-level is more convenient

  5. overload the setup(self), start(self), and finish(self) methods to implement the functinatlity of the tool (these will be called in order when you call the run() method.

  6. make sure you have a function called main() that creates and runs your tool in the source file.

  7. add the file and main() function you made in step 6 to the top-level setup.py file under the section called entry_points['console_scripts']. This will automatically create an executable called ctapipe-* where * is the name of the source file of your tool (e.g. mytool.py will become ctapipe-mytool.

  8. this new tool will be installed in the bin directory next time you run make develop at the top-level of ctapipe, or if you re-install the ctapipe package in non-developer mode.

Reference/API#

ctapipe.tools Package#

ctapipe command line tools.

ctapipe.tools.quickstart Module#

Create a working directory for ctapipe-process containing standard configuration files.

Classes#

QuickStartTool(**kwargs)

Generate quick start files and directory structure.

ctapipe.tools.process Module#

Generate DL1 (a or b) output files in HDF5 format from {R0,R1,DL0} inputs.

Classes#

ProcessorTool(**kwargs)

Process data from lower-data levels up to DL1 and DL2, including image extraction and optionally image parameterization as well as muon analysis and shower reconstruction.

ctapipe.tools.merge Module#

Merge multiple ctapipe HDF5 files into one

Classes#

MergeTool(**kwargs)

Merge multiple ctapipe HDF5 files into one

ctapipe.tools.train_energy_regressor Module#

Tool for training the EnergyRegressor

Classes#

TrainEnergyRegressor(**kwargs)

Tool to train a EnergyRegressor on dl1b/dl2 data.

ctapipe.tools.train_particle_classifier Module#

Tool for training the ParticleClassifier

Classes#

TrainParticleClassifier(**kwargs)

Tool to train a ParticleClassifier on dl1b/dl2 data.

ctapipe.tools.train_disp_reconstructor Module#

Tool for training the DispReconstructor

Classes#

TrainDispReconstructor(**kwargs)

Tool to train a DispReconstructor on dl1b/dl2 data.

ctapipe.tools.apply_models Module#

Tool to apply machine learning models in bulk (as opposed to event by event).

Classes#

ApplyModels(**kwargs)

Apply machine learning models to data.

ctapipe.tools.optimize_event_selection Module#

Tool to generate selections for IRFs production

Classes#

EventSelectionOptimizer(**kwargs)

Tool to create optimized cuts for IRF generation

ctapipe.tools.compute_irf Module#

Tool to generate IRFs

Classes#

IrfTool(**kwargs)

Tool to create IRF files in GADF format

ctapipe.tools.dump_instrument Module#

Dump instrumental descriptions in a monte-carlo (simtelarray) input file to FITS files that can be loaded independently (e.g. with CameraGeometry.from_table()). The name of the output files are automatically generated.

Classes#

DumpInstrumentTool(**kwargs)

ctapipe.tools.calculate_pixel_stats Module#

Perform statistics calculation from pixel-wise image data

Classes#

PixelStatisticsCalculatorTool(**kwargs)

Perform statistics calculation for pixel-wise image data

ctapipe.tools.store_astropy_cache Module#

Script to download astropy data needed for coordinate transformations.

Functions#

main([args])

Download data needed for astropy coordinate transformations into a cache directory.