Cook-Book

Annular Solar Eclipse 03 Oct 2005 El Escorial, Spain

You can view these in any viewer which understands JPEGs.

Eclipse photos by KeithNoddle

Galactic examples:

1. Building a query

1.1 Example queries

1. SQL: SELECT * FROM  usnob_psc as u where u.B2Mag > 21
   This means, select all columns from the USNO-B catalogue (which has to be given an alias, in this case u) where the column labelled B2Mag is greater than 21. Note that this should return only the few very faintest sources in the catalogue. The whole USNO-B catalogue is >10^7 sources, so be careful when querying such large data sets.
2. SQL: SELECT u.seqNo, u.ra, u.dec, u.B2Mag FROM usnob_psc  as u where u.B2Mag > 21
   will return just 3 columns, labelled seqNo, ra and dec, form USNO-B, where B2Mag is greater than 21.
3. SQL: SELECT * FROM twomass_psc as o where  (o.ra > 56.25) and (o.ra < 57.25) and (o.dec > 23.6167) and (o.dec < 24.6167)
   selects all columns from the 2MASS point source catalogue within a box bounded by blc (56.25, 23.6167) and trc (57.25, 24.6167). Note that position constraints must be in the same units (here, decimal degrees) and coordinate frame as the columns in question.

2. Building a workflow

In order to execute the query it must be inserted in a workflow. See BuildingWorkflow for full details. In brief:

• Go to Workflow page
• Use the File menu either to Open an exisiting workflow for editing or to select New
• Enter a Name and Description and click update workflow
• In a New workflow you will see only one element, Sequence. To make your query the first step in the workflow, use the Edit menu to Insert step > here
• Selecting the task
  • Move the mouse over the Step which has appeared in a 'tree' so that it is in a yellow box, and a large box headed Step and Task will appear.
  • Use the Select task pull-down menu to find the required application. E.g. for 1) above, you need roe.ac.uk/DSA_USNOB/ceaApplication#adql . If you don't see it, use Browse Registry which will give you the Task Microbrowser, see LocatingResources
  • Enter a Step name (for a simple query; see BuildingWorkflow if the results are to be handled by a Workflow Script) and click update step details.
    • Note that when you do this a new Step parameter box is created, it is important to do this before the next step of filling in the step parameters - unless you want to delete existing step parameters.
• Entering the query step parameters
  • Click on the Step branch of the 'tree' and another box appears
  • Leave Format as VOTABLE
  • Click Browse next to Query and Select your query from the MySpace Microbrowser which appears. This should appear in the form "Query/usnob.q".
  • Click Browse next to Result and Select an existing file name for the VOTable which will be returned to you or enter a New file name in the microbrowser. This should appear in the form "Output/usnob.vot"
    • Note that clicking on Browse automatically enters a tick in the checkbox.
  • Click on Update parameter values. This should translate the parameter box contents into IVORNs of the form "ivo://uk.ac.le.star/anitarichards#Query/usnob.q".
    • You could enter the whole IVORN as above by hand without going through the microbrowser,
    • You could instead enter a valid URL for the query as long as it pointed to a valid ADQL query.
      • In all cases whre there is an external file reference make sure that the checkbox (tool-tip Indirect flag...) is set to tick.
  • Whatever you enter, click Update parameter values to store your final inputs before moving on to construct any other step or stage in the workflow.
• Running the workflow
  • Use the File menu to Save your workflow
  • Use the File menu to Submit your workflow
• Getting at the results
  • Use the Jobs page to see when your job has finished. Note that this refreshes automatically so you do not usually need to do this manually.
  • The catalogue portion selected in response to your query will be written to MySpace in VOTable format. See UsingMySpace - Viewing/Downloading files for what you can do with it!

SimpleImageAccessProtocolExample of selection of images in a given region.

---

Extragalactic examples:

---

Solar examples:

1. Building a solar query

1.1 Query to solar datasets

To query solar datasets for files, go to the Query page and select Load a table. Type 'solarimg' into the 'resource name' box. This will display the tables of metadata associated with solar files currently available via the AstroGrid portal.

Here choose, for example 'eitdata', and the fits headers for SOHO/EIT files will be displayed in the Query builder. Any of these fits headers can be used to construct your query. (For more info on what these headers mean check: Description of FITS headers for solar instruments).

To use a keyword from the displayed table in your query, click on it and this will paste it into the query box.

Examples of queries to solar datasets are:

SELECT * FROM eitdata AS T1 where T1.DATE_OBS > "2002-07-28T01:00:00.000" and T1.DATE_OBS <= "2002-07-28T06:00:00.000"

SELECT * FROM eitdata AS T1 where T1.DATE_OBS > "2002-07-28T01:00:00.000" and T1.DATE_OBS <= "2002-07-28T06:00:00.000" and T1.WAVELNTH = 195

(same as above, only this time only files for wavelength=195 will be returned).

Once the query has been built, save it to Myspace as, for example, 'queryeit1.xml'. See below how to construct a workflow that sends the query to the data centre.

1.2 Query to the Solar Event Catalogue

The Solar Event Catalogue, developed by EGSO, provides several lists of events such as flares, coronal mass ejections. These lists can be queried on from the Astrogrid portal.

To do an SEC query go to Query page and select Load a table. Type 'solar_event' into the 'resource name' box. This will display all the tables of metadata associated with the SEC. (Note: scroll down to see the actual lists such as 'goes_xray_flare'). Here you can select the list you want to query on, for example select, 'goes_xray_flare', and this will display inside the query builder a table of metadata associated with this list. To use a keyword from this table in your query, click on it and this will paste it into the query box.

An example of SEC query using the 'goes_xray_flare' list is:

SELECT * FROM goes_xray_flare AS T1 WHERE T1.nar = 10397 and T1.xray_class > 'C5.0'

(selects all flares from AR 10397 of magnitude > C5.0 )

2. Building a solar workflow

2.1 Workflow that sends a query to a solar dataset

Go to the Workflow page and start a new workflow. (See also general comments on how to build workflows at BuildingWorkflows). Choose 'Insert Step'. Go to box at the bottom of the page. Here, to select the task that sends solar queries to the appropriate data centre, go to the 'Select task' drop down box and choose 'Browse Registry'. Type in 'solar' into the 'Task name' box, and you will get a list of all solar tasks available. Choose :

solarimg_dsa/ceaApplication

Specify a name for this step & click on 'Update step details'.

This will open a box where you need to specify input to the step, and output. For input, choose browse and select the query file previously saved, e.g. 'queryeit1.xml'. For output, type in the name for the output file: this will be in Votable format, therefore choose a name such as 'eitresult1.vot' . Click on 'update' box. Submit workflow for execution.

The output of this workflow is a Votable containing: URLs of the files matching the query, and metadata associated with each file.

---

STP examples:

1. Getting STP data from UKSSDC at RAL

• (a) Build a query for UKSSDC datasets:

Go to Query page and click on 'Select a table'. Type 'ukssdc' into the 'Resource name' box. This will display entries in the AstroGrid registry associated with ukssdc. Scroll down to the entry with Resourcekey='dsa-ukssdc-wdcdata/TDB' which lists the WDC datasets which can be queried on from the AstroGrid portal. Here you can select the dataset you want to query on, for example select, 'dst_hourly_prov', and this will display to the right of the query box the metadata associated with this dataset (e.g. for 'dst_hourly_prov', it will display as metadata: 'datetime' and 'dst' which are the 2 keyworkds you can query on). To use a keyword from this table in your query, click on it and this will paste it into the query box.

For example, one can build the following query on 'dst_hourly_prov' to get the values of Dst in the time range below:

select * FROM dst_hourly_prov AS T1 WHERE T1.datetime >= '2003-01-01 00:00:00' AND T1.datetime < '2003-01-01 23:59:59'

Now save the query into a file by clicking on 'Save to Myspace' and typing in a name for the query file, for example 'dstquery.xml'.

• (b) Build a workflow that executes the query and retrieves the results from UKSSDC:

Go to the Workflows page. (See also general comments on how to build workflows at BuildingWorkflows). Choose 'Edit', 'Insert Step' and 'here'. Scroll down to box that opens at the bottom of the page. Here, to select the tool that sends queries to UKSSDC, go to the 'Select task' drop down box and choose 'Browse Registry'. Type in 'ukssdc' into the 'Task name' box, and you will get a list of all tools on UKSSDC. Select the one with Resourcekey:

dsa-ukssdc-wdcdata/ceaApplication

This will display the selected task in the workflow page. Now specify a name for this step & click on 'Update step details'.

Click on 'Step': this will open a box where you need to specify input to the step, and output. For input, choose Browse and select the query file previously saved, e.g. 'dstquery.xml'. For output, click on Browse and either type in the name of a new file and click on 'New', or select an existing file to be overwritten. The output file will be in Votable format, therefore choose a name such as 'dstresult.vot' . Click on 'Update parameter values'.

Choose 'File' -> 'Save' to save the workflow to Myspace. Choose 'File' -> 'Submit' to submit the workflow for execution.

The output of the workflow is a Votable, e.g. for the DST example a votable containing a time column and one for DST values. Getting a votable of say DST values could be the first step of a more elaborate workflow.

The contents of the output votable can be viewed in MySpace by clicking on the file name + 'edit' + 'Properties', or by launching Topcat as a Java Webstart application.

---

-- SilviaDalla - 21 Apr 2005