Next Previous Up Contents
Next: calc: Evaluates expressions
Up: arrayjoin: Adds table-per-row data as array-valued columns
Previous: Usage

### 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.

Next Previous Up Contents
Next: calc: Evaluates expressions
Up: arrayjoin: Adds table-per-row data as array-valued columns
Previous: Usage

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk