HOW-TO Documentation¶
Documentation for the Astro-WISE Environment is copius. Wading through it can be a daunting challenge. To make learning the system as simple as possible, several levels of documentation have been compiled. This HOW-TO explains all about AWE documentation.
HOW-TOs¶
The first place any user, especially new users, should go is the Howto’s. These are task-specific documents designed to give the user good knowledge of a relatively small part of the system.
The Manual¶
The AWE Manual contains all the HOW-TOs in the same hierarchical form as the web page, but also includes more general and advanced documentation about the system. If the HOW-TO approach is not working for you, please try the Manual.
Documentation from the Code¶
Throughout the code docstrings are placed that indicate the purpose and functionality of packages, modules, classes, methods, functions etc. These can best be viewed in one of two ways: using a PyDoc server or by using the help functionality of Python while using the Python (AWE) command-line interface. See also apidoc.
Online documentation¶
A pydoc server of a standard code checkout is always accessible online at
A local pydoc server can be started with the following command:
pydoc -p <port>
or
awedoc -p <port>
This server will search any installed Python code and create HTML pages so that the code can be browsed with a webbrowser. The majority of the first page displayed will show installed Python libraries. The Astro-WISE code is marked by the location of your awe checkout. The server is accessible as
http://localhost:<port>
Inline documentation¶
It is possible to access docstrings from the Python/AWE prompt. This is often more convenient and faster than using a pydoc server.
awe> import astro.main.BiasFrame
awe> help(astro.main.BiasFrame)
Usually however you will call a similar page by calling help on a class rather than the module which contains this class (e.g. in this case, module BiasFrame.py also includes the class BiasFrameParameters):
awe> from astro.main.BiasFrame import BiasFrame
awe> help(BiasFrame)
Similarly one can get the docstring of individual methods:
awe> help(BiasFrame.make_image)
Help on method make_image in module astro.main.BiasFrame:
make_image(self) unbound astro.main.BiasFrame.BiasFrame method
Make a master bias image.
Requires:
raw_bias_frames -- A list of raw bias frames
read_noise -- A ReadNoise object
Do a trim and overscan correction on the input frames, compute
a first estimate of the mean using a median of all trimmed and
overscan-corrected raw biases. For each input bias reject
pixels which deviate more than SIGMA_CLIP * read_noise from
the median, and use the remaining pixels to compute a mean.
Note that a list of all methods, properties etc. of a class can be obtained with the “dir” command:
awe> dir(BiasFrame)
There is also a special Python help environment that can be started with this command:
awe> help()
The next command then gives an overview of the most important modules for our system:
help> modules astro.main
This (takes a little while) displays the following:
awe> help()
Welcome to Python 2.7! This is the online help utility.
If this is your first time using Python, you should definitely check out
the tutorial on the Internet at http://docs.python.org/2.7/tutorial/.
Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules. To quit this help utility and
return to the interpreter, just type "quit".
To get a list of available modules, keywords, or topics, type "modules",
"keywords", or "topics". Each module also comes with a one-line summary
of what it does; to list the modules whose summaries contain a given word
such as "spam", type "modules spam".
help> modules astro.main
Here is a list of matching modules. Enter any module name to get more help.
astro.main.AssociateList
astro.main.Astrom - the world coordinate system of a FITS file
astro.main.AstrometricCatalog
astro.main.AstrometricCorrection - Astrometric Correction
astro.main.AstrometricParameters
astro.main.AstrometricParametersFactory
astro.main.AtmosphericExtinction
astro.main.AtmosphericExtinctionCurve
astro.main.AtmosphericExtinctionFrames
astro.main.AtmosphericExtinctionZeropoint
astro.main.BaseCatalog - defines the base class for all catalogs
astro.main.BaseFlatFrame - defines the base class for all flat-fields
astro.main.BaseFrame - defines the base class for all frames (images)
astro.main.BaseWeightFrame - defines the base class for all weights
astro.main.BiasFrame - bias (req541)
astro.main.Catalog - defines a class for (SExtractor) catalogs
astro.main.Chip - class used to identify a single chip
astro.main.ColdPixelMap - cold pixel maps (req535)
astro.main.Config - provides a persistency mechanism for configuration parameters
astro.main.CosmicMap - defines classes used in detecting cosmic ray impacts
astro.main.DarkCurrent - dark current (req531) and particle event rate (req532)
astro.main.DataObject - objects with an associated data file
astro.main.DomeFlatFrame - dome flat (req542), master dome flats
astro.main.Filter - class used to identify the filter
astro.main.FringeFrame - fringe images (req545)
astro.main.GAstrometric
astro.main.GainLinearity - gain (req523) and linearity (req533)
astro.main.GainLinearity2 - gain (req523) and linearity (req533)
astro.main.HotPixelMap - hot pixel maps (req522)
astro.main.IlluminationCorrection
astro.main.IlluminationCorrectionFrame
astro.main.Imstat - image statistics
astro.main.Instrument - class used to identify the instrument
astro.main.Lamp
astro.main.LinearityMap - non-linear pixels (req533)
astro.main.LongAstrom - astrometry including PV matrix
astro.main.MasterFlatFrame - defines the final flat-field to be used (req546)
astro.main.NightSkyFlatFrame - night-sky flat frames (req544)
astro.main.ObservingBlock
astro.main.OnTheFly
astro.main.PhotExtinctionCurve
astro.main.PhotRefCatalog
astro.main.PhotSkyBrightness
astro.main.PhotSrcCatalog
astro.main.PhotTransformation
astro.main.PhotometricExtinctionReport
astro.main.PhotometricParameters
astro.main.PhotometricReport
astro.main.PhotometricSkyReport
astro.main.PixelMap - defines a class for pixel maps
astro.main.ProcessTarget - processable objects with quality control flags
astro.main.QuickCheckFrame - quick check (req547)
astro.main.RadioCube
astro.main.RawFinder
astro.main.RawFitsData - completely raw data
astro.main.RawFrame - classes for the different kinds of raw frames
astro.main.ReadNoise - read noise (req521) in ADU
astro.main.ReducedScienceFrame - de-bias & flat-field (seq632), apply astrometry (seq634/req555)
astro.main.RegriddedFrame
astro.main.RegriddedFrame_new - the support classes for regridding and coaddition
astro.main.SatelliteMap - maps of satellite tracks (if any)
astro.main.SaturatedPixelMap - maps of saturated pixels
astro.main.ScienceFrame - apply photometry (seq635)
astro.main.ShutterCheckFrame - shutter timing (req561)
astro.main.SourceList
astro.main.SubWinStat - SubWinStat
astro.main.SubWinStatFactory
astro.main.TwilightFlatFrame - twilight flat (req543), master twilight flats
astro.main.VariabilityFrame - Variability tool
astro.main.WeightFrame - individual weights (seq633)
astro.main (package) - The Persistent Object Hierarchy
astro.main.aweimports - automatic imports for the interpreter
help>
The following command can be given to get help on a specific module:
help> astro.main.BiasFrame
This will display the following page (don’t bother reading it in any detail at this point):
Help on module astro.main.BiasFrame in astro.main:
NAME
astro.main.BiasFrame - bias (req541)
FILE
/data/users/helmich/awe/astro/main/BiasFrame.py
DESCRIPTION
This module contains class definitions for BiasFrameParameters
and BiasFrame.
BiasFrame is the class that defines a master bias object.
BiasFrameParameters is a class with parameters that are used, e.g., in
trend analysis.
CLASSES
astro.main.BaseFrame.BaseFrame(astro.main.DataObject.DataObject, astro.main.
ProcessTarget.ProcessTarget)
BiasFrame
common.database.DBMain.DBObject(__builtin__.object)
BiasFrameParameters
class BiasFrame(astro.main.BaseFrame.BaseFrame)
| Class for the master bias.
|
| This class defines the master bias frame and provides the ability
| to reduce a list of raw bias input frames. The reduction consists
| of averaging the trimmed and overscan-corrected raw bias frames
| and calculating the statistics of the derived frame. Instances
| of this class have links to:
|
| raw_bias_frames - List of raw bias objects.
| process_params - Bias frame parameters object.
| prev - Previous master bias object.
| imstat - The Imstat object containing image statistics for the
| reduced bias frame object.
| instrument - The Instrument object describing which instrument the
raw
| bias frame was observed with.
| chip - The Chip object for the CCD with which the raw bias fr
ame
| was observed.
| observing_block - The ObservingBlock object to which this bias
| observation belongs.
|
| Method resolution order:
| BiasFrame
| astro.main.BaseFrame.BaseFrame
| astro.main.DataObject.DataObject
| common.database.DBMain.DBObject
| astro.main.ProcessTarget.ProcessTarget
| common.database.DBMeta.DBMixin
| __builtin__.object
| astro.main.OnTheFly.OnTheFly
|
| Methods defined here:
|
| __init__(self, pathname='')
|
| build_header(self)
| Extends BaseFrame build_header method
|
| check_preconditions(self)
|
| clean_up(self)
| This methods deletes intermediate products (like trimmed versions of
| raw frames that may cause problems when the BiasFrame is made a seco
nd
| time) from memory.
|
| compare(self)
| Compare the results with a previous version.
|
| Requires:
| prev -- A BiasFrame object for the previous Bias measurement
|
| The folowing flags may be set in the status attribute:
| MEAN_DIFFER -- (mean of bias-mean of previous) > MAXIMUM_BIAS_DIF
FERENCE
|
| copy_attributes(self)
|
| derive_timestamp(self)
| Assign the period for which this calibration frame is valid.
|
| get_canonical_name(self)
| Generate the unique filename for this BiasFrame.
|
| make(self)
| Make a master bias frame.
|
| Requires:
| raw_bias_frames -- A list of raw bias exposures.
|
| Trims and applies overscan correction to the raw input bias
| frames. Averages these frames to derive the master bias
| frame. Calculates the image statistics on the resulting
| frame. Creates the FITS header and saves it together with the
| FITS image.
|
| make_image(self)
| Make a master bias image.
|
| Requires:
| raw_bias_frames -- A list of raw bias frames
| read_noise -- A ReadNoise object
|
| Do a trim and overscan correction on the input frames, compute
| a first estimate of the mean using a median of all trimmed and
| overscan-corrected raw biases. For each input bias reject
| pixels which deviate more than SIGMA_CLIP * read_noise from
| the median, and use the remaining pixels to compute a mean.
|
| read_header(self)
| Extends the read_header method of BaseFrame
|
| set_overscan_parameter(self)
| Sets the OVERSCAN_CORRECTION attribute of the BiasFrameParameters
| object associated with the BiasFrame based on OVSC_COR header keywor
d
|
| Necessary for checking of inconsistencies between overscan correctio
n
| methods of (input) BiasFrame and (target) frame (e.g. a RawScienceFr
ame)
| that uses the BiasFrame.
|
| verify(self)
| Verify the results.
|
| The following flags may be set in the status attribute:
| BIAS_ABS_MEAN_TOO_LARGE : if the mean is significantly different f
rom zero
| BIAS_STDEV_TOO_LARGE : if the stdev is too large
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
etc.
etc.
etc.
Evidently these pages can be quite lengthy. The structure of the pages is always the same however: aside from the docstring for the current module, the docstrings of the classes, methods, functions and properties as well as those of any superclass(es) of the class in question are displayed.
Exit help as follows:
help> quit
You are now leaving help and returning to the Python interpreter.
If you want to ask for help on a particular object directly from the
interpreter, you can type "help(object)". Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.
awe>
These pages contain exactly the same information as the HTML documentation created by a pydoc server.
The Code Itself¶
If your troubles (or just your curiosity) require more information than all the
above documention can provide, the last place to look is at the code itself. If
you haven’t already done so, get a Git checkout (see HOW-TO Use Git) and
load the relevant files into your favorite text editor/viewer and have fun.
Most software of interest will be located in $AWEPIPE/astro/main,
$AWEPIPE/astro/recipes, or $AWEPIPE/astro/toolbox.
