From 3a7e838b3bb6976bbb7de12ae3f6a59bfe3622ba Mon Sep 17 00:00:00 2001 From: Pedro Bernardinelli Date: Tue, 28 Jan 2025 17:54:57 -0800 Subject: [PATCH] Pedro typos --- docs/advanced.rst | 24 +++++++++++------------ docs/postprocessing.rst | 42 ++++++++++++++++++++--------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/advanced.rst b/docs/advanced.rst index 27fe31ed..d3fdde79 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -9,7 +9,7 @@ Advanced User Features Setting the Random Number Generator Seed --------------------------------------------- -The value used to seed the random number generator can be specified via the **SORCHA_SEED** environmental variable. This allows for ``Sorcha`` to be fully reproducibly run with (if using a bash shell or Z-shell):: +The value used to seed the random number generator can be specified via the **SORCHA_SEED** environmental variable. This allows for ``Sorcha`` to be fully reproducibly run with (if using a bash shell or Z-shell):: export SORCHA_SEED=52 @@ -69,18 +69,18 @@ Applying :ref:`trailing losses` is on by default, but it can be turned Turning off Detection Efficiency/Applying the Fading Function ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :ref:`survey detection efficiency` is disabled if the fading function ([FADINGFUNCTION]) section of the :ref:`configs` is removed or not included (when **fading_function_width** and **fading_function_peak_efficency** have not been provided). +The :ref:`survey detection efficiency` is disabled if the fading function ([FADINGFUNCTION]) section of the :ref:`configs` is removed or not included (when **fading_function_width** and **fading_function_peak_efficiency** have not been provided). Turning Off the Camera Footprint Filter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In rare instances you may need to skip the :ref:`camera footprint filter` and turn it off. This can be done by setting the camera model to none in the field-of-view (FOV) section of the :ref:`configs`:: +In rare instances you may need to skip the :ref:`camera footprint filter` and turn it off. This can be done by setting the camera model to none in the field-of-view (FOV) section of the :ref:`configs`:: [FOV] camera_model = none .. note:: - If you're using ``Sorcha``'s bult-in :ref:`ephemeris generator`, the generator will apply a circular search region around each filed pointing when associating potential input population detections with the survey observations. + If you're using ``Sorcha``'s built-in :ref:`ephemeris generator`, the generator will apply a circular search region around each filed pointing when associating potential input population detections with the survey observations. SNR/Apparent Magnitude Filters @@ -95,7 +95,7 @@ below a user-defined SNR threshold; or the magnitude limit, to remove all observ of objects above a user-defined **trailed source magnitude** threshold. **These filters are applied before the detection efficiency (fading function) is applied in** ``Sorcha``. -The SNR filter which will remove synthetic observations that are less than a user-supplied SNR limit, To implement the SNR limit (in this example to keep synthetic observations of input objects with a SNR > =2) include the following in the config file:: +The SNR filter which will remove synthetic observations that are less than a user-supplied SNR limit, To implement the SNR limit (in this example to keep synthetic observations of input objects with a SNR > =2) include the following in the config file:: [EXPERT] SNR_limit = 2.0 @@ -109,7 +109,7 @@ To implement the magnitude limit (remove detections of objects fainter than 22 m Only one of these filters may be implemented at once. .. seealso:: - We have an `example Jupyter notebook `_ demonstrating how these filters work within ``Sorcha``. + We have an `example Jupyter notebook `_ demonstrating how these filters work within ``Sorcha``. Faint Object Culling Filter @@ -120,7 +120,7 @@ within the LSST before ephemeris generation begins. This has the benefit of pote speeding up simulations by removing the overhead of ephemeris generation for these unobservable objects. -The filter calculates a maximum apparent trailed source magnitude in each survey observing filter (with any relevant +The filter calculates a maximum apparent trailed source magnitude in each survey observing filter (with any relevant activity or light curve brightness modifiers) per object, and checks if all of them are brighter than 2 + the faintest survey observation per respective filter (as obtained from the pointing database). If the object is fainter in **all** filters, then it is dropped and not simulated further. @@ -146,7 +146,7 @@ To implement the faint object culling filter, include the following in the :ref: Modifying the Ephemeris Generator Interpolation -------------------------------------------------- -A user can update the number of sub-intervals for the Lagrange ephemerides interpolation used within ``Sorcha``'s internal ephemeris generator. By default this value is set to **101**, but the user can update it to a different value. 101 works for most orbits, but it may be worth exploring using a different value if you're modeling Earth impactors and very close Near-Earth Objects (NEOs). To change the number of sub-intervals, **ar_n_sub_intervals** variable is added to the ([SIMULATION]) section:: +A user can update the number of sub-intervals for the Lagrange ephemerides interpolation used within ``Sorcha``'s internal ephemeris generator. By default, this value is set to **101**, but the user can update it to a different value. 101 works for most orbits, but it may be worth exploring using a different value if you're modeling Earth impactors and very close Near-Earth Objects (NEOs). To change the number of sub-intervals, **ar_n_sub_intervals** variable is added to the ([SIMULATION]) section:: [SIMULATION] ar_n_sub_intervals = 122 @@ -159,7 +159,7 @@ A user can update the number of sub-intervals for the Lagrange ephemerides inter Specifying Alternative Versions of the Auxiliary Files Used in the Ephemeris Generator ----------------------------------------------------------------------------------------- -For backwards combability and to enable new version of the files to be run as well, users can override the default filenames and download locations of the :ref:`auxiliary files` used by ``Sorcha``'s bult-in :ref:`ephemeris generator`. These :ref:`configs`: variables are added to a new auxiliary ([AUXILIARY]) section:: +For backwards compatibility and to enable new version of the files to be run as well, users can override the default filenames and download locations of the :ref:`auxiliary files` used by ``Sorcha``'s built-in :ref:`ephemeris generator`. These :ref:`configs`: variables are added to a new auxiliary ([AUXILIARY]) section:: [AUXILIARY] @@ -198,7 +198,7 @@ For backwards combability and to enable new version of the files to be run as we You can specify one or any number of the filenames or URLs. .. note:: - If you make changes to the filenames or the download URLs, you'll likely need to first remove meta_kernel.txt from the auxiliary cache (the directory these files are stored in) or specify a different filename name for meta_kernel file in the config file so that it can be rebuilt with the appropriate names. + If you make changes to the filenames or the download URLs, you'll likely need to first remove meta_kernel.txt from the auxiliary cache (the directory these files are stored in) or specify a different filename name for meta_kernel file in the config file so that it can be rebuilt with the appropriate names. .. note:: ``Sorcha`` checks if the :ref:`auxiliary files` exist in the cache directory first before attempting to download any missing files and copies them over into the default filenames. @@ -223,10 +223,10 @@ For example, you could state this in your configuration file to get the object I late in the code, upon output. -Specifying the Decimal Precision for the Photometric and Astrometric Values +Specifying the Decimal Precision for the Photometric and Astrometric Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, no rounding is performed on any of the output values. We recommend that you do not change the decimal place precision and instead leave ``Sorcha`` to output the full value to machine precision, but there may be reasons why you need to reduce the size of the output. +By default, no rounding is performed on any of the output values. We recommend that you do not change the decimal place precision and instead leave ``Sorcha`` to output the full value to machine precision, but there may be reasons why you need to reduce the size of the output. In the [OUTPUT] section of the :ref:`configs`, you can set the decimal precision for the astrometry outputs:: diff --git a/docs/postprocessing.rst b/docs/postprocessing.rst index 722b1811..17159710 100644 --- a/docs/postprocessing.rst +++ b/docs/postprocessing.rst @@ -104,16 +104,16 @@ Accounting for Cometary Activity and Rotational Light Curves ``Sorcha`` has the capability of accounting for the rotational light curve and cometary activity effects on the calculated trailed source magnitude. Further details are available in the :ref:`addons` section. -Applying Trailing Losses and Calculating the PSF Magnigtude +Applying Trailing Losses and Calculating the PSF Magnitude ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once ``Sorcha`` calculates the trailed source magnitude for all potential detections, it then calculates the PSF magnitude for each potential detection accoutning for trailing losses (the effect that the simulated moving object does not have a perfect point-source PSF but is instead elongated due the object's on-sky motion). simulated moving object is moving fast enough in the potential detection's observation, the flux wouldform a trail (elongated source on the image in the direction of the object's motion), changing the apparent magnitude that the survey's source deteciton software will measure as well as decrease the SNR of the trailed soruce magnitude compared to a point source. ``Sorcha``'s trailing loss functions calculates these trailing losses to be used by the rest of the post-processing stage. +Once ``Sorcha`` calculates the trailed source magnitude for all potential detections, it then calculates the PSF magnitude for each potential detection accounting for trailing losses (the effect that the simulated moving object does not have a perfect point-source PSF but is instead elongated due the object's on-sky motion). Simulated moving object is moving fast enough in the potential detection's observation, the flux would form a trail (elongated source on the image in the direction of the object's motion), changing the apparent magnitude that the survey's source detection software will measure as well as decrease the SNR of the trailed source magnitude compared to a point source. ``Sorcha``'s trailing loss functions calculates these trailing losses to be used by the rest of the post-processing stage. -In order to estimate the astrometric and photometric uncertainties and determine the PSF magnitude, \sorcha calculates for each potential detection the equivalent photometric losses caused by the elongated PSFs. \sorcha calculates these losses as magnitude offsets to the trailed source magnitude. ``Sorcha`` uses the trailing loss implementation developed by `Jones et al. (2018) `_ and ther best=fit values for the parameterizations estimated for the LSST. +In order to estimate the astrometric and photometric uncertainties and determine the PSF magnitude, \sorcha calculates for each potential detection the equivalent photometric losses caused by the elongated PSFs. \sorcha calculates these losses as magnitude offsets to the trailed source magnitude. ``Sorcha`` uses the trailing loss implementation developed by `Jones et al. (2018) `_ and their best-fit values for the parametrizations estimated for the LSST. There are two different trailing losses that must be calculated. The first is the trailing loss due to the smearing of the photometric signal over a larger number of pixels than for a point-source PSF, :math:`\Delta m(\textrm{PSF})`, the **PSF trailing loss**. The second is the trailing loss due to the Rubin Data Management software detection algorithm attempting to identify sources on the image using a stellar PSF-like matched filter. We refer to this as the **detection trailing loss**, :math:`\Delta m(\textrm{PSF + detection})`, as it accounts for both the matched filter excluding part of the trail and the SNR losses due to the object's flux being distributed differently than a point source for the pixels that are included by the detection algorithm. -The PSF magnitude (:math:`m_{\textrm{PSF}}`) and the trailed source magnitude (:math:`m_{\textrm{trailed source}}`) are related by: +The PSF magnitude (:math:`m_{\textrm{PSF}}`) and the trailed source magnitude (:math:`m_{\textrm{trailed source}}`) are related by: .. math:: m_{\textrm{PSF}} = m_{\textrm{trailed source}}+\Delta m(\textrm{PSF + detection}) @@ -142,20 +142,20 @@ outer MBAs (main-belt asteroids), a Jupiter Trojan, and inner and outer MBAs (ma .. _randomization: -Applying Photometric and Astrometric Uncertainitie and Randomization +Applying Photometric and Astrometric Uncertainties and Randomization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Real astronomical surveys measure photometry and astrometry that have uncertainities. To better compare to what the survey detected, For each potential detection of the input small body population, ``Sorcha`` applies photometric and astrometric errors that modify the calculated values for the right acension, declination, trailed source magnitude, and PSF masgnitude. ``Sorcha`` computes the uncertainties for each potential detection of the input +Real astronomical surveys measure photometry and astrometry that have uncertainties. To better compare to what the survey detected, for each potential detection of the input small body population, ``Sorcha`` applies photometric and astrometric errors that modify the calculated values for the right ascension, declination, trailed source magnitude, and PSF masgnitude. ``Sorcha`` computes the uncertainties for each potential detection of the input population and use them to characterize a normal distribution with a mean equal to the true value. Full details are provided in Merritt et al. (submitted). .. note:: - As a compromise between low-probability detections and unrealistic magnitude uncertainties producing “fake detections”, by default ``Sorcha`` removes all observations with the trailed source magnitude SNR is less than 2 after calculating the astronometric and photometric uncertainties. + As a compromise between low-probability detections and unrealistic magnitude uncertainties producing “fake detections”, by default ``Sorcha`` removes all observations with the trailed source magnitude SNR is less than 2 after calculating the astrometric and photometric uncertainties. .. warning:: Right now ``Sorcha`` only has functions to compute the photometric and astrometric uncertainties and SNR estimations specifically for Rubin Observatory. .. seealso:: - We have a `Jupyter notebook `__ demonstrating the application of the uncertainities and radnomization of the photometric and astrometric values within ``Sorcha``. + We have a `Jupyter notebook `__ demonstrating the application of the uncertainties and randomization of the photometric and astrometric values within ``Sorcha``. Validating Sorcha's Trailed Source Magnitude Calculations @@ -175,13 +175,13 @@ Cometary Activity or Simulating Other Active Objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A user can use the cometary activity prescriptions available in the `Sorcha add-ons `_ package or add their own class to apply a different comentary activity model in a custom version of the ``Sorcha add-ons`` package. Once the ``Sorcha add-ons`` package is installed, ``Sorcha`` will automatically detect the available plugins and make them available during processing. +A user can use the cometary activity prescriptions available in the `Sorcha add-ons `_ package or add their own class to apply a different cometary activity model in a custom version of the ``Sorcha add-ons`` package. Once the ``Sorcha add-ons`` package is installed, ``Sorcha`` will automatically detect the available plugins and make them available during processing. Cometary Activity Configuration Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Set the **cometary_activity** :ref:`configuration file` file varialble to **none** if you do you want to apply any cometary activity brightness enhancements to ``Sorcha``'s apparent magnitude calculations. +Set the **cometary_activity** :ref:`configuration file` file variable to **none** if you do you want to apply any cometary activity brightness enhancements to ``Sorcha``'s apparent magnitude calculations. .. code-block:: @@ -214,7 +214,7 @@ Rotational Lightcurve Effects Rotational Light Curve Configuration Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A user can use the rotational light curve prescriptions available in the `Sorcha add-ons `_ package or add their own class to apply a different model for rotation effects in a custom version of the ``Sorcha add-ons`` package. Once the ``Sorcha add-ons`` package is installed, ``Sorcha`` will automatically detect the available plugins and make them available during processing. +A user can use the rotational light curve prescriptions available in the `Sorcha add-ons `_ package or add their own class to apply a different model for rotation effects in a custom version of the ``Sorcha add-ons`` package. Once the ``Sorcha add-ons`` package is installed, ``Sorcha`` will automatically detect the available plugins and make them available during processing. .. code-block:: @@ -283,7 +283,7 @@ further from the center of the FOV have shallower depths. Applying the Camera Footprint Filter ----------------------------------------- -Due to the footprint of the LSST Camera (LSSTCam), see the figure below, it is possible that some object detections may be lost in +Due to the footprint of the LSST Camera (LSSTCam), see the figure below, it is possible that some object detections may be lost in gaps between the chips. .. image:: images/Footprint.png @@ -310,10 +310,10 @@ To include this filter, the following options should be set in the :ref:`configs fill_factor = 0.9 .. warning:: - Note that the :ref:`internal ephemeris generator` also uses a circular radius for its search area. To get accurate results, the ephemeris generator search radius radius must be set to be larger than the **circle_radius**. For simulating the LSST, we recommend setting **ar_ang_fov = 2.06** and **ar_fov_buffer = 0.2**. Setting the circle_radius to be larger than the radius used for the ephemeris generation stage will have no effect. + Note that the :ref:`internal ephemeris generator` also uses a circular radius for its search area. To get accurate results, the ephemeris generator search radius must be set to be larger than the **circle_radius**. For simulating the LSST, we recommend setting **ar_ang_fov = 2.06** and **ar_fov_buffer = 0.2**. Setting the circle_radius to be larger than the radius used for the ephemeris generation stage will have no effect. .. tip:: - Applying the fill factor in the circle radius camera filter is option. If the **fill_factor** is not present in the :ref:`configs` then ``Sorcha`` includes all potential detections that land within the circular area. + Applying the fill factor in the circle radius camera filter is option. If the **fill_factor** is not present in the :ref:`configs` then ``Sorcha`` includes all potential detections that land within the circular area. .. tip:: For Rubin Observatory, the circle radius should be set to 1.75 degrees with a fill factor of 0.9 to approximate the detector area of LSSTCam. @@ -327,16 +327,16 @@ To include this filter, the following options should be set in the :ref:`configs Full Camera Footprint ~~~~~~~~~~~~~~~~~~~~~~~ -Using this filter applies a full camera footprint, including chip gaps. The full camera footprint filter figures out which of the possible input population detections (as identified by the ephemeris generation stage/input) for each survey observations land within on the survey camera's detectors. This is the slowest and most accurate version of the footprint filter. The image below shows the full camera footprint filter for the default LSSTCam architecture. +Using this filter applies a full camera footprint, including chip gaps. The full camera footprint filter figures out which of the possible input population detections (as identified by the ephemeris generation stage/input) for each survey observations land within on the survey camera's detectors. This is the slowest and most accurate version of the footprint filter. The image below shows the full camera footprint filter for the default LSSTCam architecture. .. image:: images/full_footprint_filter.png :width: 800 - :alt: Example of how the full camera footprint filter for LSSTCam. Left plot is a full circle of detections, and on the right shows those detections in the sahpe of the LSSTCam detectors where detector gaps can be seen. + :alt: Example of how the full camera footprint filter for LSSTCam. Left plot is a full circle of detections, and on the right shows those detections in the shape of the LSSTCam detectors where detector gaps can be seen. :align: center The effect of the full camera footprint filter on a selection of 100,000 random synthetic sources. -Left: original sources, distributed over a circular FOV (field-of-view) of radius 2.1 degrees. Right: the same sources after running -Sorcha’s full camera footprint filter. The shape of the LSSTCam detector footprint can be seen with the +Left: original sources, distributed over a circular FOV (field-of-view) of radius 2.1 degrees. Right: the same sources after running +``Sorcha``’s full camera footprint filter. The shape of the LSSTCam detector footprint can be seen with the loss of detections in the raft and chip gaps. To use the full camera footprint filter, the following option should be set in the :ref:`configs`:: @@ -349,7 +349,7 @@ To use the full camera footprint filter, the following option should be set in t .. warning:: Note that the :ref:`internal ephemeris generator` uses a circular radius for its search area. To get accurate results, the ephemeris generation search radius must be set to be larger than the **circle_radius**. For simulating the LSST, we recommend setting **ar_ang_fov = 2.06** and **ar_fov_buffer = 0.2**. -Additionally, the camera footprint model can account for the losses at the edge of the CCDs where the detection software will not be able to pick out sources close to the edge. You can add an exclusion zone around each CCD measured in arcseconds (on the focal plane) using the **footprint_edge_threshold** key to the configuration file. An example setup in the :ref:`configs`:: +Additionally, the camera footprint model can account for the losses at the edge of the CCDs where the detection software will not be able to pick out sources close to the edge. You can add an exclusion zone around each CCD measured in arcseconds (on the focal plane) using the **footprint_edge_threshold** key to the configuration file. An example setup in the :ref:`configs`:: [FOV] camera_model = footprint @@ -515,12 +515,12 @@ The user sets what observations from the survey :ref:`pointing` will be used by The first observing filters in the list are separated by a comma. The first observing filter listed should is the main filter that the absolute magnitude is defined for. The :ref:`physical` must have colors relative to the main filter specified for the input small body population. -If the user wants to use a subset of the observations, such as only including observations from the first year of the survey, the user can either modify the :ref:`pointing` or modify the :ref:`pointing` query in the :ref:`configs`. We recommend the user modify the input survey pointing database in this situation. +If the user wants to use a subset of the observations, such as only including observations from the first year of the survey, the user can either modify the :ref:`pointing` or modify the :ref:`pointing` query in the :ref:`configs`. We recommend the user modify the input survey pointing database in this situation. Expert Advanced Post-Processing Features --------------------------------------------------- -Once a user is familiar with ``Sorcha`` and how it works, there are additional :ref:`advanced post-processing tunable features and parameters ` available for the expert user. +Once a user is familiar with ``Sorcha`` and how it works, there are additional :ref:`advanced post-processing tunable features and parameters ` available for the expert user. .. danger:: **With great power comes great responsibility.** If you're new to ``Sorcha`` we **strongly recommend** that you first get familiar with running ``Sorcha`` and how it works before going on to apply any advanced post-processing features as they may produce unintended results. For many use cases, a user will likely not need to touch these parameters within ``Sorcha``.