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=dl_dr3.fits
                 icmd='select has_epoch_photometry'
                 atable='"https://gea.esac.esa.int/data-server/data?RETRIEVAL_TYPE=EPOCH_PHOTOMETRY&ID=Gaia+DR3+"+source_id' \
                 afmt=votable \
                 acmd='select equals(BAND,\"G\")' \
                 acmd='keepcols "time mag flux"' \
                 out=with-epoch-photom.fits

Similar to the previous example, but this time acquiring EPOCH_PHOTOMETRY rather than XP_SAMPLED data, and performing some additional processing of the main and array input tables. 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=obscore-lotssdr2.vot
                 atable='equals(dataproduct_type,"spectrum")?access_url:""'
                 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. For rows in the input table whose dataproduct_type field does not have the value "spectrum" a blank location is substituted insteead of the access_url. That has the effect of ensuring that no attempt is made to add array values for non-spectrum rows of the input table, while retaining those rows in the output. Note all the access_urls in the selected rows must point to spectrum files of a of a similar form, otherwise the command will fail.