This section describes the class libraries that are relevant for a recipe writer.
Provide spatial and/or spectral bounds for files.
This package provides functions to retrieve spatial and spectral information about an NDF containing AST FrameSet information. It currently retrieves the corners of a bounding box in the spatial extent, and the upper and lower bounds for the frequency extent.
Bounding information will be incorrect for data encompassing a pole.
This method retrieve spatial/spectral bounds for a given NDF.
The file must be an NDF. The filename need not have the ’.sdf’ extension.
The return value is a hash reference containing the following keys:
Astro::Coords object for the reference sky position.
Astro::Coords object for the top left corner of the bounding box.
Astro::Coords object for the top right corner of the bounding box.
Astro::Coords object for the bottom left corner of the bounding box.
Astro::Coords object for the bottom right corner of the bounding box.
Astro::Coords object for the central pixel in the NDF.
Barycentric frequency, in gigahertz, of the lower end of the signal sideband.
Barycentric frequency, in gigahertz, of the upper end of the signal sideband.
Barycentric frequency, in gigahertz, of the lower end of the image sideband.
Barycentric frequency, in gigahertz, of the upper end of the image sideband.
A specific key will be undefined if the given file does not have the appropriate information to calculate it with. For example, if a file does not have a SkyFrame, then none of the Astro::Coords objects listed above will be defined.
This function currently only works on files that have 3D CmpFrames.
This function creates an Astro::FITS::Header object which describes the bounds of the
observation in question.
The file must be an NDF. The ’.sdf’ extension need not be present.
The following mappings from the keys listed in the retrieve_bounds() function are made:
If any of the headers already exist, they will be overwritten.
This function sets FITS headers in the file describing the bounds of the observation in question.
The file must be an NDF. The ’.sdf’ extension need not be present.
The following mappings from the keys listed in the retrieve_bounds() function are made:
If any of the output keys from retrieve_bounds() are undefined, then the corresponding headers will not be written to the file.
Copyright (C) 2007 Science and Technology Facilities Council. All Rights Reserved.
Base class for selecting calibration frames in ORAC-DR
This module provides the basic methods available to all ORAC::Calib objects. This class should be used for selecting calibration frames.
Unless specified otherwise, a calibration frame is selected by first, the nearest reduced frame; second, explicit specification via the -calib command line option (handled by the pipeline); third, by search of the appropriate index file.
Note this version: Index files not implemented.
The following methods are available in this class. Constructors
Create a new instance of a ORAC::Calib object. The object identifier is returned.
Returns the hash that can be used for checking the validity of calibration frames. This is
a combination of the two hashes stored in thingone and thingtwo. The hash returned by
this method is readonly.
Returns or sets the hash associated with the header of the object (frame or group or whatever) needed to match calibration criteria against.
Ending sentences with a preposition is a bug.
Returns or sets the hash associated with the user defined header of the object (frame or group or whatever) against which calibration criteria are applied.
Returns the full path and filename of the requested file (the first file found in the search path).
croaks if the file can not be found. It’s likely that this is a bit drastic but it will indicate something bad is going on before some other unexpected behaviour occurs. See ORAC::Inst::Defn::orac_determine_calibration_search_path for information on setting up calibration directories.
Returns the value for the specified column in the specified index.
The first argument is a queryable
These methods create methods for the standard calibration schemes for subclasses. By default calibration "xxx" needs to create standard accessors for "xxxnoupdate", "xxxname" and "xxxindex".
Helper routine that creates an index object and returns it. Updates the object based on the root name.
Where the first argument should match the root name of the index and rules file. The second argument can have three modes:
If a third argument is supplied it is assumed to be an ORAC::Index object to be stored in the calibration object.
Generic method for retrieving or setting the current value based on index and verification. Uses ORACTIME to verify.
First argument indicates the root name for methods to be called. ie "sky" would call "skyname", "skynoupdate", and "skyindex".
Second argument controls whether the time comparison should be nearest in time (0), or earlier in time (-1).
Third argument controls croaking behaviour. False indicates that the method should croak if a suitable calibration can not be found. True indicates that it should return undef. If a code ref is provided, it will be executed if no suitable calibration is found. If it returns a defined value it will be assumed to be a valid match, and if it returns undef the method will croak as no suitable calibration will be available. This allows defaults to be inserted.
Fourth argument controls whether calibration object verification is not done.
Fifth argument controls whether warnings are displayed when searching through the index file for a suitable calibration. Default is to warn.
Like GenericIndexAccessor except that a particular value from the index is retrieved rather than
a indexing key (filename).
No verification is performed.
First argument indicates the root name for methods to be called. ie "sky" would call "skycache", "skynoupdate", and "skyindex".
If a reference to an array or columns is given in argument 2, all values are checked and the row reference is returned instead of a single value.
Dynamically create default accessors for "xxxnoupdate", "xxxname" and "xxxindex" methods.
Copyright (C) 1998-2004 Particle Physics and Astronomy Research Council. All Rights Reserved.
use ORAC::Calib::WFCAM;
This module contains methods for specifying WFCAM-specific calibration objects when using Starlink software for reduction. It provides a class derived from ORAC::Calib::Imaging. All the methods available to ORAC::Calib::Imaging objects are available to ORAC::Calib::WFCAM objects.
The following methods are available: General Methods
Determine the mask necessary for microstep interleaving.
This method returns a filename, including directory structure. If the noupdate flag is set there is no verification that the mask meets the specified rules.
Return (or set) the name of the current dark - checks suitability on return. This is subclassed for WFCAM so that the warning messages when going through the list of possible darks are suppressed.
Return (or set) the name of the current flat.
This method is subclassed for WFCAM so that the warning messages when going through the list of possible flats are suppressed.
Return (or set) the name of the current bad pixel mask.
This method is subclassed for WFCAM because we have one mask per camera and not one standard mask.
Return (or set) the name of the current skyflat.
Copyright (C) 2004-2006 Particle Physics and Astronomy Research Council. All Rights Reserved.
This module contains methods for specifying ACSIS-specific calibration objects. It provides a class derived from ORAC::Calib. All the methods available to ORAC::Calib objects are also available to ORAC::Calib::ACSIS objects.
The following methods are available: Constructor
Sub-classed constructor. Adds knowledge of pointing, reference spectrum, beam efficiency, and other ACSIS-specific calibration information.
Set or retrieve the name of the system to be used for bad receptor determination. Allowed values are:
Use the master index.bad_receptors index file in $ORAC_DATA_CAL.
Use the index.bad_receptors_qa index file in $ORAC_DATA_OUT as generated by the pipeline.
Use both the master index.bad_receptors and pipeline-generated index.bad_receptors_qa file. Results are ’or’ed together, so any receptors flagged as bad in either index file will be flagged as bad.
Use the contents of the file bad_receptors.lis, which contains a space-separated list of receptor names in the first line. This file must be found in $ORAC_DATA_OUT. If the file cannot be found, no receptors will be flagged.
A colon-separated list of receptor names can be supplied. This list can be in combination with one of the other options.
The default is to use the ’indexormaster’ method. The returned value will always be in upper-case.
Return (or set) the index object associated with the master bad receptors index file. This index file is used if bad_receptors() is set to ’MASTER’ or ’INDEXORMASTER’.
Return (or set) the index object associated with the pipeline-generated bad receptors index file. This index file is used if bad_receptors() is set to ’INDEX’ or ’INDEXORMASTER’.
Return a list of receptor names that should be masked as bad for the current observation. The source of this list depends on the setting of the bad_receptors() accessor.
Retrieve flat-field ratios for the observation’s UT date.
Retrieve the relevant standard.
This returns the permitted receptors names for the current instrument. It first looks for the header, and failing that supplies the default set.
Calculate the sideband correction factor. Requires an instrument, a time and an lofrequency, which it gets from the headers by default
Optionally you can specify the instrument, ut and lo frequency (GHz) in the call.
Copyright (C) 2007-2009, 2014, 2016, 2020 Science and Technology Facilities Council. All Rights Reserved.
This module returns (and can be used to set) calibration information for SCUBA. SCUBA calibrations are used for extinction correction (the sky opacity) and conversion of volts to Janskys.
It can also be used to set and retrieve lists of bad bolometers generated by noise observations.
This class does inherit from ORAC::Calib although nearly all the methods in the base class are irrelevant to SCUBA (this class only uses the thing() method).
The following methods are available in this class. These are in addition to the methods inherited from ORAC::Calib. Constructor
Create a new instance of a ORAC::Calib::SCUBA object. The object identifier is returned.
Return the default FCF lookup table indexed by filte.
Return the lookup table of fluxes for secondary calibrators.
Set or retrieve the name of the system to be used for bad bolometer determination. Allowed values are:
Use an index file generated by noise observations using the reflector blade. The bolometers stored in this file are those that were above the noise threshold in the _REDUCE_NOISE_ primitive. The index file is generated by the _REDUCE_NOISE_ primitive
Uses the contents of the file badbol.lis (contains a space separated list of bolometer names in the first line). This file is in ORAC_DATA_OUT. If the file is not found, no bolometers will be flagged.
A colon-separated list of bolometer names can be supplied. If badbols=h7:i12:g4,... then this list will be used as the bad bolometers throughout the reduction.
Default is to use the ’file’ method. The value is always upper-cased.
Returns list of bolometer names that should be turned off for the current observation. The source of this list depends on the setting of the badbols() parameter (controlled by the user). Can be one of ’index’, ’file’ or actual bolometer list. See the badbols() method documentation for more information.
Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
This module returns (and can be used to set) calibration information for SCUBA-2.
It can also be used to set and retrieve lists of bad bolometers generated by noise observations.
This class does inherit from ORAC::Calib although nearly all the methods in the base class are irrelevant to SCUBA-2 (this class only uses the thing() method).
Note that currently this module is mostly just a copy of the SCUBA module, with extra SCUBA-2 specific methods. Some pruning/updating WILL be necessary.
The following methods are available in this class. These are in addition to the methods inherited from ORAC::Calib. Constructor
Create a new instance of a ORAC::Calib::SCUBA2 object. The object identifier is returned.
Return the number of components in the current fit to the beam. Will be either 1 or 2 if a fit exists, otherwise undef.
A method to set or retrieve the full parameter set for the most recent fit to the beam. If setting the beam parameters, all of the parameters must be specified as a hash. The beam dimensions and orientation must be passed as array references. A hash reference containing the beam parameters is returned.
The returned hash reference has the following keys: BeamA, BeamAErr, BeamB, BeamBErr, PA,
PAErr, FWHM, Gamma and BeamComp. BeamA and BeamB are the major and minor axes respectively of
the first component of the fit. In the case of a two-component fit, the FWHM of the second
component (and its uncertainty) is stored by the errbeam method. The FWHM entry contains the
geometric mean of the major and minor axes of the first component. Gamma will always be 2 if
there are two components.
Conventionally the units of the FWHM are arcsec, but it is up to the caller to ensure that the FWHM values are in the units of choice before storing them here.
Get the catalog position for a secondary calibrator if we have a catalog position for it.
Returns undef if there is no catalog position stored for the given object. Otherwise returns a reference to a RA, Dec array of sexagesimal strings.
The current estimated FWHM of the error beam (and its uncertainty) as given in the
beampar results. Must be given and returns a hash reference with the keys BeamA and
BeamAErr.
Fractional power in the error beam as determined from aperture photometry.
Returns the FWHM of the current estimate of the error beam.
Retrieve the fitted beam full-width-at-half-maximum (FWHM). Returns the geometric mean of the major/minor axes of the fit.
If the complete beam parameters are required, the beamfit method should be used instead. Returns undef if no fit parameters have been stored.
Return the telescope beam parameters for the current wavelength. See the beamfit
method for the results of the most recent fit to the beam.
Returns a hash reference with the keys FWHM1, FWHM2, AMP1, AMP2, FRAC1 and FRAC2.
Return the relative amplitudes of the telescope beam components at the current wavelength. Returns either an array with two elements or array reference depending on caller. The first element corresponds to the main beam component.
Returns the beam area in units of arcsec^2/beam. The nominal values have been determined empirically from an ensemble of calibration data.
The optional parameter is an aperture diameter in arcsec:
This value can be thought of as an ideal Gaussian of FWHM sqrt(beamarea/1.133). It will be slightly bigger than the nominal FWHM of the primary beam because error lobes are included.
Return the fractional power in each component of the beam as an array or array reference. May also take parameter to return either the main or error beam fraction.
Return the default FCF lookup table indexed by filter.
Return the measured telescope beam FWHM for the two components at the current wavelength. Returns either an array with two elements or array reference depending on caller. The first element is the main beam component.
Returns the FWHM (in arcsec) of a Gaussian with the same area as the empirical telescope beam (see the beamarea method below).
Method to return the NEP spec for the current wavelength
Return the lookup table of fluxes for secondary calibrators. Takes an optional parameter which returns the total fluxes rather than the ‘per beam’ values.
Return (or set) the name of the current bad bolometer mask.
This method is subclassed for SCUBA-2 because we have one mask per subarray and not
one standard mask. Note that the user must set the subarray with the Frame class
subarray() method before a suitable calibration entry can be found. This is due to
the fact that it is not possible to search the Frame subheaders when evaluating the
rules.
Return (or set) the name of the current dark frame.
This method is subclassed for SCUBA-2 because we have dark frames for each subarray. Note
that the user must set the subarray with the Frame class subarray() method before a suitable
calibration entry can be found. This is due to the fact that it is not possible to search the Frame
subheaders when evaluating the rules.
Return (or set) the name of the current flatfield solution.
This method is subclassed for SCUBA-2 because we have one flatfield per subarray. Note that
the user must set the subarray with the Frame class subarray() method before a suitable
calibration entry can be found. This is due to the fact that it is not possible to search the Frame
subheaders when evaluating the rules.
Return (or set) the name of the current fast-ramp flatfield file(s).
There is one fast-ramp flatfield file per subarray. Note that the user must set the subarray with
the Frame class subarray() method before a suitable calibration entry can be found. This is due
to the fact that it is not possible to search the Frame subheaders when evaluating the
rules.
Return the name of the matching fast-ramp flatfield file from the most recent SETUP
observation.
There is one fast-ramp flatfield file per subarray. Note that the user must set the subarray with
the Frame class subarray() method before a suitable calibration entry can be found. This is due
to the fact that it is not possible to search the Frame subheaders when evaluating the
rules.
Return the name of the matching noise observation.
There is one noise file per subarray. Note that the user must set the subarray with the
Frame class subarray() method before a suitable entry can be found. This is due to
the fact that it is not possible to search the Frame subheaders when evaluating the
rules.
Return the name of the matching NEP file. This returns the name of the top-level
container file - the user must then select the .more.smurf.nep component within that
file.
There is one noise file per subarray. Note that the user must set the subarray with the
Frame class subarray() method before a suitable entry can be found. This is due to
the fact that it is not possible to search the Frame subheaders when evaluating the
rules.
Return (or set) the name of the current zeropath file(s).
Return (or set) the name of the current forward zeropath file(s).
Return (or set) the name of the current backward zeropath file(s).
Return the full path to a default makemap config file. Options to return particular
default configurations may be passed in as a hash. Valid keys are config_type and
pipeline. The config type must be one of the supported values (see the contents of
$STARLINK_DIR/share/smurf for available options). If given, the pipeline argument
must be either ql or summit and causes this method to look in the directory defined by
the environment variable ORAC_DATA_CAL.
The config_type is usually stored as a uhdr entry for the current Frame object.
The pipeline argument is ignored if the config type is given as moon.
Method to retrieve default values of the pixel scale for output images. The numbers are returned in ARCSEC. These numbers are hard-wired here and should always be retrieved with this method.
Note this is intended for use with DREAM/STARE images, not SCAN data.
Return (or set) the name of the current responsivity solution.
Note that unless the current Frame has been derived from a sub-group, the user must set the
subarray with the Frame class subarray() method before a suitable calibration entry can be
found. This is due to the fact that it is not possible to search the Frame subheaders when
evaluating the rules.
Get/set the statistics associated with the most recent flatfield solution. If setting, the user must supply a subarray and hash reference with the relevant statistics. No check is made to verify the contents of the hash. The user may pass in an optional subarray argument if retrieving the stored values, otherwise the entire hash reference is returned. If so then a hash reference is returned whicih contains only the relevant info for the given subarray. A value of undef is returned if no data exist for that subarray.
The sub-instrument associated with this calibration object. Returns either 450 or 850.
Copyright (C) 2007-2009 Science and Technology Facilities Council. Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Constants available to the ORAC system
Provide access to ORAC constants, necessary to use this module if you wish to return an ORAC__ABORT or ORAC__FATAL status using ORAC::Error.
The following constants are available from this module:
This constant contains the definition of good ORAC status.
This constant contains the definition of bad ORAC status.
An algorithm engine has returned with a status that indicates that the engine is no longer valid. This can be used to indicate that an engine has crashed and that a new one should be launched.
This constant contains the definition a user aborted ORAC process
This constant contains the definition an ORAC process which has died fatally
This constant contains the definition of an error in parsing a recipe.
This constant denotes that a recipe was terminated early, but without error.
This constant denotes that a recipe was terminated early, but with a handled error.
This constant denotes that the recipe was completed with the frame marked bad.
This constant denotes the numerical value for the special "bad" value in NDF, for doubles.
Individual sets of constants can be imported by including the module with tags. For example:
will import all constants associated with ORAC status checking.
The available tags are:
Constants associated with ORAC status checking: ORAC__OK and ORAC__ERROR.
Constants associated with bad values.
The constants can be used as if they are subroutines. For example, if I want to print the value of ORAC__ERROR I can
or
Tim Jenness t.jenness@jach.hawaii.edu and Frossie Economou frossie@jach.hawaii.edu
The constants package must be available. This is a standard perl package.
Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
Top level interface to ORAC display tools
This module provides an OO-interface to the ORAC display manager. The display object reads device information from a file or notice board (shared memory) [NBS not implemented], determines whether the supplied frame object matches the criterion for display, if it does it instructs the relevant device object to send to the selected window (creating a new device object if necessary)
Create a new instance of ORAC::Display. No arguments are required.
Returns (or sets) a hash containing the current lookup of display tool to display tool object. For example:
where %tools could look like:
etc. The current contents are overwritten when a new hash is supplied.
When called from an array context, returns the full hash contents. When called from a scalar context, returns the reference to the hash.
Set (or retrieve) the name of the file containing the display device definition. Only used when usenbs() is false.
Set (or retrieve) the value of the string used for comparison with the display device definition information (created by the separate device allocation GUI).
Determine whether NBS (shared memory) should be used to read the display device definition. Default is false.
Returns true if this object is driving a display, false if this object is monitoring a display.
File handle associated with monitor file. Will be created if necessary. If this is the master, the file is opened for write (thereby removing any existing file). If this is a monitor the file is opened for read.
It is non-fatal for the monitor to fail to open a file since this usually indicates that the master pipeline is not enabling monitoring.
Controls whether the master display object is doing local displaying of data itself (true) or whether it is simply sending information to a monitor (false). Default is true.
Set or return information to show in window titles (where possible).
Method to read a display definition, compare it with the idstring stored in the object (this is usually a file suffix) and return back an array of hashes containing all the relevant entries from the definition. If an argument is given, the object updates its definition of current idstring (and then searches).
An empty array is returned if the suffix can not be matched.
This is the main method to be used for displaying data. The supplied object must contain a method for determining the filename and the display ID (so that it can be compared with the information stored in the device definition file). It should support the file(), nfiles() and gui_id() methods.
The optional hash can be used to supply extra entries in the display definition file (or in fact do away with the definition file completely). Note that the contents of the options hash will be used even if no display definition can be found to match the current gui_id.
A third optional argument can be used in conjunction with the options hash to indicate whether these options should be used instead of the display definition file (false) or in addition to (true - the default). In addition this argument may take the value of -1 in which case the entries in $optref will be used to overwrite or supplement existing entries.
Using the current idstring, read the relevant information from a noticeboard and return it in a hash. This routine takes no arguments (idstring is read from the object) and should only be used if the usenbs() flag is true.
Currently not implemented.
Using the current idstring, read the relevant information from the text file (name stored in filename()) and return it in an array of hashes. There will be one hash per entry in the file that matches the given suffix. This routine takes no arguments (idstring is read from the object).
The input file is assumed to contain one line per ID of the following format:
Write information to a file that can be read by monitor processes. This allows the display system to be separated from the actual tools doing the displaying or for a clone display system to enable more than one person to view pipeline output.
Does nothing if this object is monitoring.
Given a line of text matching that written by the append_monitor method, trigger the display
system accordingly by calling the display_data method.
No-op if the Display is configured as a master.
Related ORAC display devices (eg ORAC::Display::KAPVIEW)
Copyright (C) 2007 Science and Technology Facilities Council. Copyright (C) 1998-2004 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Base class for dealing with observation frames in ORAC-DR
This module provides the basic methods available to all ORAC::Frame objects. This class should be used when dealing with individual observation files (frames).
The following methods are available in this class: Constructors The following constructors are available:
Create a new instance of a ORAC::Frame object. This method also takes optional arguments: if 1 argument is supplied it is assumed to be the name of the raw file associated with the observation. If 2 arguments are supplied they are assumed to be the raw file prefix and observation number. In any case, all arguments are passed to the configure() method which is run in addition to new() when arguments are supplied. The object identifier is returned.
The base class constructor should be invoked by sub-class constructors. If this method is called with the last argument as a reference to a hash it is assumed that this hash contains extra configuration information (’instance’ information) supplied by sub-classes.
Note that the file format expected by this constructor is actually the required format
of the data (as returned by format() method) and not necessarily the raw format.
ORAC-DR will pre-process the data with ORAC::Convert prior to passing it to this
constructor.
Create new instances of objects (of this class) from multiple input files.
In most cases this is identical to simply passing the files directly to the constructor. In some subclasses, files from the same observation will be grouped into multiple file objects and processed independently.
Note that framegroup() accepts multiple filenames in a list, as opposed to the frame constructors that only take single files or reference to an array.
If the framegroupkeys method returns a list, those keys are used as FITS headers that should be
used to group the input files.
Return a list of Frame objects containing files with the given header keys. All the files in each frame will have the same values for the given keys (if they exist).
Only the primary header is searched for subheaders (not the uhdr).
Each frame is in the same class as the given Frame.
This method is analagous to the Group subgrps method and will return the current Frame if
there are no subheaders.
This method returns the group name associated with the observation.
This can be configured initially using the findgroup() method. Alternatively, findgroup() is run automatically by the configure() method.
Returns the FITS header keys that should be used to group files into distinct Frame objects. Used
by the framegroup method to determine grouping.
Returns UTDATE and OBSERVATION_NUMBER in base class, to allow simple disambiguation. This is required to allow the -file option to work since that relies on framegroupkeys as it reads all files at once.
If the final element of the returned list is a reference to an array those items will be treated as alternate keywords and the first keyword to match will be used.
Whether or not the current object is an ORAC::Frame object.
Returns 1.
Flag to determine the current state of the frame. If isgood() is true the Frame is valid. If it returns false the frame object may have a problem (eg the recipe responsible for processing the frame failed to complete).
This flag is used by the ORAC::Group class to determine membership. A negative value indicates that the frame is good but should be hidden from the group.
The return value from isgood() will always be defined.
Return the number of sub-frames associated with this frame.
nfiles() should be used to return the current number of sub-frames associated with the frame (nsubs usually only reports the number given in the header and may or may not be the same as the number of sub-frames currently stored)
Usually this value is set as part of the configure() method from the header (using findnsubs()) or by using findnsubs() directly.
Return (or set) the constant part of the raw filename associated with the raw data file. (ie the bit that stays fixed for every observation)
Data format associated with the raw() data file. Usually one of ’NDF’, ’HDS’ or ’FITS’. This
format should be recognisable by ORAC::Convert.
Return (or set) the file name suffix associated with the raw data file.
This method returns the recipe name associated with the observation. The recipe name can be set explicitly but in general should be set by the findrecipe() method.
This can be configured initially using the findrecipe() method. Alternatively, findrecipe() is run automatically by the configure() method.
An array of flags, one per raw file, indicating whether the raw file is temporary, and so can be deleted, or real data (don’t want to delete it).
If a single value is given, it will be applied to all raw files
In scalar context returns true if all frames are temporary, false if all frames are permanent and undef if some frames are temporary whilst others are permanent.
This method is used to configure the object. It is invoked automatically if the new() method is invoked with an argument. The file(), raw(), readhdr(), findgroup(), findrecipe and findnsubs() methods are invoked by this command. Arguments are required. If there is one argument it is assumed that this is the raw filename. If there are two arguments the filename is constructed assuming that argument 1 is the prefix and argument 2 is the observation number.
Multiple raw file names can be provided in the first argument using a reference to an array.
Erase the current file from disk.
The optional argument specified the file number to be erased. The argument is identical to that given to the file() method. Returns ORAC__OK if successful, ORAC__ERROR otherwise.
Note that the file() method is not modified to reflect the fact the the file associated with it has been removed from disk.
This method is usually called automatically when the file() method is used to update the current filename and the nokeep() flag is set to true. In this way, temporary files can be removed without explicit use of the erase() method. (Just need to use the nokeep() method after the file() method has been used to update the current filename).
Method to determine whether the Frame file() exists on disk or not. Returns true if the
file is there, false otherwise. Effectively equivalent to using -e but allows for the
possibility that the information stored in file() does not directly relate to the file as stored
on disk (e.g. a .sdf extension). The base class is very simplistic (ie does not assume
extensions).
The optional argument refers to the file number.
Determine the raw data filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Returns group name from header. If we cannot find anything sensible, we return 0. The group name stored in the object is automatically updated using this value.
Find the number of sub-frames associated with the frame by looking in the header. Usually run by configure().
In the base class this method looks for a header keyword of ’NSUBS’.
The state of the object is updated automatically.
Method to determine the recipe name that should be used to reduce the observation. The default method is to look for an "ORAC_DR_RECIPE" entry in the user header. If one cannot be found, we assume QUICK_LOOK.
The object is automatically updated to reflect this recipe.
Groups files in a Frame object by the value of a particular header item or items. Returns a list that can be stored in a hash with the concatenated header values as the key and a reference to an array of file names as the value. If there is no subheader all the files in the frame will be returned indexed by the concatenated values of the headers.
Undefined values in subheaders will be treated as if they had the value "undef".
It is an error to call this method if the number of files in the frame does not match the number of subheaders.
Determine the name of the flag file given the variable component parts. A prefix (usually UT) and observation number should be supplied
This method should be implemented by a sub-class.
Method to return the number of the observation. The number is determined by looking for a number at the end of the raw data filename. For example a number can be extracted from strings of the form textNNNN.sdf or textNNNN, where NNNN is a number (leading zeroes are stripped) but not textNNNNtext (number must be followed by a decimal point or nothing at all).
The return value is -1 if no number can be determined.
As an aside, an alternative approach for this method (especially in a sub-class) would be to read the number from the header.
Determine the pattern for the raw filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Returns a regular expression object.
Method to change the current filename of the frame (file()) so that it matches a template. e.g.:
Would change the first file to match "something_number_flat". Essentially this simply means that the number in the template is changed to the number of the current frame object.
would change the second filename to match "something_number_dark". The base method assumes that the filename matches the form: prefix_number_suffix. This must be modified by the derived classes since in general the filenaming convention is telescope and instrument specific.
The Nth filename is modified (ie file(N)). There are no return arguments.
Copyright (C) 1998-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
Copyright (C) 2007 Science and Technology Facilities Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Class for dealing with frames based on NDF files
This class provides implementations of the methods that require knowledge of the NDF file format rather than generic methods or methods that require knowledge of a specific instrument. In general, the specific instrument sub-classes will inherit from the file type (which inherits from ORAC::Frame) rather than directly from ORAC::Frame. For JCMT and UKIRT the group files are based on NDFs and inherit from this class.
The format specific sub-classes do not contain constructors; they should be defined in either the base class or the instrument specific sub-class.
The following methods are modified from the base class versions. General Methods
Erase the current file from disk.
The optional argument specifies the file number to be erased. The argument is identical to that given to the file() method. Returns ORAC__OK if successful, ORAC__ERROR otherwise.
Note that the file() method is not modified to reflect the fact the the file associated with it has been removed from disk.
This method is usually called automatically when the file() method is used to update the current filename and the nokeep() flag is set to true. In this way, temporary files can be removed without explicit use of the erase() method. (Just need to use the nokeep() method after the file() method has been used to update the current filename).
Can support paths to HDS objects. If the last object is removed from an HDS container file, the entire container file is removed.
Checks for the existence of the frame file(). Assumes a .sdf extension.
The optional argument specifies the file number to be used. All extension are removed from the
file name before adding the .sdf so that HDS containers can be supported (and files that already
have the extension) -- but note that this version of the method does not look inside HDS
containers looking for NDFs.
Method to return the current input filename and the new output filename given a suffix. Copes with non-existence of HDS container and handles NDF subframes on the assumption that any NDF with a "." in it must be referring to an HDS component.
The suffix is appended to the root filename derived from the characters before the first ".". Note that this uses the ORAC-DR standard, replacing the first non-numeric suffix.
The following logic is applied when propogating HDS containers:
If you want to retain the HDS container syntax, this routine has to be fooled into thinking that nfiles is greater than 1 (eg by adding a dummy file name to the frame).
Returns $out in a scalar context:
Returns $in and $out in an array context:
The second (optional) argument is used to specify which of the input filenames should be used to generate an output name. This number is forwarded to the file() method and defaults to 1 (ie the first frame).
If a value of 0 is provided, the output name is derived assuming the NFILES=1 rule described above. This allows the output file name to be derived correctly in the many-to-one scenario.
Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
UKIRT class for dealing with observation files in ORAC-DR
This module provides methods for handling Frame objects that are specific to UKIRT. It provides a class derived from ORAC::Frame::NDF. All the methods available to ORAC::Frame objects are available to ORAC::Frame::UKIRT objects.
The following methods are available in this class in addition to those available from ORAC::Frame. General Methods
Determine the raw data filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
The $obsnum is zero padded to 5 digits.
pattern_from_bits() is currently an alias for file_from_bits(), and both can be used interchangably in the UKIRT subclass.
Determine the name of the flag file given the variable component parts. A prefix (usually UT) and observation number should be supplied
This generic UKIRT version returns back the observation filename (from file_from_bits) , adds a leading "." and replaces the .sdf with .ok
Method to return the current input filename and the new output filename given a suffix. Copes with non-existence of HDS container and handles NDF subframes
The following logic is applied:
If you want to retain the HDS container syntax, this routine has to be fooled into thinking that nfiles is greater than 1 (eg by adding a dummy file name to the frame).
Returns $out in a scalar context:
Returns $in and $out in an array context:
ORAC::Group, ORAC::Frame::NDF, ORAC::Frame
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
WFCAM class for dealing with observation files in ORAC-DR with Starlink software.
This module provides methods for handling Frame objects that are specific to WFCAM, allowing them to be reduced using Starlink software. It provides a class derived from ORAC::Frame::WFCAM. All the methods available to ORAC::Frame::WFCAM objects are available to ORAC::Frame::WFCAM objects. Some additional methods are supplied.
The following methods are available in this class in addition to those available from ORAC::Frame::WFCAM. Constructor
Create a new instance of a ORAC::Frame::WFCAM object. This method also takes optional arguments: if 1 argument is supplied it is assumed to be the name of the raw file associated with the observation. If 2 arguments are supplied they are assumed to be the raw file prefix and observation number. In any case, all arguments are passed to the configure() method which is run in addition to new() when arguments are supplied. The object identifier is returned.
The constructor hard-wires the ’.sdf’ rawsuffix and the prefix although these can be overriden with the rawsuffix() and rawfixedpart() methods. The prefix depends on the value of the ORAC_INSTRUMENT environment variable; if this is set to WFCAM1, WFCAM2, WFCAM3, or WFCAM4, then the prefix is set to ’w’, ’x’, ’y’, or ’z’, respectively. Otherwise the prefix defaults to ’w’.
Determine the raw data filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Method to propagate the FITS header from an HDS container to an NDF Run after updating $Frm.
Method to return the number of the observation. The number is determined by looking for a number at the end of the raw data filename. For example a number can be extracted from strings of the form textNNNN.sdf or textNNNN, where NNNN is a number (leading zeroes are stripped) but not textNNNNtext (number must be followed by a decimal point or nothing at all).
The return value is -1 if no number can be determined.
As an aside, an alternative approach for this method (especially in a sub-class) would be to read the number from the header.
Internal routine to split a ’file’ name into an actual filename (the HDS container) and the NDF name (the thing inside the container).
Splits on ’.’
Argument: string to split (eg test.i1) Returns: root name, ndf name (eg ’test’ and ’i1’)
NDF name is undef if there are no ’sub-frames’.
This routine is so simple that it may not be worth the effort.
Returns the list of primary header unit keywords @phukeys = $Frm-phukeys;
Returns the list of extension header unit keywords @ehukeys = $Frm-ehukeys;
Copyright (C) 2008 Science and Technology Facilities Council. Copyright (C) 2004-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
JCMT class for dealing with observation files in ORAC-DR.
This module provides methods for handling Frame objects that are specific to JCMT instruments. It provides a class derived from ORAC::Frame::NDF. All the methods available to ORAC::Frame objects are also available to ORAC::Frame::JCMT objects.
The following methods are available in this class in addition to those available from ORAC::Frame. Accessors
Whether or not to allow automatic header synchronization when the Frame is updated
via either the file or files method.
For modern JCMT instruments, defaults to true (1).
Return a value from either the first or last entry in the JCMT STATE structure.
If the supplied keyword does not exist in the JCMT STATE structure, this method returns undef. An optional second argument may be given, and must be either ’start’ or ’end’. If this second argument is not given, then the first entry in the JCMT STATE structure will be used to obtain the requested value.
Both arguments are case-insensitive.
Determine the base position of a data file. If the file name is not provided it will be read from the object.
Returns hash with keys
The latter will be absent if this is an observation of a moving source. In addition, returns sexagesimal strings of the base position as
Returns the group name from the header or a string formed automatically on observation metadata.
An optional argument can be provided which will be appended to the group name. This can be used by subclasses to provide additional information required to disambiguate groups. This string is only used if the group identifier is not present in the DRGROUP header.
The group name stored in the object is automatically update using this value.
Find the number of sub-frames associated by the frame by looking at the list of raw files associated with object. Usually run by configure().
The state of the object is updated automatically.
ORAC::Group, ORAC::Frame::NDF, ORAC::Frame
Copyright (C) 2009 Science and Technology Facilities Council. All Rights Reserved.
Class for dealing with ACSIS observation frames.
use ORAC::Frame::ACSIS;
$Frm = new ORAC::Frame::ACSIS(@filenames); $Frm-file("file"); $Frm-readhdr; $Frm-configure; $value = $Frm-hdr("KEYWORD");
This module provides methods for handling Frame objects that are specific to ACSIS. It provides a class derived from ORAC::Frame::NDF. All the methods available to ORAC::Frame objects are available to ORAC::Frame::IRIS2 objects.
The following methods are available in this class in addition to those available from ORAC::Frame. Constructor
Create a new instance of an ORAC::Frame::ACSIS object. This method also takes optional arguments:
In any case, all arguments are passed to the configure() method which is run in addition to new() when arguments are supplied.
The object identifier is returned.
The constructor hard-wires the ’.sdf’ rawsuffix and the ’a’ prefix, although these can be overridden with the rawsuffix() and rawfixedpart() methods.
This method is used to configure the object. It is invoked automatically if the new() method is invoked with an argument. The file(), raw(), readhdr(), findgroup(), findrecipe() and findnsubs() methods are invoked by this command. Arguments are required. If there is one argument it is assumed that this is a reference to an array containing a list of raw filenames. The ACSIS version of configure() cannot take two parameters, as there is no way to know the location of the file that would make up the Frame object from only the UT date and run number.
Returns the keys that should be used for determining whether files from a single observation should be treated independently.
For ACSIS a single frame object is returned for single sub-system observations and multiple frame objects returned in multi-subsystem mode. One caveat is that if the multi-subsystem mode looks like a hybrid mode (bandwidth mode and IF frequency identical) then a single frame object is returned.
This implementation includes an additional reference to an array containing alternate keys. ACSIS data uses IFFREQ to determine whethere subbands should be merged whereas DAS data uses SPECID.
There is no file_from_bits() for ACSIS. Use pattern_from_bits() instead.
Extra information that can be supplied to the Group file_from_bits methods when constructing the Group filename.
Determine the name of the flag file given the variable component parts. A prefix (usually UT) and observation number should be supplied.
For ACSIS the flag file is of the form .aYYYYMMDD_NNNNN.ok, where YYYYMMDD is the UT date and NNNNN is the observation number zero-padded to five digits. The flag file is stored in $ORAC_DATA_IN.
Returns the group name from the header.
The group name stored in the object is automatically updated using this value.
Similar to base class except the frame number is appended to the output suffix.
Determine the association ID to be used for the JCMT Science Archive to collect the "public"
products. This is written in plain text as it will be short enough to not require an md5sum to be
taken as is the case for asn_id().
This contains the components necessary to distinguish the desired "public" co-adds as
determined by the instrument scientist. It does not contain the tile number. Instead it identifies
the whole association -- i.e. all the public data for a particular set of configurations which we can
co-add. The wrapper script (jsawrapdr) will call the JSA::Headers::CADC::correct_asn_id()
subroutine to add the tile number to this at a later stage.
Returns "undef" on failure (e.g. for an unsupported instrument or for configurations which the instrument scientist has decided to reject).
Determine the pattern for the raw filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Returns a regular expression object.
Method to return the number of the observation. The number is determined by looking for a number after the UT date in the filename. This method is subclassed for ACSIS.
The return value is -1 if no number can be determined.
Subsystem identifier. For ACSIS this is the rest frequency, bandwidth mode and first subsystem number.
Methods specifically for ACSIS.
List of subsysnumbers in use for this frame. If there is more than one subsystem number this indicates a hybrid mode.
In scalar context returns the total number of subsystems.
Attempt to determine the rest frequency. Returns undef on failure.
Intended to maintain the historical behavior of findgroup in order that the nightly association
IDs do not change:
The first parameter can be set to a true value to allow the rest frequency to be determined by averaging FRQSIGLO and FRQSIGHI. This is just for the historical behavior mentioned above, and should not be used if a real rest frequency is required.
Copyright (C) 2008 Science and Technology Facilities Council. Copyright (C) 2004-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
SCUBA class for dealing with observation files in ORACDR
This module provides methods for handling Frame objects that are specific to SCUBA. It provides a class derived from ORAC::Frame. All the methods available to ORAC::Frame objects are available to ORAC::Frame::SCUBA objects. Some additional methods are supplied.
The following are modifications to standard ORAC::Frame methods. Constructors
Create a new instance of a ORAC::Frame::SCUBA object. This method also takes optional arguments: if 1 argument is supplied it is assumed to be the name of the raw file associated with the observation. If 2 arguments are supplied they are assumed to be the raw file prefix and observation number. In any case, all arguments are passed to the configure() method which is run in addition to new() when arguments are supplied. The object identifier is returned.
This method runs the base class constructor and then modifies the rawsuffix and rawfixedpart to be ’.sdf’ and ’_dem_’ respectively.
This method calculates header values that are required by the pipeline by using values stored in the header.
This method calculates WVM statistics in addition to calling the standard base class calculations.
This method updates the frame header. Returns a hash containing the new keywords.
This method is used to configure the object. It is invoked automatically if the new() method is invoked with an argument. The file(), raw(), readhdr(), findgroup(), findrecipe(), findsubs() findfilters() and findwavelengths() methods are invoked by this command. Arguments are required. If there is one argument it is assumed that this is the raw filename. If there are two arguments the filename is constructed assuming that arg 1 is the prefix and arg2 is the observation number.
The sub-instrument configuration is also stored.
Determine the raw data filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
pattern_from_bits() is currently an alias for file_from_bits(), and both can be used interchangably for SCUBA.
Determine the flag filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
The format is ".20021001_dem_0001"
Return the group associated with the Frame. This group is constructed from header information. The group name is automatically updated in the object via the group() method.
The group membership can be set using the DRGROUP keyword in the header. If this keyword exists and is not equal to ’UNKNOWN’ the contents will be returned.
Alternatively, if DRGROUP is not specified the group name is constructed from the MODE, OBJECT and FILTER keywords. This may cause problems in the following cases:
Bottom line is the following (I think).
In all cases the actual position in RJ coordinates should be calculated (taking into account RB-RJ and GA-RJ and map_x map_y, local_coords) using Astro::PAL. Filter should also be matched as now. Planets will be special cases - matching on name rather than position.
PHOTOM observations
JIGGLE MAP
SCAN MAP
The group name will then use the position with a number of significant figures changing depending on the position tolerance.
Forces the object to determine the number of sub-instruments associated with the data by looking in the header (hdr()). The result is stored in the object using nsubs().
Unlike findgroup() this method will always search the header for the current state.
Return the recipe associated with the frame. The state of the object is automatically updated via the recipe() method.
The recipe is determined by looking in the FITS header of the frame. If the ’DRRECIPE’ is present and not set to ’UNKNOWN’ then that is assumed to specify the recipe directly. Otherwise, header information is used to try to guess at the reduction recipe. The default recipes are keyed by observing mode:
So called "wide" photometry is treated as a map (although this depends on the name of the jiggle pattern which may change).
In future we may want to have a separate text file containing the mapping between observing mode and recipe so that we dont have to hard wire the relationship.
This method is identical to the base class template method except that only files matching the specified sub-instrument are affected.
If no sub-instrument is specified then the first file name is modified
Note that this is different from the base class which accepts a file number as the second argument. This may need some rationalisation.
This section describes methods that are available in addition to the standard methods found in ORAC::Frame. Accessor Methods The following extra accessor methods are provided:
Return or set the filter names associated with each sub-instrument in the frame.
Return or set the names of the sub-instruments associated with the frame.
Return or set the wavelengths associated with each sub-instrument in the frame.
Given a file index, (see file()) returns the associated sub-instrument.
Returns the first sub name if index is too large. This assumes that the file names associated wth the object are linked to sub-instruments (as returned by the subs method). It is up to the primitive writer to make sure that subs() tracks changes to files().
Forces the object to determine the names of all sub-instruments associated with the data by looking in the hdr().
The result is stored in the object using filters(). The sub-inst filter name is made to match the filter name such that a filter of ’450w:850w’ has filter names of ’450W’ and ’850W’ despite the entries in the header being simply ’450’ and ’850’. Photometry filter names are not modified.
Unlike findgroup() this method will always search the header for the current state.
Forces the object to determine the names of all sub-instruments associated with the data by looking in the header (hdr()). The result is stored in the object using subs().
Unlike findgroup() this method will always search the header for the current state.
Forces the object to determine the names of all sub-instruments associated with the data by looking in the header (hdr()). The result is stored in the object using wavelengths().
Unlike findgroup() this method will always search the header for the current state.
Given a sub instrument name returns the associated file index. This is the reverse of sub2file. The resulting value can be used directly in file() to retrieve the file name.
A case insensitive comparison is performed.
Returns 1 if nothing matched (ie just returns the first file in file(). This is probably a bug.
Assumes that changes in subs() are reflected in files().
Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
SCUBA-2 class for dealing with observation files in ORACDR
This module provides methods for handling Frame objects that are specific to SCUBA-2. It provides a class derived from ORAC::Frame. All the methods available to ORAC::Frame objects are available to ORAC::Frame::SCUBA2 objects. Some additional methods are supplied.
The following are modifications to standard ORAC::Frame methods. Constructors
Create a new instance of a ORAC::Frame::SCUBA2 object. This method also takes optional arguments: if 1 argument is supplied it is assumed to be the name of the raw file associated with the observation but if a reference to an array is supplied, each file listed in the array is used. If 2 arguments are supplied they are assumed to be the raw file prefix and observation number. In any case, all arguments are passed to the configure() method which is run in addition to new() when arguments are supplied. The object identifier is returned.
This method runs the base class constructor and then modifies the rawsuffix and rawfixedpart to be ’.sdf’ and ’s4’ or ’s8’ (depending on instrument designation) respectively.
Configure the frame object. Usually called from the constructor.
Can be called either with a single filename or a reference to an array of filenames
For SCUBA-2 a single frame object is returned in most cases. For focus observations each focus position is returned as a separate Frame object. This simplifies the recipes and allows the QL and standard recipes to work in the same way.
Observation ID is also kept separate in case the pipeline gets so far behind that the system detects the end of one observation and the start of the next.
Determine the raw data filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Not implemented for SCUBA-2 because of the multiple files that can be associated with a particular UT date and observation number: the multiple sub-arrays (a to d) and the multiple subscans.
Method to return extra information to be used in the file name. For SCUBA-2 this is a string
representing the wavelength. See also the subsystem_id method which currently returns the
same thing but with units included.
Acts like the base class inout method unless the uhdr entry ALLOW_NUMBERED_SUFFICES is set, in
which case, if the file already has a suffix including a 3-digit number, that number is preserved in
the suffix of the new file.
This is not quite the same as the corresponding method in the ACSIS frame class because we don’t assume that the number in the suffix is the same as the file number within the frame -- there could be multiple files with the same suffix number, e.g. from different subarrays.
Determines the pattern for the flag file. This differs from other instruments in that SCUBA-2 writes the flag files to ORAC_DATA_IN but the data are written to completely distinct trees (not sub directories of ORAC_DATA_IN).
Returns a regular expression object.
Method to return the number of the observation. The number is determined by looking for a number after the UT date in the filename. This method is subclassed for SCUBA-2 to deal with SCUBA-2-specific filenames.
The return value is -1 if no number can be determined.
Method to return the subsystem identifier. For SCUBA-2 this is a string representing the wavelength.
Determine the flag filename given the variable component parts. A prefix (usually UT) and observation number should be supplied.
Returns multiple file names (one for each array) and throws an exception if called in a scalar context. The filename returned will include the path relative to ORAC_DATA_IN, where ORAC_DATA_IN is the directory containing the flag files.
The format is "swxYYYYMMDD_NNNNN.ok", where "w" is the wavelength signifier (’8’ for 850 or ’4’ for 450) and "x" a letter from ’a’ to ’d’.
Return the group associated with the Frame. This group is constructed from header information. The group name is automatically updated in the object via the group() method.
Return a hash with subarray names as keys and values containing a list (array reference) of the associated file names.
Return the name of the subarray which corresponds to the instrument aperture at the current wavelength.
Determine the association ID to be used for the JCMT Science Archive to collect the "public"
products. This is written in plain text as it will be short enough to not require an md5sum to be
taken as is the case for asn_id().
Currently the same as subsystem_id but implemented separately so that changes to one do not
alter the other.
Search for and return the full path to the meta file associated with the given observation. The meta file is written by the SCUBA-2 data acquisition system and contains the name of the flag files (.ok) in use. The naming convention is "sw_YYYYMMDD_NNNNN.meta", where "w" is the wavelength signifier (’8’ for 850 or ’4’ for 450).
Takes two mandatory arguments which are the file prefix (usually the UT date) and the observation number. Returns undef if no such file exists.
Return the number of subarrays in use. Works by checking for unique subheaders and determining which of the abcd sub-arrays are producing data. Only works once data are read in so ORAC-DR must have some other way of knowing that there are n subarrays.
This method modifies the supplied filename to remove specific subarray designation and replace it with a generic filter designation. 4 digit subscan information is also removed but not if this is a Focus observation or if the data are a fast-ramp flatfield (as there may be multiple fastflats in a single observation).
Should be used when subarrays are merged into a single file.
If the s8a/s4a designation is missing the filename will be returned unchanged.
The output file, or output HDS extension in a container, will be removed by this routine. If no HDS container exists and it looks like one will be required, it is created.
Strip subscan number from supplied filename. This can be used when going from a group of files from a single subarray to a file associated with that subarray but no subscan.
Return the name of the subarray given either a filename or the index into a Frame object. The subarray is also stored in the current Frame uhdr. Takes a mandatory sole argument which is the file index or name. If the Frame header has subheaders then the subarray is obtained from the FITS header of the file rather than assuming the subheader order is synchronized with that of the files. Returns undef if the FITS header could not be retrieved.
Works on the current frame only.
Return a list of the subarrays associated with the current Frame object. Searches the subheaders for presence of SUBARRAY keyword which will be present if data from multiple subarrays are stored in the current Frame. If not found then just use the SUBARRAY entry in the hdr.
Returns an list. In scalar context returns the number of subarrays.
Return a list of supported arguments for makemap which may be specified as recipe parameters. Returns array or array reference depending on calling context.
The supported arguments are (currently): alignsys, config, crota, maxmem, method, pixsize, spread, system.
Retrieve files in the current Frame which have a sequence type of FASTFLAT.
Returns an array, which will be empty if no fast-ramp flatfield files could be found.
The difference between the end of the last science sequence and the start of the first science sequence. This is not quite the same as the duration of the observation because it will not include initial/trailing darks and ramps.
Returns the duration in seconds.
To calculate the duration of the observation as a whole use ORAC_UTSTART and ORAC_UTEND uhdrs.
Standard image-based DREAM and STARE processing has no need for dark frames and so these should be filtered out as early as possible to prevent weird errors. The translated header for the observation mode is used. From this point on, no dark frames will be returned unless the user accesses the raw data.
Copyright (C) 1998-2005 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Simple perl subroutines that may be useful for primitives
This module provides simple perl functions that are not available from standard perl. These are available to all ORAC primitive writers, but they are general in nature and have no connection to orac. Some of these are used in the ORAC infastructure, so ORACDR does require this library in order to run.
Return the cosine of the angle. The angle must be in degrees.
Return the sine of the angle. The angle must be in degrees.
Convert decimal angle (degrees or hours) to degrees, minutes and seconds. (or hours).
Convert hours:minutes:seconds to decimal hours.
Determine whether the supplied argument is a number or not. Returns true if it is and false otherwise.
Find the minimum value of an array. Can also be used to find the minimum of a list of scalars since arguments are passed into the subroutine in an array context.
Find the maximum value of an array. Can also be used to find the maximum of a list of scalars since arguments are passed into the subroutine in an array context.
Returns the logarithm to base ten of a scalar.
Currently uses the implementation of log10 found in the POSIX module
Return the nearest integer to a supplied floating point value. 0.5 is rounded up.
Return the UT date (strictly, GMT) date in the format yyyymmdd
Takes a string of comma-separated key-value pairs and return a hash.
The keys are down-cased.
Values can be quoted or bracketed. If values include commas themselves they will be returned as array references, e.g.
will return the following.
Note that delimiters are removed from the values and that if only a single element is quoted it will be returned as a scalar string rather than an array.
Converts a comma separated list of observation numbers (as supplied on the command line for the -list option) and converts it to an array of observation numbers. Colons are treated as range arguments.
For example,
is converted to
Convert a hash as returned by ORAC::Recipe::PrimitiveParser-_parse_prim_arguments into a string that can be output for logging.
Frame objects passed in will be stringified to "Frame::class". Group objects passed in will be stringified to "Group::class". Undefined variables will be stringified to "undef".
Given either a filename or an ORAC::TempFile object, read the contents (usually filenames) and return a list. Blank lines and anything after a # comment character are ignored.
Returns array or array reference depending on calling context. Returns undef if the given file does not exist.
Given an array of file names, open a temp file, write the filenames to it and return the name of the file. The returned object stringifies to the actual filename. It must be returned as an object so that the temp file will be deleted automatically when the variable goes out of scope.
Suitable for creating a file to be used for Starlink application group parameters.
Note that overwriting the return value (by, say, string concatenation) runs the destructor which unlinks the temporary file.
Write an input indirection file and an output indirection file using the supplied file suffix.
The first argument is the frame or group object that will be used for the inout() method and the second argument is the suffix to be supplied to the inout() method. The names of the derived output files are returned in the list. The object is not updated automatically.
If the third (optional) argument is true the output files will be pushed onto the intermediates array associated with the supplied frame/group object. This ensures the files will be cleared up even if they are not output from a primitive. If istmp is true, the output files are not returned to the caller.
Create a hard link from an input file to an output file.
If $out exists, then it will be overwritten by the link.
Returns 1 if successful, 0 otherwise, and puts the error code into $!.
Convert the standard ORACTIME format date (YYYYMMDD.frac) to a modified Julian day.
Convert the standard ORACTIME format date (YYYYMMDD.frac) to an ISO format string.
Convert the standard ORACTIME format date (YYYYMMDD.frac) to a DateTime object.
Prepare a string for use in Starlink command lines, such that the string may be passed to a character parameter without losing any quotation marks within the string. This will typically be passed to an NDF character component.
Performs this by doubling any quotation marks present within the string, and escaping these too, if necessary. This should be used where the string is a priori unknown and may contain quotes such as those to represent arcseconds and arcminutes, or a possessive like "Barnard’s Loop". A common example is a user-defined object name.
$single should be true if the string has been wrapped in single quotes. For example,
Otherwise it is assumed to have been enclosed in double quotes. For example,
Copyright (C) 2008 Science and Technology Facilities Council. Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
Base class for dealing with observation groups in ORAC-DR
This module provides the basic methods available to all ORAC::Group objects. This class should be used when storing information relating to a group of observations processed in the ORAC-DR data reduction pipeline.
Groups are composed of frame objects (ORAC::Frame) or objects that can perform those methods.
The following methods are available in this class. Constructors The following constructors are available:
Create a new instance of a ORAC::Group object. This method takes an optional argument containing the identifier of the new group. The object identifier is returned.
The base class constructor should be invoked by sub-class constructors. If this method is called with the last argument as a reference to a hash it is assumed that this hash contains extra configuration information (’instance’ information) supplied by sub-classes.
Initialise the object.
Method to return a new group (ie a sub-group of the existing group) that contains all members of the main group matching certain header values.
Arguments is a hash that is used for comparison with each frame.
The new subgrp is blessed into the same class as $Grp. All header information (hdr() and uhdr()) is copied from the main group to the sub-group.
This method is generally used where access to members of the group by some search criterion is required.
It is possible that the returned group will contain no members....
If the value looks like a number a numeric comparison will be performed. Else a string comparison is used.
Returns frames grouped by the supplied header keys. A frame can not belong to more than one sub group created by this method:
The groups in @grps are blessed into the same class as $Grp. For example, if @keys = (’MODE’,’CHOP’) then you can gurantee that the members of each sub group will have the same values for MODE and CHOP.
All header information from the main group is copied to the sub groups.
If a key is not present in the headers then all the frames will be returned in a single subgrp (since that group guarantees that the specified header item is not different - it simply is not there).
The order of the subgroups will match the position of the first member in the original group.
Set or retrieve the array containing the current group membership.
The setting function of this routine should only be used if you know what you are doing (since it completely changes the group membership). If setting the contents, the check_membership() method is run automatically so that the list of valid members can remain synchronized.
All group members are returned regardless of the state of each member. Use the members() method to return only valid members.
If called in a scalar context, a reference to an array is returned rather than the array.
Do not use this array reference to change the contents of the array directly unless the check_membership() method is run immediately afterwards. The check_membership() method is responsible for checking the state of each member and copying them to the members() array.
Removes all frames from the group. Can be used to reduce the memory footprint of the pipeline when a recipe is designed such that it never needs to go back to the original members. An optional argument may be given to indicate that the last Frame object should be retained.
Return (or set) the index object associate with the bad observation index file. A index of class ORAC::Index::Extern is used since this index is modified by an external user/program.
The index is created automatically the first time this method is invoked.
Return (or set) the array containing the list of frame numbers that have been coadded into the current group. This is not necessarily the same as the return of the membernumbers() method since that can return numbers for all the members of the group even if the full coaddition has not taken place or the pipeline has been resumed partway through a coaddition (in which case the coadds array will contain more numbers than are in the group).
Returns an array reference in a scalar context, an array in an array context.
The contents of this array are not automatically written to the group file when changed, see the coaddspush() or coaddswrite() methods for further information on object persistence. The array is simply meant as a storage area for the pipeline.
Set or retrieve the filename suffix associated with the reduced group.
Set or retrieve the part of the group filename that does not change between invocation. The output filename can be derived using this.
Whether or not the current object is an ORAC::Frame object.
Returns 0 for Group objects.
Retrieve the array containing the valid objects within the group
This is the safest way to access the group members since it only returns valid frames to the caller.
Use the allmembers() method to return all members of the group regardless of the state of the individual frames.
Group membership should not be set using ths method since that may lead to a situation where the actual membership of the group does not match the selected membership. [Valid group membership should only be set from within this class].
If called in a scalar context, a reference to an array is returned rather than the array.
Retrieve or set the name of the group.
If no name is set but is retrieved, a name string will be set automatically based on the first frame in the group.
Set or retrieve the group identifier. This will be the string derived from the OBSERVATION_GROUP header of the first input frame object.
Check whether any of the members of the group have been marked for removal from the group. The valid group members are copied to a new array and can be retrieved by the members() method. Note that all group methods use the list of valid group members.
This routine is automatically run whenever the group membership is updated (via the push() or allmembers() methods. This may cause too high an overhead with push() in, for example, the subgrps method).
This method works by looking in a text file created by the observer in $ORAC_DATA_OUT called index.badobs. This file contains a list of numbers (two per line) relating to observations that should be turned off. The first number is the UT date (YYYYMMDD) and the second number is the observation number. This is necessary so that ORAC_DATA_OUT can be reused for a different UT date without worrying about the index file file turning off incorrect observations.
The UT and observation number are compared with each member of the group (the full list of members - see allmembers()). For each group member, the following test is performed to test for validity. First it is queried to check whether it is in a good state (ie has been processed successfully). A frame will be marked as bad if the recipe fails to execute successfully. If the frame is good (from the pipeline viewpoint) the UT date and observation number is then compared with the entries in the index file. If a match can NOT be found the frame is considered to be valid and is copied to the list of valid group members (see the members() method).
The format of the index file should be of the form:
This method returns a list, the first element being an array reference to the good members, and the second being an array reference to the bad (or removed) members. Hidden members (negative isgood()) will not be returned.
Used to push observation numbers onto the coadds() array. Automatically runs coaddswrite() to update to sync the file contents with the coadds() array.
Compares the contents of the coadds() array with the supplied (single) argument. Returns true if the argument is present in the coadds() array, false otherwise. Also, returns false if no arguments are supplied or if the argument is undef.
Reads the coadds() information from the current group file and stores it in the group using the coadds() method. Should return ORAC__OK if the coadds information was read successfully, else returns ORAC__ERROR.
This is an abstract method and should be defined by a subclass.
Method to write the contents of the coadds() array to the current group file. Should return ORAC__OK if the coadds information was written successfully, else returns ORAC__ERROR.
If coadds() contains no entries, all coadds information is removed from the group file if present.
This is an abstract method and should be defined by a subclass.
Erases the group file from disk.
Returns ORAC__OK if successful, ORAC__ERROR otherwise.
Method to determine whether the group file() exists on disk or not. Returns true if the file is
there, false otherwise. Effectively equivalent to using -e but allows for the possibility that the
information stored in file() does not directly relate to the file as stored on disk (e.g. a .sdf
extension).
Method to return the group filename derived from a fixed variable part (eg UT) and a group designator (usually obs number). The full filename is returned (including suffix).
For the base class the return string is of the format
For example, with IRCAM using a UT date of 980104 and observation number 25 the returned string would be ’rg980104_25.sdf’.
Method to return the group filename using the name() method of the current Group object. The full filename is returned (including suffix).
If the name() has not been initialized, then this method returns undef. Otherwise, it removes all hashes in the string returned by name() and replaces them with underscores.
The fixedpart() and filesuffix() are prepended and appended, respectively.
Retrieve the nth frame of the group. Counting starts at 0 as for a standard perl array.
This is equivalent to
A second argument can be used to set the nth frame.
Note that this replaces the nth frame in the list of valid members and also replaces the equivalent frame in the list of all members of the group. This is done since the nth valid member is not necessarily the nth group member. If the supplied position is greater than the current number of members the supplied frame is simply pushed onto the array. Remember that just because a frame has been inserted into the group does not necessarily mean that it will be a valid member (check_membership() will be run when setting any member of the group). If the current frame at the specified position can not be found in allmembers() the supplied frame is pushed onto allmembers() and membership is re-checked.
Method to return the current filenames for each frame in the group (similar to the membernames() method) and a set of output names for each file. This is achieved by calling the inout() method for each frame in turn. This will fail if the members of the group do not possess the inout() method.
This method can take two arguments: the new suffix and, optionally, the file number to use (see the inout() documentation for ORAC::Frame). References to two arrays are returned when called in an array context; returns the output array ref when called from a scalar context
Method to determine whether the supplied argument matches the first member of the group. Returns a 1 if it is the first member and a zero otherwise.
Method to determine whether the supplied argument matches the last good member of the group. Returns a 1 if it is the last member and a zero otherwise.
If there are no good members in the group, returns false.
Method to determine whether the supplied argument matches the last member of the group. This method differs from lastmember() in that this method does not care about badness, i.e., it looks at the allmembers() list instead of the members() list.
Returns true if the supplied argument is the last member, and false otherwise.
Given a frame, determines what position this frame has in the group. This is useful in Batch mode processing where the groups are pre-populated.
Index starts counting at 0 (see the frame method) and refers only to valid members rather than
all members. If the frame is not in the group, returns undef.
Return a list of all the files associated with the group. This is achieved by invoking the file() method for each object stored in the Members array. For this to work each member must be an object capable of invoking the file() method (e.g. ORAC::Frame). Currently the routine does not check to make sure this is possible - the program will die if you try to use a SCALAR member.
If an argument list is given the file names for each member of the group are updated. This will only be attempted if the number of arguments given matches the number of members in the group.
Only the first file from each frame object is returned.
Return a list of all the observation numbers associated with the group. This is achieved by invoking the number() method for each object stored in the Members array. For this to work each member must be an object capable of invoking numbers() (e.g. ORAC::Frame). Currently the routine does not check to make sure this is possible - the program will die if you try to use a SCALAR member.
Set the tag in each of the members.
Runs the tagset method on each of the member frames.
Note that $Grp-tagset() is used for the group filenames not the input files from Frame objects.
Run the tagretrieve() method for each of the members.
Note that $Grp-tagretrieve() is used for the group filenames not the input files from Frame objects.
Return the number of frames in a group minus one. This is identical to the $# construct.
Method to push an observation into the group. Multiple observations can be pushed on at once (see perl "push()" command).
There are no return arguments.
Method to change all the current filenames in the group so that they match the supplied template. This method invokes the template() method for each member of the group.
A second argument can be specified to modify the specified frame number rather than simply the first (see the template() method in ORAC::Frame for more details):
There are no return arguments. The intelligence for this method resides in the individual frame objects.
This method updates the current filename of each member of the group when supplied with a suffix (and optionally, a file number -- see the inout() method in ORAC::Frame for more information). The inout() method (of the individual frame) is invoked for each member to generate the output name.
This can be used to update the member filenames after an operation has been applied to every file in the group. Alternatively the membernames() method can be invoked with the output of the inout() method.
These methods are provided for compatibility with the ORAC display system.
Returns the identification string that is used to compare the current frame with the frames selected for display in the display definition file.
In the default case, this method returns everything after the last suffix stored in file().
In some derived implementation of this method an argument may be used so that multiple IDs can be extracted from objects that contain more than one output file per observation.
Copyright (C) 2007-2008 Science and Technology Facilities Council. Copyright (C) 1998-2004, 2006-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Class for dealing with groups based on NDF files
This class rovides implementations of the methods that require knowledge of the NDF file format rather than generic methods or methods that require knowledge of a specific instrument. In general, the specific instrument sub-classes will inherit from the file type (which inherits from ORAC::Group) rather than directly from ORAC::Group. For JCMT and UKIRT the group files are based on NDFs and inherit from this class.
The format specific sub-classes do not contain constructors; they should be defined in either the base class or the instrument specific sub-class.
The following methods are modified from the base class versions. General Methods
Method to read the COADDS information from the group file. If the Group file exists, the file is opened and the .ORAC extension is located. The .COADDS component (ie groupfile.MORE.ORAC.COADDS) is then opened as _INTEGER and the contents are stored in the group using the coadds() method. If a .MORE.ORAC.COADDS component can not be found (e.g. because the file or component do not exist), the routine returns ORAC__ERROR, else returns ORAC__OK.
There are no arguments.
Writes the current contents of coadds() into the current group file(). Returns ORAC__OK if the coadds information was written successfully, else returns ORAC__ERROR.
There are no arguments. The information is written to a .ORAC.COADDS component in the Group file. If coadds() contains no entries, all coadds information is removed from the group file if present (and good status is returned). A .ORAC extension is always made if one does not exist and the file is present.
This module requires the NDF module.
Copyright (C) 1998-2002 Particle Physics and Astronomy Research Council. All Rights Reserved.
Base class for dealing with groups from UKIRT instruments
This class provides UKIRT specific methods for handling groups.
Copyright (C) 1998-2002 Particle Physics and Astronomy Research Council. All Rights Reserved.
Class for dealing with WFCAM observation groups in ORAC-DR
This module provides methods for handling group objects that are specific to WFCAM. It provides a class derived from ORAC::Group::UFTI. All the methods available to ORAC::Group objects are available to ORAC::Group::WFCAM objects.
The following methods are available in this class in addition to those available from ORAC::Group. Constructor
Create a new instance of a ORAC::Group::WFCAM object. This method takes an optional argument containing the name of the new group. The object identifier is returned.
This method calls the base class constructor but initialises the group with a file suffix of ’.sdf’ and a fixed part of ’g’.
Copyright (C) 2008 Science and Technology Facilities Council. Copyright (C) 2004-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
ACSIS class for dealing with observation groups in ORAC-DR
This module provides methods for handling group objects that are specific to ACSIS. It provides a class derived from ORAC::Group::NDF. All the methods available to ORAC::Group objects are available to ORAC::Group::ACSIS objects.
The following methods are available in this class in addition to those available from ORAC::Group. Constructor
Create a new instance of an ORAC::Group::ACSIS object. This method takes an optional argument containing the name of the new group. The object identifier is returned.
This method calls the base class constructor but initialises the group with a file suffix if ".sdf" and a fixed part of "ga".
Method to return the group filename derived from a fixed variable part (eg UT) and a group designator (usually obs number). The full filename is returned (including suffix).
For ACSIS the return string is of the format
Similar to base class except the frame number is appended to the output suffix. The frame number is padded with zeroes to make it three digits long.
Copyright (C) 2007-2008 Science and Technology Facilities Council. Copyright (C) 2004-2007 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
SCUBA class for dealing with observation groups in ORAC-DR
This module provides methods for handling group objects that are specific to SCUBA. It provides a class derived from ORAC::Group::NDF. All the methods available to ORAC::Group objects are available to ORAC::Group::SCUBA objects. Some additional methods are supplied.
The following methods are available in this class in addition to those available from ORAC::Group. Constructor
Create a new instance of a ORAC::Group::SCUBA object. This method takes an optional argument containing the name of the new group. The object identifier is returned.
This method calls the base class constructor but initialises the group with a file suffix of ’.sdf’ and a fixed part of ’_grp_’.
This is an extension to the default file() method. This method accepts a root name for the group file (independent of sub-instrument) - same as for the base class. If a number is supplied the root name is returned with the appropriate extension relating to the sub-instrument order in the current frame.
The number to sub-instrument conversion uses the last frame in the group to calculate the allowed number of sub-instruments and the order. Note that this may well not be what you want. Use the grpoutsub() method if you know the name of the sub-instrument.
Method to return the group filename derived from a fixed variable part (eg UT) and a group designator (usually obs number). The full filename is returned (including suffix).
Returns file of form UT_grp_00num.sdf
Note that this is the filename before sub-instruments have been taken into account (essentially this is the default root name for file() - the suffix is stripped).
Override the version in the base class since SCUBA group files use a non-standard component order.
Does not use the name method.
The file identification for comparison with the ORAC::Display system. Input argument is the file number (starting from 1).
This routine calculates the current suffix from the group file name base and prepends a string ’gN’ signifying that this is a group observation and the Nth frame is requested (N is less than or equal to nfiles()).
The assumption is that file() returns a root name (ie without a sub-instrument designation). This then allows us to create an ID based on number and suffix without having to chop the sub-instrument name off the end.
This method returns the number of files currently associated with the group. What this in fact means is that it returns the number of files associated with the last member of the group (since that is how I construct output names in the first place). grpoutsub() method is responsible for converting this number into a filename via the file() method.
Local version of inout. This version does not take a numeric argument since that would force
the file() method to return the sub-instrument as part of the name.
Returns all the filenames associated with the group.
Unlike the standard implementation this can not be used to update the list of files since that is derived from the root filename and the sub-instruments.
This section describes methods that are available to the SCUBA implementation of ORAC::Group.
Method to determine the group filename associated with the supplied sub-instrument.
This method uses the file() method to determine the group rootname and then tags it by the specified sub-instrument.
Return list of file names associated with the specified sub instrument.
Returns an array containing all the sub instruments present in the group (some frames may only have one sub-instrument)
The frames should be able to invoke the subs() method.
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
SCUBA2 class for dealing with observation groups in ORAC-DR
This module provides methods for handling group objects that are specific to SCUBA2. It provides a class derived from ORAC::Group::NDF. All the methods available to ORAC::Group objects are available to ORAC::Group::SCUBA2 objects.
The following methods are available in this class in addition to those available from ORAC::Group. Constructor
Create a new instance of an ORAC::Group::SCUBA2 object. This method takes an optional argument containing the name of the new group. The object identifier is returned.
This method calls the base class constructor but initialises the group with a file suffix if ".sdf" and a fixed part of "ga".
Method to return the group filename derived from a fixed variable part (eg UT), a group designator (usually obs number) and the observing wavelength. The full filename is returned (including suffix).
For SCUBA-2 the return string is of the format
where the number is a 5-digit zero-padded integer and the wavelen is either 850 or 450.
Returns all the FITS header values associated with a particular keyword used in all of the Frames that are members of this group (disabled frames are not used).
Calls the hdrvals method in each member and collates the results to remove duplicates. Order is
retained.
Set or retrieve the name of a reference image used to define a coordinate system when
mosaicking. The name of the reference image is stored in the Group uhdr as REFIMAGE_KEY
where KEY is either SKY of FPLANE.
Separate reference images may be defined for on-sky images and focal-plane mosaics as given
by the first (optional) argument. A SKY reference is assumed if not specified when retrieving a
reference. However, the refernce type must be given when storing the name of the reference
image.
Create a new group containing frame objects for the files from each subarray.
This method should only be used in cases where processing by subarray is required (e.g. flatfield and noise observations).
These methods are provided for compatibility with the ORAC display system.
Returns the identification string that is used to compare the current frame with the frames selected for display in the display definition file.
In the default case, this method returns everything after the last suffix stored in file().
In some derived implementation of this method an argument may be used so that multiple IDs can be extracted from objects that contain more than one output file per observation.
Copyright (C) 2005 Particle Physics and Astronomy Research Council. Copyright (C) 2008,2010 Science and Technology Facilities Council. Copyright (C) 2008,2010,2014 University of British Columbia. All Rights Reserved.
Perl routines for manipulating ORAC index files
This module provides subs for manipulating ORAC index files. ORAC index files consist of whitespace seperated columns containing information about a particular frame.
In the case of calibration index files, these may also contain rules for determining the suitability of use for these frames. These consist of code that is TRUE or FALSE depending on appropriate header values of the object to be calibrated.
The following methods are available in this class. Constructor
Create a new instance of an ORAC::Index object.
Any arguments are passed to the configure() method.
Takes an index file and a rules file and sets up the index object
Return (or set) the filename of the index file
Returns true if we are using a valid set of rules, false if the rules were automatically generated from a read of the index file (and therefore contain no clauses for verification).
Return (or set) the filename of the rules file
If the rules file has the magic value of ORAC::Index::NO_RULES a lightweight version of the object will be instantiated that does not do any explicit rules checking. This only works if an index file is being read (since the rules column names will be read from the index file), rather than being freshly created (there will be no columns in the output file!).
Returns or sets the reference to the hash containing the rules
Returns or sets the reference to the hash containing the index
Return all the keys associated with the index file (ie from indexref method. These can then be
used in conjunction with indexentry to obtain the content of the index.
Sets up the index rules in the object. Croaks if it fails. This converts the index rules file into an internal hash that can be retrieved with the rulesref() method.
Sets up the index data in the object. Croaks if it fails. This converts the index file name into an internal hash that can be retrieved using the indexref() method. There is one optional argument. The supplied argument is used to control the behaviour of the read. If the ’usekey’ flag is true the first string in each row (space separated) is used as a key for the index hash.
If ’usekey’ is false the key for each row is created automatically. This is useful for indexes where the contents of the index is more important than any particular key.
Default behaviour (ie no args) is to read the key from the index file (ie usekey=1).
writes out the current state of the index object into the index file
adds an entry to an index
Method to force an append of the specified index entry to the the index file on disk.
$name is the name of the key (indexentry) to use to select the index entry to append [cf the indexentry() method].
This method is intended to be called from the add() method to speed up index read/write when appending a new entry. Do not use this method to write a modified entry to the index file (since the original entry will still be on disk)
No return value.
Convert an index entry (in the index hash) to text suitable for writing to an index file. Called by writeindex() and append_to_index()
Returns the text string (including the entry name but no carriage return).
ARRAY or HASH references are serialised (although the current output format restricts the use of spaces).
Returns a hash containing the key value pairs of the selected index entry.
Input argument is the index entry name (ie the key in the hash that returns the information (in an array).
Returns a hash reference if successful, undef if error.
As an optimization (useful for ORAC::Index::Extern), an index hash can be supplied as the first argument.
verifies a frame (in the form of a hash reference) against a (calibration) index entry (ie by supplying the hash key to the index entry). An optional third argument is available to turn off warning messages -- default is for warning messages to be turned on (true)
Returns undef (error), 0 (not suitable), or 1 (suitable)
Chooses the optimal (nearest in time to an observation) calibration frame from the index hash
Key is the name of the field that should be compared (eg ORACTIME) and %header is the hash containing the header values that are to be compared with the index rules. $warn is an optional third argument that can be used to turn off warning messages from verify (default is to report messages - true).
This method returns the name of the calibration frame closest in time that has met the selection criteria.
If a suitable calibration can not be found an undefined value is returned.
Chooses the calibration frame closest in time from above by looking in the index file (ie difference between the index file entry and the current frame is positive).
Key is the name of the field that should be compared (eg ORACTIME) and %header is the hash containing the header values that are to be compared with the index rules. $warn is an optional third argument that can be used to turn off warning messages from verify (default is to report messages - true).
This method returns the name of the calibration frame closest in time that has met the selection criteria.
This is similar to the choosebydt() method except that only calibrations taken after the current time (read from the header) can be chosen. undef is returned if no suitable calibration frames can be found (eg because we are running on-line and they have not even been taken yet).
Chooses the calibration frame closest in time from below by looking in the index file (ie delta time between the index entry and the current frame is negative).
Key is the name of the field that should be compared (eg ORACTIME) and %header is the hash containing the header values that are to be compared with the index rules. $warn is an optional third argument that can be used to turn off warning messages from verify (default is to report messages - true).
This method returns the name of the calibration frame closest in time that has met the selection criteria.
This is similar to the choosebydt() method except that only calibrations taken before the current time (read from the header) can be chosen. undef is returned if no suitable calibration can be found.
Internal routine for handling calibraion matches using a time difference.
TYPES can be ’ABS’ (chooses the closest calibration in time), ’POSITIVE’ (chooses the closest in time from calibrations earlier than the current header) and ’NEGATIVE’ (chooses calibrations after the current observation [as described by %header]).
KEY, HEADER and WARN are described in the choosebydt() documentation.
Compares each index entry with the values in the supplied hash (supplied as a hash reference). The key to the first matching index entry is returned. undef is returned if no match could be found.
Use the indexentry() method to convert this key into the actual index entry. Note that warning messages are turned off during the verification stage since we are not interested in failed matches.
Returns ’undef’ if no match is found or if no argument is supplied [or that argument itself is undef]
Scan the index file for entries that match the supplied constraints. Only string equality constraints are supported. For more complex scans, consider using the rules system directly.
The return entries are not sorted into any particular order.
Regular expression matching is supported by supplying a string beginning and ending with forward slashes (e.g. ’/^g/’ will match a string starting with ’g’).
Matching against the index entry’s ID (i.e. the first column in an index) can be done by supplying the hash key ’:ID’.
Matching only records more recent than a given ORACTIME can be done by supplying the hash key ’:SINCE’.
Remove an item from an index file
Make sure that the rules and index entry are consistent.
Takes the entry data as argument (does not try to work out that information itself).
Will die if they are inconsistent.
Returns the number of rules.
Returns reference to the sorted list of rule keys.
Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
Routines for generating log files
Provide simple interface to generation of logfiles (eg logging of seeing statistics, photometry results or pointing logs).
The following methods are available:
Create a new instance of ORAC::LogFile and associate it with the specified log file.
If no argument is supplied, the logfile name must be set explcitly by using the logfile() method.
This constructor does not create the logfile itself.
Return or set the name of the logfile associated with this instance. Usually set directly by the constructor.
Control whether a timestamp is prepended to each entry written to the logfile. Default is to not print a timestamp.
The timestamp will be in UT.
Write header information to the file. Header information is only written if the logfile does not previously exist (since if the file exists already a header is not required). If the logfile does not exist the logfile is created by this method and all arguments written to it. A newline character "n" is automatically appended to each line.
Add a log entry. Multiple lines can be supplied (eg as an array). Each line is appended to the logfile (appending a newline "n" character to each and prepending a timestamp if required).
The logfile is closed each time this method is invoked.
Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
This module provides a set of loop handling routines for ORACDR. Each subroutine accepts the same arguments and returns the current observation number (or undef if there was an error or if the loop should be terminated).
A new Frame object is returned of class $class that has been configured for the new file (ie a
$Frm-configure
method has been run)
It is intended that this routine is called inside an infinite while loop with the same @list array. This array is modified by the loop routines so that they can keep track of the ’next’ frame number.
If a filename can not be found (eg it doesnt exist or the list has been processed) undef is returned.
The skip flag is used to indicate whether the loop should skip forward if the current observation number can not be found but a higher numbered observation is present. Currently no loops will go back to missing observations if they appear after a higher number (eg observation 10 appears before observation 9!)
The following loop facilities are available:
Takes a list of numbers and returns back a frame object for each number (one frame object per call)
undef is returned on error or when all members of the list have been returned. If the ’skip’ flag is true missing files in the list will be ignored and the next element of the list selected. If ’skip’ is false the loop will abort if the file is not present
Checks for the frame stored in the first element of the supplied array and returns the Frame object if the file exists. The number is incremented such that the next observation is returned next time the routine is called.
undef is returned on error or when there are no more data files available.
This loop does not have a facility for skipping files when observations are not present. This behaviour is obtained by combining orac_check_data_dir with the list looping option so that the last observation number can be determined before running the loop. The skip flag is ignored in this loop.
Waits for the specified file to appear in the directory. A timeout of 12 hours is hard-wired in initially -- undef is returned if the timeout is exceeded.
The first member of the array is used to keep track of the current observation number. This element is incremented so that the following observation is returned when the routine is called subsequently. This means that this loop is similar to using the ’-from’ option in conjunction with the ’inf’ loop except that new data is expected.
The loop will return undef (i.e. terminate looping) if the supplied array contains undef in the first entry.
The skip flag is used to indicate whether the loop should skip forward if the current observation number can not be found but a higher numbered observation is present.
If no data can be found, the directory is scanned every few seconds (hard-wired into the routine). A dot is printed to the screen after a specified number of scans (default is 1 dot per scan and one scan every 2 seconds).
Waits for the specified file to appear in the directory by looking for the appearance of the associated flag file. A timeout of 60 minutes is hard-wired in initially -- undef is returned if the timeout is exceeded.
The first member of the array is used to keep track of the current observation number. This element is incremented so that the following observation is returned when the routine is called subsequently. This means that this loop is similar to using the ’-from’ option in conjunction with the ’inf’ loop except that new data is expected.
The loop will return undef (i.e. terminate looping) if the supplied array contains undef in the first entry.
Takes a list of files and returns back frame objects for the files, removing them from the input array.
undef is returned on error or if the list of files is empty.
The UT and skip parameters are ignored.
The input filenames are assumed to come from $ORAC_DATA_IN if they use a relative path.
In this scheme ORAC-DR looks for a flag file of a standard name created by a task that is monitoring remote QL parameters and writing the data locally. The flag file is always the same name and contains the files that should be processed by the pipeline immediately.
When the pipeline finds a flag file the file is immediately renamed and the listed files are then "owned" by the pipeline. The QL task monitor will continue to write a new flag file when data arrives and delete the old flag file if the pipeline has not taken ownership. The QL task monitor deletes files that were never harvested. The pipeline should tidy up for itself if it finds the flag file.
In this looping scheme all except the first argument are ignored.
Routine to check the input data directory (ORAC_DATA_IN) for files in order to see whether files exist with a higher number than the supplied number. The routine is supplied with a class name, UT date and current observation number. An additional argument is provided to determine whether data files or flag files should be used for the directory search.
If called in a scalar context, the return argument is the next observation in the sequence. If called in an array context, two arguments are returned: the next observation number and the highest observation number.
undef (or undef,undef) is returned if no higher observations can be found. If it is necessary to check for the existence of current file as well (eg via a data detection loop) then simply decrement the supplied argument by 1.
This routine is used in conjunction with the -from loop (where we dont know the end) and the waiting loops where we are not sure whether new data have been written to disk but missing the next observation.
This routine does NOT look in ORAC_DATA_OUT.
A global variables (@LIST) is used to speed up the sorting by storing a list of observation numbers that have previously been shown to have a lower number than required (NOT YET IMPLEMENTED).
The following subroutines are not exported.
General subroutine for converting ut and number into file and creating a Frame object or multiple frame objects (depending on instrument and mode).
The five parameters are:
Class of Frame object
UT date in YYYYMMDD
Observation number
If filename(s) is to come from flag file
Reference to array of files names that should be excluded from the list of files read from the flag files (if flag files are non-zero). This allows for flag files that can change length during an observation (potentially allowing the pipeline to stop before the full observation is complete but after data files start appearing for the observation). The contents of this array are updated on exit to include the files that were just read. This allows the reference list to be resubmitted to this routine.
Empty list is returned on error.
Returns 1 or more configured frame objects on success.
Pause the checking for new data files by the specified number of seconds.
Where $pause is the number of seconds to wait and $time is the number of seconds actually waited. Seconds can be fractional.
If the Tk system is loaded this routine will actually do a Tk event loop for the required number of seconds. This is so that the X screen will be refreshed. Currently the only test is the Tk is loaded, not that we are actually using Tk.....
Given a pattern or string, look in ORAC_DATA_IN and return all the files that are applicable.
If the pattern finds .ok files they will be opened. It is assumed that this routine will not be triggered in dynamic flag mode.
Return true if all the specified files are present.
Returns false is no files are supplied.
Return true if all the specified files are present with a size greater than 0 bytes
Returns false if no files are supplied.
Convert a filename(s) relative to ORAC_DATA_IN to an absolute path.
Does not affect absolute paths.
In scalar context, returns the first path.
Splits path up and resolves "../" entries. This is done because normally if you use a symlink ../ ends up on the other end of the directory symlink.
This may be dangerous....
Given the supplied file names, convert and link each file to ORAC_DATA_OUT. If successful
returns a list of ORAC::Frame objects derived from the input frame.
This is the low level file conversion/linking routine used by _convert_and_link.
Given an input and output format and a list of files, returns the modified files. Returning an empty list indicates an error (but only if @input contained some filenames).
Read the specified flag files and return the contents.
Name of flag file to monitor in task mode. Includes full path.
If the file is present in ORAC_DATA_OUT the name in ORAC_DATA_OUT is returned. Otherwise returns undef. The ORAC_DATA_OUT version of the filename is returned so that a soft link can be detected by the caller even if the file supplied to this routine points to a file outside ORAC_DATA_OUT.
Can include a full path. ORAC_DATA_OUT will be prepended if the file name is not absolute.
Read the supplied flag file and remove any files that are listed and in $ORAC_DATA_OUT. Then remove the flag file itself.
Copyright (C) 2007-2009, 2011 Science and Technology Facilities Council. Copyright (C) 1998-2006 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Control and initialise ADAM messaging from ORAC
Methods to initialise the ADAM messaging system (AMS) and control the behaviour.
The following methods are available: Constructor
Create a new instance of Starlink::AMS::Init. If a true argument is supplied the messaging system is also initialised via the init() method.
Method to set whether standard messages returned from monoliths are printed or not. If set to true the messages are printed else they are ignored.
Default is to print all messages.
Method to set whether error messages returned from monoliths are printed or not. If set to true the errors are printed else they are ignored.
Default is to print all messages.
Set or retrieve the timeout (in seconds) for some of the ADAM messages. Default is 30 seconds.
Set and retrieve the current filehandle to be used for printing error messages. Default is to use STDERR.
Set and retrieve the current filehandle to be used for printing normal ADAM messages. Default is to use STDOUT. This can be a tied filehandle (eg one generated by ORAC::Print).
Set and retrieve the code reference that will be executed if the parameter system needs to ask for a parameter. Default behaviour is to call a routine that simply prompts the user for the required value. The supplied subroutine should accept three arguments (the parameter name, prompt string and default value) and should return the required value.
A simple check is made to make sure that the supplied argument is a code reference.
Warning: It is possible to get into an infinite loop if you try to continually return an unacceptable answer.
Initialises the ADAM messaging system. This routine should always be called before attempting to control I-tasks.
A relay task is spawned in order to test that the messaging system is functioning correctly. The relay itself is not necessary for the non-event loop implementation. If this command hangs then it is likely that the messaging system is not running correctly (eg because the system was shutdown uncleanly.
For ORAC-DR the message system directories are set to values that will allow multiple oracdr pipelines to run without interfering with each other.
Scratch files are written to ORACDR_TMP directory if defined, else ORAC_DATA_OUT is used. By default ADAM_USER is set to be a directory in the scratch file directory. This can be overridden by supplying an optional flag.
If $preserve is true, ADAM_USER will be left untouched. This enables the pipeline to talk to
tasks created by other applications but does mean that the users ADAM_USER may be filled
with unwanted temporary files. It also has the added problem that on shutdown the
ADAM_USER directory is removed by ORAC-DR, this should not happen if $preserve is true
but is not currently guaranteed.
Returns true, indicating that the ADAM "engine" identifiers must be unique in the client each time an engine is launched.
This module requires the Starlink::AMS::Init module.
Copyright (C) 1998-2000 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
Provide methods for loading and communicating with ADAM monoliths. This module conforms to the ORAC messaging standard. This is an ORAC interface to the Starlink::AMS::Task module.
By default all tasks loaded by this module will be terminated on exit from perl.
The following methods are available: Constructor
Create a new instance of a ORAC::Msg::Task::ADAM object.
If supplied with arguments (matching those expected by load() ) the specified task will be loaded upon creating the object. If the load() fails then undef is returned (which will not be an object reference).
Returns or set the list of tasks that should have their output silenced when an obeyw is issued.
The task will be something like "ndftrace" or "stats" and not the monolith name.
Load a monolith and set up the name in the messaging system. This task is called by the ’new’ method.
If the second argument is omitted it is assumed that the binary is already running and can be called by "name".
If a path to a binary with name "name" already exists then the monolith is not loaded.
Options (in the form of a hash reference) can be supplied in order to configure the monolith. Currently supported options are
Returns a boolean indicating whether the task output should be silenced.
Send an obey to a task and wait for a completion message
Obtain the value of a parameter
Get multiple parameter values. This method is a wrapper around the get() method, returning the values in a hash indexed by parameter name. If a parameter has only one value it will be stored in the hash directly, else if multiple values are returned for a parameter a reference to an array will be stored in the return hash.
Status will only be good if all parameter gets return good status. Status will take on the last bad status value but an attempt will be made to get all parameter values even if some return with bad status.
Set the value of a parameter
Send CONTROL messages to the monolith. The type of control message is specified via the first argument. Allowed values are:
"value" is only relevant for the "default" type and is used to specify a new working directory. $current is always returned even if it is undefined.
These commands are synonymous with the cwd() and resetpars() methods.
Reset all parameters associated with a monolith
Set and retrieve the current working directory of the monolith
This method will not return unless the monolith can be contacted. It only returns with a timeout. Returns
a ’1’ if we contacted okay and a ’0’ if we timed out. It will timeout if it takes longer than specified in
ORAC::Msg::ADAM::Control-timeout.
This method can be used to determine whether the object can contact a monolith. Returns a 1 if we can contact a monolith and a zero if we cant.
Returns process id of forked task. Returns undef if there is no external task.
This module requires the Starlink::AMS::Task module.
Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307, USA
This module provides commands for printing messages from ORAC software. Commands are provided for printing error messages, warning messages and information messages. The final output location of these messages is controlled by the object configuration.
If the ORAC::Print::TKMW variable is set, it is assumed that this is the Tk object referring to the MainWindow, and
the Tk-update()
method is run whenever the orac_* commands are executed via the method in the ORAC::Event class.
This can be used to keep a Tk log window updating even though no X-events are being
processed.
A simplified interface to Term::ReadLine is provided for use with the orac_read command. This can only be used on STDIN/STDOUT and is not object-oriented.
A simplified non-object oriented interface is provided. These routines are exported into the callers namespace by default and are the commands that should be used by primitive writers.
Print the supplied text to the ORAC output device(s) using the (optional) supplied colour.
If the colour is not specified the default value is used (magenta for primtives).
Print the supplied text to the ORAC output device(s) using the (optional) supplied colour. A carriage return is automatically appended to the text to be printed.
Print the supplied text as a warning message using the supplied colour.
Use the OS notification system (if possible) to report the message.
Prints the supplied text as a warning message and appends the line number and name of the parent primitive. This information is obtained from the standard $_PRIM_CALLERS_ variable available to each primitive.
Print the supplied text as an error message using the supplied colour.
Identical to orac_err except that an exception is thrown (see ORAC::Error) of type
ORAC::Error::FatalError immediately after the text message has been printed. Will
cause the pipeline to stop processing all data.
Identical to orac_throw except that an exception of class ORAC::Error::TermProcessing
is thrown to force the current recipe to terminate safely. orac_throw will cause the pipeline
to abort when called within a recipe.
Identical to
orac_term except that an exception of class ORAC::Error::TermProcessingErr is thrown
to force the current recipe to terminate safely but with the error state being remembered
when the pipeline exits.
Print the supplied text as a debug message using the supplied colour.
Read a value from standard input. This is simply a layer on top of Term::ReadLine.
There is no Object-oriented version of this routine. It always uses STDIN for input and STDOUT for output.
Set the prefix to be used by orac_print in all output.
As for orac_print but includes the prefix that has been specified by using orac_print_prefix.
As for orac_say but includes the prefix that has been specified by using orac_print_prefix
As for orac_warn but includes the prefix that has been specified by using orac_print_prefix.
As for orac_err but includes the prefix that has been specified by using orac_print_prefix.
Register additional information for logging to the file.
This information is added to the current set although duplicate keys will overwrite information.
An explicit undef will clear the current information.
A reference to a hash will force an overwrite of the stored information.
To obtain the messages use no arguments:
Clear the message log
Set the logging key. Usually the primitive name.
Enable or disable logging.
Returns the logged messages.
See the msglog() documentation for more information. An undefined reference epoch is equivalent to no reference epoch.
The following methods are available: Constructors
Object constructor. The object is returned.
Turns debugging messages on or off. Default is off.
Enables or disables logging of messages. Default is off.
Retrieve (or set) the colour currently used for printing output messages.
Currently no check is made that the supplied colour is acceptable.
Retrieve (or set) the colour currently used for printing warning messages.
Currently no check is made that the supplied colour is acceptable.
Retrieve (or set) the colour currently used for printing error messages.
Currently no check is made that the supplied colour is acceptable.
String to be associated with output messages. This key will be used when building up the message stack and can be used for grouping purposes.
Usually this would reflect the current primitive.
Register additional information for logging to the file.
This information is added to the current set although duplicate keys will overwrite information.
An undef will delete the key
An explicit undef will clear the current information.
A reference to a hash will force an overwrite of the stored information.
To obtain the messages use no arguments:
The information is associated with each change of logkey and so can be updated each time a logkey is updated.
Array of all logged messages.
Each entry is a reference to an array with elements
ie [ prim1, epoch, @msg, %info ], [ prim2, epoch2, @msg, %info ]
Messages will be in epoch order. If an argument is given this will be a reference epoch. Only messages more recent than this will be returned. Only works in list context.
An undefined reference epoch is ignored.
String that is prepended to all messages printed by this class. Default is to have no prefix.
Prefix that is prepended to all strings printed with the out() or say() methods. Default is to have no prefix.
Prefix that is prepended to all strings printed with the war() or carp() methods. Default is to have the string ’Warning:’ prepended.
Prefix that is prepended to all strings printed with the notify() methods. Default is to have no string prepended.
Prefix that is prepended to all strings printed with the err() method. Default is to have the string ’Error:’ prepended.
Output file handle(s). These are the filehandles that are used to send all output messages. Multiple filehandles can be supplied. Returns an IO::Tee object that can be used as a single filehandle.
Default is to use STDOUT.
Warning output file handle(s). These are the filehandles that are used to print all warning messages. Multiple filehandles can be supplied. Returns an IO::Tee object that can be used as a single filehandle.
Default is to use STDOUT.
Error output file handle(s). These are the filehandles that are used to print all error messages. Multiple filehandles can be supplied. Returns an IO::Tee object that can be used as a single filehandle.
Default is to use STDERR.
Specifies whether the terminal is to beep when an error message is printed. Default is not to beep (false).
This specifies the debug file handle. Defaults to STDERR if not defined. Returns an IO::Tee object that can be used as a single filehandle.
Print output messages. By default messages are written to STDOUT. This can be overridden with the outhdl() method.
Send message to the OS notification system if available. The title is required.
The name (or type) or message must be from an approved list defined as module constants. They are defined at the end of this document.
Print output messages, appending a carriage return to the text string.
By default messages are written to STDOUT. This can be overridden with the outhdl() method.
Print warning messages. Default is to print warnings to STDOUT. This can be overriden with the warhdl() method.
Prints the supplied text as a warning message and appends the line number and name of the parent primitive. This information is obtained from the standard $_PRIM_CALLERS_ variable available to each primitive.
Print error messages. Default is to use STDERR. This can be overriden with the errhdl() method.
Same as err method except that an exception of type ORAC::Error::FatalError is thrown
immediately after the error message is printed.
The message itself is part of the exception that is thrown.
Similar to orac_throw but can be used in primitives to throw a TermProcessing exception to allow the current recipe to be stopped. orac_throw throws a FatalError exception and so that will completely stop the pipeline.
Not recommended for use outside the recipe execution environment.
Similar to orac_term but can be used in primitives to throw a TermProcessingErr exception to allow the current recipe to be stopped. Unlike orac_term the bad error state will be remembered when the pipeline exits. Can be used when the pipeline recovered from a problem but would like the error to be investigated.
Not recommended for use outside the recipe execution environment.
Prints debug messages to the debug filehandle so long as debugging is turned on.
Does an Tk update on the Main Window widget
Clear the log. This can be used to reset logged messages when a new recipe begins.
An ORAC::Print object can also be tied to filehandle using the tie command:
where $prt is an ORAC::Print object. Currently all strings printed to this handle will be redirected to the orac_print command (and will therefore use the output filehandles associated with the most recent ORAC::Print object created). The default color used by the tied handle can be set using the outcol() method of the object associated with the filehandle
will result in all messages printed to HANDLE, being printed with no color codes to STDOUT.
The optional fourth argument to the tie() command can be used to set the default output stream. Allowed values are ’out’, ’war’ and ’err’. These correspond directly to the orac_print, orac_warn and orac_err commands. Default is to use orac_print for all tied filehandles.
It is not possible to read from this tied filehandle.
The following notification types are available
Copyright (C) 2009 Science and Technology Facilities Council. Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.
Generate temporary files for ORAC-DR
Provide a simplified means of handling temporary files from within ORAC-DR. The temporary file is automatically removed when the object goes out of scope.
The temporary file name can also be used as a temporary name for NDF files. NDF files (extension ’.sdf’) are automatically deleted in addition to the temporary file created by this class.
The following methods are available in this class. Constructor The following constructors are available:
Create a new instance of a ORAC::TempFile object.
If a false argument is supplied the temporary file name will be allocated (and the file opened) but the file itself will be closed before the new object is returned. This is so that the temporary file name can be passed directly to another process without wanting to write anything to the file yourself (for example if you want to generate a file in an external program and then read the results back into perl).
Returns ’undef’ if the tempfile could not be created. The file is opened for read/write with autoflush set to true. The file should be closed (using the close() method on the object file handle) before sending the file name to an external process (unless a false argument is supplied to the constructor).
An argument hash is also supported. These arguments are OPEN and SUFFIX. OPEN is the equivalent of passing in a solitary false argument. SUFFIX appends the given suffix to the temporary filename. For example, to create a temporary file with a closed filehandle and a .txt suffix, one would do:
Note that if you pass in an argument hash you cannot have a solitary false argument to return a closed file; if you wish to return a closed file in conjunction with setting a suffix, you must use the OPEN named argument.
Return (or set) the file handle associated with the temporary file.
Return the file name associated with the temporary file.
The file name is also returned on stringification of the object.
The destructor is run when the object goes out of scope or no longer has any references to it. When called, the temporary file is closed and unlinked. If necessary and files of the same name but with a ’.sdf’ extension are also unlinked. This allows the same class to be used for temporary plain files and temporary NDF files.
No files are removed if the debugging flag ($DEBUG) is set to true (the default is false) or if the ORAC_KEEP environment variable has a value of "temp".
The following methods are intended for use inside the module. They are included here so that authors of derived classes are aware of them.
This method is used to initialise the object. It is called automatically by the object constructor. It generates a temporary file name and attempts to open it. If the open is not successful the state of the object remains unchanged. In general, this means that the object constructor has failed.
The following global variables are available. They can be accessed directly or via Class methods of the same name.
The current version number of this module.
Debugging flag. When this flag is set to true the temporary files are not deleted by the object destructor. They can be examined at a later time.
IO::File, File::MkTemp, tmpnam() in POSIX
Copyright (C) 2008 Science and Technology Facilities Council. Copyright (C) 1998-2001 Particle Physics and Astronomy Research Council. All Rights Reserved.