stellarphot — Entry Points#

stellarphot has no command-line scripts. There are three ways in:

  1. The Jupyter launcher — .jp_app_launcher_stellarphot.yaml registers ten notebooks with jupyter-app-launcher, organized into three catalogs.

  2. The public import API — from stellarphot import ... re-exports the core data classes and catalog fetchers.

  3. Direct library use — importing classes such as stellarphot.photometry.AperturePhotometry or stellarphot.transit_fitting.TransitModelFit from subpackages.

Legend — the node types used on this page:

        flowchart LR
    classDef nb fill:#fff8e1,stroke:#f9a825,color:#212121
    classDef widget fill:#fff3e0,stroke:#ef6c00,color:#212121
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#212121
    classDef pkg fill:#e1f5fe,stroke:#0277bd,color:#212121
    classDef file fill:#eceff1,stroke:#90a4ae,stroke-dasharray: 5 5,color:#212121

    l_nb["Launcher notebook"]:::nb
    l_widget["stellarphot widget"]:::widget
    l_api["Importable function<br/>or class (public API)"]:::api
    l_pkg["Import entry point<br/>or settings model"]:::pkg
    l_file["A file on disk"]:::file

    l_nb ~~~ l_widget ~~~ l_api ~~~ l_pkg ~~~ l_file

  • Solid arrows — opens, instantiates, calls, or returns.

  • Dashed arrows — loading from or saving to a file.

Launcher notebooks and the widgets behind them#

Each launcher entry opens a notebook whose first cells instantiate one main widget or function; the diagram shows what each notebook puts on screen.

Arrows: solid = opens / instantiates / calls / returns; dashed = loading from or saving to a file.

        flowchart LR
    classDef nb fill:#fff8e1,stroke:#f9a825,color:#212121
    classDef widget fill:#fff3e0,stroke:#ef6c00,color:#212121
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#212121

    subgraph sg_setup["catalog: Stellarphot setup"]
        direction TB
        nb01["1 - Saveable settings"]:::nb
    end

    subgraph sg_phot["catalog: Stellarphot photometry"]
        direction TB
        nb02["2 - Seeing profile and<br/>comparison stars"]:::nb
        nb03["3 - Review settings"]:::nb
        nb04["4 - Launch photometry"]:::nb
    end

    subgraph sg_tools["catalog: Stellarphot analysis and tools"]
        direction TB
        nb_target["Generate TESS target list"]:::nb
        nb_flux["Calculate relative flux"]:::nb
        nb_calib["Calibrate magnitudes"]:::nb
        nb_fit1["Initial exoplanet model"]:::nb
        nb_fit2["Second exoplanet model fit"]:::nb
        nb_exotic["Exoplanet model fit<br/>with EXOTIC"]:::nb
    end

    review1["ReviewSettings([Camera,<br/>Observatory, PassbandMap])"]:::widget
    cas["ComparisonAndSeeing"]:::widget
    review3["ReviewSettings(7 settings models)"]:::widget
    runner["PhotometryRunner"]:::widget
    tps["TessPhotometrySetup"]:::widget
    addflux["add_relative_flux_column()"]:::api
    calib["transform_to_catalog() and<br/>calculate_transform_coefficients()"]:::api
    fitstack["TessAnalysisInputControls +<br/>TransitModelFit + TransitModelOptions"]:::widget
    exotic["exotic_settings_widget() +<br/>populate_TOI_boxes()"]:::widget

    apphot["AperturePhotometry"]:::api

    nb01 --> review1
    nb02 --> cas
    nb03 --> review3
    nb04 --> runner
    runner -->|"papermill runs<br/>photometry_runner.ipynb"| apphot
    nb_target --> tps
    nb_flux --> addflux
    nb_calib --> calib
    nb_fit1 --> fitstack
    nb_fit2 --> fitstack
    nb_exotic --> exotic

    click nb01 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/01-initial-settings.ipynb" "01-initial-settings.ipynb"
    click nb02 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/02-seeing-and-comparison.ipynb" "02-seeing-and-comparison.ipynb"
    click nb03 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/03-final-review-of-settings.ipynb" "03-final-review-of-settings.ipynb"
    click nb04 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/04-launch-photometry.ipynb" "04-launch-photometry.ipynb"
    click nb_target href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/tess-target-source-list-generator.ipynb" "tess-target-source-list-generator.ipynb"
    click nb_flux href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/relative-flux-calculation.ipynb" "relative-flux-calculation.ipynb"
    click nb_calib href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/transform-to-appas-dr9.ipynb" "transform-to-appas-dr9.ipynb"
    click nb_fit1 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/tess-initial-model-fit.ipynb" "tess-initial-model-fit.ipynb"
    click nb_fit2 href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/tess-second-model-fit.ipynb" "tess-second-model-fit.ipynb"
    click nb_exotic href "https://github.com/feder-observatory/stellarphot/blob/main/stellarphot/notebooks/tess-EXOTIC-fit.ipynb" "tess-EXOTIC-fit.ipynb"
    click review1 href "stellarphot/api_reference.html#module-stellarphot.gui" "custom_widgets.py"
    click cas href "stellarphot/api_reference.html#module-stellarphot.gui" "profile_and_comps.py"
    click review3 href "stellarphot/api_reference.html#module-stellarphot.gui" "custom_widgets.py"
    click runner href "stellarphot/api_reference.html#module-stellarphot.gui" "custom_widgets.py"
    click tps href "stellarphot/api_reference.html#module-stellarphot.gui" "custom_widgets.py"
    click addflux href "stellarphot/api_reference.html#module-stellarphot.differential_photometry" "aij_rel_fluxes.py"
    click calib href "stellarphot/api_reference.html#module-stellarphot.utils" "magnitude_transforms.py"
    click fitstack href "stellarphot/api_reference.html#module-stellarphot.transit_fitting" "transit_fitting/core.py"
    click exotic href "stellarphot/api_reference.html#module-stellarphot.gui.transit_fitting_gui" "gui/transit_fitting_gui.py"
    click apphot href "stellarphot/api_reference.html#module-stellarphot.photometry.photometry" "photometry.py"

What sits behind each widget:

Launcher entry

Notebook

Main objects used

1 - Saveable settings

01-initial-settings.ipynb

ReviewSettings([Camera, Observatory, PassbandMap])

2 - Seeing profile and comparison stars

02-seeing-and-comparison.ipynb

ComparisonAndSeeing (= SeeingProfileWidget + ComparisonViewer)

3 - Review settings

03-final-review-of-settings.ipynb

ReviewSettings over all seven PhotometrySettings component models

4 - Launch photometry

04-launch-photometry.ipynb

PhotometryRunner → papermill → AperturePhotometry

Generate TESS target list

tess-target-source-list-generator.ipynb

TessPhotometrySetup → tess_photometry_setup()

Calculate relative flux

relative-flux-calculation.ipynb

add_relative_flux_column(), FitsOpener, Spinner

Calibrate magnitudes

transform-to-appas-dr9.ipynb

transform_to_catalog(), vsx_vizier(), PhotometryData

Initial / Second exoplanet model

tess-initial-model-fit.ipynb, tess-second-model-fit.ipynb

TessAnalysisInputControls, filter_by_dates(), TransitModelFit, TransitModelOptions, TOI, plot_transit_lightcurve()

Exoplanet model fit with EXOTIC

tess-EXOTIC-fit.ipynb

exotic_settings_widget(), populate_TOI_boxes(), get_values_from_widget(), generate_json_file_name()

Public import API#

Arrows: solid = opens / instantiates / calls / returns; dashed = loading from or saving to a file.

        flowchart LR
    classDef pkg fill:#e1f5fe,stroke:#0277bd,color:#212121
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#212121
    classDef widget fill:#fff3e0,stroke:#ef6c00,color:#212121

    top["from stellarphot import ..."]:::pkg

    subgraph sg_tables["data classes (core.py)"]
        direction TB
        bet["BaseEnhancedTable"]:::api
        pdata["PhotometryData"]:::api
        cdata["CatalogData"]:::api
        sldata["SourceListData"]:::api
    end

    subgraph sg_cats["catalog fetchers (catalogs.py)"]
        direction TB
        apass["apass_dr9()"]:::api
        refcat["refcat2()"]:::api
        vsx["vsx_vizier()"]:::api
    end

    top --> bet
    top --> pdata
    top --> cdata
    top --> sldata
    top --> apass
    top --> refcat
    top --> vsx

    subgraph sg_deep["main subpackage imports"]
        direction TB
        apphot["stellarphot.photometry<br/>AperturePhotometry"]:::api
        tmf["stellarphot.transit_fitting<br/>TransitModelFit"]:::api
        relflux["stellarphot.differential_photometry<br/>calc_aij_relative_flux()"]:::api
        cview["stellarphot.gui<br/>ComparisonViewer, SeeingProfileWidget"]:::widget
        rsw["stellarphot.gui.custom_widgets<br/>ReviewSettings, PhotometryRunner"]:::widget
        waavso["stellarphot.io<br/>write_aavso_extended(), TOI"]:::api
    end

    apphot -->|"returns"| pdata
    relflux -->|"adds column to"| pdata
    cview -->|"writes"| sldata

    click top href "stellarphot/api_reference.html#module-stellarphot" "stellarphot/__init__.py"
    click bet href "stellarphot/api_reference.html#module-stellarphot.core" "core.py"
    click pdata href "stellarphot/api_reference.html#module-stellarphot.core" "core.py"
    click cdata href "stellarphot/api_reference.html#module-stellarphot.core" "core.py"
    click sldata href "stellarphot/api_reference.html#module-stellarphot.core" "core.py"
    click apass href "stellarphot/api_reference.html#module-stellarphot.catalogs" "catalogs.py"
    click refcat href "stellarphot/api_reference.html#module-stellarphot.catalogs" "catalogs.py"
    click vsx href "stellarphot/api_reference.html#module-stellarphot.catalogs" "catalogs.py"
    click apphot href "stellarphot/api_reference.html#module-stellarphot.photometry.photometry" "photometry.py"
    click tmf href "stellarphot/api_reference.html#module-stellarphot.transit_fitting" "transit_fitting/core.py"
    click relflux href "stellarphot/api_reference.html#module-stellarphot.differential_photometry" "aij_rel_fluxes.py"
    click cview href "stellarphot/api_reference.html#module-stellarphot.gui" "gui/"
    click rsw href "stellarphot/api_reference.html#module-stellarphot.gui" "custom_widgets.py"
    click waavso href "stellarphot/api_reference.html#module-stellarphot.io" "io/"

Source: init.py (the re-exports), core.py (the data classes), catalogs.py (the catalog fetchers).

The main programmatic entry point: AperturePhotometry#

AperturePhotometry is configured by a single PhotometrySettings object, usually loaded from photometry_settings.json via PhotometryWorkingDirSettings.

Arrows: solid = opens / instantiates / calls / returns; dashed = loading from or saving to a file.

        flowchart LR
    classDef cls fill:#e1f5fe,stroke:#0277bd,color:#212121
    classDef api fill:#e8f5e9,stroke:#2e7d32,color:#212121
    classDef file fill:#eceff1,stroke:#90a4ae,stroke-dasharray: 5 5,color:#212121

    json["photometry_settings.json"]:::file
    pwds["PhotometryWorkingDirSettings<br/>.load()"]:::cls
    ps["PhotometrySettings"]:::cls

    subgraph sg_parts["component models"]
        direction TB
        cam["camera: Camera"]:::cls
        obs["observatory: Observatory"]:::cls
        apert["photometry_apertures:<br/>PhotometryApertures"]:::cls
        srcloc["source_location_settings:<br/>SourceLocationSettings"]:::cls
        opt["photometry_optional_settings:<br/>PhotometryOptionalSettings"]:::cls
        pbm["passband_map:<br/>PassbandMap or None"]:::cls
        logset["logging_settings:<br/>LoggingSettings"]:::cls
    end

    apinst["AperturePhotometry(settings=...)"]:::api
    apcall["__call__(file_or_directory,<br/>reject_unmatched, object_of_interest)"]:::api
    result["PhotometryData"]:::api

    json -.-> pwds
    pwds --> ps
    ps --> cam
    ps --> obs
    ps --> apert
    ps --> srcloc
    ps --> opt
    ps --> pbm
    ps --> logset
    ps --> apinst
    apinst --> apcall
    apcall --> result

    click pwds href "stellarphot/settings.html#module-stellarphot.settings" "settings_files.py"
    click ps href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click cam href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click obs href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click apert href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click srcloc href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click opt href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click pbm href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click logset href "stellarphot/settings.html#module-stellarphot.settings" "models.py"
    click apinst href "stellarphot/api_reference.html#module-stellarphot.photometry.photometry" "photometry.py"
    click apcall href "stellarphot/api_reference.html#module-stellarphot.photometry.photometry" "photometry.py"
    click result href "stellarphot/api_reference.html#module-stellarphot.core" "core.py"

Source: photometry.py, models.py, settings_files.py, core.py.

AperturePhotometry.__call__ arguments#

Argument

Type / default

Meaning

file_or_directory

str | Path (required)

A single FITS file → single_image_photometry(); a directory → multi_image_photometry() over every matching image

logline

str, "single_image_photometry:"

Prefix for log messages (single-image only)

reject_unmatched

bool, True

Drop sources not detected on every image (multi-image only)

object_of_interest

str, None

Only process files whose OBJECT header matches (multi-image only)

Settings model fields (what the JSON file / widgets configure)#

Model

Fields

Camera

name, data_unit, gain, read_noise, dark_current, pixel_scale, max_data_value

Observatory

name, latitude, longitude, elevation, AAVSO_code, TESS_telescope_code

PhotometryApertures

variable_aperture, radius, gap, annulus_width, fwhm_estimate

SourceLocationSettings

source_list_file, use_coordinates ("sky" or "pixel"), shift_tolerance

PhotometryOptionalSettings

include_dig_noise, reject_too_close, reject_background_outliers, fwhm_method (fit/profile/moments), partial_pixel_method (exact/center/subpixel)

PassbandMap

name, your_filter_names_to_aavso (list of PassbandMapEntry: instrument filter → AAVSO filter)

LoggingSettings

logfile, console_log

PhotometryRunSettings

directory_with_images, photometry_settings_file, reject_unmatched, object_of_interest (parameters papermill passes to photometry_runner.ipynb)

Other notable callable entry points#

Entry point

Module

Key arguments

What’s behind it

source_detection()

stellarphot.photometry

ccd, fwhm, sigma, iters, threshold, find_fwhm

DAOStarFinder + compute_fwhm() → returns SourceListData

calc_aij_relative_flux()

stellarphot.differential_photometry

star_data, comp_stars, in_place, coord_column, star_id_column

AIJ-style comparison-star ensemble flux

TransitModelFit.setup_model() / .fit()

stellarphot.transit_fitting

t0, depth, duration, period, inclination, plus airmass/width/sky detrending

batman transit model + VariableArgsFitter (scipy leastsq)

transform_to_catalog()

stellarphot.utils

photometry table, passband options, fit order

Cross-match to APASS DR9 / RefCat2 and fit calibrated_from_instrumental()

write_aavso_extended()

stellarphot.io

photometry table, destination path, header info

Formats and writes an AAVSO extended-format submission file

tess_photometry_setup()

stellarphot.io

tic_id or TOI_object, overwrite

Queries MAST/ExoFOP, writes TIC-<id>-info.json and TIC-<id>-source-list-input.ecsv

apass_dr9(), refcat2(), vsx_vizier()

stellarphot

a WCS or SkyCoord (+ search radius)

Vizier/XMatch query → CatalogData