diff --git a/docs/observation.md b/docs/observation.md index e2dd4fb..3796f3c 100644 --- a/docs/observation.md +++ b/docs/observation.md @@ -10,7 +10,7 @@ FOXSI-4 was launched from the Poker Flat Research Range in Alaska on April 17, 2 *Relevant for functions with inputs like: `time_range`.* -The time range is important for calculating the atmospheric transmission, which is a key component of the ARF. Depending on the objectives of the analysis, the user may select the appropriate time range using the information provided below: +The time range is important for calculating the atmospheric transmission (see the [Time ranges and the atmospheric response](https://foxsi.github.io/response-tools/auto_examples/plot_atmospheric_response.html#sphx-glr-auto-examples-plot-atmospheric-response-py) example), which is a key component of the ARF. Depending on the objectives of the analysis, the user may select the appropriate time range using the information provided below: **Observation time intervals with stable pointing for more than a few seconds:** diff --git a/docs/response_guide.md b/docs/response_guide.md index 35a3b70..2c32acc 100644 --- a/docs/response_guide.md +++ b/docs/response_guide.md @@ -28,7 +28,7 @@ For a coded runthrough of creating an ARF, see the [Create an ARF from scratch]( ## What is a redistribution matrix function/file (RMF)? -The RMF is a matrix that contains the energy redistribution information of the detector, this is the photon-to-count conversion probability. An incoming photon of energy $\epsilon$ can be detected by the telescope's sensor as a count with an energy $\lesssim\epsilon$ (say, $E$) due to scattering, detection efficiency, and energy resolution. Therefore, the energies we are interested in are the ones defined for the RMF creation. I.e., the defined photon energies (input axis) controls the energies the ARF and photon models should be evaluated and the defined count bin energies (observable bins or output axis) controls the binning of the observed data. +The RMF is a matrix that contains the energy redistribution information of the detector, this is the photon-to-count conversion probability. An incoming photon of energy $\epsilon$ can be detected by the telescope's sensor as a count with an energy $\lesssim\epsilon$ (say, $E$) due to scattering, detection efficiency, and energy resolution. Therefore, the energies we are interested in are the ones defined for the RMF creation. I.e., the defined photon energies (input axis) control the energies of the ARF and are also the energies at which to evaluate any photon models; whereas, the defined count bin energies (observable bins or output axis) control the binning of the observed data. Example RMFs for the CdTe and CMOS can be seen below (see the [Example FOXSI-4 RMFs](https://foxsi.github.io/response-tools/auto_examples/plot_rmf_examples.html#sphx-glr-auto-examples-plot-rmf-examples-py) example in the example gallery) which show the conversion probability of a photon being recorded as detector observable (i.e., either a count with a calibrated energy or DN). The units of a response matrix will be observable/photon (e.g., counts/photon or DN/photon). diff --git a/docs/versions_and_releases.md b/docs/versions_and_releases.md index ff1253d..16555ed 100644 --- a/docs/versions_and_releases.md +++ b/docs/versions_and_releases.md @@ -13,6 +13,32 @@ import response_tools print(response_tools.__version__) ``` +## Version `1.0.3` + +[5 Nov. 2025] Updates to the thermal blanketing transmission files and the atmospheric attenuation file. + +### Attenuation + +- att_thermal_blanket: + - No longer exists. +- att_early_cmos_prefilter + - `v1`: attenuation-data/F4_Blanket_transmission_v1.dat + - Was att_thermal_blanket. +- att_modeled_thermal_blanket + - `v1`: attenuation-data/FOXSI4_theoretical_thermal_blanket_transmission_v1.fits + - Modeled attenuation for the thermal blanket. +- att_measured_thermal_blanket + - `v1`: attenuation-data/FOXSI4_measured_thermal_blanket_transmission_v1.fits + - Measured attenuation for the thermal blanket. +- att_foxsi4_atmosphere: + - `v2`: attenuation-data/FOXSI4_atmospheric_transmission_v2.fits + - Times can now be selected via seconds from launch or in UTC. + +### Example gallery + +- Time ranges and the atmospheric response + - Example added showing how to choose a time range in the code for atmospheric transmissions. + ## Version `1.0.2` [30 Oct. 2025] CdTe detector response files now share the same filename format across different versions and are now all supported in the codebase. @@ -147,3 +173,16 @@ print(response_tools.__version__) - qe_cmos_telescope-1: - `v1`: quantum-efficiency-data/foxsi4_telescope-1_BASIC_sensor_quantum_efficiency_v1.fits - CMOS team prepared detector quantum efficiencies for telescope 1. + +### Example gallery + +- Functions & Outputs + - Shows how to use the functions and their outputs in the package. +- Create an ARF from scratch + - Shows how to compile a telescope ARF from individual components. +- Example FOXSI-4 RMFs + - Shows how to obtain and work with a detector's RMF data-class. +- Generating and plotting ARFs, RMFs, and SRMs + - Shows how to obtain and plot the ARF, RMF, and SRM for Telescope 2. +- Telescope ARFs, RMFs, and SRMs + - Shows a test ``asset`` function to produce a response plot for all of FOXSI-4's telescopes. diff --git a/examples/README.rst b/examples/README.rst index c9268dd..53d83e4 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -21,6 +21,11 @@ Data handling examples * File: ``plot_rmf_examples.py``. * Shows how to obtain and work with a detector's RMF data-class. +* **Time ranges and the atmospheric response** + + * File: ``plot_atmospheric_response.py``. + * Shows how to choose a time range in the code for atmospheric transmissions. + Plotting examples ----------------- diff --git a/examples/plot_atmospheric_response.py b/examples/plot_atmospheric_response.py new file mode 100644 index 0000000..a5fefbb --- /dev/null +++ b/examples/plot_atmospheric_response.py @@ -0,0 +1,324 @@ +""" +Time ranges and the atmospheric response +======================================== + +Script showing how a user might want to consider choosing their analysis +time range in relation to the atmospheric response. + +Check out the `Choosing a time range `__ +section in the online documentation for more details on other +observational time range factors to consider. + +Throughout FOXSI-4's flight, there are different amounts of atmosphere +in the line of sight that will attenuate the incoming X-rays. This +example will show how to get to the atmopspheric response values. + +The example originally followed the plot produced from +``response_tools.attenuation.asset_atm()``. + +*Note:* The atmospheric response is included in the level 3 ARF response +functions that have "flight" in their name. E.g, +``response_tools.responses.foxsi4_telescope0_flight_arf`` which will +require a ``time_range`` input to work. +""" + +from astropy.time import Time +from astropy.visualization import time_support +import astropy.units as u +from matplotlib.dates import DateFormatter +import matplotlib.pyplot as plt +import numpy as np + +from response_tools.attenuation import att_foxsi4_atmosphere + +time_support() + +# %% +# The function documentation +# -------------------------- +# +# The documentation for any function in ``response-tools`` can be found +# online `here `__. +# +# The ``response_tools.attenuation.att_foxsi4_atmosphere`` documentation +# can be found `here `__, +# but we can also use the ``help`` function. + +help(att_foxsi4_atmosphere) + +# %% +# Using the function +# ------------------ +# +# Here it is seen the function would like energies and a time range. A +# user can also see there are some helpful time markers like the observation +# start (shutter door open) and observation end (shutter door closed). +# Notice these times are slightly early and late of the first and last +# time interval shown in the `Choosing a time range `__ +# table, respectively. +# +# Before getting into time ranges, a user might want to only sample one +# energy, or several, and inspect the time profile of the attenuation. +# +# To get all times back from the function, specific times don't need to +# known. The function will return all times if ``numpy.nan`` is passed +# (but it still needs to be unit-aware). +# +# So let's get the atmsopheric transmission at 1 keV for the full +# flight: + +energy0, time0 = [1]<`__.) +# +# Similar to what was seen for the ``time_range`` input, ``numpy.nan`` +# can be passed (unit-aware). Let's average over the whole time range: + +energy2 = np.nan<eV - Need an array of times included - -> 10,284 entries and t=0 is index `0` while t=100 is index `2000` - -> final time is 100/2000 * 10284 = 514.2 + """ Atmsopheric attenuation from and for FOXSI-4 flight data. Parameters ---------- @@ -456,7 +499,14 @@ def att_foxsi4_atmosphere(mid_energies, time_range=None, file=None): `[numpy.nan, numpy.nan]<>> from astropy.time import Time + >>> import astropy.units as u + # two equivalent calls to the function + # using Astorpy times + >>> a0 = att_foxsi4_atmosphere([np.nan]<>> a1 = att_foxsi4_atmosphere([np.nan]<