Command line usage

The psyplot-gui module extends the command line usage of the psyplot module. You can open one (or more) files in the graphical user interface simply via:

$ psyplot myfile.nc

By default, if the gui is already running, the file is opened in this gui unless you specify the ni option.

Load a dataset, make the plot and save the result to a file

usage: psyplot [-h] [-V] [-aV] [-i] [-lp] [-lpm] [-lds] [-lps]
               [-n [variable_name ...]] [-d dim,val1[,val2[,...]]
               [dim,val1[,val2[,...]] ...]]
               [-pm {'density', 'plot2d', 'fldmean', 'vector', 'combined', 'lineplot', 'barplot', 'violinplot'}]
               [-o str or list of str] [-p str] [-engine str]
               [-fmt FILENAME_OR_YAML] [-t] [-rc RC_FILE] [-e str]
               [--enable-post] [-sns str] [-op str] [-cd str]
               [-chname [project-variable,variable-to-use ...]] [-preset str]
               [--decoder FILENAME_OR_YAML] [-b [backend]] [-ni]
               [-rc-gui RC_GUI_FILE] [-inc str [str ...]] [-exc str [str ...]]
               [--offline] [-pwd str] [-s str] [-c str] [-a]
               [-opengl {'software', 'desktop', 'gles', 'automatic'}]
               [--webengineview] [-lgp] [--no-webengineview]
               [str ...]

Positional Arguments

str

Either the filenames to show, or, if the project parameter is set, the a list of ,-separated filenames to make a mapping from the original filename to a new one

Default: []

Named Arguments

-n, --name

The variable names to plot if the output parameter is set

Default: []

-d, --dims

A mapping from coordinate names to integers if the project is not given

-pm, --plot-method

Possible choices: density, plot2d, fldmean, vector, combined, lineplot, barplot, violinplot

The name of the plot_method to use

-p, --project

If set, the project located at the given file name is loaded

-engine

The engine to use for opening the dataset (see psyplot.data.open_dataset())

-fmt, --formatoptions

YAML-formatted formatoption (e.g. ‘cmap: Reds’), or the path to a yaml ('.yml' or '.yaml'), JSON ('.json') or pickle file defining a dictionary of formatoption that is applied to the data visualized by the chosen plot_method

-rc, --rc-file

The path to a yaml configuration file that can be used to update the rcParams

-e, --encoding

The encoding to use for loading the project. If None, it is automatically determined by pickle. Note: Set this to 'latin1' if using a project created with python2 on python3.

--enable-post

Enable the post processing formatoption. If True/set, post processing scripts are enabled in the given project. Only set this if you are sure that you can trust the given project file because it may be a security vulnerability.

Default: False

-sns, --seaborn-style

The name of the style of the seaborn package that can be used for the seaborn.set_style() function

-cd, --concat-dim

The concatenation dimension if multiple files in fnames are provided

-chname

A mapping from variable names in the project to variable names in the datasets that should be used instead. Variable names should be separated by a comma.

Default: {}

-preset

The filename or identifier of a preset. If the given preset is the path to an existing yaml file, it will be loaded. Otherwise we look up the preset in the psyplot configuration directory (see get_configdir()).

--decoder

YAML-formatted decoder options (e.g. ‘x: x-coordinate’), or the path to a yaml ('.yml' or '.yaml'), JSON ('.json') or pickle file defining a dictionary of formatoption that is applied to the data visualized by the chosen plot_method

-a, --use-all

If True, use all variables. Note that this is the default if the output is specified and not name

Default: False

Info options

Options that print informations and quit afterwards

-V, --version

show program’s version number and exit

-aV, --all-versions

Print the versions of all plugins and requirements and exit

-i, --info

Show grid information on the specified variables.

-lp, --list-plugins

Print the names of the plugins and exit

-lpm, --list-plot-methods

List the available plot methods and what they do

-lds, --list-datasets

List the used dataset names in the given project.

-lps, --list-presets

Print available presets and exit

-lgp, --list-gui-plugins

Print the names of the GUI plugins and exit. Note that the displayed plugins are not affected by the include-plugins and exclude-plugins options

Output options

Options that only have an effect if the -o option is set.

-o, --output

If set, the data is loaded and the figures are saved to the specified filename and now graphical user interface is shown

-t, --tight

If True/set, it is tried to figure out the tight bbox of the figure and adjust the paper size of the output to it

Default: False

-op, --output-project

The name of a project file to save the project to. This option has only an effect if the output option is set.

Gui options

Options specific to the graphical user interface

-b, --backend

The backend to use. By default, the 'gui.backend' key in the rcParams dictionary is used. If used without options, the default matplotlib backend is used.

Default: False

-ni, --new-instance

If True/set and the output parameter is not set, a new application is created

Default: False

-rc-gui, --rc-gui-file

The path to a yaml configuration file that can be used to update the rcParams

-inc, --include-plugins

The plugin widget to include. Can be either None to load all that are not explicitly excluded by exclude_plugins or a list of plugins to include. List items can be either module names, plugin names or the module name and widget via '<module_name>:<widget>'. Default: None

-exc, --exclude-plugins

The plugin widgets to exclude. Can be either 'all' to exclude all plugins or a list like in include_plugins.. Default: []

Default: []

--offline

If True/set, psyplot will be started in offline mode without intersphinx and remote access for the help explorer

Default: False

-pwd

The path to the working directory to use. Note if you do not provide any fnames or project, but set the pwd, it will switch the pwd of the current GUI.

-s, --script

The path to a python script that shall be run in the GUI. If the GUI is already running, the commands will be executed in this GUI.

-c, --command

Python commands that shall be run in the GUI. If the GUI is already running, the commands will be executed in this GUI

-opengl, --opengl-implementation

Possible choices: software, desktop, gles, automatic

OpenGL implementation to pass to Qt. Possible options are ‘software’, ‘desktop’, ‘gles’ and ‘automatic’ (which let’s PyQt decide).

--webengineview

If True (default), use an HTML help widget. This might not be available for all builds of PyQt5 under all circumstances. If not set, the rcParams key 'help_explorer.use_webengineview' is used.

--no-webengineview

Do not use HTML rendering.

Examples

Here are some examples on how to use psyplot from the command line.

Plot the variable 't2m' in a netCDF file 'myfile.nc' and save the plot to 'plot.pdf':

$ psyplot myfile.nc -n t2m -pm mapplot -o test.pdf

Create two plots for 't2m' with the first and second timestep on the second vertical level:

$ psyplot myfile.nc -n t2m  -pm mapplot -o test.pdf -d t,0,1 z,1

If you have save a project using the psyplot.project.Project.save_project() method into a file named 'project.pkl', you can replot this via:

$ psyplot -p project.pkl -o test.pdf

If you use a different dataset than the one you used in the project (e.g. 'other_ds.nc'), you can replace it via:

$ psyplot other_dataset.nc -p project.pkl -o test.pdf

or explicitly via:

$ psyplot old_ds.nc,other_ds.nc -p project.pkl -o test.pdf

You can also load formatoptions from a configuration file, e.g.:

$ echo 'title: my title' > fmt.yaml
$ psyplot myfile.nc -n t2m  -pm mapplot -fmt fmt.yaml -o test.pdf

If you omit the '-o' option, the file is opened in the graphical user interface and if you run:

$ psyplot -pwd .

It will switch the directory of the already running GUI (if existent) to the current working directory in your terminal. Additionally,:

$ psyplot -s myscript.py

will run the file 'myscript.py' in the GUI and:

$ psyplot -c 'print("Hello World!")'

will execute print("Hello World") in the GUI. The output, of the -s and -c options, will, however, be shown in the terminal.