Metadata-Version: 2.5
Name: tessapps
Version: 0.2.6
Summary: TESS Aperture Photometry Pollution eStimator
Author: Leonidas Liponis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Classifier: License :: OSI Approved :: MIT License
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: astropy
Requires-Dist: astroquery
Requires-Dist: lightkurve
Requires-Dist: bump-my-version ; extra == "dev"
Requires-Dist: flit ; extra == "dev"
Project-URL: Homepage, https://codeberg.org/leolip128/tessapps
Project-URL: Repository, https://codeberg.org/leolip128/tessapps
Provides-Extra: dev
Import-Name: tessapps

# TESS Aperture Photometry Pollution eStimator   [![PyPI](https://img.shields.io/pypi/v/tessapps)](https://pypi.org/project/tessapps/)

*Note: this module is not yet fully developed. For commercial use, please wait for v1.0.0. It is expected to be in development for at least another month.*

## Description

A python module that calculates a contamination factor in the aperture region of a tpf based on the relative flux of the background stars and the target.

![TESSAPPS Example: HAT-P-1](https://codeberg.org/leolip128/tessapps/raw/branch/main/examples/HAT-P-1.png "title")

## Prerequisites

Mandatory:

- ```numpy``` (2.4.2): to make all calculations
- ```scipy``` (1.17.1): to integrate the gaussian function
- ```astropy``` (8.0.1): to build data used in this module
- ```astroquery``` (0.4.11): to find stars in the target's region

Optional:

- ```lightkurve``` (2.6.0): to fetch tpf files  (unless they already exist locally)
- ```matplotlib``` (3.10.8): to plot the result (shows aperture mask with a caption at the bottom)

A future version will include minimum working versions (these are the only tested so far)

## Running the module

A tpf is needed to run this module. If no tpf is supplied, the default is a file with HAT-P-1 (the example picture above). So, here is the minimal example:
```
import tessapps as tapps

tapps.run()

>>> [0.57675, 0.00191]
```

The first number is the contamination factor, and the second is its error. Here is a more realistic example with CoRoT-1 (also in the example images):

```
import lightkurve as lk
import tessapps as tapps

tpf_CoRoT_1 = lk.search_targetpixelfile('CoRoT 1')[1].download()
contamination, error = tapps.run(tpf_CoRoT_1, result=True)

>>> The background contributes (2.249 ± 0.020)% of the total flux in the aperture region.
```

Alternatively, from a terminal:
```
tapps --tpf tpf_file
python3 -m tessapps --tpf tpf_file
```

And also:
```
tapps --tpf tpf_file --result --sigma=1
```

## File Organization

### Files in ```/src```:

```bash
src
└── tessapps
    ├── __init__.py
    ├── __main__.py
    ├── main.py
    ├── tpf_to_nearby_stars.py
    ├── nearby_stars_to_data.py
    └── data_to_contamination.py

2 directories, 6 files
```

### File description

- ```__init__.py```: makes it so that the user can run ```tessapps.run(...)```
- ```__main__.py```: executes main.py
- ```main.py```: the file that runs all other relevant files
- ```tpf_to_nearby_stars.py```: produces a list of stars near the target star only using the tpf file
- ```nearby_stars_to_data.py```: builds a data table containing all relevant information about stars, in a format readable by this module
- ```data_to_contamination.py``` constructs the gaussian fields and calulates the contamination filter

## Possible Issues

- ```ConnectionResetError```: happens sometimes due to ```urllib3```. Run again and it should compile normally.

## Authors

Leonidas Liponis

## Links

Codeberg page: https://codeberg.org/leolip128/tessapps

PyPI page: https://pypi.org/project/tessapps/

Email (for contact): lliponis (at) physics.auth.gr

## AI Disclosure

No LLMs were used in the making of this project. All code was generated and verified by humans, so it will only contain human-made mistakes. All commits on github made by bots will be refused, and commits made by humans will be checked: published code should be fully understandable by the authors.

## To-Do list

- add description
- specify dependencies' versions
- add options to run the module
- redo examples since they reference the flux instead of the contamination factor
- add the scoring function
- add more stuff in this to-do list

## Notes

### Examples

The default tpf is ```lk.search_targetpixelfile("HAT-P-1", mission="TESS", sector=84, exptime=120)[0].download()```, with ```[0]``` specified for reproducability (there is only one such file as of October 2026). HAT-P-1 has a star directly next to it with similar brightness, so it is a good default file as it is expected to find a contamination factor of about 0.5 (actual: 0.42).

All examples provided were generated with the following tpfs:

- HAT-P-1: ```lk.search_targetpixelfile("HAT-P-1", mission="TESS", sector=84, exptime=120)[0].download()```
- WASP-12: ```lk.search_targetpixelfile("WASP-12", mission="TESS", sector=20, exptime=120).download()```
- TOI-122: ```lk.search_targetpixelfile("TOI-122", mission="TESS", exptime=1800).download()```
- AUMic: ```lk.search_targetpixelfile('20:45:09.5323 -31:20:27.241')[4].download()```
- 55-Cnc: ```lk.search_targetpixelfile('55 Cnc')[6].download()```
- CoRoT-1: ```lk.search_targetpixelfile('CoRoT 1')[1].download()```
- CoRoT-10: ```lk.search_targetpixelfile('19:24:15.2868 +00:44:46.003')[1].download()```

The caption on each example was edited manually to show the name of each star.

### Other

The directory in File Organization has its files sorted manually.
