Skip to main content
`Ctrl`+`K`

# `PeriodicTable`: Atomic elements widgets

Periodic table widgets

## Classes

Widgets:

> - `PeriodicTable`

> - `PeriodicList`

> - `PeriodicCombo`

Data model:

> - `PeriodicTableItem`

> - `ColoredPeriodicTableItem`

## Example of usage

This example uses the widgets with the standard builtin elements list.

    from silx.gui import qt
    from silx.gui.widgets.PeriodicTable import PeriodicTable,         PeriodicCombo, PeriodicList

    a = qt.QApplication([])

    w = qt.QTabWidget()

    ptable = PeriodicTable(w, selectable=True)
    pcombo = PeriodicCombo(w)
    plist = PeriodicList(w)

    w.addTab(ptable, "PeriodicTable")
    w.addTab(plist, "PeriodicList")
    w.addTab(pcombo, "PeriodicCombo")

    ptable.setSelection(['H', 'Fe', 'Si'])
    plist.setSelectedElements(['H', 'Be', 'F'])
    pcombo.setSelection("Li")

    def change_list(items):
        print("New list selection:", [item.symbol for item in items])

    def change_combo(item):
        print("New combo selection:", item.symbol)

    def click_table(item):
        print("New table click:", item.symbol)

    def change_table(items):
        print("New table selection:", [item.symbol for item in items])

    ptable.sigElementClicked.connect(click_table)
    ptable.sigSelectionChanged.connect(change_table)
    plist.sigSelectionChanged.connect(change_list)
    pcombo.sigSelectionChanged.connect(change_combo)

    w.show()
    a.exec()

The second example explains how to define custom elements.

    from silx.gui import qt
    from silx.gui.widgets.PeriodicTable import PeriodicTable,         PeriodicCombo, PeriodicList
    from silx.gui.widgets.PeriodicTable import PeriodicTableItem

    # subclass PeriodicTableItem
    class MyPeriodicTableItem(PeriodicTableItem):
        "New item with added mass number and number of protons"
        def __init__(self, symbol, Z, A, col, row, name, mass,
                     subcategory=""):
            PeriodicTableItem.__init__(
                    self, symbol, Z, col, row, name, mass,
                    subcategory)

            self.A = A
            "Mass number (neutrons + protons)"

            self.num_neutrons = A - Z
            "Number of neutrons"

    # build your list of elements
    my_elements = [MyPeriodicTableItem("H", 1, 1, 1, 1, "hydrogen",
                                       1.00800, "diatomic nonmetal"),
                   MyPeriodicTableItem("He", 2, 4, 18, 1, "helium",
                                        4.0030, "noble gas"),
                   # etc ...
                   ]

    app = qt.QApplication([])

    ptable = PeriodicTable(elements=my_elements, selectable=True)
    ptable.show()

    def click_table(item):
        "Callback function printing the mass number of clicked element"
        print("New table click, mass number:", item.A)

    ptable.sigElementClicked.connect(click_table)
    app.exec()

## Widgets

class PeriodicTable(parent=None, name='PeriodicTable', elements=None, selectable=False)

  Bases: `QWidget`

  Periodic Table widget

  The following example shows how to connect clicking to selection:

      from silx.gui import qt
      from silx.gui.widgets.PeriodicTable import PeriodicTable
      app = qt.QApplication([])
      pt = PeriodicTable()
      pt.sigElementClicked.connect(pt.elementToggle)
      pt.show()
      app.exec()

  To print all selected elements each time a new element is selected:

      def my_slot(item):
          pt.elementToggle(item)
          selected_elements = pt.getSelection()
          for e in selected_elements:
              print(e.symbol)

      pt.sigElementClicked.connect(my_slot)

  sigElementClicked

    When any element is clicked in the table, the widget emits this signal and sends a `PeriodicTableItem` object.

  sigSelectionChanged

    When any element is selected/unselected in the table, the widget emits this signal and sends a list of `PeriodicTableItem` objects.

    Note

    To enable selection of elements, you must set selectable=True when you instantiate the widget. Alternatively, you can also connect `sigElementClicked` to `elementToggle()` manually:

        pt = PeriodicTable()
        pt.sigElementClicked.connect(pt.elementToggle)

    Parameters:

      - parent – parent QWidget

      - name (str) – Widget window title

      - elements – List of items (`PeriodicTableItem` objects) to be represented in the table. By default, take elements from a predefined list with minimal information (symbol, atomic number, name, mass).

      - selectable (bool) – If True, multiple elements can be selected by clicking with the mouse. If False (default), selection is only possible with method `setSelection()`.

  getSelection()

    Return a list of selected elements, as a list of `PeriodicTableItem` objects.

    Returns:

      Selected items

    Return type:

      List[PeriodicTableItem]

  setSelection(symbols)

    Set selected elements.

    This causes the sigSelectionChanged signal to be emitted, even if the selection didn’t actually change.

    Parameters:

      symbols (List[str]) – List of symbols of elements to be selected (e.g. [“Fe”, “Hg”, “Li”])

  setElementSelected(symbol, state)

    Modify selected status of a single element (select or unselect)

    Parameters:

      - symbol (str) – PeriodicTableItem symbol to be selected

      - state (bool) – True to select, False to unselect

  isElementSelected(symbol)

    Return True if element is selected, else False

    Parameters:

      symbol (str) – PeriodicTableItem symbol

    Returns:

      True if element is selected, else False

class PeriodicList(parent=None, detailed=True, single=False, elements=None)

  Bases: `QTreeWidget`

  List of atomic elements in a `QTreeView`

  Parameters:

    - parent (QWidget) – Parent widget

    - detailed (bool) – True (default) display element symbol, Z and name. False display only element symbol and Z.

    - single – True for single element selection with mouse click, False for multiple element selection mode.

  sigSelectionChanged

    When any element is selected/unselected in the widget, it emits this signal and sends a list of currently selected `PeriodicTableItem` objects.

  getSelection()

    Get a list of selected elements, as a list of `PeriodicTableItem` objects.

    Returns:

      Selected elements

    Return type:

      List[PeriodicTableItem]

  setSelectedElements(symbolList)
    Parameters:

      symbolList – List of atomic symbols [“H”, “He”, “Li”…] to be selected in the widget

class PeriodicCombo(parent=None, detailed=True, elements=None)

  Bases: `QComboBox`

  Combo list with all atomic elements of the periodic table

  Parameters:

    - detailed (bool) – True (default) display element symbol, Z and name. False display only element symbol and Z.

    - elements – List of items (`PeriodicTableItem` objects) to be represented in the table. By default, take elements from a predefined list with minimal information (symbol, atomic number, name, mass).

  sigSelectionChanged

    Signal emitted when the selection changes. Send `PeriodicTableItem` object representing selected element

  getSelection()

    Get selected element

    Returns:

      Selected element

    Return type:

      PeriodicTableItem

  setSelection(symbol)

    Set selected item in combobox by giving the atomic symbol

    Parameters:

      symbol – Symbol of element to be selected

## Data model

class PeriodicTableItem(symbol, Z, col, row, name, mass, subcategory='')

  Periodic table item, used as generic item in `PeriodicTable`, `PeriodicCombo` and `PeriodicList`.

  This implementation stores the minimal amount of information needed by the widgets:

  > - atomic symbol

  > - atomic number

  > - element name

  > - atomic mass

  > - column of element in periodic table

  > - row of element in periodic table

  You can subclass this class to add additional information.

  Parameters:

    - symbol (str) – Atomic symbol (e.g. H, He, Li…)

    - Z (int) – Proton number

    - col (int) – 1-based column index of element in periodic table

    - row (int) – 1-based row index of element in periodic table

    - name (str) – PeriodicTableItem name (“hydrogen”, …)

    - mass (float) – Atomic mass (gram per mol)

    - subcategory (str) – Subcategory, based on physical properties (e.g. “alkali metal”, “noble gas”…)

  symbol

    Atomic symbol (e.g. H, He, Li…)

  Z

    Atomic number (Proton number)

  col

    1-based column index of element in periodic table

  row

    1-based row index of element in periodic table

  name

    PeriodicTableItem name (“hydrogen”, …)

  mass

    Atomic mass (gram per mol)

  subcategory

    Subcategory, based on physical properties (e.g. “alkali metal”, “noble gas”…)

class ColoredPeriodicTableItem(symbol, Z, col, row, name, mass, subcategory='', bgcolor=None)

  Bases: `PeriodicTableItem`

  `PeriodicTableItem` with an added `bgcolor`. The background color can be passed as a parameter to the constructor. If it is not specified, it will be defined based on `subcategory`.

  Parameters:

    bgcolor (str) – Custom background color for element in periodic table, as a RGB string #RRGGBB

  COLORS = {'': '#FFFFFF', 'actinide': '#F08080', 'alkali metal': '#FFE4B5', 'alkaline earth metal': '#FFA500', 'diatomic nonmetal': '#7FFF00', 'lanthanide': '#FFB6C1', 'metalloid': '#8FBC8F', 'noble gas': '#00FFFF', 'polyatomic nonmetal': '#7FFFD4', 'post transition metal': '#D3D3D3', 'transition metal': '#FFA07A'}

    Dictionary defining RGB colors for each subcategory.

  bgcolor

    Background color of element in the periodic table, based on its subcategory. This should be a string of a hexadecimal RGB code, with the format #RRGGBB. If the subcategory is unknown, use white (#FFFFFF)