Merge pull request #22 from pcubillos/docs

Docs
pcubillos · Aug 8, 2024 · 50e270a · 50e270a
2 parents eac312b + ca8b443
commit 50e270a
Show file tree

Hide file tree

Showing 59 changed files with 1,214 additions and 241 deletions.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -8,6 +8,10 @@ include gen_tso/data/nea_data.txt
 include gen_tso/data/tess_data.txt
 include gen_tso/data/target_aliases.txt
 include gen_tso/data/trexolists.csv
+include gen_tso/data/flux_rates_miri.pickle
+include gen_tso/data/flux_rates_nircam.pickle
+include gen_tso/data/flux_rates_niriss.pickle
+include gen_tso/data/flux_rates_nirspec.pickle
 include gen_tso/data/models/.gitignore
 include gen_tso/data/throughputs/*.pickle
 
diff --git a/README.md b/README.md
@@ -1,8 +1,6 @@
 # ✨ Gen TSO ✨
 ### A general ETC interface for time-series observations with JWST
 
-(Nearly at official release...)
-
 <!--
 [![Tests](https://github.com/pcubillos/gen_tso/actions/workflows/python-package.yml/badge.svg?branch=master)](https://github.com/pcubillos/gen_tso/actions/workflows/python-package.yml)
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/gen_tso.svg)](https://anaconda.org/conda-forge/gen_tso)
@@ -26,11 +24,13 @@ To launch the application use this prompt command:
 tso
 ```
 
-### Docs at:
+### Docs:
+
+**Take the tour:**
 
-<https://pcubillos.github.io/gen_tso/>
+[https://pcubillos.github.io/gen_tso/get_started.html](https://pcubillos.github.io/gen_tso/get_started.html)
 
-### Take a look:
+**And take a look:**
 
 <img alt="Gen_TSO" src="https://github.com/pcubillos/gen_tso/blob/master/docs/gen_tso_screenshot.png">
 
@@ -39,3 +39,4 @@ tso
 Comming soon ...
 
 
+
diff --git a/docs/_quartodoc.yml b/docs/_quartodoc.yml
@@ -15,13 +15,32 @@ quartodoc:
   - title: Pandeia
     desc: Pandeia interface functions
     contents:
-    - pandeia_io.make_scene
     - pandeia_io.PandeiaCalculation
+    - pandeia_io.simulate_tso
+    - pandeia_io.make_scene
+    - pandeia_io.exposure_time
+    - pandeia_io.load_sed_list
+    - pandeia_io.find_closest_sed
+    - pandeia_io.extract_sed
     - pandeia_io.exposure_time
+    - pandeia_io.bin_search_exposure_time
+
+  - title: Catalogs
+    desc: Exoplanet and JWST catalogs
+    contents:
+    - catalogs.Catalog
+    - catalogs.Target
+    - catalogs.find_target
+    - catalogs.load_trexolists
+    - catalogs.load_targets
 
-  - title: catalogs
-    desc: Exoplanet catalogs
-    package: gen_tso.catalogs
+  - title: Plotly
+    desc: Plots
     contents:
-    - Catalog
-    - load_trexolists
+    - plotly_io.plotly_depth_spectra
+    - plotly_io.plotly_filters
+    - plotly_io.plotly_sed_spectra
+    - plotly_io.plotly_tso_fluxes
+    - plotly_io.plotly_tso_snr
+    - plotly_io.plotly_tso_spectra
+    - plotly_io.plotly_tso_2d
diff --git a/docs/get_started.qmd b/docs/get_started.qmd
@@ -3,7 +3,11 @@ title: Getting started
 page-navigation: true
 ---
 
-With `Gen TSO` you can produce JWST simulated spectra in as few as four simple steps.
+With `Gen TSO` you can produce JWST simulated spectra in as few as four simple steps.<br>
+Lets start launching the application from the prompt:
+```bash
+tso
+```
 
 ## 1 Select target
 
@@ -41,8 +45,8 @@ The transit or eclipse depth spectrum encodes the core of a science case,
 so this is the one bit of information that a user has to provide.
 In the `Gen TSO` application users can:
 
-- Search and upload specific transit/eclipse depth spectra
-- Pre-load spectra when launching the application
+- Search and [upload transit/eclipse depth spectra](select_planet_model.qmd#uploading-model-files)
+- [Pre-load spectra](select_planet_model.qmd#pre-loading-models-at-launch) when launching the application
 - Use blackbody or flat-transmission spectra for a quick S/N assessment
 - Interactively view and compare spectra in the viewer panel
 
@@ -55,5 +59,39 @@ In the `Gen TSO` application users can:
 
 ## 4 Run Pandeia
 
-TBD
+Now you are ready to simulate a TSO with JWST.  `Gen TSO` provides many
+features to facilitate this step as well. Before a run:
+
+- the text display shows [real-time exposure and saturation](run_pandeia.qmd) values in real time
+- The number of integrations can [automatically match the observation duration](run_pandeia.qmd#exposure-times)
+- [Saturation times](run_pandeia.qmd#saturation) inform on the optimal number of groups for a target/instrument combination
+
+Once a Pandeia simulation has finished:
+
+- The TSO tab shows [interactive displays](run_pandeia.qmd#figures) of the transit/eclipse depth, S/N, and more
+- The *Results* panel shows a [text summary](run_pandeia.qmd#text-outputs) of the simulation, as seen in the official ETC
+- The warnings tab alerts users of potential risks
+- Finally, [TSO runs can be saved](run_pandeia.qmd#collecting-outputs) into Python pickle files for [later use](tutorials_tso_post_processing.qmd)
+
+---
+
+{{< video images/run_pandeia.webm width='800'>}}
+
+---
+
+
+## Bonus: Target Acquisition
+
+Here's one my favorite features.  While `Gen TSO` offers acquisition on a
+science target, sometimes the target is just too bright.  For such cases you can:
+
+- Search for Gaia stellar sources around the science target
+- Use the `ESASky` viewer to guide and select a nearby target
+- Run the acquisition on the nearby target
+
+---
+
+{{< video images/target_acquisition.webm width='800'>}}
+
+
 
diff --git a/docs/images/WASP80b_nircam_flux_rates_tutorial.png b/docs/images/WASP80b_nircam_flux_rates_tutorial.png
diff --git a/docs/images/WASP80b_nircam_transit_tutorial.png b/docs/images/WASP80b_nircam_transit_tutorial.png
diff --git a/docs/images/WASP80b_nirspec_transit_tutorial.png b/docs/images/WASP80b_nirspec_transit_tutorial.png
diff --git a/docs/images/blackbody_model.png b/docs/images/blackbody_model.png
diff --git a/docs/images/bookmark_transit.png b/docs/images/bookmark_transit.png
diff --git a/docs/images/exposure_match.png b/docs/images/exposure_match.png
diff --git a/docs/images/exposure_single.png b/docs/images/exposure_single.png
diff --git a/docs/images/flat_model.png b/docs/images/flat_model.png
diff --git a/docs/images/observation_duration.png b/docs/images/observation_duration.png
diff --git a/docs/images/run_pandeia.webm b/docs/images/run_pandeia.webm
diff --git a/docs/images/run_pandeia_1D_flux_rates.png b/docs/images/run_pandeia_1D_flux_rates.png
diff --git a/docs/images/run_pandeia_1D_snr.png b/docs/images/run_pandeia_1D_snr.png
diff --git a/docs/images/run_pandeia_2D_snr.png b/docs/images/run_pandeia_2D_snr.png
diff --git a/docs/images/run_pandeia_TSO.png b/docs/images/run_pandeia_TSO.png
diff --git a/docs/images/run_pandeia_display.png b/docs/images/run_pandeia_display.png
diff --git a/docs/images/run_pandeia_menu.png b/docs/images/run_pandeia_menu.png
diff --git a/docs/images/run_pandeia_no_warnings.png b/docs/images/run_pandeia_no_warnings.png
diff --git a/docs/images/run_pandeia_results.png b/docs/images/run_pandeia_results.png
diff --git a/docs/images/run_pandeia_saturation.png b/docs/images/run_pandeia_saturation.png
diff --git a/docs/images/run_pandeia_save_file.png b/docs/images/run_pandeia_save_file.png
diff --git a/docs/images/run_pandeia_warnings.png b/docs/images/run_pandeia_warnings.png
diff --git a/docs/images/saturation_danger.png b/docs/images/saturation_danger.png
diff --git a/docs/images/saturation_display.png b/docs/images/saturation_display.png
diff --git a/docs/images/saturation_estimate.png b/docs/images/saturation_estimate.png
diff --git a/docs/images/saturation_full.png b/docs/images/saturation_full.png
diff --git a/docs/images/saturation_warning.png b/docs/images/saturation_warning.png
diff --git a/docs/images/target_acquisition.webm b/docs/images/target_acquisition.webm
diff --git a/docs/images/transit_depth_menu.png b/docs/images/transit_depth_menu.png
diff --git a/docs/images/transit_depth_viewer.png b/docs/images/transit_depth_viewer.png
diff --git a/docs/images/upload_button.png b/docs/images/upload_button.png
diff --git a/docs/images/upload_model.png b/docs/images/upload_model.png
diff --git a/docs/index.qmd b/docs/index.qmd
@@ -39,6 +39,11 @@ for known exoplanets.
 pip install gen_tso
 ```
 
+Then, you can launch the `Gen TSO` application with this prompt command:
+```bash
+tso
+```
+
 More information in the links below.
 
 - [Installation](install.qmd)

diff --git a/docs/install.qmd b/docs/install.qmd
@@ -5,12 +5,27 @@ page-navigation: true
 
 ## 1 Gen TSO Installation
 
-You can install `Gen TSO` from [PyPI](https://pypi.org/project/gen_tso/) with the following command:
+You can install `Gen TSO` from [PyPI](https://pypi.org/project/gen_tso/) with the following command (compatible with Python3.9+):
 
 ```bash
 pip install gen_tso
 ```
 
+Now you are ready to launch the `Gen TSO` application. You can do that with this prompt command:
+```bash
+tso
+```
+
+::: {.callout-note}
+If this is your first time or see any warning,
+you may need to look at the Pandeia installation section below
+:::
+
+::: {.callout-note}
+If you find Numpy compilation issues when instaling `gen_tso`, it's better to install into a freshly new virtual environment, since the new Numpy2 is incompatible with many older installed packages.
+:::
+
+
 <br>
 
 ## 2 Pandeia Engine
@@ -52,7 +67,7 @@ Pandeia also needs some stellar and throughput files to simulate exoplanet spect
 Use this prompt command to automatically check and upload the required atlases
 
 ```bash
-TSO --update_db
+tso --update_db
 ```
 
 ## Manually
@@ -101,7 +116,7 @@ current date, you can run this prompt command:
 
 
 ```bash
-TSO --update_exo
+tso --update_exo
 ```
 
 <br>

diff --git a/docs/run_pandeia.qmd b/docs/run_pandeia.qmd
@@ -0,0 +1,187 @@
+---
+title: Running Pandeia
+page-navigation: true
+---
+
+## Before running
+
+
+### Observation duration
+
+You may want to adjust the observation time in the *Observation* sub-panel
+in the lower left.
+The observation duration is automatically derived from the target's transit
+duration according to the [JWST recommendation for TSOs](https://jwst-docs.stsci.edu/jwst-near-infrared-imager-and-slitless-spectrograph/niriss-example-science-programs/niriss-soss-time-series-observations-of-wasp-39/step-by-step-etc-guide-for-niriss-soss-time-series-observations-of-wasp-39):
+
+$$T_{\rm dur} = T_{\rm start} + T_{\rm settling} + T_{\rm baseline} + T_{\rm transit} + T_{\rm baseline}$$
+
+Where each term is:
+
+- $T_{\rm start} = 1$ hour (the start timing window).
+- $T_{\rm settling} = 0.75$ hour (settling time for telescope systematics).
+- $T_{\rm transit}$ is the duration of the transit/eclipse
+- $T_{\rm baseline}$ is the baseline time before and after transit/eclipse
+
+The baseline time is calculated as
+
+$$ T_{\rm baseline}  = \min(0.5 T_{\rm tran}, 1{\rm h})$$
+
+Surely, users can directly set the observing time or adjust the
+variables for this calculation by clicking the gear icon:
+
+![](images/observation_duration.png){width=400px}
+
+### Exposure times
+
+While you are setting the target and instrumental configuration
+the **Results** text display in the lower left shows you real-time exposure
+and saturation values (i.e., values are instantly updated as you change
+the configuration)
+
+The exposure time shows you the length of the observation according
+to the instrument setting in seconds (e.g., to assess the length of a
+single integration):
+
+![](images/exposure_single.png){height=150px}
+
+And also in hours, to make sure the total TSO observing time is correct.
+to simplify this step, click the *Match obs. duration* switch to
+automatically adjust the integrations to match the *Obs_dur* time:
+
+![](images/exposure_match.png){height=150px}
+
+
+### Saturation
+
+`Gen TSO` provides pre-calculated saturation times for all PHOENIX and
+Kurucz SEDs (when calibrated in the Ks band) for most spectroscopic modes.
+So, users will immediately know how many groups can be set before a given
+saturation threshold.
+
+For other cases (e.g., when providing a custom SED), click the button
+next to *Groups per Integration* to calculate saturation level:
+
+![](images/saturation_estimate.png){width=500px}
+
+The *Results* panel will then show the max. fraction of saturation
+(updated in real-time for the current setting), and the number of groups
+that can be set before exceeding 80% and 100% of saturation at the
+brightest pixel:
+
+![](images/saturation_display.png){width=300px}
+
+
+If you have dangerously high saturation levels, you will see
+the warnings in the *Results* panel:
+
+::: {layout-ncol=2}
+
+![Over 80% saturation](images/saturation_warning.png){width=275px}
+
+![Over 100% saturation](images/saturation_danger.png){width=275px}
+
+:::
+
+
+And if the observation cannot be carried out at all without saturating,
+the panel will show the warnings:
+
+![](images/saturation_full.png){width=550px}
+
+---
+
+## Running Pandeia
+
+Once you are happy with the target and instrument configuration, just click
+the golden **Run Pandeia** button.
+
+::: {.callout-note}
+Different instrument and modes have widely different processing times
+in Pandeia; e.g., the NIRISS/SOSS and NIRCam/Short Wavelength modes will
+take some more seconds than other modes.
+:::
+
+### Figures
+
+When finished, the *TSO* tab in the viewer panel will show the simulated
+transit or eclipse depth spectrum:
+
+![](images/run_pandeia_TSO.png){width=450px}
+
+On this panel, click on the gear icon to open the plots menu
+where you can select plotting options that will update the plot
+in real-time:
+
+- How many collected observations
+- At which resolution sample the noised-up spectrum
+- Wavelength and depth ranges and scales
+- Draw a new realization of the noised-up spectrum
+
+![](images/run_pandeia_menu.png){width=400px}
+
+The first button in this menu also allows you to select and display 
+additional plots:
+
+- 1D flux rate spectra of the source (in and out of transit) an background
+- 1D S/N of the flux spectra 
+- 2D flux rates on the detector
+- 2D S/N at each pixel on the detector
+- 2D detector saturation mask
+- 2D detector map of number of group before saturation
+
+Here are some examples:
+
+::: {layout-nrow=3}
+
+![**1D flux rates** for WASP-80b with NIRSpec/G395H](images/run_pandeia_1D_flux_rates.png){width=500px}
+
+![**1D S/N** ratios for WASP-80b with NIRSpec/G395H (note this is the S/N for the total integration time, whereas the plot above shows the flux rates per second)](images/run_pandeia_1D_snr.png){width=500px}
+
+![**2D S/N** ratios for WASP-80b with NIRSpec/G395H](images/run_pandeia_2D_snr.png){width=500px}
+
+:::
+
+In case of any partial of full saturation, the 1D plots will hightlight the
+affected wavelengths:
+
+![](images/run_pandeia_saturation.png){width=500px}
+
+### Text outputs
+
+When a TSO run has finished, the *Results* panel at the bottom will
+display a summary of the run, similar to what you see in the ETC
+(with some values broken down by in- and out-of-transit):
+
+![](images/run_pandeia_results.png){width=450px}
+
+The *Warnings* tab will indicate whether Pandeia raised any
+warnings or not:
+
+::: {layout-nrow=2}
+
+![No warnings](images/run_pandeia_no_warnings.png){width=500px}
+
+![Warnings are clearly highlighted](images/run_pandeia_warnings.png){width=500px}
+
+:::
+
+
+### Collecting outputs
+
+All *Run Pandeia* calls will be collected in the *Display TSO run* menu
+on the top right panel.  These runs will be sorted by transit, eclipse,
+and aquisition run:
+
+![](images/run_pandeia_display.png){width=550px}
+
+When selecting a run frmo this menu, the target and instrument
+configuration will be updated to that of the run.  Also, the plots in the
+*TSO* tab and the results/warnings tabs below will be updated according
+to the selected run.
+
+The buttons to the right of the menu allow users to delete runs or
+save them to Python pickle files for later use.  Clicking on the *Save TSO*
+button will pop up the following panel where users can set the directory
+and file name for the pickle file:
+
+![](images/run_pandeia_save_file.png){width=550px}