Metadata-Version: 2.1
Name: octofitterpy
Version: 5.0.2
Summary: Fast and flexible orbit fitting
Author-email: William Thompson <will.thompson@outlook.com>
License: MIT License
        
        Copyright (c) 2023 William Thompson
        
        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.
        
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3.0.0,>=0.21.0
Requires-Dist: numpy<3.0.0,>=1.13.0
Requires-Dist: juliacall==0.9.23
Requires-Dist: setuptools>=50.0.0

# octofitterpy

`octofitterpy` is a python package for performing Bayesian inference 
against a wide variety of exoplanet / binary star data. It uses the [Octofitter.jl](https://sefffal.github.io/Octofitter.jl/)
julia package under the hood (just like eg numpy uses C).

`octofitterpy` can access almost all functionality of Octofitter.jl. Currently a subset of this functionality including relative astrometry fitting, absolute astrometry fitting, and various plotting functions have been wrapped with convenient python functions. Remaining functionality can be accessed via the `octofitterpy.Octofitter` submodule.


The `examples` directory and [demo notebook](https://github.com/sefffal/octofitterpy/blob/master/examples/demo.ipynb) provide an introduction to using octofitter in Python.
Extensive documentation and tutorials are available [here](https://sefffal.github.io/Octofitter.jl/) for the Julia version, and for the most part are directly translatable to Python.

![](examples/gallery.png)

## Installation
In python 3.8 to 3.11 based environment, run:
```bash
pip install -U octofitterpy
```

## Example
```python
import octofitterpy as octo

# See demo.ipynb for more details
astrom_like = octo.PlanetRelAstromLikelihood(
    epoch = [50000,50120],
    sep = [505.7,600.1],
    pa = [0.0,0.4,],
    σ_sep = [10,10],
    σ_pa = [0.01,0.01],
    cor= [0,0.2]
)
planet_b = octo.Planet(
    name="b",
    basis="Visual{KepOrbit}",
    priors=
    """            
        a ~ LogUniform(0.1, 500)
        e ~ Uniform(0.0, 0.99)
        i ~ Sine()
        ω ~ UniformCircular()
        Ω ~ UniformCircular()
        θ ~ UniformCircular()
        tp = θ_at_epoch_to_tperi(system,b,50000) # use MJD epoch of your data here!!
    """,
    likelihoods=[astrom_like]
)
sys = octo.System(
    name="HIP100123",
    priors = 
    """
        M ~ truncated(Normal(1.2, 0.1), lower=0)
        plx ~ truncated(Normal(50.0, 0.02), lower=0)
    """,
    likelihoods=[],
    companions=[planet_b]
)
model = octo.LogDensityModel(sys) # Compile model
chain = octo.octofit(model) # Sample model
octo.octoplot(model,chain) # Plot orbits
octo.octocorner(model,chain,small=True) # Make corner plot
octo.savechain("table.fits", chain)
```

![](examples/HIP100123-plot-grid.png)
![](examples/HIP100123-pairplot-small.png)


## Read the paper
In addition to these documentation and tutorial pages, you can read the paper published in the [Astronomical Journal](https://dx.doi.org/10.3847/1538-3881/acf5cc) (open-access).

## Attribution
* If you use Octofitter in your work, please cite [Thompson et al](https://dx.doi.org/10.3847/1538-3881/acf5cc):
```bibtex
@article{Thompson_2023,
    doi = {10.3847/1538-3881/acf5cc},
    url = {https://dx.doi.org/10.3847/1538-3881/acf5cc},
    year = {2023},
    month = {sep},
    publisher = {The American Astronomical Society},
    volume = {166},
    number = {4},
    pages = {164},
    author = {William Thompson and Jensen Lawrence and Dori Blakely and Christian Marois and Jason Wang and Mosé Giordano and Timothy Brandt and Doug Johnstone and Jean-Baptiste Ruffio and S. Mark Ammons and Katie A. Crotts and Clarissa R. Do Ó and Eileen C. Gonzales and Malena Rice},
    title = {Octofitter: Fast, Flexible, and Accurate Orbit Modeling to Detect Exoplanets},
    journal = {The Astronomical Journal},
}
```

* If you use the pairplot functionality, please cite:
```
@misc{Thompson2023,
    author = {William Thompson},
    title = {{PairPlots.jl} Beautiful and flexible visualizations of high dimensional data},
    year = {2023},
    howpublished = {\url{https://sefffal.github.io/PairPlots.jl/dev}},
}
```

* The python wrapper octofitterpy is based on the excellent [PySR by Miles Cranmer](https://github.com/MilesCranmer/PySR). 

* See the documentation for a list of additional papers to consider citing.

## Ready?

Start by following this [tutorial](https://github.com/sefffal/octofitterpy/blob/master/examples/demo.ipynb).
