Polarization Calibration Pipeline

This repository contains a CASA/Difmap-based pipeline for iterative polarization calibration of VLBI data. The script automates the process of loading data, imaging with Difmap, solving for instrumental polarization (D-terms), monitoring convergence, and performing absolute EVPA calibration using the PolSolve algorithm (Marti-Vidal, A&A, 646, A52), and the entropy-based cleaning methods introduced by Homan et al. (2024, AJ, 167, 11).

Requirements

• Python 3\
• CASA (≥6) with casatasks available in Python.\
• Difmap (path must be set in script).\
• VCAT (vcat module for plotting polarization images).\
• Matplotlib\
• NumPy\
• External helper scripts:
  • CASA_multisource_import.py\ -> comes with the repository
  • script_clean_v2024_01_10.py\ -> can be obtained here
  • step_4.py\ -> comes with the repository
  • step_5.py -> comes with the repository

Ensure these scripts are in the working directory

Input Data

• UVFITS files: Place in input_uvfs/ directory (naming: sourcename.uvf).\
• Window files (.win): One per source, matching the UVFITS file order, placed in the working directory, NOT in input_uvfs/

Configuration

Key user settings are defined at the top of pipeline.py:

• Paths
  • difmap_path: Path to Difmap installation.\
  • ms_name: Name of CASA Measurement Set to create, can be anything, e.g. 'test.ms'
• Imaging
  • npix: Image size (pixels).\
  • cellsize: Pixel size (mas).\
  • clean_gain, cc_per_iter: Entropy cleaning parameters.
• Calibration
  • calibrator_sources: Names of calibrators.\
  • target_sources: Names of science targets.\
  • evpa_calibrator: Source name used for absolute EVPA calibration. (optional) \
  • evpa_cal_angle: Known EVPA of calibrator (degrees). (optional) \
  • refant: Reference antenna for polcal.\
  • num_ifs: Number of IFs in data.
• Iteration Control
  • min_runs: Minimum number of polsolve iterations.\
  • max_runs: Maximum number of iterations.
• Plotting
  • Axis limits (xlim, ylim).\
  • Sigma cuts for polarization maps.\
  • EVPA vector plotting options (color, length, width, spacing).

Usage

1. Place input UVFITS files into input_uvfs/.\

2. Place corresponding .win files in the working directory.\

3. Adjust parameters at the top of pipeline.py.\

4. Run the pipeline:

   python3 pipeline.py

5. Outputs:

   • CASA Measurement Sets and intermediate UVFITS files.\
   • D-term solutions (*.Dterms.ascii).\
   • Convergence log (*.converge_check.txt).\
   • Polarization plots (.pdf per iteration).\
   • Final calibrated UVFITS files (*_pol_calibrated.iter.XX.uvf).

Notes

• Parallelization of cleaning is not yet implemented; tasks run sequentially.\
• Ensure that the order of .win files matches the input UVFITS files.\
• EVPA calibration requires a known calibrator angle between -90° and 180°.\
• Additional plotting scripts are available for rl-phase difference, and D-terms. \
• Additional data modification scripts are available to apply D-terms from a file and to modify the RL-phase difference using ParselTongue.\