Metadata-Version: 2.4
Name: tess-dv-fast
Version: 0.10.0.post20260710
Summary: Fast lookup of TESS mission SPOC and TESS-SPOC TCE Data Validation (DV) reports
Author: Sam Lee
License-Expression: MIT
Project-URL: Homepage, https://github.com/orionlee/tess_dv_fast/
Project-URL: Issues, https://github.com/orionlee/tess_dv_fast/issues
Keywords: NASA,TESS,Astronomy,exoplanets
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Provides-Extra: build-db
Requires-Dist: requests>=2.0; extra == "build-db"
Requires-Dist: scipy; extra == "build-db"
Provides-Extra: webapp
Requires-Dist: Flask>=3.0; extra == "webapp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# TESS TCE Data Validation (DV) Reports Fast Lookup

A Python package / webapp that provides a fast lookup of TESS threshold crossing event (TCE) data validation reports from SPOC (2 minute cadence) pipeline and TESS-SPOC (FFI / HLSP) pipeline.

For SPOC, it also provides a summary of key TCE parameters, e.g. looking up all the TCEs for [pi Men / TIC 261136679](https://exofop.ipac.caltech.edu/tess/target.php?id=261136679):

![sample lookup result screenshot](https://raw.githubusercontent.com/orionlee/tess_dv_fast/main/assets/screenshot_tce_results.png)


## Installation

Install the package into your Python environment:

```shell
# include the web application
pip install ."[webapp,build_db]"

# Or just the core package:
# * build_db is needed to create the database.
pip install ."[build_db]"
```

For development: install the package in editable mode:

```shell
pip install -e ."[webapp,build_db,dev]"
```

Download the required data and build the local database:

```shell
python -m tess_dv_fast.tess_dv_fast_build --update --minimal_db
python -m tess_dv_fast.tess_spoc_dv_fast_build --update
```

Start the webapp:

```shell
flask --app tess_dv_fast.tess_dv_fast_webapp run
```

You are done! The app will be available at http://localhost:5000/tces .

Notes:

- To change the port of the webapp, add `-p <port_number>` to the `flask` command.
- The package downloads the data from MAST and creates local SQLite databases under `./data/tess_dv_fast/` by default. To use a different base directory, set `TESS_DB_BASE_PATH` before running the build commands, for example:

  ```shell
  export TESS_DB_BASE_PATH=/path/to/base
  ```

  The resulting database files will then be located at `$TESS_DB_BASE_PATH/data/tess_dv_fast/tess_tcestats.db` (SPOC) and `$TESS_DB_BASE_PATH/data/tess_dv_fast/tess_spoc_tcestats.db` (TESS-SPOC).
- For SPOC, the SQLite database contains a minimal set of data needed to support the webapp. Optionally, you could create a database with all the TCE parameters provided by MAST by omitting `--minimal_db`.
- It is tested on Python 3.10, but should be compatible with any recent Python 3 versions.


## Adding new data

The package relies on TCE bulk download data provided by MAST. When new data is available, the local database needs to be updated.

1. In `tess_dv_fast_spec.py` (SPOC),
    - update `sources_tcestats_single_sector` and `sources_tcestats_multi_sector` to include the URLs of the new TCE `csv` files at: https://archive.stsci.edu/tess/bulk_downloads/bulk_downloads_tce.html .
    - update `sources_dv_sh_single_sector` and `sources_dv_sh_multi_sector` to include the URLs of the new DV download `sh` files at: https://archive.stsci.edu/tess/bulk_downloads/bulk_downloads_ffi-tp-lc-dv.html .

2. In `tess_spoc_fast_spec.py` (TESS-SPOC),
    - update `sources_dv_sh_single_sector` and `sources_dv_sh_multi_sector` to include the URLs of the new DV download `sh` files at: https://archive.stsci.edu/hlsp/tess-spoc .

3. Update the database:

```shell
python -m tess_dv_fast.tess_dv_fast_build --update --minimal_db
python -m tess_dv_fast.tess_spoc_dv_fast_build --update
```

## Deploying the app to cloud environments

- Instructions for [Google Cloud Run deployment](src/python_gcloud/README.md).
