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 nds.iaea.org/relnsd/v0/data? followed by parameters. For example:
nds.iaea.org/relnsd/v0/data?fields=decay_rads&nuclides=241am&rad_types=g.
The API v0 guide gives the detailed description, here a short summary

`fields=` specifies what is retrieved (at the bottom of this notebook there is the list of the columns for each choice)
these are the possible options

ground_states
levels
gammas
decay_rads
cumulative_fy
independent_fy
bin_beta

for ground_states, levels, gammas, decay_rads, bin_beta it is mandatory to add the nuclide parameter
fields=levels&nuclides=135xe

for decay_rads and bin_beta also the parameter rad_types is mandatory.
For decay_rads values are a, bp, bm, g, e, x (alpha, beta+, beta-, gamma, electron, X-ray)
For bin_beta values are bp, bm (beta+, beta-)
fields=decay_rads&nuclides=135xe&rad_types=bm
Be aware e aware of the fields "p_energy" and "decay". 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

for _cumulative_fy, independentfy one has to specify the parent and/or the product. Parents are 232th, 233u, 235u, 238u, 237np, 239pu, 241pu, 241am
fields=cumulative_fy&parents=233u&product=135xe

Examples

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

.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 [ ]: