wiki:VsoIDL/VsoSearch
Last modified 9 years ago Last modified on 09/20/10 12:41:05

For the time being (17 Sept 2010), this is basically just what you'd get from running doc_menu, 'vso_search' and doc_menu, 'vso_get', but I hope to get a better list of real-world examples up. So, if you have a question about how to do something using the client, contact me, and I'll add to the list:

;+
; Project     : VSO
;
; Name        : VSO_SEARCH()
;
; Purpose     : Send a search request to VSO
;
; Explanation : Sends a query to VSO, to obtain metadata records corresponding
;               to the records that match the query parameters.
;
; Category    : Utility, Class2, VSO
;
; Syntax      : IDL> a = vso_search('2005-JAN-01', instrument='eit')
;
; Examples    : IDL> a = vso_search(date='2004-01-01', provider='sdac')
;               IDL> a = vso_search(date='2002-1-4 - 2002-1-4T07:05', inst='mdi')
;               IDL> a = vso_search(date='2004/1/4T07:40-2004/1/4T07:45', inst='trace')
;               IDL> a = vso_search(date='2004-1-1', extent='CORONA', /FLAT)
;               IDL> a = vso_search(date='2001-1-1', physobs='los_magnetic_field')
;               IDL> a = vso_search(date='2004/1/1', inst='eit', /DEBUG)
;               IDL> a = vso_search('2004/1/1','2004/12/31', wave='171 Angstrom', inst='eit')
;               IDL> a = vso_search('2004/6/1','2004/6/15', wave='284-305 Angstrom', inst='eit')
;               IDL> a = vso_search('2005-JAN-1', inst='eit', /FLAT, /URL)
;
;               IDL> print_struct, a
;               IDL> print_struct, a.time       ; if not called w/ /FLATTEN
;               IDL> sock_copy, a.url           ; if called w/ /URLS
;               IDL> vso_get, a                 ; attempt to download products
;               
;
; History     : Ver 0.1, 27-Oct-2005, J A Hourcle.  split this out from vso__define
;               Ver 1,   08-Nov-2005, J A Hourcle.  Released
;                        12-Nov-2005, Zarro (L-3Com/GSFC)
;                         - added TSTART/TEND for compatability with SSW usage.
;                         - added _REF_EXTRA to communicate useful keywords
;                           such as error messages.
;               Ver 1.1, 01-Dec-2005, Hourcle.  Updated documentation
;               Ver 1.2, 02-Dec-2005, Zarro. Added call to VSO_GET_C
;               Ver 1.3, 18-May-2006, Zarro. Removed call to VSO_GET_C
;                           because it confused the compiler
;               Ver 2.0, 06-Jul-2010, Hourcle.  Updated documentation (see vso__define:buildquery)
;
; Contact     : oneiros@grace.nascom.nasa.gov
;               http://virtualsolar.org/
;
; Input:
;   (note -- you must either specify DATE, START_DATE or TSTART)
; Optional Input:
; (positional)
;   TSTART     : date   ; the start date
;   TEND       : date   ; the end date
; Keywords:
;   DATE       : string ; (start date) - (end date)
;   START_DATE : date   ; the start date
;   END_DATE   : date   ; the end date
;   WAVE       : string ; (min) - (max) (unit)
;   MIN_WAVE   : string ; minimum spectral range
;   MAX_WAVE   ; string ; maximum spectral range
;   UNIT_WAVE  ; string ; spectral range units (Angstrom, GHz, keV)
;   EXTENT     ; string ; VSO 'extent type' ... (FULLDISK, CORONA, LIMB, etc)
;   PHYSOBS    ; string ; VSO 'physical observable'
;   PROVIDER   ; string ; VSO ID for the data provider (SDAC, NSO, SHA, MSU, etc)
;   SOURCE     ; string ; spacecraft or observatory (SOHO, YOHKOH, BBSO, etc)
;                         synonyms : SPACECRAFT, OBSERVATORY
;   INSTRUMENT ; string ; instrument ID (EIT, SXI-0, SXT, etc)
;                         synonym : TELESCOPE
;   DETECTOR   ; string ; detector ID (C3, EUVI, COR2, etc.)
;   LAYOUT     ; string ; layout of the data (image, spectrum, time_series, etc.)

; Keywords with limited support; (may not work with all archives)
;   LEVEL      ; range* ; level of the data product (see below)
;   PIXELS     ; range* ; number of pixels (see below)
;   RESOLUTION ; range* ; effective resolution (1 = full, 0.5 = 2x2 binned, etc)
;   PSCALE     ; range* ; pixel scale, in arcseconds
;   NEAR_TIME  ; date   ; return record closest to the time.  See below.
;   SAMPLE     ; number ; attempt to return only one record per SAMPLE seconds.  See below.
;   
; (flag keywords)
;   QUICKLOOK  ; boolean ; retrieve 'quicklook' data if available (see below)
;   LATEST     ; boolean ; sets ( near=now, end=now, start=(now - 7 days) ) (see below)
;   URLS       ; boolean ; attempt to get URLs, also
;   QUIET      ; boolean ; don't print informational messages
;   DEBUG      ; boolean ; print xml soap messages
;   FLATTEN    ; boolean ; return vsoFlat Record (no sub-structures)
;
; (placeholders for the future)
;   FILTER     ; string ; filter name (same problems as detector)
;   WAVETYPE   ; string ; type of spectral range (LINE, NARROW, BROAD)
;                         (WARNING : causing errors to be thrown when using 'wave')
;   CARTID     ; string ; load a VSO Cart by its identifier
;   EVENT      ; string ; search for data using an event from HEK
;
; Outputs:
;   a null pointer -> no matches were found
;   (or)
;   struct[n] : (vsoRecord or vsoFlatRecord) the metadata from the results
;
; Limitations : if using /URLS, you may wish to examine output.getinfo for messages
;               SHA requires 'STAGING' the data, and vso_get() does not yet have
;                 support for anything other than direct URLs
;
; Other Notes :
;
; VSO Searching:
; * By default, if a VSO data provider (ie, archive) does not support
;   a given search parameter, it will default to returning everything
;   that *might* match.  This will occassionally result in many more
;   fields being returned than expected.
; * Some data providers will limit the number of results that they 
;   return, and you'll see a message such as:
;       Records Returned : SDAC : 1000/31772
;   You will need to break the query into smaller time ranges to get all
;   of the records.  Some data providers have implemented a 'summary rows'
;   feature where excessive returns will cause the archive to return records
;   corresponding to more than one record:
;       IDL> sot = vso_search( '2006-01-01', '2007-01-01', inst='sot' )
;       Records Returned : SDAC_SOT : 488118/488118
;       IDL> help, sot
;       SOT             STRUCT    = -> VSORECORD Array[5321]
;   Examine the 'info' field for a clue as to how many observations were
;   rolled up into each record.  We hope to provide improved support
;   for expanding these 'summary' records into individual observations
;   in the future.
; * If you have a query that's not returning what you're expecting,
;   please contact :  joseph.a.hourcle AT nasa.gov
;   (and make sure to send the query!)
;
; Source / Instrument / Detector / Phys. Obs. / Layout / Extent Tye / etc:
; * These items are enumerations.  For a list of valid values, see:
;     http://sdac.virtualsolar.org/cgi/show_details
; * We hope to soon have a 'vso_info' program to get the list from within IDL
;
; Dates within VSO_SEARCH:
; * All dates are in UTC.
; * Dates may be entered in any format accepted by 'anytim2utc', EXCEPT for the
;   'DATE' keyword, which expects a string containing a range
;       (eg, '2004/01/01 - 2004/02/01')
; * The 'NEAR_TIME' keyword is not yet supported by all data providers.  As a
;   precaution, using NEAR without specifying a start or end time will use a
;   window of +/- 1hr to prevent extremely large data returns from data providers
;   that do not support this keyword, but it may cause the data provider to return
;   no data if there is no data in that 2 hr window.  You can override the window.
; * The /LATEST flag will set the following, where 'NOW' is the current time
;       START_DATE=(NOW - 7 days), END_DATE=NOW, NEAR_TIME=NOW
;   It will not override existing start dates, so if the data you're interested in
;   lags by more than a week, you can set START_DATE further into the past, and
;   it will still set END_DATE and NEAR_TIME for you.
; * Order of precidence for start and end dates:
;     * DATE keyword (a string containing 2 dates)
;     * TSTART/TEND (positional parameters)
;     * START_DATE/END_DATE keywords
; * If no end date is specified, it will use the start of the next day
;
; Numeric Ranges : (marked as 'range*')
; * May be entered as a string or any numeric type for equality matching
; * May be a string of the format '(min) - (max)' for range matching
; * May be a string of the form '(operator) (number)' where operator is one of:
;     lt gt le ge < > <= >=
;
; Level :
; * Whatever numeric value the PI assigns.
; * If the PI's designation is '1.5q', search for : LEVEL=1.5,/QUICKLOOK
;
; Quicklook : 
; * Quicklook items are assumed to be generated with a focus on speed rather
;   than scientific accuracy.  They are useful for instrument planning and
;   space weather but should not be used for science publication.
; * This concept is sometimes called 'browse' or 'near real time' (nrt)
; * Quicklook products are *not* searched by default
;
; Resolution / Pixels / Pixel Scale :  (currently SDO/AIA and HMI only)
; * The "resolution" is a function of the highest level of data available.
;   If the CCD is 2048x2048, but it's binned to 512x512 before downlink,
;   the 512x512 product is designated as '1'.  If a 2048x2048 and 512x512
;   product are both available, the 512x512 product is designated '0.25'.
; * Pixels are (currently) limited to a single dimension. (and only implemented
;   for SDO data)  We hope to change this in the future to support TRACE,
;   Hinode and other investigations where this changed between observations
; * Pixel Scale (PSCALE) is in arc seconds.  It's currently only implemented
;   for SDO, which is 0.6 arcsec per pixel at full resolution for AIA.
;
;-