<resource schema="toss">
	<meta name="title">TOSS – Tübingen Oscillator Strengths Service</meta>
	<meta name="creationDate">2015-08-10T11:30:00</meta>
	<meta name="schema-rank">100</meta>
	<meta name="description">
		This service provides oscillator strengths and transition probabilities.
		Mainly based on experimental energy levels, these were calculated with the
		pseudo-relativistic Hartree-Fock method including core-polarization
		corrections.
	</meta>
	<meta name="copyright">
		When publishing research making use of this tool, please acknowledge:
		“The TOSS service (http://dc.g-vo.org/TOSS) used for this paper
		was constructed as part of the activities of the German Astrophysical
		Virtual Observatory.”
	</meta>
	<meta name="creator">Rauch, T.; Quinet, P.; Hoyer, D.; Werner, K.;
		Demleitner, M.; Kruk, J. W.</meta>

	<meta name="subject">atomic-physics</meta>
	<meta name="subject">spectral-line-identification</meta>

	<meta name="source">2016A&amp;A...587A..39R</meta>
	<meta name="doi">10.21938/3i01isnuCODnh1zjbCvuwA</meta>

	<meta name="_news" date="2016-01-15" author="MD">
		Added lines for Krypton.

	</meta>
	<meta name="_news" date="2016-09-26" author="MD">
		Added lines for Zirconium and Xenon.
	</meta>

	<meta name="_news" date="2017-01-17" author="MD">
		Added lines for Selenium, Tellurium, and Iodine.
	</meta>

	<meta name="_news" date="2019-09-11" author="MD">
		Added lines for Copper.
	</meta>

	<meta>
		date: 2023-10-27
		date.role: ExportRequested
	</meta>

	<!-- upstream wanted a version of the data with air wavelength.  That's
	why we have two tables here. -->

	<table id="data" mixin="//slap2#lines">
		<meta name="description">
			This table contains line data computed using a pseudo-relativistic
			Hartree-Fock method including core-polarization corrections.
		</meta>

		<script type="afterMeta" lang="python" name="add biblinks">
			from gavo.protocols import biblinks

			biblinks.clearLinks(table.connection, table.tableDef.rd)

			src_id = base.getMetaText(
				table.tableDef.rd.getById("q"), "identifier")
			pubs_mentioned = [r[0].replace("bibcode:", "") for r in
				table.connection.query("SELECT DISTINCT reference_uri FROM toss.data")]
			biblinks.defineLinks(table.connection,
				table.tableDef.rd,
				[(pub, "IsSupplementedBy", src_id)
					for pub in pubs_mentioned])
		</script>

		<column original="species_name">
			<values>
				<option title="Z = 29: Cu">Cu</option>
				<option title="Z = 30: Zn">Zn</option>
				<option title="Z = 31: Ga">Ga</option>
				<option title="Z = 32: Ge">Ge</option>
				<option title="Z = 34: Se">Se</option>
				<option title="Z = 36: Kr">Kr</option>
				<option title="Z = 38: Sr">Sr</option>
				<option title="Z = 40: Zr">Zr</option>
				<option title="Z = 42: Mo">Mo</option>
				<option title="Z = 43: Tc">Tc</option>
				<option title="Z = 52: Te">Te</option>
				<option title="Z = 53: I">I</option>
				<option title="Z = 54: Xe">Xe</option>
				<option title="Z = 56: Ba">Ba</option>
			</values>
		</column>
		<column original="species_mass"
			description="Assumed mass of the atom; this is the mass given
				by NIST, https://www.nist.gov/pml/periodic-table-elements"/>
		<column name="ion_stage" type="text"
			ucd="phys.atmol.ionStage"
			tablehead="Stage"
			description="Ionisation stage"
			verbLevel="1"/>

		<column name="c_wavelength" type="double precision"
			unit="Angstrom" ucd="em.wl;phys.atmol.transition"
			tablehead="Lambda_c"
			description="Conventional wavelength of the transition.
				This is the air wavelength between 2000 and 20000 Angstrom,
				the vacuum wavelength otherwise."
			verbLevel="1">
		</column>

		<LOOP listItems="init final">
			<events>
				<column name="par_\item" type="char" required="True"
					ucd="phys.atmol.parity"
					tablehead="par_\item"
					description="Parity of the \item level of the transition"
					verbLevel="1">
					<values>
						<option>e</option>
						<option>o</option>
					</values>
				</column>
				<column name="j_\item"
					ucd="phys.atmol.qn"
					tablehead="j_\item"
					description="Angular momentum quantum number of the \item level of
						the transition."
					verbLevel="1"/>
			</events>
		</LOOP>
		<column name="log_gf"
			ucd="phys.atmol.wOscStrength"
			tablehead="log(gf)"
			description="Calculated HRF log(gf) (g – statistical weight
				of the lower level; f – oscillator strength)"
			verbLevel="1">
		</column>
		<column name="cf"
			ucd=""
			tablehead="CF"
			description="Cancellation factor as defined by 1981tass.book.....C"
			verbLevel="1"/>
	</table>

	<table id="legacy_data" onDisk="True" namePath="data">
		<meta name="description">A view on top of toss.data that
		has values in conventional units and with air wavelengths
		(rather than vacuum) between 2000 and 20000 Angstrom.</meta>
		<column original="c_wavelength"/>
		<column original="species_name"/>
		<column original="ion_stage"/>
		<column original="log_gf"/>
		<column original="einsteina"/>
		<column original="par_init"/>
		<column original="j_init"/>
		<column original="par_final"/>
		<column original="j_final"/>
		<column original="reference_uri"/>
		<viewStatement>
			CREATE VIEW \curtable as (SELECT
				c_wavelength,
				species_name,
				ion_stage,
				log_gf,
				einsteina,
				par_init,
				j_init,
				par_final,
				j_final,
				reference_uri
				FROM \schema.data)
		</viewStatement>
	</table>

	<data id="import">
		<recreateAfter>make_view</recreateAfter>
		<sources pattern="data/*.dat"/>
		<columnGrammar id="toss_grammar">
			<sourceFields>
				<setup>
					<par key="PUBLICATION_MAP"><![CDATA[{
						"AA_2012_20014": ("2012A&A...546A..55R",
							 "10.1051/0004-6361/201220014"),
						"AA_2014_24199": ("2015A&A...574A..29W",
							 "10.1051/0004-6361/201424199"),
						"AA_2014_23491": ("2014A&A...564A..41R",
							"10.1051/0004-6361/201423491"),
						"AA_2014_23878": ("2014A&A...566A..10R",
							"10.1051/0004-6361/201423878"),
						"AA_2014_25326": ("2015A&A...577A...6R",
							"10.1051/0004-6361/201425326"),
						"AA_2015": ("2016A&A...587A..39R",
							"10.1051/0004-6361/201527324"),
						"AA_2016_28131": ("2016A&A...590A.128R",
							"10.1051/0004-6361/201628131"),
						"AA_2016_29794": ("2017A&A...599A.142R",
							"10.1051/0004-6361/201629794"),
						"AA_2017_30383": ("2017A&A...606A.105R",
							"10.1051/0004-6361/201730383"),
						"AA_2019_36620": ("2020A&A...637A...4R",
							"10.1051/0004-6361/201936620"),
					}]]></par>
				</setup>
				<code>
					# add the publication
					key = re.sub("_table.*", "", os.path.basename(sourceToken))
					return {
						"pub": PUBLICATION_MAP[key][0],
						"doi": PUBLICATION_MAP[key][1],
					}
				</code>
			</sourceFields>
			<colDefs>
				chemical_element: 1-2
				ion_stage: 3-10
				wavelength:12-22
				c_wavelength:24-34
				initial_nubar: 36-45
				par_init: 47
				j_init: 49-52
				final_nubar: 54-63
				par_final: 65
				j_final: 67-70
				log_gf: 72-78
				ga: 80-89
				cf: 91-98
			</colDefs>
		</columnGrammar>

		<make table="data">
			<rowmaker idmaps="*">
				<var key="j_init"/>
				<var key="j_final"/>
				<var key="chemical_element"
					>@chemical_element.lower().capitalize()</var>

				<var key="ion_charge">{"I": 0, "II": -1, "III": -2, "IV": -3,
					"V": -4, "VI": -5, "VII": -6}[@ion_stage]</var>

				<!-- upstream used NIST masses (pers. comm.) -->
				<var key="nist_mass">{
					"Cu": 63.546,
					"Zn": 118.71,
					"Ga": 69.723,
					"Ge": 72.630,
					"Se": 78.971,
					"Kr": 83.798,
					"Sr": 87.62,
					"Zr": 91.224,
					"Mo": 95.95,
					"Tc": 97,
					"Te": 127.60,
					"I": 126.90,
					"Xe": 131.29,
					"Ba": 137.33}[@chemical_element]</var>

				<apply name="compute_energies">
					<setup imports="json">
						<par name="PER_CENTIMETER"
							>base.computeConversionFactor("cm**-1", "J")</par>
						<code>
							# the file is produced by res/res/get_ground_states.py
							with open(rd.getAbsPath(
									"res/ground_states.json")) as f:
								GROUND_STATE_MAP = json.load(f)
						</code>
					</setup>

					<code>
						try:
							e0 = GROUND_STATE_MAP[@chemical_element][@ion_stage]
						except KeyError:
							raise base.ReportableError("Can't find ground state"
								 " energy for {} at ionisation {}.  See"
								 " res/get_ground_states.py for how to fix this.".format(
								 @chemical_element, @ion_stage))

						energies = [
							(e0-float(@initial_nubar)*PER_CENTIMETER,
								"%s %s %s/2 %s"%(
									@chemical_element, @ion_stage,
									int(float(@j_init))*2, @par_init)),
							(e0-float(@final_nubar)*PER_CENTIMETER,
								"%s %s %s/2 %s"%(
									@chemical_element, @ion_stage,
									int(float(@j_final))*2, @par_final))]

						energies.sort()
						@lower_energy, @upper_energy = (
							energies[0][0], energies[1][0])
						@lower_level_description, @upper_level_description = (
							energies[0][1], energies[1][1])
					</code>
				</apply>

				<apply procDef="//slap2#populate-lines">
					<bind key="einsteina">float(@ga)</bind>
					<bind key="ion_charge">@ion_charge</bind>
					<bind key="line_title">"%s %s %s A"%(
						@chemical_element, @ion_stage, @wavelength)</bind>
					<bind key="lower_level_energy">@lower_energy</bind>
					<bind key="lower_level_description"
						>@lower_level_description</bind>
					<bind key="reference_doi">@doi</bind>
					<bind key="reference_uri">"bibcode:"+@pub</bind>
					<bind key="species_mass">@nist_mass</bind>
					<bind key="species_name">@chemical_element</bind>
					<bind key="upper_level_energy">@upper_energy</bind>
					<bind key="upper_level_description"
						>@upper_level_description</bind>
					<bind key="vacuum_wavelength">float(@wavelength)*1e-10</bind>
				</apply>

				<apply procDef="//slap2#compute-atomic-inchis"/>
			</rowmaker>
		</make>
	</data>

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

	<service id="legacy" allowed="form">
		<meta name="shortName">TOSS legacy</meta>
		<meta name="title"
			>Tübingen Oscillator Strengths Service Form Interface</meta>
		<meta name="_intro" format="rst">TOSS data is also available in a form
			compliant to the IVOA spectral line data model in a
			\RSTservicelink{toss/q/q/info}{SLAP service} and within our TAP
			service (\RSTservicelink{toss/q/q/examples}{usage examples}).
		</meta>

		<dbCore queriedTable="legacy_data">
			<condDesc buildFrom="c_wavelength"/>
			<condDesc>
				<inputKey original="species_name"
					tablehead="Atomic Number or Element"
					showItems="9"/>
			</condDesc>
			<condDesc buildFrom="ion_stage"/>
			<condDesc buildFrom="log_gf"/>
		</dbCore>
	</service>

	<service id="sp" allowed="species">
		<meta name="shortName">TOSS species</meta>
		<meta name="title">TOSS slap species endpoint</meta>
		<meta name="description">Search for species reflected in TOSS.</meta>
		<FEED source="//pql#DALIPars"/>
		<slap2SpeciesCore queriedTable="data">
			<FEED source="//slap2#species-pars"/>
		</slap2SpeciesCore>
	</service>

	<service id="q" allowed="form,lines,static">
		<meta name="title">TOSS slap lines endpoint</meta>
		<property key="staticData">static</property>
		<meta name="_intro" format="rst">A legacy interface (conventional
			units, air wavelength around the optical range) to
			TOSS data is also available at
			\RSTservicelink{toss/q/legacy/form}.  See also
			\RSTservicelink{toss/q/q/examples}{usage examples} for how to do
			TAP queries on this data.
		</meta>
		<meta name="shortName">TOSS slap</meta>
		<meta name="slap.dataSource">abstract-model</meta>

		<publish render="lines" sets="ivo_managed"/>
		<publish render="form" sets="ivo_managed,local" service="legacy"/>
		<publish render="species" sets="ivo_managed" service="sp"/>

		<dbCore queriedTable="data">
			<FEED source="//slap2#lines-pars"/>
		</dbCore>
		<FEED source="//pql#DALIPars"/>

		<meta name="_example" title="Matching a line list"><![CDATA[
			TOSS is accessible for remote database queries through TAP as
			:taptable:`toss.data`.  You can therefore match local line lists.
			This example assumes you're using the TOPCAT TAP client (but any other
			should do as well).

			Load the fictional line list from
			http://dc.g-vo.org/toss/q/q/static/sample.vot.  Then open VO/TAP, search
			for TOSS and select the GAVO DC server.

			To simply match lines (with a bit of a wiggle), you could use the
			following query::

				SELECT t.* FROM toss.data AS t
					JOIN TAP_UPLOAD.t1 AS u
					ON (abs(t.vacuum_wavelength-in_unit(u.lambda, 'm'))<1e-10)

			Note that ``toss.data`` uses the data model implied by SLAP2
			and therefore has vacuum wavelengths throughout the
			electromagnetic spectrum; and it's all in metres.

			You may have to change the ``t1`` after ``TAP_UPLOAD`` and adapt the 1 the
			number the sample table has in TOPCAT's table list.  If you use
			tables of your own, you will have to change lambda to whatever name
			the column has in your table.

			What's happening here is that ``toss.data`` is "joined" (in effect,
			building a cartesian product) with the table you uploaded.  There's a
			join condition (after the ON) which says that the two wavelengths
			must be within an Angstrom of each other.

			SLAP2 gives wavelengths in metres; the uploaded table has lambda in
			Angstrom (check the table metadata), so we use the ``in_unit`` function
			to turn it into meters.

			Also note the table aliases: To save typing, we're assinging t and u
			to the database and uploaded tables, respectively, in the AS clauses.
			You can even use that in the FROM clause: t.* just takes all the columns
			from the database table.

			There's quite a lot of rows coming back there.  To only retrieve the
			10 lines with the highest einstein A, add two simple ingredients:

			.. tapquery::

				SELECT TOP 10 t.vacuum_wavelength, line_title, einsteina
				FROM toss.data AS t
					JOIN TAP_UPLOAD.t1 AS u
					ON (abs(t.vacuum_wavelength-in_unit(u.lambda, 'Angstrom'))<1)
				ORDER BY einsteina DESC

			In addition to our last query, we have restricted the result to 10
			matches and told the engine to sort by einsteina (DESCending).

			Also, we now specify what columns we want in the result.  In such
			a join, it's enough to just give the name if the column is only
			present in one table.  Otherwise, it must be “qualified”, i.e.,
			furnished with a table name (as wavelength is in the example, though
			it wouldn't have been necessary here).
		]]></meta>

		<meta name="_example" title="Aggregate functions on TOSS"><![CDATA[
			To follow this example, you should prepare your TAP client as in
			the `previous example`_; again, we're talking about
			:taptable:`toss.data`.

			The `sample table`_ used there has another column, strength.  Let's say
			that's something like a filter width and we want to know how many lines
			are within than many Angstroms of the line center::

				SELECT u.lambda, COUNT(*) as n_lines
				FROM toss.data AS t
					JOIN TAP_UPLOAD.t1 AS u
					ON (abs(t.vacuum_wavelength-in_unit(u.lambda, 'm'))<strength*1e-10)
				GROUP BY u.lambda

			GROUP BY takes a bit of wrapping one's mind around – essentially, it groups the
			result by distinct values of its argument.  Clearly, the select
			clause can then only refer to what's constant within such a group.
			This can be what the table is grouped by, or it can be an "aggregate
			function", a function working on the elements of the group.  COUNT
			just counts them, but there's also things like AVG and SUM:

			.. tapquery::

				SELECT u.lambda, sqrt(COUNT(*)) as weight,
					SUM(log10(einsteina)) as totala, AVG(cf) as cfavg
				FROM toss.data AS t
					JOIN TAP_UPLOAD.t1 AS u
					ON (abs(t.vacuum_wavelength-in_unit(u.lambda, 'm'))<strength*1e-10)
				GROUP BY u.lambda

			For this example's sake, we sum the logs of the Einstein As (rather than
			doing something sensible with them) – this shows that the arguments
			of the aggregate functions can be arithmetic expressions.

			.. _previous example: #Matchingalinelist
			.. _sample table: http://dc.g-vo.org/toss/q/s/static/sample.vot
		]]></meta>
	</service>

	<regSuite title="TOSS">
		<regTest title="TOSS slap2 lines gives reasonable  results">
			<url WAVELENGTH="702.110e-10 702.120e-10"
				SPECIES="Mo">q/lines</url>
			<code>
				rows = self.getVOTableRows()
				self.assertEqual(len(rows), 1)
				self.assertAlmostEqual(rows[0]['lower_level_energy'],
					2.05219718095184e-19)
				self.assertEqual(rows[0]["line_title"], "Mo IV 702.115 A")
			</code>
		</regTest>

		<regTest title="TOSS conventional data">
			<url parSet="form" chemical_element="Mo"
				c_wavelength="702.110 .. 702.120" _FORMAT="CSV"
				>legacy/form</url>
			<code>
				self.assertHasStrings(
					"c_wavelength,species_name,ion_stage,log_gf,einsteina,par_init,j_init,par_final,j_final,reference_uri\\r\\n",
					"702.115,Mo,IV,-2.57",
					"bibcode:2016A&amp;A...587A..39R\\r\\n")
			</code>
		</regTest>

		<regTest title="TOSS species works">
			<url>sp/species?INCHIKEY
				=DYKUGZBZRDUQEH-UHFFFAOYSA-N&amp;INCHIKEY
				=XFRVYUZOCXVRNN-UHFFFAOYSA-N</url>
			<code>
				rows = self.getVOTableRows()
				self.assertEqual(len(rows), 2)
				self.assertEqual({r["species_name"] for r in rows}, {'Ba', 'Mo'})
			</code>
		</regTest>
	</regSuite>

</resource>
