TargetList
The target list modules take catalog data from a StarCatalog object and, using additional information and methods from Completeness, OpticalSystem, and ZodiacalLight objects, generate an input target list for a survey simulation. The basic functionality is fully implemented by the TargetList prototype, with other implementations focused on special cases, such as the KnownRVPlanetsTargetList. The end result is an object analogous to the StarCatalog, with target attributes stored in equally sized numpy.ndarrays. Fig. 31 shows the initialization of the TargetList prototype.
flowchart TB
subgraph TLinit["<pre>TargetList.__init__</pre>"]
direction TB
subgraph submods[Instantiate submodules]
direction LR
SM1[StarCatalog]---
SM2[OpticalSystem]---
SM3[ZodiacalLight]---
SM4[PostProcessing]---
SM5[Completeness]
linkStyle 0 stroke-width:0px
linkStyle 1 stroke-width:0px
linkStyle 2 stroke-width:0px
linkStyle 3 stroke-width:0px
end
B0([" "])---B1([Assign reserved keywords to attributes and copy to: <pre>self._outspec</pre>])-->submods
style B0 fill:none,stroke-width:0px
linkStyle 4 stroke-width:0px
subgraph detmode[Identify detection mode]
B3{<pre>int_WA</pre> is None}
B3 -- True --> B4{"<pre>detmode[OWA]</pre>is infinite"}
B4 -- True --> B5("<pre>int_WA = 2*detmode[IWA]</pre>")
B4 -- False --> B6("<pre>int_WA = 1/2 * (detmode[IWA] +
detmode[OWA])</pre>")
B5 & B6-->B7([Assign <pre>int_WA</pre> and <pre>int_dMag</pre> as array attributes])
B3 --> False -->B7
end
submods-->detmode
detmode--> B8[["<pre>self.set_catalog_attributes()</pre> Populates catalog_atts and required_catalog_atts"]]
B8-->B9[["<pre>self.populate_target_list()</pre>Copies catalog_atts from StarCatalog"]]
B9-->B10(["<pre>if self.popStars is not None()</pre>Remove all targets in popStars"])
subgraph fillphot["<pre>self.fillPhotometryVals()</pre>"]
direction TB
subgraph foreachtarg["For Each Target"]
direction LR
B12{"Spectral type
can be determined"}
B12 -- False --> B13{"<pre>self.fillPhotometry</pre> is True
and type can be determined
from other data"}
B13 -- True --> B14{"Target is
White dwarf
or subdwarf"}
B13 -- False --> B15([Drop Target])
B12 -- True --> B14
B14 -- True --> B15
B14 -- False --> B16([Keep Target])
end
B11([" "])---foreachtarg
style B11 fill:none,stroke-width:0px
linkStyle 23 stroke-width:0px
subgraph fillphot2["<pre>if self.fillPhotometry is True</pre>"]
direction LR
B17(["Fill as many missing values as possible for <pre>MV, L, BC, Vmag, Bmag, BV</pre>"])-->
B18(["<pre> if self.fillMissingBandMags is True</pre> Fill as many other band mags as possible"])
end
foreachtarg-->fillphot2
end
B10 --> fillphot
fillphot-->B19[["<pre>self.nan_filter()</pre> Remove targets with NaN in any required_catalog_atts"]]
subgraph othercalcs["Fill Other Target Properties as Needed"]
direction LR
B20[["<pre>self.stellar_Teff()</pre>"]]---
B21[["<pre>self.stellar_mass()</pre>"]]---
B22[["<pre>self.stellar_diameter()</pre>"]]---
B23[["<pre>self.gen_inclinations()</pre>Generate system plane inclination"]]
linkStyle 28 stroke-width:0px
linkStyle 29 stroke-width:0px
linkStyle 30 stroke-width:0px
end
B19-->othercalcs
subgraph calcsatandcutoff["<pre>self.calc_saturation_and_intCutoff_vals()</pre>Calculate saturation and intCutoff delta mags and completeness values"]
direction LR
B240([" "])
style B240 fill:none,stroke-width:0px
subgraph calcsatsub1[" "]
direction TB
B24a[["<pre>self.OpticalSystem.calc_saturation_dMag()</pre>"]]-->
B24b[["<pre>self.Completeness.comp_calc()"]]
end
style calcsatsub1 fill:none,stroke-width:0px
subgraph calcsatsub2[" "]
direction TB
B24c[["<pre>self.OpticalSystem.calc_dMag_per_intTime(intCutoff)</pre>"]]-->
B24d[["<pre>self.Completeness.comp_calc()"]]
end
style calcsatsub2 fill:none,stroke-width:0px
calcsatsub1 --- calcsatsub2
end
othercalcs-->calcsatandcutoff
linkStyle 34 stroke-width:0px
subgraph compcalcs["Completeness Calculations"]
direction LR
B25[["<pre>self.Completeness.target_completeness()</pre>Calculate completeness for each target"]]---
B26[["<pre> self.Completeness.gen_update()</pre>Generate dynamic completeness data"]]
linkStyle 36 stroke-width:0px
end
calcsatandcutoff-->compcalcs
compcalcs--> B27[["<pre> self.filter_target_list()</pre>Apply any other requested filtering"]]
end
Fig. 31 TargetList Prototype __init__.
After parsing keyword inputs and instantiating objects of StarCatalog, OpticalSystem, PostProcessing, ZodiacalLight, and Completeness, the prototype TargetList initialization calls populate_target_list(), which makes StarCatalog attribute property arrays attributes of the TargetList object, fills in missing photometric data (if the fillPhotometry keyword input is set to True), and assigns each target system additional, computed attributes:
The true and approximate stellar mass (attributes
MsEstandMsTrue, respectively) is calculated instellar_mass(). The estimated mass is based on the Mass-Luminosity relationship defined by the user, defaulting to [Henry1993].The inclination of the target system’s orbital plane (attribute
I), calculated ingen_inclinations(). This is used only if thecommonSystemInclinationskeyword input to the SimulatedUniverse is set to True. The inclinations are sinusoidally distributed, within the bounds set by the PlanetPopulation attributeIrange.The \(\Delta\textrm{mag}\) and completeness values associated with the integration cutoff time set in the OpticalSystem and the saturation integration time (i.e., the point at which these values stop changing). For optical systems where there is no fundamental noise floor (i.e., where SNR can always be increased with additional integration time) the saturation \(\Delta\textrm{mag}\) is effectively infinite, but the saturation completeness is limited to the maximum obscurational completeness for that system (see [Brown2005] for details). These values, along with the user-selectable \(\Delta\textrm{mag}_\textrm{int}\) and \(WA_\textrm{int}\) are calculated in
calc_saturation_and_intCutoff_vals(), which calls helper methodscalc_saturation_dMag()andcalc_intCutoff_dMag().The single-visit Completeness (attribute
int_comp) based on \(\Delta\textrm{mag}_\textrm{int}\).
Finally, the whole target list is filtered by filter_target_list(), based on filters selected by input keywords. The default filter set removes binary stars (or stars with close companions), systems where obscurational completeness is zero (i.e., all planets are inside the IWA or outside the OWA), and systems for which the integration cutoff completeness is less than the minComp input value.
Mass-Luminosity Relationship
The Mass Luminsoity Relationship (MLR) gives us an estimate for the mass of stars, which becomes extremely important for later caclulations. When the mass is not given by the catalog, we can estimate it using a variety of different models pre-programmed. Henry1993 is the default model, however there are more options and the ability to framework to add new models is in place.
The first calculation is of the ‘Estimated’ mass, which is the approximate stellar mass according to the model. We impose the standard deviation error described in the publication onto this value to create the ‘True’ mass.
All graphs shown below are using the HWO mission stars catalog with filtering to test the frameworks.
Henry 1993 - This is a great generalist and will output reliable data. The ‘true’ mass is equal to the estimated mass of each star plus a randomly generated Gaussian value with mean 0 and standard deviation of 7% (the error associated with the fit in that publication). (See [Henry1993] for details.)
Fernandes 2021 - This model is much more up to date, but should only be used for FGK stars. Not reliable on other spectral classes. If your catalog only includes these stars or other stars are filtered out at this point, this model is highly suggested. Erorr is described in publication as 3%. (See [Fernandes2021] for details.)
Henry 1993 + 1999 - This includes the paper from Henry 1999, where the caculations for lower mass stars are considered as well. Best generalist when working with a large variety of masses, especially into M dwarf territory. (See [Henry1999] for details.)
Fang 2010 - Great generalist, includes more specific data with a slightly smaller error. Good for all main sequence stars. (See [Fang2010] for details.)
