tessapps 0.1.1__tar.gz

tessapps-0.1.1/.gitignore

@@ -0,0 +1 @@
+dist/

tessapps-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Leonidas Liponis
+
+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.

tessapps-0.1.1/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.1
+Name: tessapps
+Version: 0.1.1
+Summary: TESS Aperture Photometry Pollution eStimator
+Author-email: Leonidas Liponis <leolip128@proton.me>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: astropy
+Requires-Dist: astroquery
+Requires-Dist: lightkurve
+
+TESS Aperture Photometry Pollution eStimator
+

tessapps-0.1.1/README.md

@@ -0,0 +1 @@
+TESS Aperture Photometry Pollution eStimator

tessapps-0.1.1/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "tessapps"
+authors = [{name = "Leonidas Liponis", email = "leolip128@proton.me"}]
+license = {file = "LICENSE"}
+classifiers = ["License :: OSI Approved :: MIT License"]
+dynamic = ["version", "description"]
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["numpy", "scipy", "matplotlib", "astropy", "astroquery", "lightkurve"]
+
+[project.scripts]
+tapps = "tapps.main:main"
+
+[tool.flit.module]
+name = "tapps"

tessapps-0.1.1/src/tapps/__init__.py

@@ -0,0 +1,3 @@
+"TESS Aperture Photometry Pollution eStimator"
+
+__version__ = "0.1.1"

tessapps-0.1.1/src/tapps/__main__.py

@@ -0,0 +1,2 @@
+from tapps.main import main
+if __name__ == "__main__": main()

tessapps-0.1.1/src/tapps/data_to_contamination.py

@@ -0,0 +1,53 @@
+import numpy as np
+from scipy import integrate
+
+def pixels_in_mask(tpf):                                                # this function returns an array that contains all pixels used for photometry
+    raw_pixels_in_mask = np.where(tpf.pipeline_mask == True)            # it finds the pixel coordinates
+    return np.array([raw_pixels_in_mask[0], raw_pixels_in_mask[1]]).T   # then pairs them up in this way
+
+def gaussian(x, y, area, sigma): return area / (2 * np.pi * sigma**2) * np.exp(-(x**2 + y**2) / (2 * sigma**2)) # the standard 2D gaussian function
+
+def background_gaussian_field(tpf, data, sigma):      # this function calculates the ideal gaussian field comprised of all stars' contributions
+    pixels = pixels_in_mask(tpf)        # these are the pixels of interest: all calculations are done for these only
+    field = np.zeros((tpf.shape[1:]))   # the field is defined as an 11x11 matrix of zeros, filled iteratively
+    error = np.zeros_like(field)        # its error is also the same matrix
+    total_error_squared = 0.0           # total error is initialized at 0 and grows after each star
+
+    for star in data[1:]:                                   # data[0] is the target star, since the data is sorted. data[1:] has all other stars
+        total_star_flux = 0.0                               # this will accumulate the flux of each pixel in the mask
+        for i, j in pixels:                                 # i -> y, j -> x. the integration below is done for the entirety of the pixel
+            gauss, _ = integrate.dblquad(lambda y, x: gaussian(x - star["x"], y - star["y"], star["flux"], sigma), j - 0.5, j + 0.5, i - 0.5, i + 0.5)
+            field[i, j] += gauss                                            # the field grows in this pixel by the flux of this specific star
+            error[i, j] += (star["flux_er"] * (gauss / star["flux"])) ** 2  # the error grows too, by this formula (error propagation)
+            total_star_flux += gauss                                        # the total flux of this star accumulates the gauss area from each pixel
+        total_error_squared += (star["flux_er"] * total_star_flux / star["flux"]) ** 2  # the full error has a similar formula
+    return field, np.sqrt(error), field.sum(), np.sqrt(total_error_squared)             # also returns the total flux of background stars (with error)
+
+def target_gaussian_field(tpf, data, sigma):    # this function returns the gaussian field of the target star in the aperture pixels
+    star = data[0]                              # it is the same function as 'background_gaussian_field', without the loop for each star
+    field = np.zeros((tpf.shape[1:]))
+    error = np.zeros_like(field)
+    total_star_flux = 0.0
+
+    for i, j in pixels_in_mask(tpf):
+        gauss, _ = integrate.dblquad(lambda y, x: gaussian(x - star["x"], y - star["y"], star["flux"], sigma), j - 0.5, j + 0.5, i - 0.5, i + 0.5)
+        field[i, j] += gauss
+        error[i, j] += (star["flux_er"] * (gauss / star["flux"])) ** 2
+        total_star_flux += gauss
+    total_error = star["flux_er"] * total_star_flux / star["flux"]
+    return field, np.sqrt(error), field.sum(), total_error  # returns the field, the field of errors in each pixel, the total flux, and its error
+
+def contribution_calculator(tpf, data, sigma, digits, result):      # this function calculates the fields for the target star and all background stars
+    background_field, background_field_error, background_total_flux, background_total_error = background_gaussian_field(tpf, data, sigma)
+    target_field, target_field_error, target_total_flux, target_total_error = target_gaussian_field(tpf, data, sigma)
+
+    background_contribution = background_total_flux / (background_total_flux + target_total_flux)   # the observed field is ideally the sum of the two
+    target_contribution = target_total_flux / (background_total_flux + target_total_flux)           # in reality both will be biased in some way
+
+    error_term = 1 / (background_total_flux + target_total_flux)**2
+    total_error = error_term * np.sqrt((background_total_flux * target_total_error)**2 + (target_total_flux * background_total_error)**2)
+
+    if result:
+        print(f"The target star contributes ({100 * target_contribution :.{digits}f} ± {100 * total_error :.{digits}f})% of the total flux.")
+
+    return np.round(target_contribution, digits + 2), np.round(total_error, digits + 2)

tessapps-0.1.1/src/tapps/main.py

@@ -0,0 +1,68 @@
+import warnings
+from erfa import ErfaWarning
+warnings.filterwarnings("ignore", category=ErfaWarning)
+warnings.filterwarnings("ignore", message=".*tpfmodel submodule is not available.*")
+
+import lightkurve as lk
+import numpy as np
+from scipy import integrate
+import astropy.units as u
+from astropy.table import Table
+from astropy.time import Time
+from astropy.coordinates import SkyCoord
+from astropy.wcs.utils import proj_plane_pixel_scales
+from astroquery.mast import Catalogs
+
+import argparse
+import matplotlib.pyplot as plt
+from pathlib import Path
+
+import tapps.tpf_to_nearby_stars as ttns
+import tapps.nearby_stars_to_data as nstd
+import tapps.data_to_contamination as dtc
+
+def run(tpf, pixel_overshoot, sigma, digits, info, result, plot, output_directory):
+    if tpf is None: tpf = lk.search_targetpixelfile("HAT-P-1", mission="TESS", sector=84, exptime=120).download()
+    stars = ttns.tpf_to_nearby_stars(tpf, pixel_overshoot, info)
+    data = nstd.data_builder(tpf, stars)
+    target_contribution, total_error = dtc.contribution_calculator(tpf, data, sigma, digits, result)
+
+    print(data[:6])
+
+    if plot:
+        fig, ax = plt.subplots(figsize=(8, 8))
+        tpf.plot(ax=ax, aperture_mask=tpf.pipeline_mask)
+        text = f"Target star contributes ({100 * target_contribution :.{digits}f} ± {100 * total_error :.{digits}f})% of the total flux"
+        fig.text(0.5 , 0.01, text, ha="center", fontsize=14)
+        out_path = Path(f"{output_directory}/TIC_{tpf.targetid}.png")
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        fig.savefig(out_path, dpi=200, bbox_inches="tight")
+        plt.show
+    return [float(target_contribution), float(total_error)]
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tpf", default=None)
+    parser.add_argument("--overshoot", type=float, default=1)
+    parser.add_argument("--sigma", type=float, default=1)
+    parser.add_argument("--digits", type=int, default=3)
+    parser.add_argument("--info", dest="info", action="store_true")
+    parser.add_argument("--result", dest="result", action="store_true")
+    parser.add_argument("--plot", dest="plot", action="store_true")
+    parser.add_argument("--out_dir", default="tapps-results")
+    args = parser.parse_args(argv)
+    run(args.tpf, args.overshoot, args.sigma, args.digits, args.info, args.result, args.plot, args.out_dir)
+
+# tpf_file = lk.search_targetpixelfile("HAT-P-1", mission="TESS", sector=84, exptime=120).download()
+# tpf_file = lk.search_targetpixelfile("WASP-12", mission="TESS", sector=20, exptime=120).download()
+# tpf_file = lk.search_targetpixelfile("TOI-122", mission="TESS", exptime=1800).download()
+# tpf_file = lk.search_targetpixelfile("TOI-122", mission="TESS")[-1].download()
+# tpf_file = lk.search_targetpixelfile('20:45:09.5323 -31:20:27.241')[4].download()  # AUMic
+# tpf_file = lk.search_targetpixelfile('55 Cnc')[6].download()
+# tpf_file = lk.search_targetpixelfile('CoRoT 1')[1].download()
+# tpf_file = lk.search_targetpixelfile('19:24:15.2868 +00:44:46.003')[1].download()   # CoRoT 10
+
+# tpf_file.plot(aperture_mask=tpf_file.pipeline_mask)
+# run(tpf_file, result=True, plot=True)
+
+# main()

tessapps-0.1.1/src/tapps/nearby_stars_to_data.py

@@ -0,0 +1,48 @@
+import numpy as np
+import astropy.units as u
+from astropy.table import Table
+from astropy.time import Time
+from astropy.coordinates import SkyCoord
+
+def stars_to_raw_data(stars):          # this function extracts TIC, positions, Tmag, Tmag_error from the mast catalog
+    def converter(name): return np.asarray(stars[name].filled(np.nan), dtype=float)
+
+    tic = np.asarray(stars["ID"], dtype=np.int64)                       # the tess id for each star
+    ra = converter("ra") * u.deg                                        # it needs degrees as a unit for SkyCoords
+    dec = converter("dec") * u.deg                                      # degrees here as well
+    pm_ra_cosdec = np.nan_to_num(converter("pmRA")) * u.mas / u.yr      # mas = milli-arcseconds per year (tess gives these units)
+    pm_dec = np.nan_to_num(converter("pmDEC")) * u.mas / u.yr           # the above line has cos(dec) to get the actual angular speed across the sky
+    time = Time(2000.0, format="jyear")                                 # the stars have the listed coordinates in this date exactly
+    tmag = converter("Tmag")                                            # Tess magnitude, in order to find electrons
+    tmag_error = converter("e_Tmag")                                    # error in Tess magnitude
+
+    positions = SkyCoord(ra=ra, dec=dec, pm_ra_cosdec=pm_ra_cosdec, pm_dec=pm_dec, obstime=time)    # these are the positions in the past
+    return tic, positions, tmag, tmag_error
+
+def flux_calculator(tmag, tmag_error):                      # this function finds the flux from Tmag for all stars at once
+    tess_zero_point, m = 15000, 10                          # The TESS cameras create 15,000 e−/s for a star of m = 10, as per the handbook
+    flux = tess_zero_point * 10 ** (-0.4 * (tmag - m))      # this is the standard formula for flux in e−/s
+    flux_error = flux * 0.4 * np.log(10) * tmag_error       # derived from error propagation
+    return flux, np.nan_to_num(flux_error)                  # these are arrays, containing flux for every star
+
+def data_builder(tpf, stars):                                   # this function uses the above 2 functions to make a table containing relevant data
+    tic, positions, tmag, tmag_error = stars_to_raw_data(stars)     # first it calculates the stars' (ra, dec) positions and extracts Tmag
+    positions = positions.apply_space_motion(new_obstime=Time(tpf.time.mean()))     # these are the positions at the time of observation
+    flux, flux_error = flux_calculator(tmag, tmag_error)                            # then it finds the flux of each star
+    x, y = tpf.wcs.world_to_pixel(positions)                                        # and their positions in pixels
+
+    data = Table({"TIC": tic, "Tmag": tmag, "Tmag_er": tmag_error, "flux": flux, "flux_er": flux_error, "x": x, "y": y})    # build the table
+    data["Tmag"].info.format = ".2f"        # these are custom formatting options
+    data["Tmag_er"].info.format = ".3f"     # so that it appears nice when printing the data
+    data["flux"].info.format = ".2f"        # no rounding is applied to any number, only when showing them
+    data["flux_er"].info.format = ".2f"     # data contains for each star: TIC, Tmag and flux (with errors), pixel positions (without errors)
+    data["x"].info.format = ".2f"           # x and y pixel positions are considered not to have error because it is too small to be important
+    data["y"].info.format = ".2f"           # and would make error propagation difficult when calculating the gaussians
+
+    print(f"{(~np.isfinite(data["flux"])).sum()} of {len(data)} stars removed (NaN or infinite flux)")
+
+    data = data[np.isfinite(data["flux"])]                      # filter out NaN cases, substitute with 0 (where there are no values for Tmag, rare)
+    is_target = np.asarray(data["TIC"]) == int(tpf.targetid)    # get the target star's position in the list
+    data = data[np.lexsort((data["Tmag"], ~is_target))]         # sort by ascending magnitude (bright to faint), with the target star always first
+    assert data[0]["TIC"] == int(tpf.targetid), "Error: Target star missing from data"      # hasn't happened yet
+    return data

tessapps-0.1.1/src/tapps/tpf_to_nearby_stars.py

@@ -0,0 +1,38 @@
+import numpy as np
+import astropy.units as u
+from astropy.wcs.utils import proj_plane_pixel_scales
+from astroquery.mast import Catalogs
+
+def tpf_to_nearby_stars(tpf, pixel_overshoot, info):        # this function takes a tpf file and returns the search radius
+    pixels_y, pixels_x = tpf.shape[1:]                      # it should return 11x11 (pixels). for tpf files, y is first, x is second
+    pixels_max = np.maximum(pixels_x, pixels_y)             # in case it doesn't, take the bigger value of the two
+    diagonal = pixels_max * np.sqrt(2)                      # the diagonal of the 11x11 square (or the square of the biggest pixel length)
+    sharp_radius_p = diagonal / 2                           # the radius of the circumscribed circle around the square, in pixels
+    safe_radius_p = sharp_radius_p + pixel_overshoot        # this is bigger to account for projection errors and distortions, to get more stars
+
+    pixel_scale_x, pixel_scale_y = proj_plane_pixel_scales(tpf.wcs)             # pixel scale from wcs (coordinates). x is first, y is second
+    pixel_scale = (pixel_scale_x + pixel_scale_y)/2                             # the average should suffice as an approximation
+    scale_difference = np.abs((pixel_scale_x - pixel_scale_y)/2) / pixel_scale  # here is the relative difference between the scales
+    safe_radius_d = safe_radius_p * pixel_scale * u.deg                         # convert to degrees using pixel scale
+
+    center_x = (pixels_x - 1) / 2       # the center of the image (x coordinate): -1 because index starts at 0
+    center_y = (pixels_y - 1) / 2       # the center of the image (y coordinate)
+    center = tpf.wcs.pixel_to_world(center_x, center_y)
+
+    if info: print(f"""    TICID: {tpf.targetid}
+    Time:
+        Observation start and stop time in TJD: {tpf.get_header(ext=0)["TSTART"]:.3f}, {tpf.get_header(ext=0)["TSTOP"]:.3f}
+        Observation start and stop time in UTC: {tpf.get_header(ext=0)["DATE-OBS"]}, {tpf.get_header(ext=0)["DATE-END"]}
+        Observed for {tpf.get_header(ext=0)["TSTOP"] - tpf.get_header(ext=0)["TSTART"]:.3f} days
+    Place:
+        Center of the {pixels_x} by {pixels_y} frames is at RA: {center.ra:.3f}, DEC = {center.dec:.3f}
+        The image spans {pixels_x * pixel_scale_x:.3f} by {pixels_y * pixel_scale_y:.3f} degrees on the sky
+    Results:
+        The background stars in the images will be searched in a circle of radius {safe_radius_d:.3f} from the center
+        This circle circumscribes the square image, and has a {safe_radius_p / sharp_radius_p * 100:.2f}% bigger radius than needed
+        The circle covers {(np.pi * safe_radius_p**2 - pixels_x * pixels_y) / (pixels_x * pixels_y) * 100:.1f}% more area around the square
+    Errors:
+        Pixel scale is {pixel_scale:.3f} deg/pixel with {scale_difference * 100:.2f}% scale difference
+        The error is due to differences in horizontal ({pixel_scale_x:.5f}) and vertical ({pixel_scale_y:.5f}) pixel scales
+        If the error is more than 5%, then increase 'pixel_overshoot' to make sure the search finds enough stars""")
+    return Catalogs.query_region(center, radius=safe_radius_d, catalog="TIC")