matminer.utils package — matminer 0.2.4 documentation

# matminer.utils package

## Subpackages

- matminer.utils.data_files package
  - Submodules
  - matminer.utils.data_files.deml_elementdata module
  - Module contents
- matminer.utils.tests package
  - Submodules
  - matminer.utils.tests.test_conversions module
  - matminer.utils.tests.test_data module
  - matminer.utils.tests.test_flatten_dict module
  - Module contents

## Submodules

## matminer.utils.conversions module

`matminer.utils.conversions.` `composition_to_oxidcomposition`(series, **kwargs)

  Adds oxidation states to a Composition using pymatgen’s guessing routines

  Args:
    series: a pd.Series with Composition object components **kwargs: parameters to control Composition.oxi_state_guesses()
  Returns:
    a pd.Series with oxidation state Composition object components

`matminer.utils.conversions.` `dict_to_object`(series)

  Decodes a dict Series to Python object series via MSON

  Args:
    series: a pd.Series with MSONable dict components, e.g., pymatgen Structure.as_dict()
  Returns:
    a pd.Series with MSON objects, e.g. Structure objects

`matminer.utils.conversions.` `json_to_object`(series)

  Decodes a json series to Python object series via MSON

  Args:
    series: a pd.Series with MSONable JSON components (string)
  Returns:
    a pd.Series with MSON objects, e.g. Structure objects

`matminer.utils.conversions.` `str_to_composition`(series, reduce=False)

  Converts a String series to a Composition series

  Args:
    series: a pd.Series with str components, e.g. “Fe2O3” reduce: (bool) whether to return a reduced Composition
  Returns:
    a pd.Series with pymatgen Composition components

`matminer.utils.conversions.` `structure_to_composition`(series, reduce=False)

  Converts a Structure series to a Composition series

  Args:
    series: a pd.Series with pymatgen.Structure components reduce: (bool) whether to return a reduced Composition
  Returns:
    a pd.Series with pymatgen Composition components

`matminer.utils.conversions.` `structure_to_oxidstructure`(series, inplace=False, **kwargs)

  Adds oxidation states to a Structure using pymatgen’s guessing routines

  Args:
    series: a pd.Series with Structure object components inplace: (bool) whether to override original Series (this is faster) **kwargs: parameters to control to Structure.add_oxidation_state_by_guess
  Returns:
    a pd.Series with oxidation state Structure object components

## matminer.utils.data module

class `matminer.utils.data.` `AbstractData`

  Bases: `object`

  Abstract class for retrieving elemental properties

  All classes must implement the get_elemental_property operation. These operations should return scalar values (ideally floats) and nan if a property does not exist

  `get_elemental_properties`(elems, property_name)

    Get elemental properties for a list of elements

    Args:
      elems - ([Element]) list of elements property_name - (str) property to be retrieved
    Returns:
      [float], properties of elements
  `get_elemental_property`(elem, property_name)

    Get a certain elemental property for a certain element.

    Args:
      elem - (Element) element to be assessed property_name - (str) property to be retreived
    Returns:
      float, property of that element

class `matminer.utils.data.` `CohesiveEnergyData`

  Bases: `matminer.utils.data.AbstractData`

  Get the cohesive energy of an element.

  TODO: Where is this data from? -wardlt

  `__init__`()
  `get_elemental_property`(elem, property_name='cohesive energy')
    Args:
      elem: (Element) Element of interest property_name (str): unused, always returns cohesive energy
    Returns:
      (float): cohesive energy of the element

class `matminer.utils.data.` `DemlData`

  Bases: `matminer.utils.data.OxidationStateDependentData`, `matminer.utils.data.OxidationStatesMixin`

  Class to get data from Deml data file. See also: A.M. Deml, R. O’Hayre, C. Wolverton, V. Stevanovic, Predicting density functional theory total energies and enthalpies of formation of metal-nonmetal compounds by linear regression, Phys. Rev. B - Condens. Matter Mater. Phys. 93 (2016).

  `__init__`()
  `get_charge_dependent_property`(element, charge, property_name)
  `get_elemental_property`(elem, property_name)
  `get_oxidation_states`(elem)

class `matminer.utils.data.` `MagpieData`

  Bases: `matminer.utils.data.AbstractData`, `matminer.utils.data.OxidationStatesMixin`

  Class to get data from Magpie files. See also: L. Ward, A. Agrawal, A. Choudhary, C. Wolverton, A general-purpose machine learning framework for predicting properties of inorganic materials, Npj Comput. Mater. 2 (2016) 16028.

  `__init__`()
  `get_elemental_property`(elem, property_name)
  `get_oxidation_states`(elem)

class `matminer.utils.data.` `OxidationStateDependentData`

  Bases: `matminer.utils.data.AbstractData`

  Abstract class that also includes oxidation-state-dependent properties

  `get_charge_dependent_property`(element, charge, property_name)

    Retrieve a oxidation-state dependent elemental property

    Args:
      element - (Element), Target element charge - (int), Oxidation state property_name - (string), name of property
    Return:
      (float) - Value of property
  `get_charge_dependent_property_from_specie`(specie, property_name)

    Retrieve a oxidation-state dependent elemental property

    Args:
      specie - (Specie), Specie of interest property_name - (string), name of property
    Return:
      (float) - Value of property

class `matminer.utils.data.` `OxidationStatesMixin`

  Bases: `object`

  Abstract class interface for retrieving the oxidation states of each element

  `get_oxidation_states`(elem)

    Retrieve the possible oxidation states of an element

    Args:
      elem - (Element), Target element
    Returns:
      [int] - oxidation states

class `matminer.utils.data.` `PymatgenData`(use_common_oxi_states=True)

  Bases: `matminer.utils.data.OxidationStateDependentData`, `matminer.utils.data.OxidationStatesMixin`

  Class to get data from pymatgen. See also: S.P. Ong, W.D. Richards, A. Jain, G. Hautier, M. Kocher, S. Cholia, et al., Python Materials Genomics (pymatgen): A robust, open-source python library for materials analysis, Comput. Mater. Sci. 68 (2013) 314-319.

  `__init__`(use_common_oxi_states=True)
  `get_charge_dependent_property`(element, charge, property_name)
  `get_elemental_property`(elem, property_name)
  `get_oxidation_states`(elem)

    Get the oxidation states of an element

    Args:

      elem - (Element) target element common - (boolean), whether to return only the common oxidation states,

      > or all known oxidation states

    Returns:
      [int] list of oxidation states

## matminer.utils.flatten_dict module

`matminer.utils.flatten_dict.` `flatten_dict`(nested_dict, lead_key=None, unwind_arrays=True)

  Helper function to flatten nested dictionary, recursively walks through nested dictionary to get keys corresponding to dot-notation keys, e. g. converts {“a”: {“b”: 1, “c”: 2}} to {“a.b”: 1, “a.c”: 2}

  Args:

    nested_dict ({}): nested dictionary to flatten unwind_arrays (bool): whether to flatten lists/tuples

    > with numerically indexed dot notation, defaults to True

    lead_key (str): string to append to front of all keys,
      used primarily for recursion
  Returns:
    non-nested dictionary

## matminer.utils.kernels module

`matminer.utils.kernels.` `gaussian_kernel`

  staticmethod(function) -> method

  Convert a function to be a static method.

  A static method does not receive an implicit first argument. To declare a static method, use this idiom:

  > class C:

  >   @staticmethod def f(arg1, arg2, …):

  >   > …

  It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class.

  Static methods in Python are similar to those found in Java or C++. For a more advanced concept, see the classmethod builtin.

`matminer.utils.kernels.` `laplacian_kernel`

  staticmethod(function) -> method

  Convert a function to be a static method.

  A static method does not receive an implicit first argument. To declare a static method, use this idiom:

  > class C:

  >   @staticmethod def f(arg1, arg2, …):

  >   > …

  It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class.

  Static methods in Python are similar to those found in Java or C++. For a more advanced concept, see the classmethod builtin.

## Module contents