<resource schema="gedr3dist">
	<meta name="creationDate">2020-11-13T13:09:26Z</meta>
	<meta name="schema-rank">20</meta>

	<meta name="title">Geometric
		and photogeometric distances to 1.47 billion stars in Gaia Early
		Data Release 3 (eDR3)</meta>
	<meta name="description" format="rst">
We estimate the distance from the Sun to sources in Gaia eDR3 that have
parallaxes. We provide two types of distance estimate, together with
their corresponding asymmetric uncertainties, using Bayesian posterior
density functions that we sample for each source.  Our prior is based
on a detailed model of the 3D spatial, colour, and magnitude
distribution of stars in our Galaxy that includes a 3D map of
interstellar extinction.

The first type of distance estimate is purely geometric, in that it only
makes use of the Gaia parallax and parallax uncertainty. This uses a
direction-dependent distance prior derived from our Galaxy model.  The
second type of distance estimate is photogeometric: in addition to
parallax it also uses the source's G-band magnitude and BP-RP
colour. This type of estimate uses the geometric prior together with a
direction-dependent and colour-dependent prior on the absolute magnitude
of the star.

Our distance estimate and uncertainties are quantiles, so are invariant
under logarithmic transformations. This means that our median estimate
of the distance can be used to give the median estimate of the distance
modulus, and likewise for the uncertainties.

For applications that cannot be satisfied through TAP, you can download
a `full table dump`_.

.. _full table dump: /gedr3dist/q/download/form
	</meta>
	
	<meta name="subject">milky-way-galaxy</meta>
	<meta name="subject">stellar-distance</meta>
	<meta name="subject">surveys</meta>
	<meta name="subject">stars</meta>

	<meta name="creator">Bailer-Jones, C.A.L.; Rybizki, J.;
	Fouesneau, M.; Demleitner, M.; Andrae, R.</meta>
	<meta name="instrument">Gaia</meta>

	<meta name="source">2021AJ....161..147B</meta>
	<meta name="contentLevel">Research</meta>
	<meta name="type">Catalog</meta>

	<meta name="_news" author="MD" date="2022-08-29" role="updated">
		The litewithdist join and hence the data coming out of the cone
		service are now based on the final DR3 gaia_source rather than
		eDR3 as before.
	</meta>

	<FEED source="//procs#license-cc-by" what="The Gaia eDR3 (photo-) geometric
		distances catalogue."/>
	<meta name="coverage.waveband">Optical</meta>

	<STREAM id="edr3distcolumns">
		<column name="r_med_geo"
			unit="pc" ucd="pos.distance"
			tablehead="Dist"
			description="The median of the geometric distance posterior.
				The geometric distance estimate."
			displayHint="sf=3"
			verbLevel="1" note="d">
			<property name="statisticsTarget">3000</property>
		</column>
		<column name="r_lo_geo"
			unit="pc" ucd="pos.distance;stat.min"
			tablehead="Dist. Low"
			description="The 16th percentile of the geometric distance posterior.
				The lower 1-sigma-like bound on the confidence interval."
			displayHint="sf=3"
			verbLevel="5" note="d"/>
		<column name="r_hi_geo"
			unit="pc" ucd="pos.distance;stat.max"
			tablehead="Dist. High"
			description="The 84th percentile of the geometric distance posterior. The
				upper 1-sigma-like bound on the confidence interval."
			displayHint="sf=3"
			verbLevel="5" note="d"/>

		<column name="r_med_photogeo"
			unit="pc" ucd="pos.distance"
			tablehead="Dist"
			description="The median of the photogeometric distance posterior.
				The photogeometric distance estimate."
			displayHint="sf=3"
			verbLevel="1" note="d">
			<property name="statisticsTarget">3000</property>
		</column>
		<column name="r_lo_photogeo"
			unit="pc" ucd="pos.distance;stat.min"
			tablehead="P. Dist. Low"
			description="The 16th percentile of the photogeometric distance
				posterior. The lower 1-sigma-like bound on the confidence interval."
			displayHint="sf=3"
			verbLevel="5" note="d"/>
		<column name="r_hi_photogeo"
			unit="pc" ucd="pos.distance;stat.max"
			tablehead="P. Dist. High"
			description="The 84th percentile of the photogeometric distance
				posterior. The upper 1-sigma-like bound on the confidence interval."
			displayHint="sf=3"
			verbLevel="5" note="d"/>

		<column name="flag" type="text"
			ucd="meta.code"
			tablehead="Flags"
			description="Additional information on the solution.  Do not use
				for filtering (see table note in the reference URL)."
			verbLevel="15"
			note="f"/>

		<meta name="note" tag="d">
			For each source we compute two posterior probability distributions over
			distance: a geometric one and a photogeometric one.  “Geometric” means
			only parallax and the parallax uncertainty were used.  “Photogeometric”
			means the G magnitude and the BP-RP colour were used as well.  For each
			of these posterior distributions we estimate and provide three quantiles:
			0.158655 (“Lo“), 0.5 (“Med”), and 0.841345 (“Hi”).

			“Med” is the median of the distribution, and should be taken as the
			distance estimate itself. “Lo” and “Hi” define the lower and upper ends
			of the equal-tailed 68% (actually 68.269%) confidence interval on this
			estimate.  If the posterior were Gaussian, then (r_hi_geo-r_lo_geo)/2
			would be the 1-σ Gaussian uncertainty of the geometric distance (and
			similarly for the photogeometric distance). However, we stress that
			these confidence bounds are asymmetric, sometimes significantly so.

			The distance estimates are predicated on the assumption that the source
			is a single star in our Galaxy.  Estimates are provided whereever
			possible for sources that have the required input data, independent of
			any other knowledge on the nature of that source (e.g. being a binary
			star or quasar).
		</meta>

		<meta name="note" tag="f"><![CDATA[
The flag is normally a string with 5 decimal digits, ABBCC, the meaning of
which is explained below. In some cases it can be "99", as also explained
below.

This flag field is for information. It is not recommended to use this to filter
out sources.  Users may want to filter on the size of the distance confidence
interval or on quality fields in the eDR3 gaia_source catalogue, such as ruwe,
visibility_periods_used, or parallax_over_error. See the `accompanying
paper`_ for more information.

:A:
  :0:
  	source does not have a G magnitude
  :1:
  	source has G <= G_lim for that HEALpixel
  :2:
  	source has G >  G_lim for that HEALpixel

:B:
  The first (left-most) digit refers to the geometric posterior, the
  second to the photogeometric posterior.
  It indicates whether we have a low p-value (<1e-3) in the Hartigan Dip test
  (null hypothesis that posterior is unimodal, so small p suggests
  evidence against this).  Two-digit integer. Each digit can be:

  :0:
    not set, so assume unimodal hypothesis okay (or if test is not done
    or gives no answer)
  :1:
    set, so possibly multimodal.

  For instance, 10 means geo possibly multimodal, photgeo probably unimodal
  Moreover, the computed confidence interval often spans any multimodality, so
  generally speaking sources do not need to be excluded just because of
  evidence of multimodality from this test. This flag refers to the
  posterior as sampled by the MCMC rather than the true posterior.

:C:
  QG models used to compute the photogeometric posterior. Two digit integer.
  Each digit can be:

  :0:
    NULL
  :1:
    one-component Gaussian model
  :2:
    two-component Gaussian model
  :3:
    smoothing spline

  The first (left-most) digit refers to the lower (bluer) model, the second to
  the upper (redder) model.
  E.g. 13 means the lower one was a one-component Gaussian and the upper
  one was was spline.

There is also a special setting of this flag:

:99:
  data (G or BP-RP) were missing (so no photogeo distance could be computed)

	.. _accompanying paper: http://www.mpia.de/homes/calj/gedr3_distances.html
		]]></meta>
	</STREAM>

 	<table id="main" onDisk="True" adql="True" nrows="1470000000">
 		<publish sets="ivo_managed,local"/>
		<primary>source_id</primary>
		<index columns="r_med_geo"/>
		<index columns="r_med_photogeo"/>

		<column original="gaia/q3#dr3lite.source_id"/>
	
		<FEED source="edr3distcolumns"/>
	</table>


	<coverage>
		<spatial>0/0-11</spatial>
	</coverage>

	<data id="import">
		<sources pattern="data/dist_*.csv"/>
		<recreateAfter>make_view</recreateAfter>

		<directGrammar id="booster" cBooster="res/boosterfunc.c"
			type="split" autoNull="NA" splitChar=","/>

		<make table="main"/>

<!-- Fallback for non-booster operation
		<csvGrammar/>

		<make table="main">
			<rowmaker idmaps="*">
				<LOOP>
					<csvItems>
						ourName, theirName
						r_med_geo, rMedGeo
						r_lo_geo, rLoGeo
						r_hi_geo, rHiGeo
						r_med_photogeo, rMedPhotogeo
						r_lo_photogeo, rLoPhotogeo
						r_hi_photogeo, rHiPhotogeo
					</csvItems>
					<events>
						<map key="\ourName">parseWithNull(@\theirName, float, "NA")</map>
					</events>
				</LOOP>
			</rowmaker>
		</make>-->
	</data>

	<service id="download" allowed="form">
		<!-- I don't want to have the endless download to be handled by DaCHS,
		as I'd hate it if I'd have to wait for many hours for one of these
		huge downloads to finish.  Thus, I let apache do the actual download;
		the redirect below assumes hsoy/static is readable for the web server
		and there's something like

		location /gedr3dist/ {
			alias /data/gavo/inputs/gedr3dist/data/;
		}
		
		/etc/nginx/site-enabled/vo.ari.conf on alnilam -->

		<meta name="title">Download guard for gedr3dist dump</meta>
		<template key="form">res/downloadguard.html</template>
		<pythonCore>
			<inputTable>
				<inputKey type="text" name="input" multiplicity="single"
					tablehead="I read the warning"
					description="Type in 'yes' here to pull the data"/>
			</inputTable>
			<outputTable/>
			<coreProc>
				<code>
					from gavo import svcs

					if inputTable.getParam("input")=="yes":
						raise svcs.WebRedirect(
							"http://vo.ari.uni-heidelberg.de/gedr3dist/gedr3dist.dump.gz")
					else:
						raise base.ValidationError("This must be 'yes' (without any"
							" quotes)", "input")
				</code>
			</coreProc>
		</pythonCore>
	</service>

	<table id="litewithdist" onDisk="True" adql="True" nrows="1470000000">
		<meta name="title">Gaia (e)DR3 lite distances subset</meta>
		<meta name="description" format="rst">This table joins the DR3 "lite" table
			(consisting only of the columns necessary for the most basic
			science) with the estimated geometric and photogeometric distances.
			Note that this is an inner join, i.e., DR3 objects without
			distance estimates will not show up here.

			Note: Due to current limitations of the postgres query planner,
			this table cannot usefully be used in positional joins
			("crossmatches").  See the `Tricking the query planner`_ example.

			.. _tricking the query planner: http://dc.g-vo.org/tap/examples#Trickingthequeryplanner
		</meta>

		<FEED source="gaia/q3#dr3litecolumns"/>
		<FEED source="edr3distcolumns"/>

		<FEED source="//procs#declare-indexes-from"
			sourceTables="gaia/q3#dr3lite main"/>

		<viewStatement>
			CREATE VIEW \qName AS (
				SELECT \colNames FROM (
					\schema.main
					JOIN gaia.dr3lite
					USING (source_id)))
		</viewStatement>
	</table>

	<data id="make_view" auto="False">
		<make table="litewithdist"/>
	</data>

	<service id="cone" allowed="scs.xml,form,static">
		<meta name="title">Gaia DR3 Lite Distances Subset Cone Search</meta>
		<meta name="description">This service returns the most important
			Gaia DR3 gaia_source columns together with robust geometric and
			photogeometric distances for the ~1.47 billion objects in Bailer-Jones
			et al's distance catalogue.</meta>
		<meta name="shortName">DR3 lite+dist</meta>
		<publish sets="local,ivo_managed" render="form"/>
		<publish sets="ivo_managed" render="scs.xml"/>
		<meta>
			testQuery.ra: 303.28511
			testQuery.dec: 40.92948
			testQuery.sr: 0.001
		</meta>

		<property name="staticData">data</property>
		<scsCore queriedTable="litewithdist">
			<FEED source="//scs#coreDescs"/>
			<condDesc buildFrom="source_id"/>
			<condDesc buildFrom="r_med_geo"/>
			<condDesc buildFrom="r_med_photogeo"/>
		</scsCore>
	</service>

	<regSuite title="gedr3dist regression">
		<regTest title="gedr3dist SCS serves some data">
			<url RA="303.29915"
					DEC="41.03876" SR="0.001"
				>cone/scs.xml</url>
			<code>
				row = self.getFirstVOTableRow(rejectExtras=False)
				self.assertEqual(row["source_id"], "2062599774097558784")
				self.assertAlmostEqual(row["pmra"], 0.08117900043725967)
				self.assertAlmostEqual(row["r_lo_photogeo"], 2672.26171875)
			</code>
		</regTest>
	</regSuite>
</resource>
