Basic outline for new sky catalog search function

[rebekah9969]

This PR will create a new function called get_skycatalog.

This is very initial code and the function will likely be captured within another file or function like search.py
LOTS OF REFORMATTING

The goal of this function is to provide the user with a list of stars/objects within a defined region around a requested target.

The returned list contains the proper motion corrected R.A and Dec. positions of the objects in addition to several other parameters.

This tool should be applied to the following TESS products

• LightCurve Objects
• TargetPixelFile Objects
• TESSCut Objects

Eventual use case will be:
mytpf.get_skycatalog()
Returning a table of objects and their parameters.

Several adjustments to be made inclide

• A check to make sure that the file type input is correct i.e., LC, TPF, TESSCut
• Adjust the search region to be by default slightly larger than the input TPF or TESSCut size
• Make the catalog search conduct a box search instead of a radius search
• Based on the mission keyword make the catalog search be either TIC or KIC etc

[christinahedges]

This is looking dangerously close, you need to add

• An entry to the changelog
• Update the API reference in the docs folder (docs/source/reference/targetpixelfile.rst) to ensure that your new functionality shows up
• Optional; add the functionality to a tutorial page

[rebekah9969]

Created a GitHub gist notebook demonstrating how this works.
https://gist.github.com/rebekah9969/3ba956149325acab679e66ae39babb56

[rebekah9969]

The following warning appears when running
tpf.skycatalog
ErfaWarning: ERFA function "pmsafe" yielded 472 of "distance overridden (Note 6)" warnings.warn('ERFA function "{}" yielded {}'.format(func_name, wmsg),

Looking at https://pyerfa.readthedocs.io/en/latest/api/erfa.pmsafe.html note 6

"6) An extremely small (or zero or negative) parallax is overridden
to ensure that the object is at a finite but very large distance,
but not so large that the proper motion is equivalent to a large
but safe speed (about 0.1c using the chosen constant). A warning
status of 1 is added to the status if this action has been taken."

I think that this happens because some stars have zero proper motion - these are listed as "--" in the catalog and as such converted into 0.0 to preserve the original R.A and Dec.
I think that this is probably something we can ignore and catch.

[orionlee]

Some comments from using and implementing tpf.interact_sky().

[orionlee]

A style comment: exposing the list of neighboring TICs/KICs/EPICs via a property tpf.skycatalog could be somewhat misleading from programming point of view.

Conventionally, data exposed via properties tend to be in-memory or easily computed. The tpf.skycatalog here is much more involved.

An alternative is to provide it as a method tpf.query_skycatalog(...), with parameters' default values do what the property currently does.

[rebekah9969]

@christinahedges what do you think with regards to this?

[orionlee]

For the use cases for supporting contamination calculation / PRF, etc,

1. it might make sense to let users easily customize the catalog to
   a. include stellar companion identified in follow up, and/or
   b. exclude duplicates, artifacts, etc.
   One way to do it is through a method tpf.query_skycatalog(...), something like the following:

# add a stellar companion identified in follow up
cat = tpf.query_skycatalog(additions=[
    dict(id="stellar companion 1", sep=0.3*u.arcsec, angle=Angle(131.3 * u.deg), delta_mag=1),
])

# TIC 237184773 is split to 1715469662, 1715469667
cat = tpf.query_skycatalog(subtractions=[237184773])

2. Are we concerned about the cases a bright star that is just outside of the tpf, but it significantly affects many pixels inside the tpf?
   This is probably too much of an edge case. I suppose users can workaround it somewhat easily if they can add additional stars, say, via tpf.query_skycatalog(additions=...).

[orionlee]

I believe the relative flux calculation is buggy. np.exp() should probably be replaced by 10 **.

E.g., assume the target star is of magnitude 10, the nearby star is of magnitude 9, i.e., the relative flux is about ~2.512.

np.exp((9 - 10) / -2.5) : 1.492
10 ** ((9 - 10) / -2.5) : 2.512