Argos

Argos is a GUI for viewing and exploring scientific data, written in Python and Qt. It has a plug-in architecture that allows it to be extended to read new data formats. At the moment plug-ins are included to read HDF-5, NetCDF-4, WAV, Exdir, numpy binary files and various image formats, but a plug-in could be written for any data that can be expressed as a Numpy array.

Installing Argos

Argos works with Python 3.7 and higher.

Argos requires at least PyQt5 and Numpy and CmLib. It is strongly recommended to also install PyQtGraph and PgColorBar, which are required to visualize the data as image plots or line plots. Without them the data can only be examined as tables or text.

The following dependencies are optional. You only need to install them if you want to read the corresponding file formats.

| Optional Python package | File formats | |------------------------------------------------------|---------------------------------| | h5py | HDF-5 | | netCDF4 | NetCDF (v3 and v4) | | pillow | BMP, JPEG, PNG, TIFF, GIF, etc. | | scipy | Matlab & IDL save-files. WAV | | pandas | Comma-separated files | | exdir | Exdir |

Installing Argos with Pip

First install PyQt5 with pip, then install Argos.

%> pip install PyQt5
%> pip install argos

After that, install the optional dependencies with pip install <package>.

For convenience, you can install Argos with Qt and all optional dependencies in one command like so:

%> pip install argos[pyqt5,all-formats]

Installing Argos with Anaconda

Argos is available at the conda-forge channel. To install it type:

%> conda install pyqt
%> conda install -c conda-forge argos

After that, install the optional dependencies with conda install <package> (or pip install <package> for exdir).

Starting Argos

After installation, Argos can be started from the command-line with

    %> argos [FILE [FILE ...]]

where [FILE [FILE ...]] are zero or more files or directories you want to view.

For a complete list of command line options, run argos with `-h'.

    %> argos -h

Trouble shooting

If you start argos and nothing happens, you probably didn't install PyQt or numpy. You can try to start argos as follows to get more information

    %> python -m argos

Resetting Argos

At start-up, Argos reads some persistent settings (window position and size, plot settings, etc) from a configuration file so that you can continue where you left off the previous session.

If, for some reason, you want Argos to reset to its initial state, you can simply delete this config file before starting Argos (please make a backup just in case). Argos will then start with the original configuration.

The configuration file is called settings.json by default. Its location is platform dependent:

	Windows: C:\Users\<user>\AppData\Local\titusjan\argos
	MacOS: ~/Library/Preferences/titusjan/argos
	Linux: ~/.config/titusjan/argos

Note that this directory might be hidden. For convenience you can open this directory in a file browser by selecting Configure | Show Config Files... from the Argos main menu.

Using Argos

The Argos main window consists of a central panel that holds a visualization, and some smaller windows that surround the main panel. The smaller windows can be moved around by dragging them by their title bar. They can be separated from the main window or can be docked at an at another position. Collectively they are called the dock panels. You can show and hide them via the View | Panels main menu (although there is typically no need to do so).

The main panel is called the (data) Inspector. From the View main menu you can select one of the following inspector types: Line Plot, Image Plot, Table, or Text inspector. The current inspector type is shown in the menu button above the inspector panel. Clicking this button (or pressing ctrl-I) is an alternative way of selecting a different inspector.

If you want to have multiple inspectors open at the same time, you can select New Window from the File menu.

Selecting Data

Note: the HDF5 file that is used in the screenshot and in the examples below can be downloaded here (2.4 MB). More (NetCDF4) example data can be found at the UCAR site here.

The Data dock panel displays the list of files and directories that are loaded and are available for inspection. The repository has the form of a tree, or more precisely a list of trees (a forest). You can add files by selecting the Open Files from the File menu, and add directories with the Browse Directory option. Argos uses the file extension to determine which plug-in to use for opening the file. The icon color of the tree items indicates which plug-in was used. With the Open as menu option you can force Argos to open a file with the a certain plug-in. If a plug-in raises an error while opening a file, it will get a red triangle as icon (hover over the item to get a tool-tip with the error message).

Expanding the items in the tree will automatically open the underlying files. Collapsing an item will close the file again. Right-clicking the item will bring forward a context menu that makes it possible to collapse the item without closing the underlying file, to reload the file, or to open the file with a different plug-in.

Note that the data repository is shared between all Argos main windows. That is, opening a file will add a new item to the Data tree of all open windows.

Slicing Data

Selecting an item in the tree will automatically place it in the Collector table at the bottom right of the windows. If the item contains numerical data, drop-down and spinbox widgets will appear in the table. These enable you to specify a slice of the data that the inspector will then visualize.

In the screen shot for example, the ColumnAmountO3 HDF-5 dataset is selected and placed in the collector. This is a two-dimensional data array, it contains a world wide distribution of ozone in the atmosphere. The first dimension corresponds to longitude, the second to latitude. These dimensions have no name since the dataset has no associated dimension scales. Therefore, Argos just calls them dim-0 and dim-1.

The inspector in the screen shot is an Image Plot. This is a two-dimensional inspector so there will appear two drop-down box in the table: the first specifies which dimension will be mapped onto the Y-axis (dim-0 in the example) and the second determines the data dimension that is mapped to the X-axis.

When you select the Line Plot inspector from the View menu or the Inspector button, the selected data will be drawn as a line plot. A line plot can only show one-dimensional data, but because since the example data is two-dimensional only a sub-slice of the dataset can be visualized. The collector will therefore contain a drop-down box for specifying which data dimension will be laid along the X-axis, and a spinbox-slider combination for selecting the index of the other dimension. Below you see the case that the line plot will draw row 360. By the way, this is reflected in the plot title, which will be ColumnAmountO3[360, :]).

By default Argos will put the first array dimension(s) in the spinbox(es), and select the fasted changing array dimension(s) in the drop-down box(es).

Inspecting Data and Configuring the Visualization

The Settings dock panel, located at the top right, contains settings for configuring the current inspector. If you click on a config value, an appropriate widget will appear for editing, together with a reset button <img src="argos/img/snipicons/reset-l.svg" width="16" height="16"> that will reset the config value to its default when clicked.

The settings are hierarchical so that related settings are grouped together in a branch. Branches also have a reset button that resets the complete branch. For instance by clicking on the reset button of the y-axis config value branch, all settings pertaining to the Y-axis are reset.

<img src="docs/screen_shots/settings.png" width="350">

Note that some branches are collapsed by default to hide the infrequently used settings and reduce clutter. For instance the cross-hair item can be expanded for further tweaking of the cross-hair plots.

When you click on the Reset Ranges button at the bottom of the Settings panel, all settings that are related to the data range (such as the range of the axes and the color scale) are reset to their default values. This gives you a convenient way to go back to viewing all the data after zooming in. Pressing Ctrl-0 has the same effect.

If the auto checkbox is checked, the Range settings are automatically reset every time you select a new item in the Data tree or select a new axis in drop-down box in the data Collector panel. Normally this is desired behavior because a new dataset or axis will have a totally different data range. Unchecking the auto scale checkbox allows you to retain the axes range settings, which