Supplementary Tools for polsalt Spectropolarimetry (stops)

stops is a Python3-based pipeline designed to provide additional functionality to the polsalt pipeline. This pipeline provides a command-line interface (CLI) that can call four main classes, each implementing a unique function: Split, Join, Skylines, and CrossCorrelate. For an in-depth discussion and usage, see the stops writeup.

Installation

To install the stops pipeline, simply download the wheel file and run:

cd ~/Downloads
# Activate any conda environment
pip install STOPS

The repository may also be cloned and the dependencies installed:

git clone https://github.com/JustinotherGitter/STOPS.git # or manually download the repository
cd STOPS
# Additionally create and activate a python3 `STOPS` venv
pip install -r requirements.txt

Note: stops also requires $\LaTeX$ to be installed as well as to have polsalt installed in the Home, ~/, directory.

Classes

• Split: Separate the pre-processed polsalt FITS files by their perpendicular polarization beams into two iraf parsable FITS files.
• Join: Combine external wavelength calibration solutions with the perpendicular beams, as expected by polsalt's spectral extraction
• Skylines: Automatically identify and calculate the difference between known and observed sky lines (or arc lines) in wavelength calibrated spectropolarimetric data.
• CrossCorrelate: Perform cross-correlation analysis on the spectropolarimetric data (possible after polsalt's spectral extraction), either for each file comparing the perpendicular polarization beams, or across multiple files comparing a singular polarization beam.

Procedure

A simplistic workflow is provided below, for further information and implementation please see the [write-up] of stops.

1. Pre-reductions may be performed on the raw data using polsalt, or downloaded directly alongside the raw data.
2. The $O$- & $E$-beams are split into two separate FITS files using split, into the format required by iraf.
3. Wavelength calibrations are performed via iraf, replacing the polsalt wavelength calibration.
   • Alternate external tools, such as Python may also be used for wavelength calibrations.
   • Formatting of non-iraf wavelength solutions must be formatted as described in the Wavelength section.
4. The $O$- & $E$-beams, along with their respective wavelength solutions, are recombined into a single file using join, and cosmic-ray cleaning performed via the lacosmic algorithm implemented through ccdproc.
5. The wavelength calibrations for the $O$- & $E$-beams may be compared using skylines, highlighting variations between the individual wavelength solutions.
6. Spectral extraction is performed via polsalt.
7. The extracted spectra may be compared using correlate, allowing the correlation between the perpendicular polarization beams within a file to be correlated, or for a polarization beam across multiple files.
8. If either skylines or correlate show poor wavelength calibrations, the wavelength calibration procedure may be repeated.
9. The files generated, excluding the wavelength solution, for wavelength calibrations may be moved or deleted.
10. Polarization calculations are performed via polsalt.
11. Flux calibration may be performed using the astropy and scipy packages, assuming a standard is available for the observational setup.

Wavelength Calibration

Wavelength calibrations are ideally intended for iraf. The iraf wavelength calibration procedure uses identify, reidentify, fitcoords, and optionally transform. Any preferred parameters may be used during calibration with only the polynomial type of the resultant wavelength solution (as produced by fitcoords) being limited to either Chebyshev or Legendre polynomials.

Alternate wavelength solutions may be used but must be:

• Saved in the working directory,
• Have separate files for the $O$- and $E$-beams,
• Have a name containing:
  • The polynomial type (e.g. cheb for Chebyshev, or leg for Legendre), and
  • The polarization beam contained within (e.g. O or E),
• Contain on:
  • line 1 → the $x$-order of the 2D wavelength solution,
  • line 2 → the $y$-order of the 2D wavelength solution,
  • lines 3+ → the ($x * y$) solution coefficients, in order, separated by line, and
  • all lines → no delimiters.

e.g.

cheb_params_e.txt

5
5
7419.096745914063
1510.03933621895
-21.10886852752348
-2.079553916887794
0.06772631420528228
0.7720164913117386
'...'

CLI Usage

The stops pipeline is most generally controlled via a CLI. The basic format of commands follows:

<py_dir>python<3> <STOPS_dir>STOPS (General Options) [data_dir] MODE (Options) [File names]

where:

• <> parameters are optional depending on the system setup, e.g. if Python or stops has been added to $PATH, etc. (for simplicity, these parameters will be left out of the usage examples below),
• MODE refers to the operational mode of stops, as listed in Modes,
• () parameters are optional, and
• [] parameters are compulsory (unless otherwise stated).

Below are the details of the stops options, the available Modes, and their respective sub-options.

stops Options

Optional:

• -V, --version: Show the version of stops.
• -v, --verbose: Enable and increase verbosity. Use -v or -vv for greater verbosity levels.
• -l, --log: Specify the filename of the logging file, which is created if it does not exist.

Compulsory:

• data_dir : The Path (absolute or relative) to the directory containing the Working data. . may be used to indicate the current directory that the CLI is running in.

Help Commands

For detailed information on stops, use the help command:

python STOPS . --help

Help for each mode is also accessible, and may be viewed using the help command:

python STOPS . MODE --help

where MODE may be replaced with split, join, skylines, or crosscorrelate.

Modes

---

split

python STOPS . split (Options) [mxgbp*.fits]

split Options

Optional:

• -n, --no_arc: Exclude arc files from processing.
• -s, --split_row: Row along which the $O$- & $E$-beams are split. Defaults to the polsalt's default.
• -p, --save_prefix: Prefix appended to the filenames for saving the $O$- & $E$-beams. Defaults to the polsalt's default.

Compulsory:

• Filenames to be split. May be excluded if the RegEx pattern in the example matches the desired files.

---

join

python STOPS . join (Options) []

join Options

Optional:

• -n, --no_arc: Exclude arc files from processing.
• -s, --split_row: Row along which the $O$- & $E$-beams are split. Defaults to the pipeline's default.
• -p, --save_prefix: Prefix appended to the filenames for saving the $O$- & $E$-beams. Defaults to the pipeline's default.
• -c, --coefficients: Custom coefficients to use instead of the IRAF fitcoords database. Use as -c <o_solution> <e_solution> or a RegEx descriptor -c <*solution*extension>.

Compulsory:

• May be excluded as join will identify all split files and wavelength solution database entries to recombine.

---

skylines

python STOPS . skylines (Options) [Filenames]

skylines Options

Optional:

• -b, --beams: Beams to process. Defaults to OE, but may be given O, E, or OE.
• -ccd, --split_ccd: Flag to NOT split CCD's.
• -c, --continuum_order: Order of continuum to remove from spectra.
• -p, --plot: Flag for additional debug plot outputs.
• -s, --save_prefix: Prefix used when saving plot.
• -t, --transform: Force transform images, for iraf transform FITS file debugging.

Compulsory:

• Filenames to be considered for skyline comparisons. May either be:
  • the wmxgbp*.fits RegEx pattern for polsalt formatted, wavelength calibrated, FITS files, or
  • the tbeam*.fits RegEx pattern for iraf formatted, transform output, FITS files.

---

correlate

python STOPS . correlate (Options) [ecwmxgbp*.fits]

correlate Options

Optional:

• -b, --beams: Beams to process. Defaults to OE, but may be given O, E, or OE.
• -ccd, --split_ccd: Flag to NOT split CCD's.
• -c, --continuum_order: Order of continuum to remove from spectra.
• -p, --plot: Flag for additional debug plot outputs.
• -s, --save_prefix: Prefix used when saving plot.
• -o, --offset: Introduce an offset when correcting for known offset in spectra or for testing purposes. Deprecated keyword.

Compulsory:

• Filenames to be considered for correlate cross-correlation. May be excluded if the RegEx pattern in the example matches the desired files.

Contributing

Contributions are welcome! Please fork the repository and create a pull request with your changes. The following styles are broadly implemented, and serve as a collection of references used when creating the stops pipeline:

• General Python project structure applies

• Docstrings follow the NumPy documentation style

  • Possible sphinx docs?

• Classes and methods implement typing for type hinting

• Logging is implemented

• Tests are planned but not implemented

  • pytest or unittest (pytest-cov | tox)?

• requirements.txt was generated using pipreqs

  • Found using:

    cd /media/justin/Transcend/STOPS
    pipreqs

• The minimum required Python version was found using vermin

  • Found using:

    cd /media/justin/Transcend/STOPS
    vermin --eval-annotations --feature union-types ./src/STOPS

• stops management

  • Building generates tar.gz and whl files, overwrites if version not updated. Built using:

    cd /media/justin/Transcend/STOPS
    python3 -m build

  • Installed using pip in an editable format (exclude -e for stable release):

    cd /media/justin/Transcend/STOPS
    pip install -e ../STOPS

See Also

• Package creation:

  • https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
  • https://packaging.python.org/en/latest/tutorials/packaging-projects/
  • https://packaging.python.org/en/latest/tutorials/installing-packages/

• Package resources

  • https://docs.python.org/3.11/library/importlib.resources.html
  • https://importlib-resources.readthedocs.io/en/latest/using.html
  • https://setuptools.pypa.io/en/latest/userguide/datafiles.html

• SALT Line Atlases

  • http://pysalt.salt.ac.za/lineatlas/

License

This project is licensed under the BSD 3-Clause License. See the LICENSE for further details.