Livechart API + Data Science packages

Version 1

This notebook makes use of

Pandas : a library for data manipulation: https://pandas.pydata.org

**Plotly** http://plotly.com : a package for interactive data visualization, here how to get it work with jupyter lab

In short : ``` $ pip install pandas $ pip install plotly $ pip install ipywidgets $ jupyter labextension install jupyterlab-plotly




Write your feedback to nds.contact-point@iaea.org

## API Quick how-to
The service URL is  <b>nds.iaea.org/relnsd/v0/data?</b>
followed by parameters. For example:
<br> nds.iaea.org/relnsd/v0/data?<b>fields=decay_rads&nuclides=241am&rad_types=g</b>.<br>
The <a href=//nds.iaea.org/relnsd/vcharthtml/api_v0_guide.html><b>API v0 guide</b></a> gives the detailed description, here a short summary
<br><br>
<b>`fields=`</b> specifies what is retrieved  (at the bottom of this notebook there is the list of the columns for each choice)
<br> these are the possible options<br><br>
ground_states <br> levels  <br> gammas  <br> decay_rads  <br> cumulative_fy  <br> independent_fy <br> bin_beta 
<br><br>
for ground_states, levels, gammas, decay_rads, bin_beta it is mandatory to add the <b>nuclide</b> parameter<br>
`fields=levels&nuclides=135xe`
<br><br>
for decay_rads and bin_beta also the parameter <b>rad_types</b> is mandatory. 
<br>For decay_rads values are a, bp, bm, g, e, x (alpha, beta+, beta-, gamma, electron, X-ray) 
<br>For bin_beta values are bp, bm (beta+, beta-) 
<br>
`fields=decay_rads&nuclides=135xe&rad_types=bm`
<br>Be aware e aware of the fields <b>"p_energy" and
                        "decay"</b>. For
                    the same nuclide there can
                    be more than one decay mode, and, in case of metastable states, more states than the simple ground
                    state. This might result in gamma lines having the
                    same energy, but emitted by different decays 
<br><br>
for  _cumulative_fy, independent_fy_ one has to specify the <b>parent</b> and/or the <b>product</b>. Parents are _232th, 233u, 235u, 238u, 237np, 239pu, 241pu, 241am_ 
<br>
`fields=cumulative_fy&parents=233u&product=135xe `

<div style="margin-top:10px;font-size:18pt;font-weight:bold;">  Examples</div>
<br>

In [1]:

import pandas as pd
import plotly.express as px
import plotly.graph_objects as go

# the service URL
livechart = "https://nds.iaea.org/relnsd/v1/data?"

# There have been cases in which the service returns an HTTP Error 403: Forbidden
# use this workaround
import urllib.request
def lc_pd_dataframe(url):
    req = urllib.request.Request(url)
    req.add_header('User-Agent', 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:77.0) Gecko/20100101 Firefox/77.0')
    return pd.read_csv(urllib.request.urlopen(req))

Plot γ energy vs intensity for Am-241 decay¶

fields=decay_rads specifies to retrieve the decay radiations, nuclides=241am specifies the parent of the decay (241am), rad_types=g for the radiation type (gamma).

On the **plot** below, mouseover the points to see the data. Zoom an pan are enabled, and the option to save as png is is activated when the mouse is over the top-right

Important
For nuclides having metastable stable states one might want to filter the radiations coming only from the Ground State.
The energy of the parent is stored in the "p-energy" field. The dataframe below has the query option that makes the job
See below the full list of fields, and the API v0 guide for the full description of the fields

In [2]:

# load data into a dataframe 
df = lc_pd_dataframe(livechart + "fields=decay_rads&nuclides=241am&rad_types=g").query("p_energy==0")

df = df[pd.to_numeric(df['intensity'],errors='coerce').notna()] # remove blanks (unknown intensities)
df.intensity = df['intensity'].astype(float) # convert to numeric. Note how one can specify the field by attribute or by string 


fig = px.scatter(df, x="energy", y="intensity", log_y=True) # plot in log scale
fig.show()

Plot Log FT vs Transition type for Nb-100 decay¶

The fields to be retieved are decay_rads, the nuclide is 100-Nb, and the radiation type is bm

In this case, only the relevant fields are loaded into the dataset; then data are grouped by transition, binned, and plotted

The transition types in the plot legend are not decoded. A stands for Allowed, 1NU for 1st non unique, ...

In [3]:

url = livechart+"fields=decay_rads&nuclides=100nb&rad_types=bm"

df=lc_pd_dataframe(url)[['transition_type','log_ft']] # optional:load only transition_type and log_ft 

df = df[pd.to_numeric(df.log_ft,errors='coerce').notna()] # remove unknowns and convert to numeric values
df.log_ft = df.log_ft.astype(float)

ans = [pd.DataFrame(y) for x, y in df.groupby('transition_type', as_index=False)] # group log ft values by transition
fig = go.Figure()

for a in ans:
    ct = pd.cut(a.log_ft, bins=10)   # bin each grouping 
    tst = ct.apply(lambda x: x.mid).value_counts(sort=False)  # assign the mid value to each bin
    fig.add_trace(go.Scatter(x=tst.index.values, y = tst, mode="markers", line_shape='spline', name=a.transition_type.iloc[0]))
fig.show()

Plot the total beta- and anti-nu spectra from the decay of Xe-135, metastable @526 keV¶

In [4]:

url=livechart+"fields=bin_beta&nuclides=135xe&rad_types=bm&metastable_seqno=1"

df=lc_pd_dataframe(url)
fig = px.scatter(df, x="bin_en", y="dn_de")
fig.add_trace(go.Scatter(x=df["bin_en"], y=df["dn_de_nu"]))

fig.show()

Apply further filters once the data are loaded¶

The pandas query function acts on the loaded dataset.

To plot the Half-life of Ac isotopes, apply the *query* function to the column *symbol* to extract the *Ac* isotopes ```python .query('symbol=="Ac"') ```

In [5]:

url=livechart+"fields=ground_states&nuclides=all"

df=lc_pd_dataframe(url)[['symbol','n','half_life_sec']].query('symbol=="Ac"') # further filter

fig = px.scatter(df, x="n", y="half_life_sec", log_y=True)
fig.show()

3D and 2D plots of fission yields¶

Use the mouse to rotate and zoom

In [6]:

url=livechart+"fields=cumulative_fy&parents=235u"
df = lc_pd_dataframe(url) [['z_daughter','a_daughter',"element_daughter",'cumulative_fast_fy']]
df = df[pd.to_numeric(df.cumulative_fast_fy,errors='coerce').notna()]
df.cumulative_fast_fy = df.cumulative_fast_fy.astype(float)
  

fig = go.Figure(data=[go.Scatter3d(
    x=df["z_daughter"],
    y=df["a_daughter"]-df["z_daughter"],
    z=df["cumulative_fast_fy"],
    mode='markers',
    text = df['a_daughter'].apply(str) + df["element_daughter"],
    marker=dict(
        size=7
        ,color=df["cumulative_fast_fy"] # array/list of values setting the color
        ,colorscale='Viridis'           # colorscale
    )
     

)])

camera = dict(                          # initial spacial settings 
    up=dict(x=0, y=0, z=1),
    center=dict(x=0, y=0, z=0),
    eye=dict(x=0.1, y=2, z=-1.5)        # view it from the bottom
)

fig.update_layout(scene_camera=camera, margin=dict(l=0, r=0, b=0, t=0), height=900)
fig.show()

# 2D plot
fig2 = go.Figure()
fig2.add_trace(go.Scatter( x=df[df.columns[1]], y=df['cumulative_fast_fy'], mode="markers", text= df['a_daughter'].apply(str) + df["element_daughter"]))
fig2.update_layout( height=600, xaxis_title="A", yaxis_title="Yield ") 
fig2.show()

Column titles and samples of the available sets¶

• Ground state

In [7]:

pd.set_option('display.max_columns', None)
pd.set_option("display.max_rows", 3)

# GS
df=lc_pd_dataframe(livechart+"fields=ground_states&nuclides=236np")
df

Out[7]:

	z	n	symbol	radius	unc_r	abundance	unc_a	energy_shift	energy	unc_e	ripl_shift	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay_1	decay_1_%	unc_1	decay_2	decay_2_%	unc_2	decay_3	decay_3_%	unc_3	isospin	magnetic_dipole	unc_md	electric_quadrupole	unc_eq	qbm	unc_qb	qbm_n	unc_qbmn	qa	unc_qa	qec	unc_qec	sn	unc_sn	sp	unc_sp	binding	unc_ba	atomic_mass	unc_am	massexcess	unc_me	me_systematics	discovery	ENSDFpublicationcut-off	ENSDFauthors	Extraction_date
0	93	143	Np	NaN	NaN	NaN	NaN	NaN	0	NaN	NaN	6(-)	155000.0	NaN	1	Y	4.891324e+12	3.155693e+10	EC	87.8	0.2	B-	12	0.1	A	0.16	0.04	NaN	NaN	NaN	NaN	NaN	476.5854	50.3887	-6875.5708	54.4139	5006.629	50.9333	933.512	50.433	5736.2687	50.4196	4829.6598	50.4139	7579.2148	0.2136	2.360466e+08	54.129	43378.094	50.421	N	1949	1-Apr-2022	Shaofei Zhu	2024-03-06

• Level

Note the "X" in the energy_shift field for the 2nd level, and the value in the "ripl_shift" column (see the API guide for the meaning of the shift)

In [8]:

# LEVEL
df=lc_pd_dataframe(livechart+"fields=levels&nuclides=236np")
df

Out[8]:

	z	n	symbol	idx	energy_shift	energy	unc_e	ripl_shift	jp	jp_order	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hl.1	decay_1	decay_1_%	unc_1	decay_2	decay_2_%	unc_2	decay_3	decay_3_%	unc_3	isospin	magnetic_dipole	unc_mn	electric_quadrupole	unc_eq	ENSDF_publication_cut-off	ENSDF_authors	Extraction_date
0	93	143	Np	0	NaN	0	NaN	NaN	6(-)	1	155000.0	NaN	1.0	Y	4.891324e+12	3.155693e+10	EC	87.8	0.2	B-	12.0	0.1	A	0.16	0.04	NaN	NaN	NaN	NaN	NaN	1-Apr-2022	Shaofei Zhu	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
4	93	143	Np	4	NaN	334	50.0	NaN	(5-)	1	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	1-Apr-2022	Shaofei Zhu	2024-03-06

5 rows × 33 columns

•Gamma

In [9]:

# GAMMA transitions
df=lc_pd_dataframe(livechart+"fields=gammas&nuclides=135xe")
df

Out[9]:

	z	n	symbol	start_level_idx	start_level_energy	unc_sle	start_level_jp	end_level_idx	end_level_energy	unc_ele	end_level_jp	gamma_idx	energy	unc_en	relative_intensity	unc_ri	multipolarity	mixing_ratio	unc_mr	b_e1	unc_be1	b_e2	unc_be2	b_m1	unc_bm1	b_m2	unc_bm2	tot_conv_coeff	tce_unc	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	54	81	Xe	1	288.455	0.015	1/2+	0	0.0	NaN	3/2+	0	288.451	0.016	100.0	NaN	[M1 E2]	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	0.0463	0.0014	22-Jan-2008	BALRAJ SINGH and ALEXANDER A. RODIONOV and YU...	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
96	54	81	Xe	37	3169.900	0.900	NaN	26	2356.5	0.8	NaN	1	813.400	0.900	75.0	20.0	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	22-Jan-2008	BALRAJ SINGH and ALEXANDER A. RODIONOV and YU...	2024-03-06

97 rows × 32 columns

•Cumulative fission

In [10]:

# CUMULATIVE_FISSION
df=lc_pd_dataframe(livechart+"fields=cumulative_fy&products=135xe")
df

Out[10]:

	z_daughter	a_daughter	element_daughter	z_parent	z_parent.1	element_parent	daughter_level_idx	cumulative_thermal_fy	unc_ct	cumulative_fast_fy	unc_cf	cumulative_14mev_fy	unc_c14	Extraction_date
0	54	135	Xe	92	235	U	0	0.066140	0.002249	0.063210	0.001833	0.064242	0.018117	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
15	54	135	Xe	95	241	Am	2	0.020204	0.006154	0.020925	0.006764	NaN	NaN	2024-03-06

16 rows × 14 columns

•Independent fission

In [11]:

# INDEPENDENT FISSION
df=lc_pd_dataframe(livechart+"fields=independent_fy&parents=235u")
df

Out[11]:

	z_daughter	a_daughter	element_daughter	z_parent	a_parent	element_parent	daughter_level_idx	independent_thermal_fy	unc_it	independent_fast_fy	unc_if	independent_14mev_fy	unc_i14	Extraction_date
0	1	1	H	92	235	U	0	0.000017	0.000003	0.000027	0.000009	0.000026	0.000009	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
1226	72	179	Hf	92	235	U	0	NaN	NaN	NaN	NaN	0.000000	0.000000	2024-03-06

1227 rows × 14 columns

•Decay radiation

In [12]:

# DECAY_RADIATION, type alpha
df=lc_pd_dataframe(livechart+"fields=decay_radiations&nuclides=238u&rad_types=a")
df

Out[12]:

	3

In [13]:

# DECAY_RADIATION, type gamma
df=lc_pd_dataframe(livechart+"fields=decay_rads&nuclides=238u&rad_types=g")
df

Out[13]:

	energy	unc_en	intensity	unc_i	start_level_energy	end_level_energy	multipolarity	mixing_ratio	unc_mr	conversion_coeff	unc_cc	p_z	p_n	p_symbol	p_energy_shift	p_energy	unc_pe	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay	decay_%	unc_d	q	unc_q	d_z	d_n	d_symbol	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	44.915	NaN	NaN	NaN	44.916	0.0	E2	NaN	NaN	NaN	NaN	92	146	U	NaN	2557.9	0.5	0+	280.0	NaN	6	ns	2.800000e-07	6.000000e-09	IT	97.4	0.4	NaN	NaN	92	146	U	1-Jun-2014	E. BROWNE and J. K. TULI	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
19	114.446	NaN	0.00798	0.00162	NaN	NaN	NaN	NaN	NaN	NaN	NaN	92	146	U	NaN	2557.9	0.5	0+	280.0	NaN	6	ns	2.800000e-07	6.000000e-09	IT	97.4	0.4	NaN	NaN	92	146	U	1-Jun-2014	E. BROWNE and J. K. TULI	2024-03-06

20 rows × 35 columns

In [14]:

# DECAY_RADIATION, type x-ray
df=lc_pd_dataframe(livechart+"fields=decay_rads&nuclides=238u&rad_types=x")
df

Out[14]:

	energy	unc_en	intensity	unc_i	type	shell	p_z	p_n	p_symbol	p_energy_shift	p_energy	unc_pe	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay	decay_%	unc_d	q	unc_q	d_z	d_n	d_symbol	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	15.784	NaN	7.32262	0.958957	X	L	92	146	U	NaN	0.0	NaN	0+	4.468000e+09	NaN	6	Y	1.409963e+17	1.893416e+14	A	100.0	NaN	4269.9	21.0	90	144	Th	1-Jun-2006	E. BROWNE and J. K. TULI	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
11	114.446	NaN	0.00798	0.001620	X	KpB2	92	146	U	NaN	2557.9	0.5	0+	2.800000e+02	NaN	6	ns	2.800000e-07	6.000000e-09	IT	97.4	0.4	NaN	NaN	92	146	U	1-Jun-2014	E. BROWNE and J. K. TULI	2024-03-06

12 rows × 30 columns

In [15]:

# DECAY_RADIATION, type beta-
df=lc_pd_dataframe(livechart+"fields=decay_rads&nuclides=135xe&rad_types=bm")
df

Out[15]:

	mean_energy	unc_me	intensity_beta	unc_ib	daughter_level_energy	max_energy	unc_me.1	log_ft	unc_lf	transition_type	anti_nu_mean_energy	unc_ame	p_z	p_n	p_symbol	p_energy_shift	p_energy	unc_pe	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay	decay_%	unc_d	q	unc_q	d_z	d_n	d_symbol	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	26.9	1.1	0.123	0.006	1062.42	103	4	5.71	0.06	NaN	NaN	NaN	54	81	Xe	NaN	0.000	NaN	3/2+	9.14	NaN	2	h	32904.0	72	B-	100.0	NaN	1169	4	55	80	Cs	22-Jan-2008	BALRAJ SINGH and ALEXANDER A. RODIONOV and YU...	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
9	641.4	1.7	0.600	0.600	0.00	1692	4	8.50	NaN	1U	NaN	NaN	54	81	Xe	NaN	526.551	0.013	11/2-	15.29	NaN	5	m	917.4	3	B-	0.6	NaN	1169	4	55	80	Cs	22-Jan-2008	BALRAJ SINGH and ALEXANDER A. RODIONOV and YU...	2024-03-06

10 rows × 36 columns

In [16]:

# DECAY_RADIATION, type electron
df=lc_pd_dataframe(livechart+"fields=decay_rads&nuclides=238u&rad_types=e")
df

Out[16]:

	energy	unc_en	intensity	unc_i	type	shell	p_z	p_n	p_symbol	p_energy_shift	p_energy	unc_pe	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay	decay_%	unc_d	q	unc_q	d_z	d_n	d_symbol	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	13.113	NaN	8.061035	1.047936	AU	L	92	146	U	NaN	0.0	NaN	0+	4.468000e+09	NaN	6	Y	1.409963e+17	1.893416e+14	A	100.0	NaN	4269.9	21.0	90	144	Th	1-Jun-2006	E. BROWNE and J. K. TULI	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
29	2512.371	NaN	0.000301	0.000074	CE	O	92	146	U	NaN	2557.9	0.5	0+	2.800000e+02	NaN	6	ns	2.800000e-07	6.000000e-09	IT	97.4	0.4	NaN	NaN	92	146	U	1-Jun-2014	E. BROWNE and J. K. TULI	2024-03-06

30 rows × 30 columns

In [17]:

# DECAY_RADIATION, type beta+/electron capture
df=lc_pd_dataframe(livechart+"fields=decay_rads&nuclides=236np&rad_types=bp")
df

Out[17]:

	mean_energy	unc_me	intensity_beta	unc_ib	daughter_level_energy	energy_ec	unc_eec	intensity_ec	unc_ie	log_ft	unc_lf	transition_type	nu_mean_energy	unc_ame	p_z	p_n	p_symbol	p_energy_shift	p_energy	unc_pe	jp	half_life	operator_hl	unc_hl	unit_hl	half_life_sec	unc_hls	decay	decay_%	unc_d	q	unc_q	d_z	d_n	d_symbol	ensdf_publication_cut-off	ensdf_authors	Extraction_date
0	NaN	NaN	NaN	NaN	309.788	620	50	87.0	4.0	14.1	0.10	1NU	NaN	NaN	93	143	Np	NaN	0	NaN	6(-)	155000.0	NaN	1	Y	4.891324e+12	3.155693e+10	EC	87.8	0.2	934	50	92	144	U	1-Apr-2022	Shaofei Zhu	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
4	NaN	NaN	NaN	NaN	0.000	987	71	40.0	7.0	7.1	0.11	1NU	NaN	NaN	93	143	Np	NaN	57	51.0	1(-)	22.5	NaN	4	h	8.100000e+04	1.440000e+03	EC	51.0	1.0	934	50	92	144	U	1-Apr-2022	Shaofei Zhu	2024-03-06

5 rows × 38 columns

•Beta and Neutrino spectra

In [18]:

df=lc_pd_dataframe(livechart+"fields=bin_beta&nuclides=135xe&rad_types=bm&metastable_seqno=1")
df

Out[18]:

	p_z	p_n	p_symbol	p_energy	d_z	d_n	d_symbol	bin_en	dn_de	unc_dn_de	dn_de_nu	unc_dn_de_nu	extraction_date
0	54	81	Xe	526.551	55	80	Cs	0.0	0.00171	0.000062	0.000000	0.000000	2024-03-06
...	...	...	...	...	...	...	...	...	...	...	...	...	...
384	54	81	Xe	526.551	55	80	Cs	915.2	0.00000	0.000000	0.002075	0.000525	2024-03-06

385 rows × 13 columns

In [ ]: