printer friendly version
1.1 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.
1.1.1 HOW-TOs
The first place any user, especially new users, should go is the http://www.astro-wise.org/portal/aw_howtos.shtmlAWE HOW-TOs. These are task-specific documents designed to give the user good knowledge of a relatively small part of the system.
1.1.2 The Manual
The http://www.astro-wise.org/docs/Manual.pdfAWE 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.
1.1.3 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.
1.1.3.1 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>
1.1.3.2 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.BiasFrameThis 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.
1.1.4 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, http://www.astro-wise.org/portal/howtos/man_howto_start/man_howto_start.shtmlget a Git checkout
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.
page generated Tue Nov 21 10:29:17 CET 2017