User Guide

Quick Start

This section only provides a basic description of the interface. See next section for specific questions.

The entry page is divided in two columns. The leftmost one is the query area, the rightmost part is the result display area. A menu under Help in the upper right corner provides links to external tools and help (this page

Query Form

The left area displays a form that allows the user to build his query. This consists in providing values to standard query fields. Each one acts as a filter which reduces the number of results; none is mandatory (no requested value = no filtering). Fields are grouped in thematic panels, with the "Main parameters" panel open by default. Contextual help is displayed when hovering the mouse over the field name for 1s.

Main fields

• Target Name: Start typing a Solar System object name. A name resolver is available for field completion and disambiguation.
• Other field panels: Open field panels by clicking on their banner. Fields set in closed panels are included in the query (click the "Reset" button at the bottom if needed). Some parameters (underlined in blue) only accept predefined values - click on them to choose from a list.

Send query

To send the query, click the blue "Submit" button at the bottom of the column.

Query Result

The main area displays all connected services with the number of results - by default the number of information they contain.When submitting a query, the central area is rebuilt to display the number of matches in each connected service. Services containing elements matching the query are displayed first, in green.Pick up your favorite service and click on its title to access detailed content.

Service Results

When entering the service mode, the main area now displays a table of results described by several parameters. By default, only the top of the table is displayed with a selection of parameters. The set of buttons below the green info box are used to set the table layout (number of columns/parameters). All parameters are displayed by clicking the "Show all" button. The exposed table can be enlarged with the "Show n entries" button at the bottom left corner, and browsed with the buttons at the bottom right corner.
The first line above the green box returns to the display of all services.
The link under the service acronym (second line) redirects to the main web site of the service, if available.
The left menu is still available to change or refine your query in the displayed service.

Mouse actions

• Mouse over: When hovering the mouse over the table, a thumbnail may be displayed in real time (if provided by the service).
• Selections: Individual results can be selected/unselected by simply clicking on table lines. "Select all" / "Reset" buttons are available on top of the table.

Data & metadata retrieval

Information can be sent to open VO applications using the local menus at the bottom left of the table. Select line(s) of interest and click:

• Data/Send [type]: Send data file(s) with specified data type - will open in VO applications supporting this data type, e.g., images in Aladin (see "VO tools" under "Help"). This menu is greyed out when the data are scalars values (included in the table itself).
• Metadata/Send table: Send the description table to VO applications (in VOTable format, typically handled by TOPCAT).

The two menus on the bottom right provide support functions when available:

• Target menu: List all targets present in this service, regardless of the current query.
• Footprints: Send the footprints of selected rows in various format to adequate applications. GeoJSON may open in TOPCAT, s_region and MOC will open in Aladin (you may want to load a HiPS map of the target first in Aladin).

Detailed Interface Description

The first page should present two vertical areas. If the interface looks weird, try and clear your browser's cache.

Query Form

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse varius enim in eros elementum tristique. Duis cursus, mi quis viverra ornare, eros dolor interdum nulla, ut commodo diam libero vitae erat. Aenean faucibus nibh et justo cursus id rutrum lorem imperdiet. Nunc ut sem vitae risus tristique posuere.

Fields

• Info buttons: Contextual help is displayed when hovering the mouse over the field name for 1s. Definition and usage of EPN-TAP parameters are described here.
• Multiple choice fields / lists: Fields presenting a list of values allow multiple selections (e.g., Target Class); click on parameter name to show the list and check boxes as desired.
• Other field panels: Other field panels (Time, Location...) are opened by clicking on their banner. Fields set in closed panels are included in the query (click the "Reset" button at the bottom to make sure). Some parameters (underlined in blue) only accept predefined values - click on them to choose from a list.
• Target Name: Accepts standard IAU names of Solar System bodies (only one at a time). The Quaero name resolver is used for field completion, disambiguation, and query extension. Two characters are required for completion; all known aliases of the target are included in the query; if a target_class is selected, only targets in this class will be proposed by the resolver and included in the query (both fields are required for disambiguation of bodies sharing the same name, e. g., Dione).

Special parameters:

• Spatial coordinates (in Location panel): first select the Spatial frame type, which determines the nature of the coordinates; tags will adapt to the system in use. In body-fixed frame, longitudes range from 0° to 360° eastward (IAU planetocentric convention).
• Spectral range (in Spectral panel): first select the unit (Hz, µm, or cm-1) to set the scale as frequency, wavelength, or wavenumber, then enter range.
• Granule and Obs IDs (in Data reference panel) are service-specific and provide grouping in different types of products. Use these to restrain a search when using a service you know in details.
• Measurement type (in Data reference panel) describes the physical quantities provided in the service, encoded as UCDs. An interactive resolver of IVOA UCDs is available here; a more complete list is available here (including values defined for the Solar System); or have a look at a service of interest to see how your preferred value is encoded.

Send Query

To send the query, click the blue "Submit" button at the bottom of the column.

Query modes

Other query modes are available in the portal. In standard mode, the "Form" and "All services" buttons should be selected (default).

Custom service mode

Choose "Custom service" from the cog wheel menu on the upper right to query a single service. This opens a window were you can enter the server url and service name (or enter them later in the first two fields of the form):

• Service URL: URL of a TAP server (e.g., http://DacHS_server.../tap - "/tap" will be added if missing).
• Schema name: Name of the EPN-TAP schema to query - this is normally the service short name (e.g., vvex, not vvex.epn_core)

These two fields must be informed in Custom Service mode. This mode is mostly intended to access services which are not publicly open, i.e., installed on a TAP server but not declared in the registry (e.g., a test version). It can also be used to bypass the query of all services if you want to work with a specific published service. Note: these fields are usually memorized by your browser and available for completion. To remove a memorized value, highlight it and press Shift-Delete.

All service mode

Choose "All services" from the cog wheel menu on the upper right to return to standard mode and query all registered services (as described above).

ADQL query

Click the "ADQL query" field on top of the parameter form (this toggles between standard and ADQL forms). The parameter form is replaced by a free text field where advanced users can write a query directly in ADQL language. The Query mode only addresses the WHERE clause of the ADQL query. This mode can be combined with the Custom service mode to send a query to a single service.
Beware that comparison operators write, e.g., >= for ≥
This mode allows for powerful searches using the footprint provided in the s_region parameter, such as:
 INTERSECTS(s_region, POLYGON('UNKNOWNFrame', 150, 0, 150, 5, 190, 5, 190, 0))=1
 CONTAINS(s_region, POLYGON('UNKNOWNFrame', 150, 0, 150, 5, 190, 5, 190, 0))=1
and searches of individual values in lists, such as:
 ivo_hashlist_has(lower(instrument_name), 'iks') = 1
The latter function is supported at least by DaCHS servers (used by most EPN-TAP services).
To issue more sophisticated queries on a single service (or to non EPN-TAP services on a single server), TOPCAT and TapHandle may prove more flexible than the VESPA portal.

Advanced query

This mode is accessible from the Result page of an individual service.
In the query form area, all non-mandatory parameters present in the service are accessible in the "Other" panel with a scroll-down menu starting with "s_region". Click the "+" button to use several such parameters, "x" to remove one.

Query results

Service status

• Green (with 3 icons): Results exist
• Grey (with 2 icons): No result found
• Red (with a single icon): Error (service not responding, or not supporting the query)

The server answer is always be available under the "Download VOTable" icon, even if the service is in error. In this case it provides a diagnosis of possible issues, as per TAP protocol requirements.

Service details

A short description of each service is available by clicking the rightmost icon info.

Service actions

Several actions are possible on services providing results:

• Clicking the name of the service displays a table of all results in this service for further examination.
• Send with SAMP: Will send the metadata VOTable to another VO application using the SAMP protocol (typically TOPCAT).
  If no SAMP compatible application is open, the TOPCAT webstart will be downloaded. Links to common VO applications are available under the "Help" menu in the upper right corner of the page.
• Download VOTable: Load the metadata VOTable on your computer (possibly including an error message from the server).

EPN-TAP compilation results

Below the list of services, a single box provides a list of cumulated results from all EPN-TAP services. This is provided as a VOTable which can only be downloaded or sent via SAMP (typically to TOPCAT). The VOTable contains a list of matching elements from all services with description limited to mandatory EPN-TAP parameters.
Beware that only the first 10 results of each service are included to keep this function responsive - if you get too many results, you may want to restrain your query further.

Other data services

The user's EPN-TAP query is also converted and forwarded to other services, so as to support discovery in other data distribution systems. Links appear in separated boxes below the list of EPN-TAP services.
First, the query is sent to PDAP servers located at ESA (PSA) and JAXA (DARTS). PDAP is an older protocol mainly used to mirror archives between space agencies. It is limited to return only matching datasets, not data files (the DARTS interface also requires a target_name value, or will return an error). PDAP results can be downloaded as a VOTable from the portal.
Second, the query is converted to address the NASA PDS catalogue service, again at dataset level. The link provided in the portal leads to a NASA page listing results found in both NASA and ESA PDS archives. This page starts with a list of links grouped in various categories (agency, mission, instrument, etc).

Service results

This page displays a table containing the service results with basic description. Extra parameters can be selected in the "Column visibility" and with the "Show all" buttons. The number of rows per page can be selected in the "Show xx entries" button at the bottom left corner, and browsed with the buttons at the bottom right corner.
The link under the service acronym (second line) redirects to the main web site of the service, if available.
The left menu is still available to change or refine your query in the displayed service.

Mouse actions

• Mouse over: When hovering the mouse over the table, a thumbnail may be displayed in real time (if provided by the service).
• Access_url field: Clicking the link will load the data file (will be downloaded if format can't be plotted in a browser).
• Selections: Individual results can be selected/unselected by simply clicking on table lines. "Select all" / "Reset" buttons are available on top of the table.
• Sorting: Rows are sorted according to a parameter when clicking on the column headers.
• Unit: Spectral scale can be displayed as frequency (in Hz), wavelength (in µm), or wavenumber (in cm-1) by clicking the unit in the header - spectral step is only available as frequency, while spectral resolution is dimensionless.

Data & metadata retrieval

Information can be sent to open VO applications using the local menus at the bottom of the list. If required, the preferred VO application will be downloaded on your machine (as java webstart) - alternatively you can run an existing local version to save time; links to common VO applications are also available under the "Help" menu in the upper right corner. Four menus are available to process data (links provided under access_url) or metadata (the table content), either for the whole table or the currently selected lines.

• Data/Download: Will download the data file on your computer for manual use (multiple entries are zipped). This menu and the next one are greyed out when the data are scalars included in the table itself.
• Data/Send [type]: Send data file(s) with specified data type - will open in VO applications supporting this data type, e.g., images in Aladin (see "VO tools" under "Help"). Special types include CDF (sent to TOPCAT) and Virtis PDS spectral cubes (opens APERICubes for display and converts to fits - you still have to click on the "Process Samp Cube" button to see it)
• Metadata/Download: Will download the metadata file on your computer as a VOTable for manual use (multiple entries are merged - same as the corresponding icon on the Query result page).
• Metadata/Send table: Send the footprints of selected rows in various format to adequate applications. GeoJSON may open in TOPCAT, s_region and MOC will open in Aladin (you may want to load a HiPS map of the target first in Aladin).

The two menus on the bottom right allow you to visualize data footprints:

• Target: List the targets present in the service
• Footprints: Send the footprints of selected rows in various format to adequate applications. GeoJSON may open in TOPCAT, s_region and MOC will open in Aladin (you may want to load a HiPS map of the target first in Aladin)

If you need to retrieve an ascii version of data provided as VOTable (e.g., Titan profiles service), first check if the service includes rows providing the data in ascii format. Otherwise, send as Table to TOPCAT and save it in ascii from there (this can be scripted for pipeline processing).
In case the data are not sent to the support application (webstart reloaded continuously), try and deactivate any proxy in your browser.
Direct solutions exist to load data in IDL/GDL, in particular for PDS3 files and VOTables. Queries are also possible from python (pyvo library) and other environments.