Update source injection package documentation

README.rst

@@ -2,6 +2,44 @@
 source_injection
 ################
 
-``source_injection`` is a package in the `LSST Science Pipelines <https://pipelines.lsst.io>`_.
+The ``source_injection`` package contains tools designed to assist in the injection of synthetic sources into scientific imaging.
+Source generation and subsequent source injection is powered by the `GalSim`_ software package.
 
-The Source Injection package contains Synthetic Source Injection (SSI) tasks and configuration.
+.. _GalSim: https://galsim-developers.github.io/GalSim/
+
+For more information, see the ``source_injection`` documentation on `pipelines.lsst.io`_.
+
+.. _pipelines.lsst.io: https://pipelines.lsst.io/v/daily/modules/lsst.source.injection
+
+.. figure:: doc/lsst.source.injection/_assets/t9813p42i_zoom_sersic_prepost_injection.gif
+    :name: t9813p42i_zoom_sersic_prepost_injection
+    :alt: An HSC i-band cutout from tract 9813, patch 42, showing the injection of a series of synthetic Sérsic sources.
+    :align: center
+    :width: 100%
+
+    ..
+
+    An HSC i-band cutout from tract 9813, patch 42, showcasing the injection of a series of synthetic Sérsic sources.
+    Images are ~100 arcseconds on the short axis, log scaled, and smoothed with a Gaussian kernel.
+
+    .. list-table::
+        :widths: 1 1
+
+        * - .. figure:: doc/lsst.source.injection/_assets/t9813p42i_zoom_sersic_pre_injection.png
+                :name: t9813p42i_zoom_sersic_pre_injection
+                :alt: Tract 9813, patch 42, HSC i-band cutout, before source injection.
+                :align: center
+                :width: 100%
+
+                ..
+
+                Before injection.
+          - .. figure:: doc/lsst.source.injection/_assets/t9813p42i_zoom_sersic_post_injection.png
+                :name: t9813p42i_zoom_sersic_post_injection
+                :alt: Tract 9813, patch 42, HSC i-band cutout, after source injection.
+                :align: center
+                :width: 100%
+
+                ..
+
+                After injection.

doc/conf.py

@@ -11,3 +11,6 @@
 html_theme_options["logotext"] = project  # noqa: F405
 html_title = project
 html_short_title = project
+
+# Update intersphinx configuration to allow finding butler/pipe_base entries.
+intersphinx_mapping["lsst"] = ("https://pipelines.lsst.io/v/daily/", None)  # noqa

doc/index.rst

@@ -10,3 +10,4 @@ source_injection documentation preview
    :maxdepth: 1
 
    lsst.source.injection/index
+   lsst.source.injection/faqs

doc/lsst.source.injection/_assets/graph_post.dot

@@ -0,0 +1,231 @@
+digraph Pipeline {
+	graph [nodesep=0.5,
+		pad=0.5,
+		ranksep=0.75,
+		splines=ortho
+	];
+	node [fontname=Monospace,
+		fontsize=14,
+		margin="0.2,0.1",
+		penwidth=3,
+		shape=box
+	];
+	edge [arrowsize=1.5,
+		color=black,
+		penwidth=1.5
+	];
+	task0	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">calibrate</FONT></B></TD></TR><TR><TD>lsst.pipe.tasks.calibrate.CalibrateTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument, visit</TD></TR></TABLE>>,
+		style=filled];
+	injected_calexp	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_calexp</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task0 -> injected_calexp	[minlen=1];
+	injected_calexpBackground	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_calexpBackground</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task0 -> injected_calexpBackground	[minlen=2];
+	injected_src	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_src</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task0 -> injected_src	[minlen=3];
+	injected_srcMatch	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_srcMatch</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task0 -> injected_srcMatch	[minlen=1];
+	injected_srcMatchFull	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_srcMatchFull</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task0 -> injected_srcMatchFull	[minlen=2];
+	injected_icExp	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_icExp</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injected_icExp -> task0;
+	injected_icExpBackground	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_icExpBackground</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injected_icExpBackground -> task0;
+	injected_icSrc	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_icSrc</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injected_icSrc -> task0;
+	ps1_pv3_3pi_20170110	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">ps1_pv3_3pi_20170110</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;skypix</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	ps1_pv3_3pi_20170110 -> task0	[style=dashed];
+	ps1_pv3_3pi_20170110 -> task0	[style=dashed];
+	task5	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">writePreSourceTable</FONT></B></TD></TR><TR><TD>lsst.pipe.tasks.postprocess.WriteSourceTableTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument, visit</TD></TR></TABLE>>,
+		style=filled];
+	injected_src -> task5	[minlen=1];
+	task1	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">characterizeImage</FONT></B></TD></TR><TR><TD>lsst.pipe.tasks.characterizeImage.CharacterizeImageTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument, visit</TD></TR></TABLE>>,
+		style=filled];
+	task1 -> injected_icExp	[minlen=1];
+	task1 -> injected_icExpBackground	[minlen=2];
+	task1 -> injected_icSrc	[minlen=3];
+	injected_postISRCCD	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_postISRCCD</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, exposure, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injected_postISRCCD -> task1;
+	task2	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">inject_exposure</FONT></B></TD></TR><TR><TD>lsst.source.injection.inject_exposure.ExposureInjectTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument, visit</TD></TR></TABLE>>,
+		style=filled];
+	task2 -> injected_postISRCCD	[minlen=1];
+	injected_postISRCCD_catalog	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_postISRCCD_catalog</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, exposure, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task2 -> injected_postISRCCD_catalog	[minlen=2];
+	finalVisitSummary	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">finalVisitSummary</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	finalVisitSummary -> task2	[minlen=1];
+	postISRCCD	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">postISRCCD</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, exposure, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	postISRCCD -> task2;
+	injection_catalog	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injection_catalog</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, htm7</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injection_catalog -> task2	[minlen=2,
+		style=dashed];
+	task3	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">isr</FONT></B></TD></TR><TR><TD>lsst.ip.isr.isrTask.IsrTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, exposure, instrument</TD></TR></TABLE>>,
+		style=filled];
+	task3 -> postISRCCD	[minlen=1];
+	raw	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">raw</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, exposure, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	raw -> task3	[minlen=1];
+	bfKernel	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">bfKernel</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	bfKernel -> task3	[minlen=2,
+		style=dashed];
+	bias	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">bias</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	bias -> task3	[minlen=3,
+		style=dashed];
+	brighterFatterKernel	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">brighterFatterKernel</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	brighterFatterKernel -> task3	[minlen=1,
+		style=dashed];
+	camera	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">camera</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	camera -> task3	[minlen=2,
+		style=dashed];
+	crosstalk	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">crosstalk</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	crosstalk -> task3	[minlen=3,
+		style=dashed];
+	dark	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">dark</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	dark -> task3	[minlen=1,
+		style=dashed];
+	defects	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">defects</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	defects -> task3	[minlen=2,
+		style=dashed];
+	flat	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">flat</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	flat -> task3	[minlen=3,
+		style=dashed];
+	fringe	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">fringe</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	fringe -> task3	[minlen=1,
+		style=dashed];
+	isrOverscanCorrected	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">isrOverscanCorrected</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, exposure, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	isrOverscanCorrected -> task3	[minlen=2,
+		style=dashed];
+	linearizer	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">linearizer</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	linearizer -> task3	[minlen=3,
+		style=dashed];
+	transmission_atmosphere	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">transmission_atmosphere</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	transmission_atmosphere -> task3	[minlen=1,
+		style=dashed];
+	transmission_filter	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">transmission_filter</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	transmission_filter -> task3	[minlen=2,
+		style=dashed];
+	transmission_optics	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">transmission_optics</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	transmission_optics -> task3	[minlen=3,
+		style=dashed];
+	transmission_sensor	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">transmission_sensor</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	transmission_sensor -> task3	[minlen=1,
+		style=dashed];
+	yBackground	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">yBackground</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	yBackground -> task3	[minlen=2,
+		style=dashed];
+	task4	[color=black,
+		fillcolor="#B1F2EF",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">transformPreSourceTable</FONT></B></TD></TR><TR><TD>lsst.pipe.tasks.postprocess.TransformSourceTableTask</TD></TR><TR><TD><I>dimensions:</I>&nbsp;detector, instrument, visit</TD></TR></TABLE>>,
+		style=filled];
+	injected_preSourceTable	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_preSourceTable</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	task4 -> injected_preSourceTable	[minlen=1];
+	injected_preSource	[color="#00BABC",
+		fillcolor="#F5F5F5",
+		label=<<TABLE BORDER="0" CELLPADDING="5"><TR><TD><B><FONT POINT-SIZE="18">injected_preSource</FONT></B></TD></TR><TR><TD><I>dimensions:</I>&nbsp;band, detector, instrument, physical_filter, visit</TD></TR></TABLE>>,
+		style="rounded,filled,bold"];
+	injected_preSource -> task4	[minlen=1];
+	task5 -> injected_preSource	[minlen=1];
+}