User documentation for the program reSpefo (v1.1.0)

Released on the 4th of October 2020, written by Adam Harmanec (adam@harmanec.com)

ReSpefo is a modern refresh of the original program Spefo, a "Simple, Yet Powerful Program for One-Dimensional Spectra Analysis" originally written in Turbo Pascal. The new version is written in Java using contemporary tools with an improved user interface and functionality.

Using ReSpefo

ReSpefo is distributed as a runnable .jar archive. The program can be started from a terminal or command line using the following command:

java -jar reSpefo.jar

System requirements

• Java 8 or higher
• At least 1 GB of RAM
• Linux 64/32 bit, Windows 64/32 bit or MacOS 64 bit

Controls

The communication between the application and the user is mostly carried out using dialog windows where user can select files, directories or additional settings for the corresponding functionality. Dialogs are usually confirmed by pressing the OK button and canceled by pressing the Cancel button or by closing the window.

For information and debugging purposes, the program also logs messages into the console. Some important messages are also displayed as a pop-up message box.

A lot of the work is done with charts displayed in the main section of the user interface. The chart can be navigated using the mouse and the keyboard. The common controls are as follows:

Note: The movement speed depends on the zoom level. More precise movement can be done when zoomed in whereas faster movement is more easily done when zoomed out.

File Formats

The program currently supports three file formats:

• FITS - Flexible Image Transport System (.fits, .fit, .fts)

• Ascii plain-text (.txt, .ascii, no extension)

• Original Spefo formats (.uui, .rui, .con)

  • only for import

Note: The use of the FITS file format is strongly encouraged and sometimes necessary.

Menu

All the program's functionality can be accessed through the menu in top-left corner:

• File

  → Open

  → Save

  → Quit

• Project

  → FITS to Lst

  → Prepare Directory

  → Apply HelCorr

  → Add to Lst

  → RV Results

  → EW Results

  → Compare

• Tools

  → Rectify

  → Clear Cosmics

  → Measure RV

  → Measure EW

  → Convert

  → to Ascii

  → to FITS

• Extra

  → Chiron to Ascii

  → Extract FITS Header

Each individual function will be further discussed in the following sections.

Note: When using the program, please keep in mind that most functions can be activated at almost any time, but using them may result in the loss of your unsaved work.

Functions

All functions can be launched from the menu but some of them have shortcut keys associated with them. They are listed in the brackets next to the function name.

Open (Ctrl + O)

This function is used to display and inspect individual spectrum files. No changes to the file can be made.

When selected, the user is prompted to choose a file to open. The chosen spectrum is then displayed as a line chart. It can then be navigated as described in the section Controls. Additionally, the user can hold Ctrl and use mouse Click and Drag to draw a rectangle. When released, a zoomed-in view of the selected area is displayed. The current cursor position is shown in the bottom right corner.

Save (Ctrl + S)

This function is complementary to the Open function. It saves the file that is currently opened. This can be used to change the file format or name.

When selected, the user is prompted to choose the file destination. The target format is determined by the file extension. If there is a file with the same name, a dialog window opens to confirm overwriting of the original file.

Note: This function is available at all times but it might not make sense to use it in some situations.

Quit (Ctrl + Q)

This function is used to close the application.

When selected, a confirmation dialog window opens. If confirmed, the program is terminated. Otherwise it returns to it’s previous state.

Fits to Lst

This function is used to create a new .lst file from a directory containing FITS files.

When selected, a dialog window appears where the user selects a directory with desired FITS files and fills in a header for the new file. Optionally, the user can choose to also search nested directories. The selected directory (and possibly also nested directories) will then be scanned for FITS files. All discovered files will be used to create a table in the new .lst file with the provided file header. The program will also try to extract date and time as well as the exposure time of the spectrum and write that information into the created table. All invalid files will be skipped.

Note: Some functionality in the dialog is disabled and will be implemented in the future.

Prepare Directory

This function is used to rename a batch of spectra, their .lst file and also to apply heliocentric or barycentric RV correction.

When selected, a dialog window opens where the user selects a .lstfile and a prefix for the new file names. Optionally, the user can choose to also apply RV correction. The .lst file is then loaded and all files in the file table are renamed using the file name prefix and their table index. If selected, the RV correction associated with each table row is also applied to the spectrum files. Finally, the .lst file is also renamed using the file name prefix.

Note: RV correction will only be applied to FITS files. It ignores any previous RV correction values present in the file. This behavior might get changed in the future.

Apply HelCorr

This function is used to apply heliocentric RV correction specified in a .lst file to the actual spectrum files.

When selected, the user is prompted to select a .lst file. The file is then loaded and for each table entry the specified RV correction is applied to the respective spectrum file. If a different RV correction is already applied to a spectrum file, then the difference between the value in the table and in the file is calculated and applied instead. Physical spectrum files are searched by their .lst file name prefix and by their table index.

Note: This function will only apply RV corrections to FITS files.

Add to Lst

This function is used to append new entries to an existing .lst file.

When selected, a dialog window appears where the user selects the .lst file to append to and the files to be appended. Optionally, the user can also choose a file prefix different from the .lst file and the option to add the original file names to the table. The .lst file is then loaded and new table entries are appended to it based on the selected files. These files are then renamed based on the specified file prefix and their new table index. Based on the user selection, their original file name can also be added to their table entry.

Note: Multiple files can be selected in the file dialog for adding spectrum files to be appended.

RV Results (Ctrl + T)

This function is used to combine multiple .rvr files obtained using the function Measure RV into a single overall summary .rvs file.

When selected, a dialog window appears where the user selects the .lst file. When a valid file is selected, it is loaded and the table underneath is populated with it's entries. If it isn't a valid file or some files couldn't be found, their field is marked red. If the .rvr file names are different from the naming convention, it is possible to set them manually. If the files in a project are named using an incrementing number in their file name (abc001.fits, abc002.fits, etc.), then the first one can be selected and using the Fill below button, the program will automatically fill in the rest of the table .

When the whole dialog is filled in and confirmed, two files will be created. A .rvs file with all measured categories and, if possible, a .cor file with all RV measurements adjusted by the difference between the measured RV correction and the RV correction in the .lst file.

EW Results (Ctrl + Shift + T)

This function is used to combine multiple .eqw files obtained using the function Measure EW into a single overall summary .eqw file.

When selected, a dialog window appears where the user selects the .lst file. When a valid file is selected, it is loaded and the table underneath is populated with it's entries. If it isn't a valid file or some files couldn't be found, their field is marked red. If the .eqw file names are different from the naming convention, it is possible to set them manually. If the files in a project are named using an incrementing number in their file name (abc001.fits, abc002.fits, etc.), then the first one can be selected and using the Fill below button, the program will automatically fill in the rest of the table .

When the whole dialog is filled in and confirmed, a new .rvs file will be created. It will contain a table of measurements for each measured line. If there are multiple measurements for the same line in any .eqw file, they will be averaged.

Compare

This function is used to compare two spectrum files and measure their differences.

When selected, the user is prompted to consequently select two spectrum files. They will then be displayed in a line chart with different colors.

The chart can then be navigated as described in the section Controls. Additionally, the user can use the keys J and L to move the second line left and right and the keys I and K to scale the second line vertically.

Information about the x-shift in units of radial velocity and about the y-scale can be viewed in the bottom bar. It can also be adjusted using the + and - buttons or set to an exact value using the Set Values button. The Reset button sets the shift and scale values to zero and one.

Rectify (Ctrl + R)

This function is used to rectify a spectrum. It works by defining a continuum using multiple points selected in a chart. The program models and displays the continuum in real-time using Hermite polynomials. When confirmed, the flux values of the original spectrum are divided by the values defined by the continuum, therefore transforming them into relative values.

When selected, the user is prompted to select a spectrum file. The spectrum is then loaded and displayed in a line chart. In addition, two initial rectification points are created or points are transferred from the previous rectification (if there was any). One of the points is always considered to be active and is displayed in a different color. When a mouse moves, the closest point to it is selected as the active one.

The chart can then be navigated as described in the section Controls. Additionally, there is a number of other control elements:

The continuum selection is confirmed by pressing Enter. That will rectify and display the spectrum with a line corresponding to relative intensity of one. The auxiliary line can be hidden or shown again by pressing Tab. Pressing Enter again confirms and saves the spectrum. Pressing Escape returns the chart to the continuum selection.

Note: If the new point after using N or M isn't visible, the view will also move so that it is in the center.

Clear Cosmics

This function is used to remove excessive noise or bad pixels from a spectrum file.

When selected, the user is prompted to select a spectrum file. The spectrum is then loaded and displayed in a scatter chart. One of the points is always considered to be active and is displayed in a different color. When a mouse moves, the closest point to it is selected as the active one. Unwanted points can be cleared and the program will calculate a new position for them using Hermite polynomials. The deleted points are still visible and displayed in a different color and can be restored. Points that weren't cleared can be moved up or down to help smoothing out large cleared areas.

The chart can then be navigated as described in the section Controls. Additionally, there is a number of other control elements:

The clearing process is confirmed by pressing Enter. That will clear and display the spectrum as if it was just loaded. Pressing Enter again confirms and saves the spectrum. Pressing Escape returns the chart to the clearing process.

Measure RV (Ctrl + M)

This function is used to measure radial velocity on spectrum files.

When selected, a dialog window appears where the user selects the measured spectrum file and two lists of .stl files. The first one is for regular measurements and the second one is for measuring telluric lines. The user can also choose to specify a fixed value for the RV step. When the dialog is confirmed, the program tries to determine the RV correction of the spectrum file. If it can't find it, the user is prompted to insert it in manually.

The files are then loaded and a part of the spectrum as well as a flipped part of it is displayed in a line chart on the left. This is where the user measures the center or any other region of the line profile by aligning the original and flipped lines. When the measurement is confirmed, a new dialog appears where the user selects a category and optionally a comment. Correction measurements have their category predefined.

The chart can then be navigated as described in the section Controls with some exceptions and additions:

On the right side, there are two lists. The top one corresponds to valid measurements from the provided .stl files. This list can be used to browse through them. The bottom list corresponds to results. By clicking on one of them, one can edit and save them using Enter or save them as a different result using Insert. They can also be deleted using Delete or Backspace.

Under the lists there is a label showing the RV step. It can be changed in a dialog window opened by pressing the button ... next to the label.

When the last item from the list is measured, the whole spectrum is displayed with points showing the locations of all RV settings. By pressing Enter, the results are confirmed and saved into a .rvr file. This can also be done using the button on the bottom right. If a .rvr file already exists, it can be overridden or appended to.

Measure EW (Ctrl + E)

This function is used to measure equivalent widths and other properties on spectrum files.

When selected, a dialog window appears where the user selects the measured spectrum file and a lists of .stl files. The files are then loaded and a part of the spectrum is displayed in a line chart on the left. This is where the user measures the center or any other region of the line profile.

To add a new measurement to the current line, press Insert or Enter. That will open a dialog window where the user can select which part of the line is currently being measured. Afterwards, an orange line will appear that represents the selected point. It can be dragged using the mouse or using Arrow Left or A to move left and Arrow Right or D to move right. There is no need to confirm the selection. A measurement can be deleted using Backspace or Delete.

The user can also change the boundaries used for EW calculations by selecting them from the right bar. The active line has a cyan color.

To move to the next line, End or Escape can be used or any line can be selected from the list in the top right.

When the last line is measured, the results can be saved by pressing End, Escape or the Finish button in the bottom right. After confirmation, this will write the results into an .eqw file. If an .eqw file already exists, it can be overridden or appended to.

Convert

to Ascii

to FITS

This function is used to convert individual or multiple files to different formats.

When one of the options is selected, a dialog window appears where the user selects a file or multiple files as well as the desired file extension. Optionally, the user can choose the option to adjust the file values for the difference between the computed and measured RV correction. The files will then be converted to the chosen format with the chosen file extension and if selected, they're values will be adjusted. They will retain their original folder and file name (except for the file extension). Files that couldn't be opened or converted are skipped.

Note: This function will overwrite any files with the same name.

Chiron to Ascii

This function is used to convert Chiron FITS files to Ascii format and extract their header.

When selected, the user is prompted to choose a spectrum file. The file will then be loaded and converted to Ascii. It's header will be saved into a separate .header file.

Note: This function was created for one specific spectrograph, use with caution.

Extract FITS Header

This function is used to extract the header from a FITS file.

When selected, the user is prompted to choose a spectrum file. The file will then be loaded and it's header will be saved into a new .header file.

The new file is a plain text formatted file which can be easily opened and inspected in a text editor.

Final Remarks

This program is still in active development and may contain bugs or crash unexpectedly, please always save and back up your work.

Any and all feedback is greatly appreciated.

Software is distributed under EPL 2.0.