Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Tickets/dm-15684: Convert to numpydoc #106

Merged
merged 1 commit into from
Jan 31, 2019
Merged

Tickets/dm-15684: Convert to numpydoc #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/lsst.ip.diffim/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _lsst.ip.diffim:

##############
lsst.ip_diffim
lsst.ip.diffim
##############

.. Paragraph that describes what this Python module does and links to related modules and frameworks.
Expand Down
1 change: 1 addition & 0 deletions python/lsst/ip/diffim/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
from .diffimLib import *

# Python code
from .dcrModel import *
from .psfMatch import *
from .imagePsfMatch import *
from .modelPsfMatch import *
Expand Down
66 changes: 20 additions & 46 deletions python/lsst/ip/diffim/diaCatalogSourceSelector.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,58 +99,32 @@ def __call__(self, source):
return False
return True

## @addtogroup LSST_task_documentation
## @{
## @page DiaCatalogSourceSelectorTask
## @ref DiaCatalogSourceSelectorTask_ "DiaCatalogSourceSelectorTask"
## @copybrief DiaCatalogSourceSelectorTask
## @}


@pexConfig.registerConfigurable("diaCatalog", measAlg.sourceSelectorRegistry)
class DiaCatalogSourceSelectorTask(measAlg.BaseSourceSelectorTask):
r"""!Select sources for Kernel candidates

@anchor DiaCatalogSourceSelectorTask_

@section ip_diffim_diaCatalogSourceSelector_Contents Contents

- @ref ip_diffim_diaCatalogSourceSelector_Purpose
- @ref ip_diffim_diaCatalogSourceSelector_Initialize
- @ref ip_diffim_diaCatalogSourceSelector_IO
- @ref ip_diffim_diaCatalogSourceSelector_Config
- @ref ip_diffim_diaCatalogSourceSelector_Debug

@section ip_diffim_diaCatalogSourceSelector_Purpose Description
"""A task that selects sources for Kernel candidates.

A naive star selector based on second moments. Use with caution.

@section ip_diffim_diaCatalogSourceSelector_Initialize Task initialisation

@copydoc \_\_init\_\_

@section ip_diffim_diaCatalogSourceSelector_IO Invoking the Task
Notes
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a heads-up that all this content will eventually move out of the docstring to a task topic page: https://developer.lsst.io/stack/task-topic-type.html

I think it's find to ship this initial numpydoc conversion with this as-is, but keep in mind that this is a TODO item.

-----
Debug Variables

Like all star selectors, the main method is `run`.

@section ip_diffim_diaCatalogSourceSelector_Config Configuration parameters
DiaCatalogSourceSelectorTask has a debug dictionary with the following keys:

See @ref DiaCatalogSourceSelectorConfig
display : `bool`
if True display debug information
displayExposure : `bool`
if True display exposure
pauseAtEnd `bool`
if True wait after displaying everything and wait for user input

@section ip_diffim_diaCatalogSourceSelector_Debug Debug variables
Examples
--------
For example, put something like:

DiaCatalogSourceSelectorTask has a debug dictionary with the following keys:
<dl>
<dt>display
<dd>bool; if True display debug information
<dt>displayExposure
<dd>bool; if True display exposure
<dt>pauseAtEnd
<dd>bool; if True wait after displaying everything and wait for user input
</dl>
.. code-block:: py

For example, put something like:
@code{.py}
import lsstDebug
def DebugInfo(name):
di = lsstDebug.getInfo(name) # N.b. lsstDebug.Info(name) would call us recursively
Expand All @@ -160,7 +134,7 @@ def DebugInfo(name):
return di

lsstDebug.Info = DebugInfo
@endcode

into your `debug.py` file and run your task with the `--debug` flag.
"""
ConfigClass = DiaCatalogSourceSelectorConfig
Expand All @@ -169,8 +143,8 @@ def DebugInfo(name):
def selectSources(self, sourceCat, matches=None, exposure=None):
"""Return a selection of sources for Kernel candidates.

Parameters:
-----------
Parameters
----------
sourceCat : `lsst.afw.table.SourceCatalog`
Catalog of sources to select from.
This catalog must be contiguous in memory.
Expand All @@ -179,8 +153,8 @@ def selectSources(self, sourceCat, matches=None, exposure=None):
exposure : `lsst.afw.image.Exposure` or None
The exposure the catalog was built from; used for debug display.

Return
------
Returns
-------
struct : `lsst.pipe.base.Struct`
The struct contains the following data:

Expand Down
142 changes: 125 additions & 17 deletions python/lsst/ip/diffim/diffimTools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,13 +61,24 @@ def makeFlatNoiseImage(mi, seedStat=afwMath.MAX):
def makePoissonNoiseImage(im):
"""Return a Poisson noise image based on im

Uses numpy.random; you may wish to call numpy.random.seed first.
Parameters
----------
im : `lsst.afw.image.Image`
image; the output image has the same dimensions and shape
and its expectation value is the value of im at each pixel

@warning This uses an undocumented numpy API (the documented API
uses a single float expectation value instead of an array).
Returns
-------
noiseIm : 'lsst.afw.image.Image'
TODO: DM-17458

@param[in] im image; the output image has the same dimensions and shape
and its expectation value is the value of im at each pixel
Notes
-----

- Warning: This uses an undocumented numpy API (the documented API
uses a single float expectation value instead of an array).

- Uses numpy.random; you may wish to call numpy.random.seed first.
"""
import numpy.random as rand
imArr = im.getArray()
Expand Down Expand Up @@ -100,7 +111,30 @@ def fakeCoeffs():
def makeFakeKernelSet(sizeCell=128, nCell=3,
deltaFunctionCounts=1.e4, tGaussianWidth=1.0,
addNoise=True, bgValue=100., display=False):

"""TODO: DM-17458

Parameters
----------
sizeCell : `int`, optional
TODO: DM-17458
nCell : `int`, optional
TODO: DM-17458
deltaFunctionCounts : `float`, optional
TODO: DM-17458
tGaussianWidth : `float`, optional
TODO: DM-17458
addNoise : `bool`, optional
TODO: DM-17458
bgValue : `float`, optional
TODO: DM-17458
display : `bool`, optional
TODO: DM-17458

Returns
-------
TODO: DM-17458
TODO: DM-17458
"""
from . import imagePsfMatch
configFake = imagePsfMatch.ImagePsfMatchConfig()
configFake.kernel.name = "AL"
Expand Down Expand Up @@ -229,6 +263,20 @@ def makeFakeKernelSet(sizeCell=128, nCell=3,
#######

def backgroundSubtract(config, maskedImages):
"""Subtract the background from masked images.

Parameters
----------
config : TODO: DM-17458
TODO: DM-17458
maskedImages : `list` of `lsst.afw.image.MaskedImage`
TODO: DM-17458

Returns
-------
TODO: DM-17458
TODO: DM-17458
"""
backgrounds = []
t0 = time.time()
algorithm = config.algorithm
Expand Down Expand Up @@ -257,6 +305,19 @@ def backgroundSubtract(config, maskedImages):


def writeKernelCellSet(kernelCellSet, psfMatchingKernel, backgroundModel, outdir):
"""TODO: DM-17458

Parameters
----------
kernelCellSet : TODO: DM-17458
TODO: DM-17458
psfMatchingKernel : TODO: DM-17458
TODO: DM-17458
backgroundModel : TODO: DM-17458
TODO: DM-17458
outdir : TODO: DM-17458
TODO: DM-17458
"""
if not os.path.isdir(outdir):
os.makedirs(outdir)

Expand Down Expand Up @@ -285,20 +346,41 @@ def writeKernelCellSet(kernelCellSet, psfMatchingKernel, backgroundModel, outdir


def sourceToFootprintList(candidateInList, templateExposure, scienceExposure, kernelSize, config, log):
""" Takes an input list of Sources that were selected to constrain
"""Convert a list of sources for the PSF-matching Kernel to Footprints.

Parameters
----------
candidateInList : TODO: DM-17458
Input list of Sources
templateExposure : TODO: DM-17458
Template image, to be checked for Mask bits in Source Footprint
scienceExposure : TODO: DM-17458
Science image, to be checked for Mask bits in Source Footprint
kernelSize : TODO: DM-17458
TODO: DM-17458
config : TODO: DM-17458
Config that defines the Mask planes that indicate an invalid Source and Bbox grow radius
log : TODO: DM-17458
Log for output

Returns
-------
candidateOutList : `list`
a list of dicts having a "source" and "footprint" field, to be used for Psf-matching

Raises
------
RuntimeError
TODO: DM-17458

Notes
-----
Takes an input list of Sources that were selected to constrain
the Psf-matching Kernel and turns them into a List of Footprints,
which are used to seed a set of KernelCandidates. The function
checks both the template and science image for masked pixels,
rejecting the Source if certain Mask bits (defined in config) are
set within the Footprint.

@param candidateInList: Input list of Sources
@param templateExposure: Template image, to be checked for Mask bits in Source Footprint
@param scienceExposure: Science image, to be checked for Mask bits in Source Footprint
@param config: Config that defines the Mask planes that indicate an invalid Source and Bbox grow radius
@param log: Log for output

@return a list of dicts having a "source" and "footprint" field, to be used for Psf-matching
"""

candidateOutList = []
Expand Down Expand Up @@ -365,8 +447,34 @@ def sourceToFootprintList(candidateInList, templateExposure, scienceExposure, ke

def sourceTableToCandidateList(sourceTable, templateExposure, scienceExposure, kConfig, dConfig, log,
basisList, doBuild=False):
"""Takes an input list of Sources, and turns them into
KernelCandidates for fitting of the Psf-matching kernel."""
"""Convert a list of Sources into KernelCandidates.

The KernelCandidates are used for fitting the Psf-matching kernel.

Parameters
----------
sourceTable : TODO: DM-17458
TODO: DM-17458
templateExposure : TODO: DM-17458
TODO: DM-17458
scienceExposure : TODO: DM-17458
TODO: DM-17458
kConfig : TODO: DM-17458
TODO: DM-17458
dConfig : TODO: DM-17458
TODO: DM-17458
log : TODO: DM-17458
TODO: DM-17458
basisList : TODO: DM-17458
TODO: DM-17458
doBuild : `bool`, optional
TODO: DM-17458

Returns
-------
TODO: DM-17458
TODO: DM-17458
"""
kernelSize = basisList[0].getWidth()
footprintList = sourceToFootprintList(list(sourceTable), templateExposure, scienceExposure,
kernelSize, dConfig, log)
Expand Down