SMACT Utilities Oxidation Module

SMACT Utilities Oxidation Module#

Miscellaneous utilities for creating SMACT compatible oxidation states list

Utility functions for handling oxidation states.

class smact.utils.oxidation.ICSD24OxStatesFilter[source]#

Bases: object

Class to handle filtering the ICSD 24 oxidation states list.

The ICSD 24 oxidation states list is a list of oxidation states for each element in the ICSD 24 database.

ox_states_df#

The ICSD 24 oxidation states list as a DataFrame.

Type:

pd.DataFrame

filter(consensus: int = 3, include_zero: bool = False, commonality: str | float = 'low') → DataFrame[source]#

Filter the ICSD 24 oxidation states list by a threshold.

Parameters:

  • consensus (int) – Minimum number of occurrences in literature for an ion to be considered valid. Default is 3.

  • include_zero (bool) – Include oxidation state of zero in the filtered list. Default is False.

  • commonality (str) – Excludes species below a certain proportion of appearances in literature with respect to the total number of reports of a given element (after the consensus threshold has been applied). “low” includes all species, “medium” excludes rare species below 10% occurrence, and “high” excludes non-majority species below 50% occurrence. “main” selects the species with the highest occurrence for a given element. Users may also specify their own threshold (float or int). Default is “low”.

Returns:

The filtered oxidation states list as a DataFrame.

Return type:

pd.DataFrame

get_species_list(consensus: int = 3, include_zero: bool = False, include_one_oxidation_state: bool = False, commonality: str | float = 'low') → list[str][source]#

Get the filtered ICSD 24 oxidation states list as a list of species.

Parameters:

  • consensus (int) – Minimum number of occurrences in literature for an ion to be considered valid. Default is 3.

  • include_zero (bool) – Include oxidation state of zero in the filtered list. Default is False.

  • include_one_oxidation_state (bool) – Include oxidation states +1 and -1 in the filtered list or include as + and - signs. Default is False.

  • commonality (str) – Excludes species below a certain proportion of appearances in literature with respect to the total number of reports of a given element (after the consensus threshold has been applied). “low” includes all species, “medium” excludes rare species below 10% occurrence, and “high” excludes non-majority species below 50% occurrence. “main” selects the species with the highest occurrence for a given element. Users may also specify their own threshold (float or int). Default is “low”.

Returns:

The filtered oxidation states list as a list of species.

Return type:

list

get_species_occurrences_df(consensus: int = 3, include_one_oxidation_state: bool = False, sort_by_occurrences: bool = True, include_zero: bool = False) → DataFrame[source]#

Get the ICSD 24 oxidation states list as a dataframe of species with their occurrences.

Parameters:

  • consensus (int) – Minimum number of occurrences in literature for an ion to be considered valid. Default is 3.

  • include_one_oxidation_state (bool) – Include oxidation states +1 and -1 in the species or include as + and - signs. Default is False.

  • sort_by_occurrences (bool) – Sort the species list by occurrences. Default is True.

  • include_zero (bool) – Include oxidation state of zero in the filtered list. Default is False.

Returns:

The species list as a dataframe of species with their occurrences.

Return type:

dataframe

write(filename: str, comment: str | None = None, consensus: int = 3, include_zero: bool = False, commonality: str = 'low') → None[source]#

Write the filtered ICSD 24 oxidation states list to a SMACT-compatible oxidation states txt file.

Parameters:

  • filename (str) – The filename to write the filtered oxidation states list to.

  • comment (str) – A comment to include in the txt file. Default is None.

  • consensus (int) – Minimum number of occurrences in literature for an ion to be considered valid. Default is 3.

  • include_zero (bool) – Include oxidation state of zero in the filtered list. Default is False.

  • commonality (str) – Excludes species below a certain proportion of appearances in literature with respect to the total number of reports of a given element (after the consensus threshold has been applied). “low” includes all species, “medium” excludes rare species below 10% occurrence, and “high” excludes non-majority species below 50% occurrence. “main” selects the species with the highest occurrence for a given element. Users may also specify their own threshold (float or int). Default is “low”.