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