Metadata-Version: 2.2
Name: bayes_pol
Version: 1.1
Summary: Bayesian Spectral Polarization Models
Home-page: https://github.com/tvwenger/bayes_pol
Author: Trey V. Wenger
Author-email: Trey Wenger <tvwenger@gmail.com>
License: The MIT License (MIT)
        
        Copyright (c) 2025 Trey V. Wenger
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in
        all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
        THE SOFTWARE.
Project-URL: Homepage, https://github.com/tvwenger/bayes_pol
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bayes_spec>=1.7.2
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# bayes_pol <!-- omit in toc -->

![publish](https://github.com/tvwenger/bayes_pol/actions/workflows/publish.yml/badge.svg)
![tests](https://github.com/tvwenger/bayes_pol/actions/workflows/tests.yml/badge.svg)
[![Documentation Status](https://readthedocs.org/projects/bayes-pol/badge/?version=latest)](https://bayes-pol.readthedocs.io/en/latest/?badge=latest)
[![codecov](https://codecov.io/gh/tvwenger/bayes_pol/graph/badge.svg?token=Q9zM8gvHhE)](https://codecov.io/gh/tvwenger/bayes_pol)

Bayesian Spectral Polarization Models

`bayes_pol` implements models to infer the physics of the interstellar medium from radio continuum polarization observations.

- [Installation](#installation)
  - [Basic Installation](#basic-installation)
  - [Development installation](#development-installation)
- [Models](#models)
  - [`FaradayModel`](#faradaymodel)
- [Syntax \& Examples](#syntax--examples)
- [Issues and Contributing](#issues-and-contributing)
- [License and Copyright](#license-and-copyright)


# Installation

## Basic Installation

Install with `pip` in a `conda` virtual environment:
```
conda create --name bayes_pol -c conda-forge pymc>=5.20 pip
conda activate bayes_pol
pip install bayes_pol
```

## Development installation
Alternatively, download and unpack the [latest release](https://github.com/tvwenger/bayes_pol/releases/latest), or [fork the repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) and contribute to the development of `bayes_pol`!

Install in a `conda` virtual environment:
```
conda env create -f environment.yml
conda activate bayes_pol-dev
pip install -e .
```

# Models

The models provided by `bayes_pol` are implemented in the [`bayes_spec`](https://github.com/tvwenger/bayes_spec) framework. `bayes_spec` assumes that the source of the polarization signal can be decomposed into a series of "clouds" with Gaussian-like Faraday depth distributions, each of which is defined by a set of model parameters. Here we describe the models available in `bayes_pol`.

## `FaradayModel`

The `FaradayModel` predicts observations of Stokes Q, U, and Faraday depth (the Fourier transform of the complex polarization) by assuming the polarized intensity is modified by a series of "clouds" in Faraday depth space. The following diagram demonstrates the relationship between the free parameters (empty ellipses), deterministic quantities (rectangles), model predictions (filled ellipses), and observations (filled, round rectangles). Many of the parameters are internally normalized (and thus have names like `_norm`). The subsequent tables describe the model parameters in more detail.

![faraday model graph](docs/source/notebooks/faraday_model.png)

| Cloud Parameter<br>`variable` | Parameter                           | Units           | Prior, where<br>($p_0, p_1, \dots$) = `prior_{variable}`     | Default<br>`prior_{variable}` |
| :---------------------------- | :---------------------------------- | :-------------- | :----------------------------------------------------------- | :---------------------------- |
| `polarized_intensity`         | Polarized intensity                 | data brightness | $P_I \sim {\rm HalfNormal}(\sigma=p)$                        | `100.0`                       |
| `faraday_depth_mean`          | Mean Faraday depth                  | `rad/m2`        | $\langle F \rangle \sim {\rm Cauchy}(\alpha=p_0, \beta=p_1)$ | `[0.0, 1000.0]`               |
| `faraday_depth_fwhm`          | Faraday depth FWHM                  | `rad/m2`        | $\Delta F \sim {\rm HalfNormal}(\sigma=p)$                   | `10.0`                        |
| `pol_angle0`                  | Polarization angle at $\lambda = 0$ | `rad`           | $\phi_0 \sim {\rm Uniform}(-\pi/2, \pi/2)$                   |                               |  |

# Syntax & Examples

See the various tutorial notebooks under [docs/source/notebooks](https://github.com/tvwenger/bayes_pol/tree/main/docs/source/notebooks). Tutorials and the full API are available here: https://bayes-pol.readthedocs.io.

# Issues and Contributing

Anyone is welcome to submit issues or contribute to the development
of this software via [Github](https://github.com/tvwenger/bayes_pol).

# License and Copyright

Copyright(C) 2025 by Trey V. Wenger

This code is licensed under MIT license (see LICENSE for details)
