Merge pull request #3 from lsst/tickets/SP-2127

tickets/SP-2127: set up basic draft content

Author: MelissaGraham

docs/brokers/index.rst

@@ -0,0 +1,19 @@
+#############
+Alert brokers
+#############
+
+Find more information about the nine alert brokers and how to access them in the `Rubin Observatory For Scientists <https://rubinobservatory.org/for-scientists/data-products/alerts-and-brokers>`_ website.
+
+**Alert broker:** Software systems that ingest and process astronomical alerts from the LSST and other surveys, and serve them to the scientific community.
+
+**Alert filter:** A set of rules that an alert packet either passes or fails.
+E.g., "if brighter than 21st magnitude, and if discovered less than 6 days ago, and if two detections exist, then pass" would be is a very simple filter.
+
+Community filters
+=================
+
+Up to 20 community alert filters will be defined, implemented, validated, and maintained by Rubin staff with input from the broad Rubin science community, and with support from the ANTARES broker.
+
+These community filters will be designed to serve a variety of common time-domain science goals, and lower the barrier to entry into alert-based science.
+
+See the "Roadmap for Community Alert Filters with the ANTARES Broker" `RTN-090 <https://rtn-090.lsst.io/>`_.

docs/cite.rst

@@ -0,0 +1,56 @@
+.. _citedp1:
+
+###########
+How to cite
+###########
+
+`How to cite Rubin Observatory <https://rubinobservatory.org/for-scientists/documentation/cite>`_.
+
+When citing the Prompt Products please reference this paper: |pp_paper|.
+
+For AAS publications please refer to the `facility <https://journals.aas.org/facility-keywords/>`_ as "Rubin:Simonyi".
+
+The `Minor Planet Center <https://minorplanetcenter.net/iau/lists/ObsCodesF.html>`_ has allocated the telescope code X05.
+
+The instrument (LSST Science Camera) can be formally cited as
+
+|lsstcam_doi|
+
+and that page includes additional references describing the camera.
+
+When asked to cite the Prompt Products dataset as a whole please use:
+
+|prompt_doi|
+
+If you only use a specific subset, such as only the alerts, or a specific catalog table or image type, you may cite the DOI explicitly assigned to that subset.
+Each individual page in :doc:`/products/index` includes the relevant DOI.
+
+
+How to refer to single objects
+==============================
+
+If you are referring to individual sources or objects from the Prompt alerts or catalogs, please use the naming convention described here, which has been registered with the International Astronomical Union (IAU) and was developed following `IAU specifications <https://cdsweb.u-strasbg.fr/Dic/iau-spec.html>`_.
+All designations should begin with "LSST-P" (denoting the Legacy Survey of Space and Time, Prompt products), followed by a string that specifies which table the object was obtained from.
+These strings should be "DO" (``DiaObject``), "DS" (``DiaSource``), or "SSO" (``SSObject``).
+Following this table identifier, the (18-digit for all tables except ``SSObject``, for which the ID is 17 digits long) unique numeric identifier from the specified table (i.e., the ``diaObjectId``, ``diaSourceId``, or ``ssObjectId``) should be included.
+The "fields" of the identifier should be separated by dashes, so that the designation appears like "LSST-P-TAB-123456789012345678."
+To summarize, here are examples for objects from each table:
+
+* ``DiaObject``: LSST-P-DO-609788942606140532 (for ``diaObjectId`` 609788942606140532)
+* ``DiaSource``: LSST-P-DS-600359758253260853 (for ``diaSourceId`` 600359758253260853)
+* ``SSObject``: LSST-P-SSO-21163611375481943 (for ``ssObjectId`` 21163611375481943)
+
+All catalog entries reported in Prompt tables will have at least one of these three types of IDs.
+
+Reporting data to external systems
+==================================
+
+When reporting discoveries or followup information from Prompt products to external archives and messaging mechanisms
+(e.g., the IAU Transient Name Service (``https://www.wis-tns.org/``),
+please remember to use "LSSTCam" as the instrument name and "Rubin:Simonyi"
+(or just "Rubin" if that's not available) as the observatory/facility/telescope name,
+and please look for an option to report filters as "LSST" and not "Sloan", despite the similarity in photometric systems.
+
+If you encounter a service where these metadata options are not yet available,
+we ask that you bring this to our attention;
+a post on the "Support" category on https://community.lsst.org/ would be very much appreciated.

docs/doi.png

@@ -4,7 +4,7 @@
 Vera C. Rubin Observatory Prompt Products
 #########################################
 
-**Anticipated release date**: June/July 2025
+**Anticipated start of Alert Production**: July 2025
 
 .. important::
 
@@ -13,18 +13,30 @@ Vera C. Rubin Observatory Prompt Products
 Overview
 ========
 
-General information about LSST prompt data products.
+General information about the observations and data products.
 
 .. toctree::
    :maxdepth: 2
    :titlesonly:
 
    Overview <overview/index>
 
+
+Brokers
+=======
+
+Software to process and serve alerts to scientists.
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   Brokers <brokers/index>
+
 Data products
 =============
 
-Descriptions and schema for the images and catalogs.
+Descriptions and schema for the alert packets, catalogs, and images.
 
 .. toctree::
    :maxdepth: 2
@@ -35,7 +47,7 @@ Descriptions and schema for the images and catalogs.
 Data processing
 ===============
 
-Summaries of the data processing steps that generated the data products.
+Summaries of the data processing steps that generate the data products.
 
 .. toctree::
    :maxdepth: 2
@@ -53,3 +65,14 @@ Tutorials demonstrating how to access and analyze data via the Rubin Science Pla
    :titlesonly:
 
    Tutorials <tutorials/index>
+
+How to cite
+===========
+
+How to cite Rubin Observatory and the Prompt data products.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    cite

docs/index.rst

@@ -1,5 +1,33 @@
-################################
-Overview of prompt data products
-################################
+########
+Overview
+########
+
+General information about the Prompt data products generated by the Rubin Observatory.
+
+.. _overview-comcam:
+
+LSST Science Camera
+===================
+
+All observations were obtained with the LSST Science Camera (LSSTCam).
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    lsstcam
+
+
+.. _overview-observations:
+
+Observations
+============
+
+The observations contributing to Prompt products.
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    observations
 
-General information about prompt data products generated by the Rubin Observatory.

docs/overview/images/sitcomtn-005_figure4.png

@@ -0,0 +1,18 @@
+.. _lsstcam:
+
+###################
+LSST Science Camera
+###################
+
+.. important::
+
+   **Placeholder.** This website is currently under development.
+
+
+|lsstcam_doi|
+
+The LSST Camera is the world's largest digital camera. It has 3.2 Gigapixels over a 9.6 square degree field of view and six optical filters.
+
+For more information about the focal plane, filters, key numbers, and technical references for LSSTCam, visit:
+
+* Rubin Observatory `Instruments <https://rubinobservatory.org/for-scientists/rubin-101/instruments>`_ webpage

docs/overview/index.rst

@@ -0,0 +1,70 @@
+.. _observations:
+
+############
+Observations
+############
+
+.. important::
+
+   **Placeholder.** This website is currently under development.
+
+
+Rubin Observatory is still in the commissioning phase.
+The key objective is to verify the as-built system and to evaluate the operational efficiency.
+The amount of science-grade data collected during commissioning is dependent on several potentially compounding factors, such as resolving emergent technical challenges, calibrating the system performance, weather in Chilean winter, and so on.
+
+
+Science Validation (SV) surveys
+===============================
+
+The baseline Science Validation survey design is described in Section 6 of the
+"Construction Completeness and Operations Readiness Criteria" document,
+`SITCOMTN-005 <https://sitcomtn-005.lsst.io/>`_.
+
+As of Jun 2025, the SV surveys were expected to begin in late Jun 2025.
+It is anticipated that 55% of the night would be available for observations
+(after accounting for, e.g., engineering time, weather).
+SV survey visits will consist of 30-second exposures in *grizy*-bands and 38-second exposures in *u*-band.
+The SV survey design incorporates two components: Deep and Wide.
+
+Deep survey:
+
+* targets four Deep Drilling Fields
+* ELAIS S1, XMM LSS, ECDFS, and EDFSa + EDFSb
+* rapid temporal sampling
+* reaching LSST 10-year depths
+
+Wide survey:
+
+* spans ~160 deg in RA a within 10 degrees of the Ecliptic
+* covers extragalactic and Galactic regions
+* for template generation in support of Prompt Processing
+
+Any "extra" time is planned to be spent broadening the area of sky
+covered by templates for difference imaging.
+
+
+.. figure:: images/sitcomtn-005_figure4.png
+    :name: sitcomtn-005_figure4
+    :alt: A sky map showing the locations of the planned science validation surveys.
+
+    Figure 1: This is Figure 4 from SITCOMTN-005, showing the planned science validation surveys coverage expressed as total number of overlapping visits across the ugrizy bands.
+
+
+
+
+Survey strategy
+===============
+
+Information about the strategy and cadence for the Legacy Survey of Space and Time can be found at `survey-strategy.lsst.io <https://survey-strategy.lsst.io/>`_.
+
+Nightly projection
+------------------
+
+*Placeholder for a future link to a live projection of the LSST scheduler.*
+
+
+Alert stream status
+===================
+
+*Placeholder for a future link to a live dashboard of alert stream status.*

docs/overview/lsstcam.rst

@@ -0,0 +1,12 @@
+.. _alert-gen:
+
+################
+Alert generation
+################
+
+.. important::
+
+   **Placeholder.** Prompt data processing is under construction.
+
+
+This includes the creation of packets from the APDB, and alert distribution to brokers.

docs/overview/observations.rst

@@ -0,0 +1,107 @@
+.. _dia:
+
+###############################
+Difference image analysis (DIA)
+###############################
+
+.. important::
+
+   **Placeholder.** Prompt data processing is under construction.
+
+
+DIA uses the decorrelated `Alard and Lupton (1998) <https://ui.adsabs.harvard.edu/abs/1998ApJ...503..325A/abstract>`_
+image differencing algorithm,
+as described in "Implementation of Image Difference Decorrelation" (`dmtn-021.lsst.io <https://dmtn-021.lsst.io/>`_)
+and in the LSST Science Pipelines documentation for
+the `Alard-Lupton implementation <https://pipelines.lsst.io/modules/lsst.ip.diffim/AL_implementation.html>`_.
+
+Key terminology:
+
+* ``DiaSource``: a detection, positive or negative, in a single difference image
+* ``DiaObject``: the astrophysical transient or variable object at a static sky coordinate
+
+
+**Light curves:** the forced photometry fluxes should be used for light curves.
+
+All measurements are stored in the catalog :doc:`/products/index`.
+
+
+Difference images
+=================
+
+Template coadd images are warped, scaled, and PSF-matched to a visit image,
+and then subtracted from the visit image to create a difference image.
+
+In the context of DIA, the visit image is sometimes referred to as the
+"direct" or "science" image.
+
+
+DIA source detection
+====================
+
+DIA source detection refers to the process of finding regions with above-threshold
+absolute flux in difference images, where the threshold is a signal-to-noise ratio of 5.
+
+Difference images contain sources of residual flux from the subtraction, both
+positive and negative.
+Real astrophysical transients, variables, and moving objects appear as sources with
+a flux that is equal to the difference between their flux in the template and visit images.
+
+Spurious sources are also present due to unavoidably imperfect template matching.
+
+Deblending is not run on difference image sources.
+
+The results of DIA source detection are stored in the ``DiaSource`` catalog.
+
+
+Reliability score
+-----------------
+
+Both real and spurious DIA sources can be detected with a signal-to-noise ratio of 5.
+An estimate of how likely a source is to be real is provided to enable filtering of DIA sources by users.
+
+Dipoles
+-------
+
+Sources with footprints containing both positive and negative peaks are fit with a
+dipole centroid code.
+Dipoles represent sources that have moved only slightly (e.g., less than the PSF)
+between template and visit image.
+
+Pixel flags
+-----------
+
+If the footprint contains one or more flagged pixels,
+e.g., for cosmic rays, detector edge, bad pixels,
+known artifacts, non-astrophysical trails,
+the source is also flagged.
+
+
+
+DIA object association
+======================
+
+DIA sources are associated into DIA objects using a radius of 1 arcsecond.
+
+The DIA objects are stored in the ``DiaObject`` catalog.
+
+
+Variability characterization
+----------------------------
+
+Light curve characterization parameters are calculated for all DIA objects,
+such as the minimum, mean, maximum, standard deviation, and skew in the
+difference image fluxes, the light curve's slope, percentiles, and ``StetsonJ``
+parameter.
+
+
+DIA forced photometry
+=====================
+
+In general, "forced" photometry means a measurement made at a fixed coordinate in an image,
+regardless of whether an above-threshold region was detected in that particular image.
+
+Forced PSF photometry measurements are made on all visit and difference images
+at the locations of all DIA objects.
+The results are stored in the ``ForcedSourceOnDiaObject`` catalog.
+