[OpenMadrigal-developers] Changes to Madrigal Matlab API and
isprint
William Rideout
brideout at haystack.mit.edu
Wed Nov 26 16:05:46 EST 2003
John,
Please let me know if this meets your needs.
Bill
***************************************************************
The following is the list of planned Matlab methods to implement what
John has planned. Note that every local method has a web counterpart.
This allows the flexibility to run these methods over the web, with the
cost of slower performance. The methods getExperiments and
getExperimentsWeb return an indicator as to whether the experiment is
local or not, so the user can choose at run-time which method to call.
The four local methods are:
1. getInstruments
2. getExperiments
3. getExperimentFiles
4. getParameters
and four additional methods with "Web" as a suffix.
Error handling: All madmatlab methods will throw Matlab errors if they
encounter a problem. These errors will be explained in the err.message
field, and the err.identifier field will always be 'madmatlab'. The
application can catch these errors or not as it sees fit.
Time: Matlab has a standard date/time format which is the number of days
since Jan. 1, 0000 as a double. Since using this format allows the use
of Matlab's time methods, I use this format in all my API. Please let
me know if you'd prefer a non-Matlab format.
Note on setting MADROOT: Since madmatlab uses the C API, it follows the
same
rules about the MADROOT directory. That rule is that it will use the
$MADROOT
environment variable if its defined; otherwise it will use the value set
when
Madrigal was installed.
For ease in programing, most methods will return Matlab struct arrays.
For example, the call "getInstruments()" will return an array of
instrument structs with the fields:
instrument.name (string) Example: 'Millstone Hill Incoherent Scatter Radar'
instrument.code (int) Example: 30
instrument.mnemonic (3 char string) Example: 'mlh'
instrument.latitude (double) Example: 45.0
instrument.longitude (double) Example: 110.0
instrument.altitude (double) Example: 0.015 (km)
Proposed methods:
**********************************************
1. [Instrument struct array] = getInstruments()
Local method
Inputs: None
Returns an array of instrument structs, where an instrument struct has
the fields:
instrument.name (string) Example: 'Millstone Hill Incoherent Scatter Radar'
instrument.code (int) Example: 30
instrument.mnemonic (3 char string) Example: 'mlh'
instrument.latitude (double) Example: 45.0
instrument.longitude (double) Example: 110.0
instrument.altitude (double) Example: 0.015 (km)
**********************************************
2. [Instrument struct array] = getInstrumentsWeb(cgiurl)
Web method
Input - cgiurl (string) to Madrigal site cgi directory (Example:
'http://www.haystack.mit.edu/cgi-bin/madrigal/') Note that method
getMadrigalCgiUrl converts homepage url into cgiurl.
Returns an array of instrument structs, where an instrument struct has
the fields defined above.
**********************************************
3. [Experiment struct array] = getExperiments(instrumentCode array,
starttime, endtime, localFlag)
Local method
Inputs:
1. instrumentCode array - a 1 X N array of ints containing
selected instrument codes. Special value of 0 selects all instruments.
2. starttime - Matlab datenum double
3. endtime - Matlab datenum double
4. localFlag - 1 if local experiments only, 0 if all experiments
Return array of Experiment struct:
experiment.id (int) Example: 10000111
experiment.url (string) Example:
'http://www.haystack.edu/cgi-bin/madtoc/1997/mlh/03dec97'
experiment.name (string) Example: 'Wide Latitude Substorm Study'
experiment.siteid (int) Example: 1
experiment.sitename (string) Example: 'Millstone Hill Observatory'
experiment.instcode (int) Code of instrument. Example: 30
experiment.instname (string) Instrument name. Example: 'Millstone Hill
Incoherent Scatter Radar'
experiment.starttime (double) Matlab datenum of experiment start
experiment.endtime (double) Matlab datenum of experiment end
experiment.isLocal (int) 1 if local, 0 if not
**********************************************
4. [Experiment struct array] = getExperimentsWeb(cgiurl, instrumentCode
array, starttime, endtime, localFlag)
Web method
Inputs:
1. Input - cgiurl (string) to Madrigal site cgi directory
(Example: 'http://www.haystack.mit.edu/cgi-bin/madrigal/') Note that
method getMadrigalCgiUrl converts homepage url into cgiurl.
2. instrumentCode array - a 1 X N array of ints containing
selected instrument codes. Special value of 0 selects all instruments.
3. starttime - Matlab datenum double
4. endtime - Matlab datenum double
5. localFlag - 1 if local experiments only, 0 if all experiments
Return array of Experiment struct as above
**********************************************
5. [File struct array] = getExperimentFiles(experiment_url)
Local method
Inputs:
1. experiment_url (string) experiment url, as returned in
experiments struct.
Fails if url passed in was not local.
Return array of File struct:
file.name (string) Example '/opt/mdarigal/blah/mlh980120g.001'
file.kindat (int) Kindat code. Example: 3001
file.kindatdesc (string) Kindat description: Example 'Basic Derived
Parameters'
file.category (int) (1=default, 2=variant, 3=history, 4=real-time)
file.status (string)('preliminary', 'final', or any other description)
file.permission (int) 0 for public, 1 for private
**********************************************
6. [File struct array] = getExperimentFilesWeb(cgiurl, experiment_url)
Local method
Inputs:
1. cgiurl (string) to Madrigal site cgi directory (Example:
'http://www.haystack.mit.edu/cgi-bin/madrigal/') Note that method
getMadrigalCgiUrl converts homepage url into cgiurl.
2. experiment_url (string) experiment url, as returned in
experiments struct.
Return array of File struct as in getExperimentFiles.
**********************************************
7. [Madrigal parameter array] = GetParameters(filename)
Local method
Inputs:
1. filename, as returned by getExperimentFiles (string)
Return array of Parameter struct that are measured or derivable:
parameter.mnemonic (string) Example 'dti'
parameter.description (string) Example:
"F10.7 Multiday average observed (Ott) - Units: W/m2/Hz"
parameter.isError (int) 1 if error parameter, 0 if not
parameter.units (string) Example "W/m2/Hz"
parameter.isMeasured (int) 1 if measured, 0 if derivable
parameter.lowestValidValue (double) lowest valid value found, may be NaN
parameter.highestValidValue (double) highest valid value found, may be NaN
parameter.category (string) Example: "Time Related Parameter"
**********************************************
8. [Madrigal parameter array] = GetParametersWeb(cgiurl, filename)
Web method
Inputs:
1. cgiurl (string) to Madrigal site cgi directory (Example:
'http://www.haystack.mit.edu/cgi-bin/madrigal/') Note that method
getMadrigalCgiUrl converts homepage url into cgiurl.
2. filename, as returned by getExperimentFiles (string)
Return array of Parameter struct as in GetParameters.
**********************************************
Bill
John Holt wrote:
> The Matlab code I am working on is basically a graphics version of
> isprint. For those who remember the Harris days, it would restore the
> graphics functionality provided by the MGRAIL program, which was not
> transfered to the Solaris version of Madrigal. To do this, I need to be
> able to implement close analogs of the Madrigal Experiment Selector,
> Madrigal Experiment Listing and Madrigal Experiment Page in Matlab.
> Matlab methods to fetch the appropriate information should be fairly
> straightforward since on the server side they would be very similar to
> the current cgi scripts.
>
> John
>
> _______________________________________________
> OpenMadrigal-developers mailing list
> OpenMadrigal-developers at openmadrigal.org
> http://www.openmadrigal.org/mailman/listinfo/openmadrigal-developers
>
>
--
Bill Rideout
MIT Haystack Observatory
Email: brideout at haystack.mit.edu
Phone: 781 981-5624
More information about the OpenMadrigal-developers
mailing list