# scripts - Command line tools¶

Warning

The Gammapy command line interface (CLI) described here is experimental and only supports a small sub-set of the functionality available via the Gammapy Python package.

## Introduction¶

Currently, Gammapy is first and foremost a Python package. This means that to use it you have to write a Python script or Jupyter notebook, where you import the functions and classes needed for a given analysis, and then call them, passing parameters to configure the analysis.

We have also have a analysis - High-level interface that provides high-level Python functions for the most common needs present in the analysis process.

That said, for some very commonly used and easy to configure analysis tasks we have implemented a command line interface (CLI). It is automatically installed together with the Gammapy python package.

### Execute¶

To execute the Gammapy CLI, type the command gammapy at your terminal shell (not in Python):

$gammapy --help  or equivalently, just type this: $ gammapy


Either way, the command should print some help text to the console and then exit:

Usage: gammapy [OPTIONS] COMMAND [ARGS]...

Gammapy command line interface (CLI).

Gammapy is a Python package for gamma-ray astronomy.

Use --help to see available sub-commands, as well as the available
arguments and options for each sub-command.

For further information, see https://gammapy.org/ and
https://docs.gammapy.org/

Examples
--------

$gammapy --help$ gammapy --version
$gammapy info --help$ gammapy info

Options:
--log-level [debug|info|warning|error]
Logging verbosity level.
--ignore-warnings               Ignore warnings?
--version                       Print version and exit.
-h, --help                      Show this message and exit.

Commands:
analysis  Automation of configuration driven data reduction process.
check     Run checks for Gammapy
jupyter   Perform actions on notebooks


All CLI functionality for Gammapy is implemented as sub-commands of the main gammapy command. If a command has sub-commands, they are listed in the help output. E.g. the help output from gammapy above shows that there is a sub-command called gammapy analysis. Actually, gammapy analysis itself isn’t a command that does something, but another command group that is used to group sub-commands.

So now you know how the Gammapy CLI is structured and how to discover all available sub-commands, arguments and options.

### Running config driven data reduction¶

Here’s the main usage of the Gammapy CLI for data processing: use the gammapy analysis command to first create a default configuration file with default values and then perform a simple automated data reduction process (i.e. fetching observations from a datastore and producing the reduced datasets.)

$gammapy analysis --help Usage: gammapy analysis [OPTIONS] COMMAND [ARGS]... Automation of configuration driven data reduction process. Examples --------$ gammapy analysis config
$gammapy analysis run$ gammapy analysis config --overwrite
$gammapy analysis config --filename myconfig.yaml$ gammapy analysis run --filename myconfig.yaml

Options:
-h, --help  Show this message and exit.

Commands:
config  Writes default configuration file.
run     Performs automated data reduction process.

$gammapy analysis config INFO:gammapy.scripts.analysis:Configuration file produced: config.yaml  You can manually edit this produced configuration file and the run the data reduction process: $ gammapy analysis run

INFO:gammapy.analysis.config:Setting logging config: {'level': 'INFO', 'filename': None, 'filemode': None, 'format': None, 'datefmt': None}
INFO:gammapy.analysis.core:Fetching observations.
INFO:gammapy.analysis.core:Number of selected observations: 4
INFO:gammapy.analysis.core:Reducing spectrum datasets.
INFO:gammapy.analysis.core:Processing observation 23592
INFO:gammapy.analysis.core:Processing observation 23523
INFO:gammapy.analysis.core:Processing observation 23526
INFO:gammapy.analysis.core:Processing observation 23559
Datasets stored in datasets folder.


This section explains how to write your own command line interface (CLI).

We will focus on the command line aspect, and use a very simple example where we just call gammapy.stats.CashCountsStatistics.sqrt_ts.

From the interactive Python or IPython prompt or from a Jupyter notebook you just import the functionality you need and call it, like this:

>>> from gammapy.stats import CashCountsStatistic
>>> CashCountsStatistic(n_on=10, mu_bkg=4.2).sqrt_ts
2.3979181291475453


If you imagine that the actual computation involves many lines of code (and not just a one-line function call), and that you need to do this computation frequently, you will probably write a Python script that looks something like this:

# Compute significance for a Poisson count observation
from gammapy.stats import CashCountsStatistic

n_observed = 10
mu_background = 4.2

s = CashCountsStatistic(n_observed, mu_background).sqrt_ts
print(s)


We have introduced variables that hold the parameters for the analysis and put them before the computation. Let’s say this script is in a file called significance.py, then to use it you put the parameters you like and then execute it via:

$python significance.py  If you want, you can also put the line #!/usr/bin/env python at the top of the script, make it executable via chmod +x significance.py and then you’ll be able to execute it via ./significance.py if you prefer to execute it like this. This works on Linux and Mac OS, but not on Windows. It is also possible to omit the .py extension from the filename, i.e. to simply call the file significance. Either way has some advantages and disadvantages, it’s a matter of taste. Omitting the .py is nice because users calling the tool usually don’t care that it’s a Python script, and it’s shorter. But omitting the .py also means that some advanced users that open up the file in an editor have a harder time (because the editor might not recognise it as a Python file and syntax highlight appropriately), or more importantly that importing functions of classes from that script from other Python files or Jupyter notebooks is not easily possible, leading some people to rename it or copy & paste from it. We’re explaining these details, because if you work with colleagues and share scripts, you’ll encounter the #!/usr/bin/env python and scripts with and without .py and will need to know how to work with them. Writing and using such scripts is perfectly fine and a common way to run science analyses. However, if you use it very frequently it might become annoying to have to open up and edit the significance.py file every time to use it. In that case, you can change your script into a command line interface that allows you to set analysis parameters without having to edit the file, like this: $ python significance.py --help
Usage: significance.py [OPTIONS] N_OBSERVED MU_BACKGROUND

Compute significance for a Poisson count observation.

The significance is the tail probability to observe N_OBSERVED counts or
more, given a known background level MU_BACKGROUND.

Options:
--value [sqrt_ts|p_value]  Square root TS or p_value
--help                     Show this message and exit.

$python significance.py 10 4.2 2.39791813$ python significance.py 10 4.2 --value p_value
0.01648855015875024


In Python, there are several ways to do command line argument parsing and to create command line interfaces. Of course you’re free to do whatever you like, but if you’re not sure what to use to build your own CLIs, we suggest you give click a try. Here is how you’d rewrite your significance.py as a click CLI:

"""Example how to write a command line tool with Click"""
import click
from gammapy.stats import CashCountsStatistic

# You can call the callback function for the click command anything you like.
# cli is just a commonly used generic term for "command line interface".
@click.command()
@click.argument("n_observed", type=float)
@click.argument("mu_background", type=float)
@click.option(
"--value",
type=click.Choice(["sqrt_ts", "p_value"]),
default="sqrt_ts",
help="Significance or p_value",
)
def cli(n_observed, mu_background, value):
"""Compute significance for a Poisson count observation.

The significance is the tail probability to observe N_OBSERVED counts
or more, given a known background level MU_BACKGROUND."""
stat = CashCountsStatistic(n_observed, mu_background)
if value == "sqrt_ts":
s = stat.sqrt_ts
else:
s = stat.p_value

print(s)

if __name__ == "__main__":
cli()


We use click in Gammapy itself. We also use click frequently for our own projects if we choose to add a CLI (no matter if Gammapy is used or not). Putting the CLI in a file called make.py makes it easy to go back to a project after a while and to remember or quickly figure out again how it works (as opposed to just having a bunch of Python scripts or Jupyter notebooks where it’s harder to remember where to edit parameters and which ones to run in which order). One example is the gamma-cat make.py.

If you find that you don’t like click, another popular alternative to create CLIs is argparse from the Python standard library. To learn argparse, either read the official documentation, or the PYMOTW argparse tutorial. For basic use cases argparse is similar to click, the main difference being that click uses decorators (@command, @argument, @option) attached to a callback function to execute, whereas argparse uses classes and method calls to create a parser object, and then you have to call parse_args yourself and also pass the args to the code or function to execute yourself. So for basic use cases, but also for more advanced use cases where you define a CLI with sub-commands, argparse can be used just as well, it’s just a little harder to learn and use than click (of course that’s a matter of opinion). Another advantage of choosing Click is that once you’ve learned it, you’ll be able to quickly read and understand, or even contribute to the Gammapy CLI.

## Troubleshooting¶

Usually tools that install Gammapy (e.g. setuptools via python setup.py install or pip or package managers like conda) will put the gammapy command line tool in a directory that is on your PATH, and if you type gammapy the command is found and executed.

However, due to the large number of supported systems (Linux, Mac OS, Windows) and different ways to install Python packages like Gammapy (e.g. system install, user install, virtual environments, conda environments) and environments to launch command line tools like gammapy (e.g. bash, csh, Windows command prompt, Jupyter, …) it is not unheard of that users have trouble running gammapy after installing it.

This usually looks like this:

$gammapy -bash: gammapy: command not found  If you just installed Gammapy, search the install log for the message “Installing gammapy script” to see where gammapy was installed, and check that this location is on your PATH: echo$PATH


If you don’t manage to figure out where the gammapy command line tool is installed, you can try calling it like this instead:

$python -m gammapy  This also has the advantage that it avoids issues where users have multiple versions of Python and Gammapy installed and accidentally launch one they don’t want because it comes first on their PATH. For the same reason these days the recommended way to use e.g. pip is via python -m pip. If this still doesn’t work, check if you are using the right Python and have Gammapy installed: $ which python
$python -c 'import gammapy'  To see more information about your shell environment, these commands might be helpful: $ python -m site
$python -m gammapy info$ echo $PATH$ conda info -a # if you're using conda


If you’re still stuck or have any question, feel free to ask for help with installation issues on the Gammapy mailing list of Slack any time!

## Reference¶

Here is auto-generated documentation for all available sub-commands, arguments and options of the gammapy command line interface (CLI).

### gammapy¶

Gammapy command line interface (CLI).

Gammapy is a Python package for gamma-ray astronomy.

Use --help to see available sub-commands, as well as the available arguments and options for each sub-command.

For further information, see https://gammapy.org/ and https://docs.gammapy.org/

Examples
——–
$gammapy –help$ gammapy –version
$gammapy info –help$ gammapy info
gammapy [OPTIONS] COMMAND [ARGS]...


Options

--log-level <log_level>

Logging verbosity level.

Options

debug|info|warning|error

--ignore-warnings

Ignore warnings?

--version

Print version and exit.

#### analysis¶

Automation of configuration driven data reduction process.

Examples
——–
$gammapy analysis config$ gammapy analysis run
$gammapy analysis config –overwrite$ gammapy analysis config –filename myconfig.yaml
$gammapy analysis run –filename myconfig.yaml gammapy analysis [OPTIONS] COMMAND [ARGS]...  ##### config¶ Writes default configuration file. gammapy analysis config [OPTIONS]  Options --filename <filename> Filename to store the default configuration values. [default: config.yaml] --overwrite Overwrite existing file. ##### run¶ Performs automated data reduction process. gammapy analysis run [OPTIONS]  Options --filename <filename> Filename with default configuration values. [default: config.yaml] --out <out> Output folder where reduced datasets are stored. [default: datasets] --overwrite Overwrite existing datasets. #### check¶ Run checks for Gammapy gammapy check [OPTIONS] COMMAND [ARGS]...  ##### logging¶ Check logging gammapy check logging [OPTIONS]  #### download¶ Download notebooks, scripts and datasets. Download notebooks published as tutorials, example python scripts and the related datasets needed to execute them. It is also possible to download individual notebooks, scrtipts or datasets. - The option tutorials will download versioned folders for the notebooks and python scripts into a gammapy-tutorials folder created at the current working directory, as well as the datasets needed to reproduce them. - The option notebooks will download the notebook files used in the tutorials into a gammapy-notebooks folder created at the current working directory. - The option scripts will download a collection of example python scripts into a gammapy-scripts folder created at the current working directory. - The option datasets will download the datasets used by Gammapy into a gammapy-datasets folder created at the current working directory. Examples ——–$ gammapy download scripts
$gammapy download datasets$ gammapy download notebooks
$gammapy download tutorials –release 0.8$ gammapy download notebooks –src overview
$gammapy download datasets –src fermi-3fhl-gc –out localfolder/ gammapy download [OPTIONS] COMMAND [ARGS]...  ##### datasets¶ Download datasets gammapy download datasets [OPTIONS]  Options --src <src> Specific dataset to download. --out <out> Destination folder. [default: gammapy-datasets] --release <release> Number of release - ex: 0.12 ##### notebooks¶ Download notebooks gammapy download notebooks [OPTIONS]  Options --src <src> Specific notebook to download. --out <out> Path where the versioned notebook files will be copied. [default: gammapy-notebooks] --release <release> Number of release - ex: 0.12) --all Consider also other notebooks than tutorials ##### scripts¶ Download scripts gammapy download scripts [OPTIONS]  Options --src <src> Specific script to download. --out <out> Path where the versioned python scripts will be copied. [default: gammapy-scripts] --release <release> Number of release - ex: 0.12 --silent ##### tutorials¶ Download notebooks, scripts and datasets gammapy download tutorials [OPTIONS]  Options --src <src> Specific tutorial to download. --out <out> Path where notebooks and datasets folders will be copied. [default: gammapy-tutorials] --release <release> Number of release - ex: 0.12 #### info¶ Display information about Gammapy gammapy info [OPTIONS]  Options --system, --no-system Show system info --version, --no-version Show version --dependencies, --no-dependencies Show dependencies --envvar, --no-envvar Show environment variables #### jupyter¶ Perform a series of actions on Jupyter notebooks. The chosen action is applied by default for every Jupyter notebook present in the current working directory. Examples ——–$ gammapy jupyter strip
$gammapy jupyter –src my/notebook.ipynb run$ gammapy jupyter –src my/folder test
\$ gammapy jupyter –src my/recursive/folder –r black
gammapy jupyter [OPTIONS] COMMAND [ARGS]...


Options

--src <src>

Local folder or Jupyter notebook filename.

--r

Apply to notebooks found recursively in folder.

##### black¶

Format code cells with black.

gammapy jupyter black [OPTIONS]

##### run¶

Execute Jupyter notebooks.

gammapy jupyter run [OPTIONS]


Options

--tutor

Tutorials environment? [default: False]

--kernel <kernel>

Kernel name [default: python3]

##### strip¶

Strip output cells.

gammapy jupyter strip [OPTIONS]

##### test¶

Check if Jupyter notebooks are broken.

gammapy jupyter test [OPTIONS]


Options

--tutor

Tutorials environment? [default: False]

--kernel <kernel>

Kernel name [default: python3]