Génération d'un graphe VizieR à partir d'un fichier SQL

Contents:

2 méthodes sont disponibles dans VizieR pour générer des graphes.

Le document traite uniquement de la méthode utilisant le pseudo-SQL pour extraire des données. La méthode peut s'appliquer aux fichiers FITS, TSV, ASCII ou depuis une commande SHELL.

1  Interrogation WEB

2 méthodes sont disponibles:
  1. exécution (du script) sur le serveur. Cette méthode est à privilégier lorsque le nombre de lignes est > 10,000.
    Le résultat est une simple page statique contenant le graphe et un formulaire

    Exemple

  2. exécution sur le navigateur client.
    Le résultat est une page dynamique contenant le graphe et un formulaire complet.

    Exemple

2  Mise en oeuvre - Apercu

Dans le fichier ".status", l'instruction \vPlot indique le fichier SQL qui sera exécuté lors de l'affichage du graphe.

3  Description des syntaxes utilisées

3.1  Le pseudo-SQL

Le language d'extraction des donnés s'apparente au SQL. La syntaxe générale est la suivante:

SELECT expression1, expression2, ... FROM ressource WHERE conditions

Où:
expression : expression arithmétique constituée par des noms de colonnes. Une colonne peut être désignée par son numéro de colonne: $i (i-ème colonne)
ressource : le nom de la ressource entouré par des doubles-quotes: un fichier ASCII, TSV, FITS ou une commande SHELL
conditions : Condition d'extraction de la donnée

Exemple:
Sélection des 2 premières colonnes du fichier 'fichier.fits' lorsque la valeur de la premi\ère colonne est inférieur à 10: 

SELECT $1,$2 FROM "fichier.fits" WHERE $1<10
Sélection des colonnes RAW, FLUX, ERRFLUX du fichier 'fichier.fits' lorsque la valeur ERRFLUX est inérieur à 0.1: 
SELECT RAW, FLUX, ERRFLUX FROM "fichier.fits" WHERE ERRFLUX < 0.1
Sélection de 2 colonnes calculés à partir des 2 premi\ères colonnes du fichier 'fichier.fits': 
SELECT  ($1+2)*10, $1+$2 FROM "fichier.fits"

Notes: on peut:

3.2  Le fichier .status

\vPlot{catalogue}{fichier_sql}{options}{column_value}
Graphe standard exécuté sur le serveur (cas 1) 
\vplot{catalogue}{fichier_sql}{options}{column_value}
Graphe standard exécuté sur le navigateur (cas 2) 
\vPlotTS{catalogue}{fichier_sql}{options}{column_value}
Time serie exécuté sur le serveur (cas 1) 
\vplotTS{catalogue}{fichier_sql}{options}{column_value}
Time serie exécuté sur le serveur (cas 2)

Explications des arguments:
catalogue : nom du catalogue (ex: II/246)
fichier_sql : nom du fichier SQL (ex: graph) 
options : liste de paramètres séparés par des & (ex:file=file.dat&id=1)

Notes concernant les options:

param=value : modifie les variables ${param} du fichier SQL par value

Exemple: 

\vplotTS{@{@cat}}{graph1}{corot=@{CoRoT}&file=files/@{*FileName}}{}

3.3  Le fichier SQL et exemples pratiques

Le fichier SQL utilise le pseudo-SQL comme language.

3.3.1  Type de plot, barres d'erreurs, ...

Pour construirre le plot, il faudra renseigner :

3.3.2  Interagir sur le plot

En plus de la requête, le fichier SQL permet de modifier la sortie du graphe:

3.3.3  Interagir sur des valeurs variables ou des valeurs de colonnes(SQL dynamique)

Il s'agit de valeurs identifiées par ${...} du fichier SQL. Elles peuvent être modifiées par la commande \vPlot du fichier ".statut" par le paramètre {options}.
La syntaxe du fichier ".status" authorise l'utilisation des valeurs de colonne (ex: recno=${recno}, dans ce cas la colonne recno).

Exemple B/corot graphe

La définition de la colonne Plot dans le fichier .Summary modifie les valeur corot et file du fichier SQL .graph1 par les valeurs des colonnes de la table. 

\vizLink{ astero }{ Plot }{ Plot }{ \vizContent{timeSerie}\vPlotTS{@{@cat}}{.graph1}{corot=@{CoRoT}&file=files/@{FileName}}{plot}}{ Plot the time serie }

Fichier SQL ".graph1" 

set Title=CoRoT ${corot}
corot:-y:SELECT f.$1.DATEJD, f.$1.RAWFLUX from "${file}" f  where RAWSTATUS=0

Note: les variables peuvent être utilisées dans tout le fichier SQL: ce qui comprend les valeurs du titre, période, etc.

3.3.4  Plusieurs plots dans un seul graphe

Un fichier peut contenir plusieurs requêtes SQL. Dans ce cas le plot sera composé de plusieurs graphes.

Syntaxe 

titre1:SELECT .....
titre2:SELECT .....

Exemple: B/corot graph

colonne ajoutée (fichier .Summary) 

\vizLink{ exo }{ Plot1 }{ Plot1 }{ \vizContent{timeSerie}\vPlotTS{@{@cat}}{.graphexo}{corot=@{CoRoT}&file=files/@{FileName}}{plot}}{ Plot the time serie }

Fichier SQL ".graphexo" 

set Title=CoRoT ${corot}
set Filter=red
white: select f.$1.$2, f.$1.$8 from "${file}" f where $4=0
red:   select f.$1.$2, f.$1.$5 from "${file}" f where $4=0
green: select f.$1.$2, f.$1.$6 from "${file}" f where $4=0
blue:  select f.$1.$2, f.$1.$7 from "${file}" f where $4=0

Dans l'exemple ci dessus, l'instruction "set Filter" a pour but de n'afficher que le plot correspondant à la ligne commencant par "red".

3.3.5  Simplification du SQL: utiliser un alias

la commande set permet de créer un alias.

Exemple III/185 graph (serveur) graph (client)

colonne ajoutée (fichier .Summary) 

\vizLink{ stars }{}{Plot}{+\vizContent{timeSerie}\vPlotTS{${$cat}}{.graph1}{HR=${HR}}{plot} }{plot}

Fichier SQL ".graph1" 

set asu="asu -source=III/185/table1 -out=JD-2440000,RV,e_RV"
Light_curves: SELECT $1 as 'JD-2440000', $2 as 'V[m/s]', $3 as err FROM "${asu} HR==${HR}"

3.3.6  Timeserie avec une periode dynamique

Dans l'exemple suivant la periode est calculée \à partir de la valeur d'une colonne.

Pour cela, on utilise le paramètre option de la command vplot du fichier .status: 

\vPlot{@{@cat}}{.graph_sql}{Name=@{Name}&Per=@{*Per}}{LC}
La variable Per est utilisée ensuite dans le fichier SQL: 
Set Period=${Per}

Example J/AJ/145/60 graphe

3.3.7  Ajouter des conditions à l'aide de la commande ifmatch (fichier .status)

Dans l'exemple suivant le graph peut ou non avoir une période selon que la colonne Per est valuée. L'instruction du fichier SQL "Set Period=0" permet de n'appliquer aucune Période. Ensuite le test se fait dans le fichier .status 

\ifmatch{[0-9]*}{@{*Per}}\vPlotTS{@{@cat}}{.graph_sql}{LRL=@{LRL}&m_LRL=@{m_LRL}&Per=@{*Per}}{LC}\else \vPlotTS{@{@cat}}{.graph_sql}{LRL=@{LRL}&m_LRL=@{m_LRL}&Per=0}{LC}\fi

Example J/AJ/145/66 graphe

Dans l'exemple suivant, le titre est construit a l'aide du nom de l'objet qui est donné par la colone Name. Lorsque la valeur de la colonne Name est un nombre, il s'agit d'un numéro HD. 

\ifmatch{[0-9]*}{@{Name}}
\vPlotTS{@{@cat}}{.graph_sql}{Name=@{Name}&STAR=HD}{VP}\else \vPlotTS{@{@cat}}{.graph_sql}{Name=@{Name}&STAR=}{VP}\fi
Example J/ApJS/210/5 graphe

3.3.8  Un plot composé par plusieurs requêtes SQL

Il est possible de scinder les valeurs (X,Y) en deux requêtes SQL. La première requête contenant la valeur en abscisse, la seconde la valeur en ordonnée. Pour ce faire, on utilise le même "titre".

Syntaxe 

titre:SELECT \$1 FROM resource1
titre:SELECT \$2 FROM resource2

Exemple J/A+A/558/A18 graph

colonne ajoutée (fichier .status) 

\vizLink{ table2 }{ Plot }{ Plot }{ \vizContent{timeSerie}\vPlotTS{@{@cat}}{.graph1}{file=@{*FileName}}{plot}}{ Plot the time serie) }

Fichier SQL ".graph1" 

set fits=fits2a -x 1 -par /home/cats/J/A+A/558/A18/sp/
spectrum: SELECT $1 as 'v(km/s)' from "transpose(${fits}${file}| egrep VLSR)" f
spectrum: SELECT $1 as 'T(K)' from "transpose(${fits}${file}| egrep DATA)" g

3.3.9  Utiliser une constante issue d'une commande SHELL

On utilise le symbole "`" pour délimiter une commande SHELL (comme c'est le cas dans un scipt SHELL).

Syntaxe 

set cst=`comande shell`
sql:select ${cst}*$1,$2 FROM ....

Exemple: catalogue RAM30m reduced spectra of 59 sources (Gerner+, 2014)

colonne ajoutée (fichier .status) 

\vPlot{@{@cat}}{.graph1}{file=@{sp}}{plot}

Dans l'exemple suivant, les valeurs v0 et nu0 sont calculés avec la commande fits.

Fichier SQL ".graph1" 

set v0=`fits2a -TOC ${file} | fgrep "VELO-LSR" | acut -c10-20`
set nu0=`fits2a -TOC ${file} | fgrep "RESTFREQ" | acut -c10-30`
graph:SELECT ${v0}-$1*(299792458/${nu0}/1000),$2 FROM "${file}"

Exemple graphe

3.3.10  Tracer un plot à partir d'une colonne contenant des vecteurs dans un fichier FITS

Nous utilisons ici la fonction transpose.

Exemple: voir section

L'instruction "fits2a -x 1 -par /home/cats/J/A+A/558/A18/sp/${file}" récupère les données du fichier fits.

L'instruction "${fits}| egrep VLSR" filtre le précédent résultat en n'afichant que la ligne VLSR.

L'instruction "transpose(${fits}| egrep VLSR)" transforme la ligne du résultat précédent en une colonne.

3.3.11  Utilisation d'un compteur

Il est possible d'ajouter une variable type compteur avec l'instruction "set Counter=true" du fichier SQL. Ainsi définit, la variable COUNTER peut être utilisée comme un compteur dans l'instruction SQL.

Exemple 

set Counter=True
graphe_label:select COUNTER as n , $1 from ...

qui renvoie quelque chose du genre
1	val1
2	val2
3	val3
....

La variable COUNTER peut être incluse dans une expression arithmétique: 

graphe_label:select COUNTER*2 as n , $1 from ...

qui renvoie quelque chose du genre
2	val1
4	val2
6	val3
....

Autre exemple 

...
Set Counter=true
...
graph:SELECT 36.499-(${f0}+(COUNTER-1)*${df})*(299792458/${nu0}/1000) as 'V[km/s]', $2 as 'T[K]' FROM "${file}"

Exemple J/A+A/564/A99 graphe

3.3.12  Personnalisation des labels des axes du graphe

S'il s'agit d'un fichier FITS, les métadonnées du fichier permettront de créer des labels pour décrire les axes des abscisses et des ordonnées.

Il est possible de forcer l'utilisation d'un label en utilisant le mot clé SQL: AS.

Exemple: 

titre: SELECT $1 AS 'titre abscisse', $2 AS 'titre ordonnees

3.3.13  Personnalisation du mode de tracé et des couleurs

Exemple: 

titre:-b:SELECT ....

Les couleurs:
Abv color
k black
m magenta
v viollet
b blue
c cyan
G dark green
g green
R dark red
r red
y orange

Les tracés:
- les points sont reliés par des traits
. un point
o un gros point
* une étoile
+ un plus

4  Description des Outils

Description du programme vizgraph

Le programme vizgraph utilise le même script (vizgraph.py) que les pages WEB décrites à la section Interrogation WEB.
La commande vizgraph exécute le fichier SQL et retourne le résultat au format TSV. Le programme permet en outre de visualiser la commande AWK générée puis exécutée.
Enfin, l'argument '-d' permet d'afficher des messages de debuggage.

Exécution du fichier SQL: 

vizgraph fichier_sql

La même commande utilisant un script SQL contenant des variables ${..} à substituer:
(toutes les chaînes ${param} du fichier SQL sont remplacées par value) 

vizgraph fichier_sql param=value

La commande de base, sans arguments, affiche l'aide en ligne ainsi que les fichiers graphes présents dans le répertoire: 

vizgraph

Relation entre l'outil et les métadonnées

Le schéma suivant montre les relations entre le fichier .status, le fichier SQL et l'interrogation WEB.

5  Creation d'imagettes

Le programme vizgraph permet de generer des imagettes avec l'option -i.

Example: 

vizgraph -i sp .graph_sql
Dans l'exemple le programme genere des imagettes a partir des fichiers qui sont sous le repertoire "sp".

Limitations:la creation d'imagette se limite a generer des fichiers a partir de resources de type fichiers (FITS, ASCII, mais PAS de commade ASU). De plus, la creation est possible que s'il existe 1 ressource dans la partie FROM de la requete SQL (donc PAS de jointure).

Options de sorties: le processus cree des imagettes au format PNG. Il est possible de borner l'axe des abscisses dans le fichier SQL:

set Icon-xmax=... set Icon-xmin=...

Example: 

set Title=Spectrum ${FITSfile1}
set Icon-xmin=4000
set Icon-xmax=7000
spectrum:-g:SELECT $1 as '10e19 W/m2/A',$2 FROM "fits/${FITSfile1}"