.. ixpepy documentation master file

.. image:: _static/logo.png
   :alt: ixpepy logo
   :align: center
   :width: 300px

ixpepy Documentation
====================

**ixpepy** is a Python package for analyzing data from the **IXPE** (Imaging X-ray Polarimetry 
Explorer) mission using the `3ML <https://threeml.readthedocs.io/en/latest/>`_ (Multi-Mission Maximum Likelihood) framework. IXPE is NASA's 
first mission dedicated to measuring the polarization of X-rays from cosmic sources, providing 
unprecedented insights into the geometry and physics of extreme environments.

About IXPE
----------

The Imaging X-ray Polarimetry Explorer (IXPE) was launched in December 2021 and observes 
X-ray polarization in the 2-8 keV energy range. IXPE features three identical detector units 
(DU1, DU2, DU3) that measure not only the intensity of X-ray sources but also the polarization 
properties through Stokes parameters (I, Q, U).

What is ixpepy?
---------------

**ixpepy** provides a comprehensive toolkit for IXPE data analysis, seamlessly integrating 
with the 3ML framework for multi-mission likelihood analysis. The package handles the 
complexities of IXPE data formats (OGIP-compliant PHA files) and enables joint spectral 
and polarimetric fitting with physically motivated models.

Key Features
------------

**Data Management**
  - Automatic download of IXPE observations from the XPQLT database by source name or observation ID
  - Support for both XPQLT-processed and original HEASARC archive files
  - Organized file management for multiple observations and detector units

**Spectral Analysis**
  - Load and analyze IXPE spectral data for all Stokes parameters (I, Q, U)
  - Support for all three IXPE detector units with consistent data handling
  - Flexible energy range selection and spectral rebinning
  - Background subtraction and effective area corrections

**Polarization Analysis**
  - Joint fitting of intensity and polarization spectra
  - Stokes parameter calculations and polarization metrics
  - Support for energy-dependent polarization analysis
  - Automatic linking of Q/U parameters to intensity normalization

**Integration with 3ML**
  - Native compatibility with 3ML's likelihood framework
  - Joint analysis with other X-ray missions (NuSTAR, XMM-Newton, Chandra, etc.)
  - Access to 3ML's extensive model library (Astromodels)
  - Bayesian and frequentist inference methods

**Visualization Tools**
  - Spectral plotting for intensity and polarization
  - Q-U plane visualization with confidence regions
  - Polarization maps and angle distributions
  - Customizable publication-quality figures

Installation
============

To install ixpepy, you can use pip:

.. code-block:: bash

    pip install ixpepy

Or install from source:

.. code-block:: bash

    git clone https://github.com/threeML/ixpepy.git
    cd ixpepy
    pip install -e .

Quick Start
===========

Getting started with ixpepy is straightforward. See the :doc:`quickstart` 
section for a complete workflow from downloading data to performing 
spectral-polarimetric analysis.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   quickstart
   api
   examples
   release_notes

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`