A Python package for detecting and analyzing Electric Vector Position Angle (EVPA) rotations in polarimetric monitoring data of Active Galactic Nuclei (AGN).

1. Features
2. Installation
3. Quick Start
4. Data Format
5. Methodology
6. Output
7. Examples
8. Testing
9. Citation & Contact
10. References

• Data Loading & Preprocessing

  • Automatic filtering: PD/σ_PD ≥ 3 [1]
  • MJD conversion & gap segmentation

• Angle Ambiguity Resolution

  • Error-weighted 180° wrap optimization [2]

• Bayesian Blocks Segmentation

  • astropy.stats.bayesian_blocks with measurement uncertainties [3]

• Rotation Detection

  • Local extrema pairing (max↔min)
  • Statistical tests: Student's t-test [4], binomial test [5]

• Visualization

  • Publication-ready EVPA & Bayesian Blocks plots

• CLI Support

  • Batch or single-source processing
  • Customizable thresholds (amplitude, p-values)

Perfect for quick testing or if you don't have Git installed:

1. Download: Click the green "Code" button on GitHub → "Download ZIP"
2. Extract: Unzip the downloaded file
3. Setup environment:

   cd blazar-evpa-rotation-detector-main
   conda env create -f environment.yml
   conda activate evpa-rotation

4. Run analysis:

   python analyze.py

⚠️ Important: You must be in the extracted directory to run the code.

git clone https://github.com/glykanastasia/blazar-evpa-rotation-detector.git
cd blazar-evpa-rotation-detector
pip install -e .

git clone https://github.com/glykanastasia/blazar-evpa-rotation-detector.git
cd blazar-evpa-rotation-detector
conda env create -f environment.yml
conda activate evpa-rotation

git clone https://github.com/glykanastasia/blazar-evpa-rotation-detector.git
cd blazar-evpa-rotation-detector
pip install -e .[dev,docs,plotting]

from evpa_rotation import RotationAnalyzer

analyzer = RotationAnalyzer(data_file="data/monitoring_data.csv")
results = analyzer.analyze_all_sources(
    p0=0.001, diff_threshold=90,
    t_test_threshold=0.05, binom_threshold=0.0625
)
print(analyzer.get_summary_statistics())

# Full dataset
evpa-analyze --data monitoring_data.csv --output results/

# Specific sources & stricter criteria
evpa-analyze --data monitoring_data.csv \
  --sources "3C 454.3" "CTA 102" \
  --min-amp 30 --t-threshold 0.01 --binom-threshold 0.01 \
  --show-plots

• Data Source: Monitoring data compiled by Blinov et al. (2021) [6]

1. Preprocessing

   • Convert to MJD, filter PD/σ_PD ≥ 3 [1], segment gaps (30 d).

2. Angle Adjustment

   • Minimize error-weighted Δψ between points, resolve 180° wraps [2].

3. Bayesian Blocks

   • Identify change points with heteroscedastic errors [3].

4. Rotation Detection

   • Pair extrema → compute Δψ, Δt.
   • t-test: H₀: EVPA distribution centered on 180° [4].
   • Binomial test: random orientation around 180° [5].

5. Criteria

   • p_t ≤ 0.05, p_b ≤ 0.0625, Δψ ≥ 0° (customizable)

• CSV: rotation_events.csv (detailed event table)
• Plots: PNG per event (time series & blocks)
• Summary: aggregated statistics

Columns: Source, Period, t_start, t_end, ΔMJD, AMPLITUDE, AMPLITUDE_error, t-test p, Binom test p, n_points, extrema_type

analyzer = RotationAnalyzer(data_file="data.csv")
rotations = analyzer.analyze_source("3C 454.3", show_plots=True)

results = analyzer.analyze_all_sources(
  p0=1e-4, diff_threshold=45,
  t_test_threshold=1e-2, binom_threshold=1e-2
)

from evpa_rotation import plot_source_overview

plot_source_overview(analyzer.load_data("3C 454.3"), "3C 454.3")

pytest tests/             # Run tests
pytest --cov=evpa_rotation  # Coverage report

If you use this software in your research, please cite it! This helps support continued development and allows others to discover the tool.

@software{glykopoulou2025evpa,
  author = {Glykopoulou, Anastasia},
  title = {EVPA Rotation Analysis: A Python package for detecting EVPA rotations in AGN},
  year = {2025},
  url = {https://github.com/glykanastasia/blazar-evpa-rotation-detector},
  version = {1.0.0}
}

Glykopoulou, A. (2025). EVPA Rotation Analysis: blazar-evpa-rotation-detector (Version 1.0.0) [Computer software]. https://github.com/glykanastasia/blazar-evpa-rotation-detector

Glykopoulou, A. (2025). EVPA Rotation Analysis: blazar-evpa-rotation-detector (Version 1.0.0) [Computer software]. GitHub. https://github.com/glykanastasia/blazar-evpa-rotation-detector

If this software contributed to your published work, we kindly request that you:

1. Cite the software using one of the formats above
2. Mention it in your acknowledgments section, for example:

"This research made use of the EVPA Rotation Analysis package (Glykopoulou, 2025), available at https://github.com/glykanastasia/blazar-evpa-rotation-detector"

3. Reference the underlying methodology from:
   • Blinov et al. (2015) for rotation detection criteria (MNRAS, 453, 1669)
   • Blinov et al. (2021) for the monitoring data compilation (MNRAS, 501, 3715)

• Developer: Glykopoulou Anastasia (Bachelor Student)
  Department of Physics, University of Crete
  Institute of Astrophysics, Foundation for Research and Technology – Hellas (FORTH)
  Email: [email protected]

• Report Issues: GitHub Issues

• Contributions: Pull requests are welcome! Please see our contributing guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.

1. Angel, J. R. P. & Stockman, H. S. (1980). Optical and Infrared Polarization of Active Extragalactic Objects. Annual Review of Astronomy and Astrophysics, 18, 321–361. https://doi.org/10.1146/annurev.aa.18.090180.001541

2. Hovatta, T., Lindfors, E., Blinov, D., Pavlidou, V., Nilsson, K., Kiehlmann, S., Angelakis, E., et al. (2016). Optical polarization of high-energy BL Lacertae objects. Astronomy & Astrophysics, 596, A78. https://doi.org/10.1051/0004-6361/201628974

3. Scargle, J. D., et al. (2013). Bayesian Block Representations of Poisson Data. The Astrophysical Journal, 764, 167. https://doi.org/10.1088/0004-637X/764/2/167

4. Blinov, D., Pavlidou, V., Papadakis, I., Kiehlmann, S., Panopoulou, G., Liodakis, I., King, O. G., et al. (2015). RoboPol: first season rotations of optical polarization plane in blazars. Monthly Notices of the Royal Astronomical Society, 453, 1669–1683. https://doi.org/10.1093/mnras/stv1723

5. Myserlis, I., Komossa, S., Angelakis, E., Gómez, J. L., Karamanavis, V., Krichbaum, T. P., Bach, U., et al. (2018). Polarimetric monitoring and EVPA rotations in AGN. Astronomy & Astrophysics, 619, A88. https://doi.org/10.1051/0004-6361/201732273

6. Blinov, D., Kiehlmann, S., Pavlidou, V., Panopoulou, G. V., Skalidis, R., Angelakis, E., Casadio, C., et al. (2021). RoboPol: connection between optical polarization plane rotations and gamma-ray flares in blazars. Monthly Notices of the Royal Astronomical Society, 501, 3715–3726. https://doi.org/10.1093/mnras/staa3777