INTRODUCTION

pandora.ez (easy-z) is a software which allows to estimate redshifts for extragalactic objects. It compares the observed spectrum with a set of (user given) spectral templates to find out the best value for the redshift. To accomplish this task, it uses a highly configurable set of algorithms, easily estendible with new ones.

pandora.ez is distributed “as is” in the hope that it will be useful (for a more detailed disclaimer open this page).

Unfortunately we do not have the resources to provide assistance with installation and operations for this package. However should you find some serious bug or some really unexpected feature in the software please contact us and we will do our best to help solving the problem.

If you publish scientific results obtained with pandora.ez please cite this paper and acknowledge it with the sentence “The data published in this paper have been obtained using the pandora.ez software developed by INAF IASF-Milano”

INSTALLATION

pandora.ez is distributed in binary form as an Anaconda Python package and it is available for Linux and macOS systems. It can be installed as a standalone program or within an existing Anaconda Python installation.

STANDALONE INSTALLATION

The standalone installation provides pandora.ez together with a minimal Anaconda Python distribution which contains the needed third-party packages. Simply download the installer script appropriate for your system

http://pandora.lambrate.inaf.it/downloads/pandora.ez-latest-Linux-x86_64.sh

or

http://pandora.lambrate.inaf.it/downloads/pandora.ez-latest-macOS-x86_64.sh

set it as executable and run it:

shell> chmod u+x <installer-name>.sh
shell> ./<installer-name>.sh

Follow the instructions and the program with all the needed dependencies will be installed in the directory you provide to the script.

To start pandora.ez open a terminal and issue the command:

shell> <your_installation_dir>/bin/pandora.ez

macOS-like installation (experimental)

Using the above outlined procedure on macOS systems do not properly integrate pandora.ez into the OS; pandora.ez is not managed as a macOS application and the name displayed on the Menubar during the execution is a anonymous “python”. An experimental DMG is available at this URL

http://pandora.lambrate.inaf.it/downloads/pandora.ez-latest-x86_64.dmg

to perform a standard macOS installation. This installation provides the program as a macOS application located in the directory:

/Applications/Pandora

The application can be launched with a double-click, can be linked into the Dock and is properly managed by the Finder. A script is also provided to open the pandora.ez application from the command line passing arguments to it (see section THE COMMAND-LINE)

/Applications/Pandora/pandora.ez.app/bin/pandora.ez

The installed program is fully functional and identical to the one installed by the installer script, only the OS integration is still experimental. Please contact us if you experience any problem.

ANACONDA INSTALLATION

pandora.ez can be installed into and existing Anaconda Python installation using the standard package manager (the “conda” tool). Given that pandora.ez is built on fixed and specific versions of some third-party packages, we suggest to install it in a dedicated environment:

shell> conda create --name <pandora_ez_environment_name> python
shell> conda install -c http://pandora.lambrate.inaf.it/repo -n <pandora_ez_environment_name> pandora.ez

To start pandora.ez from the newly created environment issue the command:

shell> <anaconda_installation_dir>/<pandora_ez_environment_name>/bin/pandora.ez

However, if you prefer to install pandora.ez in the root of an existing Anaconda Python installation just issue the standard command:

shell> conda install -c http://pandora.lambrate.inaf.it/repo pandora.ez

Then start pandora.ez issuing the command:

shell> <anaconda_installation_dir>/bin/pandora.ez

Installing pandora.ez in this way on macOS systems results in the same OS integration issues described above2 (see section macOS-like installation (experimental)).

MAIN WINDOW

Once launched, pandora.ez tool shows a main panel with six buttons:

  • “Open” : automatically detects the file type and opens it accordingly
  • “Open Seq file”: opens a VIPGI SEQ file and displays it in a new SPECTRAL VIEWER window (see section THE SPECTRAL VIEWER);
  • “Open Single file”: opens a single mono-dimensional spectrum (FITS) and displays it in a new SPECTRAL VIEWER window (see section THE SPECTRAL VIEWER);
  • “Open PND file”: opens a file in PND format. This is a multi-extension FITS file comprising a mono-dimensional spectrum in the primary extension, and the corresponding sky/noise/2D spectra in other extensions. Moreover, an unedited instance of the original mono-dimensional spectrum is stored in another extension;
  • “Open List file”: opens a file of type “list” and displays the synchronized groups of spectrum/sky/noise/2D in a new SPECTRAL VIEWER window. Files of type “list” are described in section FILENAME PATTERN, subsection Filename Pattern;
  • “Open File Customized”: allows the user to select a spectrum and/or a sky, and/or a noise, and/or a spectrum 2D from FITS files, specifying the extension, the row/Y-range, X-range to read and display in a new SPECTRAL VIEWER window;
  • “Preferences”: allows to configure some options described within the section PREFERENCES;

THE SPECTRAL VIEWER

The SPECTRAL VIEWER has a different behaviour depending on the input file type: in case of a SEQ or PND file all plotting and managing features are available; in case of a simple 1D spectrum only a subset of those available for the SEQ files are at the disposal of the user; in case of spectra, noises, skies and 2D spectra open through a “list” file or with the customized opening panel, only the suitable controls are put at the disposal of the user. In the following paragraph we explain the SEQ file case (the most complete), highlighting which features are available for the other cases as well.

The SPECTRAL VIEWER consists in two panels and a button-box:

  • the right panel is the plotting area where you find (from the top the bottom):
    • the current 2D spectrum [SEQ, PND, list and customized]
    • the current 1D spectrum [all]
    • the sky of the current spectrum [SEQ, PND, list and customized]
    • the noise of the current spectrum [SEQ, PND, list and customized]
  • the left panel is the control area where you find eight groups of controls (from the top the bottom):
    • Obj: showing the objects info as loaded from the summary file if available, otherwise just the file name [SEQ, PND, list and customized]
    • Stats: showing the latest statistics on the 1D spectrum (see section STATISTICS) [all]
    • Fit: showing the fitting values of the latest line fitted in the 1D spectrum (see section LINE FITTING) [all]
    • Mouse: allowing to select which operations associate to the mouse buttons keys (see from section STATISTICS up to LINE FITTING) [all]
    • View: providing the spectrum smoothing tool and the wavelength range selector tool [all]
    • 2D Image: allowing to modify the 2D image color-map (and revert it) and the cut levels [SEQ, PND, list and customized]
    • Browse: allowing to select the spectrum running from the first to the last spectrum in the spectra list [SEQ and list] thanks to the “Pevious” and “Next” buttons. You can directly go to a specific slit (SEQ case only) or object, exploiting the sliding bar below the buttons. In case of SEQ files, it also possible to select the spectrum type to be displayed.
    • Redshift: displaying the redshift value and the information taken from the summary file if available. It also allows to reload the data from the summary file and open the COMPUTE REDSHIFT panel (see section COMPUTE REDSHIFT) [all]
  • the button-box beneath the two panels provides other features described in the following section.

ZOOMING AND PANNING

All plots can be always zoomed-in clicking the left button of the mouse and dragging the mouse with the left button pressed, in order to highlight the area to be zoomed.

It is also possible to pan the current view by dragging the spectrum around while keeping the central button of the mouse pressed.

It is not possible to zoom-out with the right button. To zoom-out you can use the mouse wheel (if available) or click on the button “Zoom Out” in the button-box. “Zoom Out” button restores the plots ranges to the wavelengths specified in the View tab (left panel).

STATISTICS

To compute some statistics on the spectrum within a specific range of wavelengths, set the “Mouse action” list-box in the Mouse tab (left panel) to STATS and select the area of interest in the 1D spectrum clicking and dragging the right mouse button. The statistics are displayed in the Stats tab.

EDITING

The 1D spectrum can be edited point by point pressing “j” key, or selecting the wavelength range with “e” key. In the latter case a straight line is drawn from the leftmost spectrum point selected up to the rightmost selected point.

If the “Mouse action” list-box is set to EDIT (Mouse tab), then it is possible to edit the spectra directly with the mouse: the middle button performs the point by point editing (equivalent to “j” key) while clicking and dragging the right button performs the selected range editing (equivalent to “e” key).

All edits performed to the 1D spectrum are stored in memory and can be undone pressing “u” key on the keyboard (up to the complete restoration of the original spectrum), provided you did not move to a different spectrum.

In case something goes really wrong it is also possible to restore the original data (EXR1D or EXR1DATM extension of the SEQ file, depending on the case), and restart the editing from scratch clicking on the button “Undo Edits”.

LINE MARKING

The simple line marking (to be used to perform the “simple” redshift measurement) can be performed in any moment just locating the mouse on the 1D spectrum centered in the line of interest and pressing the “m” key on the keyboard. Otherwise the same operation can be performed with the mouse, selecting MARK as “Mouse action” (Mouse tab) and clicking the right button.

To clear the marked line sign on the plot, press “c” key.

LINE FITTING

Spectral lines can be fitted (and then used for the “simple” redshift measurement) using two methods:

  • Gaussian fit: a Gaussian is fitted around the selected wavelength range and the resulting statistics shown in the STATISTICS panel.
  • Peak fit: the peak of the line around the selected wavelength range is computed finding the barycenter of the points.

The method used to perform the fitting is the one specified in the “Fit type” list-box (Mouse tab), which can be changed only if “Mouse action” is set to FIT.

To select the wavelength range, locate the mouse in the leftmost point of the range, then press the “f” key on the keyboards, move the mouse on the rightmost point of the range and the press “f” again. The same action can be performed setting “Mouse action” to FIT (Mouse tab), then dragging and dropping the right mouse button along the range of interest.

To clear the fit result from the plot, press “c” key.

SAVING

In the lower part of the Spectral Viewer window, there are two buttons for saving:

  • “Save”: which automatically saves the current spectrum with all changes. In case of SEQ file all edits are saved into the EXR1DEDIT extension; in other cases a new 1D file is created on disk; this file is named <original_filename>_<extension>_<row>_<edit>.<original_filename_extension>. (extension and row are added only in case of FITS file);
  • “Save as”: which allows to save the current 1D spectrum as a mono-dimensional FITS file with a custom name. If a noise and/or sky spectrum and/or a 2D spectrum have also been loaded (by default for SEQ files) then they are saved as well, in three different files having the mono-dimensional FITS file name suffixed with _noise or _sky or _2d, depending on the case.

All changes are automatically saved whenever a new spectrum is browsed (Next or Previous button) or when the Spectral Viewer is closed. Iin case of a SEQ file no confirmation is asked; in other cases, if the edited file already exists, a confirmation dialog is showed only if the “Silently overwrite edited files” option is not checked in the Preferences panel.

DUMP Z

The “Dump Z” button allows to save to disk information pertaining to the redshift measurement. An ASCII file in tabular form is created and filled with information which varies on the basis of the type of file(s) loaded in the spectral viewer:

  • the redshift value, the method employed to measure it, the flags and the comment are always saved
  • for SEQ files, the object id is saved
  • for PND files, the filename and the object id are saved
  • for single file, the filename is saved

CUSTOM SEQ FILE BUTTONS

There are two buttons which are available in the SEQ file case only:

  • “Extr. Profile”: which shows the 2D image extraction profile; the extraction profiles is provided with three additional horizontal lines showing:

    • the median value of the profile (green line);
    • the RMS of the profile (red line);
    • the detection threshold (blue line);

    A yellow line following the mouse moving allows display the profile position directly over the 2D image.

  • “Window Table”: which shows the WINDOW TABLE of the SEQ file.

REDSHIFT MEASUREMENT

The Spectral Viewer is able to connect with the redshift measurement engine, which appears as a separate window clicking the “Compute” button. More details in next section. It is however possible to manually insert redshift value and the other corresponding parameters in the Redshift section of the Spectral Viewer interface.

Please note that those values, both being automatically or manually computed, will be saved only in case of SEQ files, PND files or list files; for single spectra or list of spectra loaded from commandline by wildcard expansion the values will be lost after closing the Spectral Viewer.

INTERACTIVITY

In this table summarizes the mouse buttons and keyboard shortcuts to interact with the Spectral Viewer.

Action Mouse button Keyboard
zoom-in wheel  
zoom-out wheel  
zoom-in fluxes   Shift-Up
zoom-out fluxes   Shift-Down
zoom-in waves   Shift-Right
zoom-out waves   Shift-Left
pan middle  
pan-left   Left
pan-right   Right
pan-up   Up
pan-down   Down
statistics right s (double)
fit right f (double)
edit point middle j
edit range right e (double)
mark right m
undo   u
clear plot   c
add wavelength to comments   p (emission) o (absorb.)

COMPUTE REDSHIFT

The Compute Redshift windows is composed by two panels:

  • On the left, the content of the summary file is shown and enabled for editing. The list of the most common spectral lines is shown as well (listing both rest-frame and observed wavelength, with respect to the current redshift), together with three checkboxes, which allow:

    • to overlap the catalog lines to the spectrum (Lines checkbox)
    • to highlight the lines found by the Advanced EZ engine during the redshift measure. Strong lines are drawn with a continuous cyan line, while week lined with a dashed blue line (EZ lines checkbox) [1].
    • to display the currently selected EZ template spectrum overlaid to the 1D spectrum (Template) [1].
    • to overlap the spectrum continuum as computed by the Advanced EZ engine [1].

    The buttons “Zero”, “Star” and “Fake” can be used to quickly set the redshift value, flag, comment and method to the related predefined values.

  • On the right, there is a panel including two tabs, providing interfaces to the ADVANCED redshift measurement engine (EZ solve method) and the SIMPLE measurement engine.

[1](1, 2, 3) only when using the Advanced compute redshift window.

ADVANCED PANEL

This panel allows to fit the spectrum and measure the redshift using cross-correlation and fitting algorithms (SOLVE button). The main parameters to drive the solve method are shown in the LAMBDA, TEMPLATES and Z frames.

Using the EDIT PARAMS button the algorithms behaviour can be fine tuned by setting the values of various parameters.

To select the list of templates to be used within those defined in your workspace, flag them in the TEMPLATES frame. The special Custom template entry allows to customize the set of templates to be used, overwriting the default value.

To execute a specific command, the EXEC button can be used: the command specified in the entry field on its right is then executed. Any command output is printed out in the terminal where the current pandora.ez has been started.

The RESULTS frame lists all the templates used to provide a possible redshift solution, and the possible solutions found for each template (Solve result branch). It is possible to select any of these solutions by clicking with the left mouse button on the redshift value in the RESULTS frame, or by clicking with the right mouse button on the SOLVE or SUMMARY plots on the right, which show the correlations and fit outcome of the solve method for the current template, and a summary of all templates fit outcome, respectively.

The RESULTS frame lists also all the templates available, even those not used by SOLVE (All templates branch). It is possible to select any of these templates by clicking with the left mouse button on the template name in the RESULTS frame: the template selected is thus set at the current redshift and shown in the Spectral Viewer.

SIMPLE PANEL

This panel allows to simply compute a redshift based on the lines marked with the Spectral Viewer. The marked lines are shown in the LINES table, allowing to remove any unwanted or wrongly marked line.

SOLVE button performs the redshift computation and shows the results into RESULTS frame. To select one of the candidate redshifts, just click on it with the left button.

Note

It is possible to temporarily select a subset of the marked lines to use for the redshift computation: keep pressed the Ctrl key and select with the left mouse button the subset of lines.

PREFERENCES

The preferences windows is accessed from the main pandora.ez window, clicking “Preferences” button.

pandora.ez preferences window allows to configure just these options:

  • the wavelength range to be plotted by default by the Spectral Viewer;
  • the default 2D image cut levels, color map and reversion flag that must be used by the Spectral Viewer.
  • if the object detection limits have to be shown on the 2D image
  • if a confirmation dialog has to be opened each time an edited 1D spectrum needs to be overwritten (non SEQ case only)

THE COMMAND-LINE

If you want to get more information on the execution options of pandora.ez, launch the program with the help argument:

shell> <ez_installation_dir>/bin/pandora.ez --help

The command above prints out the following help, showing the optional command-line parameters of pandora.ez tool:

Usage:
  pandora.ez [filename] [minwave] [maxwave] [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit

  Tool parameters:
    --filename=FILENAME
                        Filename to load [None]
    --minwave=MINWAVE   Minimum wavelength to plot [5500.0]
    --maxwave=MAXWAVE   Maximum wavelength to plot [9500.0]
    --sky=SKY           Sky pattern to load [None]
    --noise=NOISE       Noise pattern to load [None]
    --sp2d=SP2D         Spectrum 2D image pattern to load [None]
    --cut_level_low=CUT_LEVEL_LOW
                        Low 2D image cut level [-50]
    --cut_level_high=CUT_LEVEL_HIGH
                        High 2D image cut level [300]
    --cmap=CMAP         2D image color map (one in BB, JET, HOT, GRAY, COOL)
                        [BB]
    --cmap_revert=CMAP_REVERT
                        Color map reverted flag [False]

  FASE standard parameters:
    --ipset=IPSET       Input pset file or directory
    --opset=OPSET       Output pset file or directory
    --log-level=LOG_LEVEL
                        Set the LOG_LEVEL for the current process

FILENAME PATTERN

The command-line parameters --filename, --sky, --noise and --sp2d get as input a FITS file name. However it is possible to specify, along with the file name, the HDU to be loaded and the x y data range to extract in order to load the actual spectrum or 2D image.

In case of a spectrum (being the 1D spectrum, the sky or the noise) this is the syntax to use:

Token Syntax
file name (required) <any valid file path>
extension name or number [EXT. NAME] or [EXT. NUM.]
row number (row)

Examples:

  • myspec.fits[1](1): open myspec.fits file, read the primary image extension, first row (y = 1)

In case of the 2D image, the syntax is slightly different:

Token Syntax
file name (required) <any valid file path>
extension name or number [EXT. NAME] or [EXT. NUM.]
data range (from Y: to Y, from X: to X) or (from Y: to Y,*) or (*, from X: to X)

Examples:

  • my2dimg.fits[5](31:58,10:500): open my2dimg.fits file, read the 5th extension and extract a region starting from the 31st pixel in Y and ending to the 58th pixel in Y, starting from 10th pixel in X and ending to the 500th pixel in Y (included).
  • my2dimg.fits[EXR2D](31:58,*): open my2dimg.fits file, read the extension EXR2D, extract from pixel 31 to pixel 58 in Y and the full X length.

LIST FILES

List files are simple ASCII files containing a list of files to be loaded, each file name following the pattern described in section FILENAME PATTERN (if needed). Example:

# example list of 4 spectra
myspec.fits[1](1,10:500)
myspec.fits[EXTA](2,50:400)
myspec.fits[5](3,*)
myspec.fits

Supposing to name the list file above my4spec.list, it can be loaded by command-line with the command:

pandora.ez --filename @my4spec.list

or through the “Open File Customized” button of MAIN WINDOW.

List files can be used to load paired list of spectra, skies, noises and 2D spectra (or a subset of them) providing the list of files as:

  • a set of separated list files, example:

    pandora.ez --filename @my4spec.list --sky @my4sky.list --sp2d @my4img.list
    

    where @my4sky.list and @my4img.list are list files providing a list of 4 sky files and 2D images compatible with my4spec.list example file;

  • a single list file listing the spectra, skies, noises and 2D images to be loaded (the columns order is fixed, put a character - to skip an entry) as in the example here below:

    myspec.fits[1](1,10:500)                -                   mynoise.fits[8](1,10:500)  my2dimg.fits[EXR2D](31:58,10:500)
    myspec.fits[EXTA](2,50:400)  mysky.fits[SKY2D](15,50:400)                 -            my2dimg.fits[EXR2D](31:58,50:400)
    myspec.fits[5](3,*)          mysky.fits[SKY2D](15,*)        mynoise.fits[8](1,*)       my2dimg.fits[EXR2D](31:58,*)
    myspec.fits                  mysky.fits[SKY2D](15,100:300)  mynoise.fits[8](1,100:300)             -
    

    Single all inclusive list file like this can be loaded by command-line typing (supposing to name if my4group.list):

    pandora.ez --filename @my4group.list
    

    or through the “Open File Customized” button of the main window (see MAIN WINDOW).

RED FILES

When a file list is opened in the Spectral Viewer, it looks for an associated Red (redshift) file in the same directory of the file list, which name is the same as the file list name with an added “.red” extension. The Red file is an ASCII file used to gather information about the redshift measurements made on the files present in the file list, and is composed by the following colums, separated by tabs:

  • Filename: the name of the spectrum fits file
  • Z: the computed redshift value of the spectrum
  • Zmethod: the method used to compute the redshift value
  • Zflag: the confidence level assigned to the computed redshift value
  • Zcomment: a free-form comment

The first time a file list is loaded into the Spectral Viewer, if on Red file can be found an empty one is automatically created and filled only with the filenames:

#Filename       Z       Zmethod Zflag   Zcomment
/absolute/path/to/spec1.fits  -       -       -
/absolute/path/to/spec2.fits  -       -       -
/absolute/path/to/spec3.fits  -       -       -
/absolute/path/to/spec4.fits  -       -       -

After the Red file has been created, it is used by the Spectral Viewer to save the values of the corresponing columns:

#Filename       Z       Zmethod Zflag   Zcomment
/absolute/path/to/spec1.fits      1.0176        E      2   barely detected
/absolute/path/to/spec2.fits      9.9999        -      0   barely detected
/absolute/path/to/spec3.fits      0.8526        E      1   4000
/absolute/path/to/spec4.fits      0.7884        E      3   3728 -3968.5

If you want to craft your Red file by hand, it is also possible to specify just filename the and the redshift value:

#Filename       Z       Zmethod Zflag   Zcomment
/absolute/path/to/spec1.fits      1.0176
/absolute/path/to/spec2.fits      9.9999
/absolute/path/to/spec3.fits      0.8526
/absolute/path/to/spec4.fits      0.7884