B.1.2 Examples

Here are some examples of using arrayjoin:

stilts arrayjoin in=dr3-sources.vot
                 atable='"https://gea.esac.esa.int/data-server/data?RETRIEVAL_TYPE=XP_SAMPLED&RELEASE=Gaia+DR3&ID="+source_id'
                 icmd=progress
                 out=sources-with-xp.fits

This command uses the Gaia DR3 DataLink service to attach sampled XP spectrum data to an input table containing other information about Gaia DR3 sources.

The input file dr3-sources.vot must contain the column source_id giving the Gaia DR3 source ID corresponding to that row. The atable expression is a URL built using that source_id column and a base URL that can be obtained by examining the DR3 catalogue documentation, or by examining the DataLink service descriptor returned from a source catalogue query.

The output file sources-with-xp.fits is a FITS table with the same content as the input but with three added array-valued columns, wavelength, flux and flux_error as supplied by tables downloaded from the URL in the atable parameter. For each row of the output table, the lengths of those three arrays will be the same, namely the row count of the table that supplied them. These matched arrays can be manipulated within STILTS, for instance using the Arrays functions or to produce plots using the lines or arrayquantile plot layer types.

The icmd=progress filter is a useful convenience to see how the command is progressing, since the operation requires multiple downloads and so may be time-consuming.

stilts arrayjoin in=dr3-sources.vot
                 atable='"https://gea.esac.esa.int/data-server/data?RETRIEVAL_TYPE=XP_SAMPLED&RELEASE=Gaia+DR3&ID="+source_id'
                 icmd=progress
                 keepall=false
                 ocmd='constcol -acceptnull'
                 out=sources-with-xp.fits

Similar to the previous example, but with a couple of variations.

The keepall=false parameter means that only those rows for which array data exists will be retained in the output table, rather than including blank entries in the array columns in cases for which the remote table couldn't be loaded.

The ocmd='constcol -acceptnull' filter looks for columns in the output that have the same value (or null) in every row. Since Gaia DR3 sampled spectra are all sampled onto the same grid, in this case the wavelength column will have the same array value for every row, which is harmless but makes the output table larger than required. The constcol filter spots this and removes the wavelength column, replacing it with a parameter having the same name, which can therefore be referred to using the expression language as param$wavelength.

stilts arrayjoin in=dl_dr3.fits
                 icmd='select has_epoch_photometry'
                 atable='"https://gea.esac.esa.int/data-server/data?RETRIEVAL_TYPE=EPOCH_PHOTOMETRY&ID="+urlEncode(designation)'
                 afmt=votable
                 acmd='select equals(BAND,\"G\")'
                 acmd='keepcols "time mag flux"'
                 out=with-epoch-photom.fits

Similar to the first example, but this time acquiring EPOCH_PHOTOMETRY rather than XP_SAMPLED data, and performing some additional processing of the main and array input tables. The value of the designation field is wrapped in the urlEncode function when preparing the URL; this is necessary since that field may contain spaces which are not legal URL characters. Only those input rows are used for which the boolean has_epoch_photometry column is True; for the linked array tables the rows are limited to those with the BAND column having the value "G"; and only the array columns time, mag and flux are retained for inclusion into the output.

stilts arrayjoin in=rrlyrae.vot
                 atable='"https://gaia.ari.uni-heidelberg.de/timeseries/gaiadr3?sourceid="+source_id'
                 acmd='keepcols "time mag flux flux_error"'
                 aparams='p1 pf'
                 icmd=progress
                 out=rrlyrae-timeseries.vot

Acquires Gaia DR3 epoch photometry from a different service, ARI-Gaia. In this case the epoch photometry tables have parameters characterising the variability; the aparams='p1 pf' parameter takes two of these and adds them as scalar-valued columns in the output table. Since the pf parameter gives the variability period, a period-folded variability graph can then be plotted using an X coordinate like arrayFunc("x%1",divide(time,pf)).

stilts arrayjoin in=obscore-lotssdr2.vot
                 atable=access_url
                 icmd=progress
                 icmd='select equals(dataproduct_type,\"spectrum\")'
                 out=with-spectra.vot

Takes an ivoa.ObsCore-like table and adds array-valued columns giving the content of spectrum files linked from the access_url field. Only those rows with a dataproduct_type of "spectrum" are included. Note all the access_urls in the selected rows must point to spectrum files of a similar form (i.e. having the same columns), otherwise the command will fail.