User API

Note

The common classes Oxides, Ions and APFU could be imported directly from main namespace, e.g.:

>>> from epmatools import Oxides

The modules minerals and plotting are available in main namespace as mindb and minplot for convenience.

For interactive use you can import all above using:

>>> from epmatools import *

EPMAtools provides following modules:

epmatools.datatables

class epmatools.datatables.APFU(df, mineral, **kwargs)

A class to store cations p.f.u for mineral.

There are different way to create APFU object:

passing pandas.DataFrame with analyses in rows and cations in columns. Note, that cations needs to by defined with charge e.g. “Si{4+}”, “Na{+}” or “O{2-}”
calculated from Oxides datatable

Parameters:

df (pandas.DataFrame) – plunge direction of linear feature in degrees
mineral (Mineral) – mineral used for formula calculations. See epmatools.mindb
units (str, optional) – units of datatable. Default is “wt%”
name (str, optional) – name of datatable. Default is “Compo”
desc (str, optional) – description of datatable. Default is “Original data”
index_col (str, optional) – name of column used as index. Default None

df

subset of datatable with only ions columns

Type:: pandas.DataFrame

mineral

mineral used for formula calculations

Type:: Mineral

units

units of data

Type:: str

others

subset of datatable with other columns

Type:: pandas.DataFrame

props

chemical properties of present ions

Type:: pandas.DataFrame

names

list of present ions

Type:: list

sum

total sum of oxides in current units

Type:: pandas.Series

mean

mean of oxides in current units

Type:: pandas.Series

name

name of datatable.

Type:: str

desc

description of datatable.

Type:: str

reminder

Returns remaining atoms after mineral formula occupation

Type:: APFU

error

Returns percentage error of calculated cations

Type:: pandas.Series

Example

>>> d = APFU(df)
>>> d = Oxides.apfu(mindb.Garnet_Fe2())

drop(labels)

Drop rows based on index

Parameters:: labels – single or list of indexes to be dropped

endmembers(force=False)

Calculate endmembers proportions

Parameters:: force (bool, optional) – when True, remaining cations are added to last site

head(n=5)

Return first n rows

Parameters:: n (int) – Number of rows. Default 5

iterrows(what=None)

Return row iterator yielding tuples (label, row)

Parameters:: what (str) – Which columns are included. None for all, ‘valid’ for valid, ‘elements’ for elements and ‘others’ for others. Default None

mineral_apfu(force=False)

Calculate apfu from structural formula

Parameters:: force (bool, optional) – when True, remaining cations are added to last site

reset_index(): Reset index to default pandas.RangeIndex

reversed(): Return in reversed order

row(label, what='valid')

Return row as pandas Series

Parameters:

label (label) – label from index
what (str) – Which columns are included. None for valid, ‘elements’ for elements, ‘others’ for others and ‘all’ for all. Default ‘valid’

search(s, on=None)

Search subset of data from datatable containing string s in index or column

Note: Works only with non-numeric index or column

Parameters:: s (str) – Returns all data which contain string s in index.
Returns:: Selected data as datatable

select(loc)

Select rows by label(s) or a boolean array

Parameters:: loc – Single or list of labels, slice or boolean array.
Returns:: Selected data as datatable

set_index(key)

Set index of datatable

Parameters:: key (str or list like) – Either name of column (see Oxides.others) or collection of same length as datatable

tail(n=5)

Return last n rows

Parameters:: n (int) – Number of rows. Default 5

to_clipboard(add_total=True, transpose=True)

Copy table to clipboard

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

to_latex(add_total=True, transpose=True, precision=2)

Convert datatable to LaTeX representation

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

class epmatools.datatables.Ions(df, **kwargs)

A class to store cations composition.

There are different way to create Ions object:

passing pandas.DataFrame with analyses in rows and cations in columns. Note, that cations needs to by defined with charge e.g. “Si{4+}”, “Na{+}” or “O{2-}”
calculated from Oxides datatable

Parameters:

df (pandas.DataFrame) – plunge direction of linear feature in degrees
units (str, optional) – units of datatable. Default is “wt%”
name (str, optional) – name of datatable. Default is “Compo”
desc (str, optional) – description of datatable. Default is “Original data”
index_col (str, optional) – name of column used as index. Default None

df

subset of datatable with only ions columns

Type:: pandas.DataFrame

units

units of data

Type:: str

others

subset of datatable with other columns

Type:: pandas.DataFrame

props

chemical properties of present ions

Type:: pandas.DataFrame

names

list of present ions

Type:: list

sum

total sum of oxides in current units

Type:: pandas.Series

mean

mean of oxides in current units

Type:: pandas.Series

name

name of datatable.

Type:: str

desc

description of datatable.

Type:: str

Example

>>> d = Ions(df)
>>> d = Oxides.cations(noxy=12, ncat=8)

drop(labels)

Drop rows based on index

Parameters:: labels – single or list of indexes to be dropped

head(n=5)

Return first n rows

Parameters:: n (int) – Number of rows. Default 5

iterrows(what=None)

Return row iterator yielding tuples (label, row)

Parameters:: what (str) – Which columns are included. None for all, ‘valid’ for valid, ‘elements’ for elements and ‘others’ for others. Default None

reset_index(): Reset index to default pandas.RangeIndex

reversed(): Return in reversed order

row(label, what='valid')

Return row as pandas Series

Parameters:

label (label) – label from index
what (str) – Which columns are included. None for valid, ‘elements’ for elements, ‘others’ for others and ‘all’ for all. Default ‘valid’

search(s, on=None)

Search subset of data from datatable containing string s in index or column

Note: Works only with non-numeric index or column

Parameters:: s (str) – Returns all data which contain string s in index.
Returns:: Selected data as datatable

select(loc)

Select rows by label(s) or a boolean array

Parameters:: loc – Single or list of labels, slice or boolean array.
Returns:: Selected data as datatable

set_index(key)

Set index of datatable

Parameters:: key (str or list like) – Either name of column (see Oxides.others) or collection of same length as datatable

tail(n=5)

Return last n rows

Parameters:: n (int) – Number of rows. Default 5

to_clipboard(add_total=True, transpose=True)

Copy table to clipboard

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

to_latex(add_total=True, transpose=True, precision=2)

Convert datatable to LaTeX representation

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

class epmatools.datatables.Oxides(df, **kwargs)

A class to store oxides composition.

There are different way to create Oxides object:

passing pandas.DataFrame with analyses in rows and oxides in columns
from clipboard using from_clipboard() method
from Excel using from_excel() method
using from_examples method

Parameters:

df (pandas.DataFrame) – plunge direction of linear feature in degrees
units (str, optional) – units of datatable. Default is “wt%”
name (str, optional) – name of datatable. Default is “Compo”
desc (str, optional) – description of datatable. Default is “Original data”
index_col (str, optional) – name of column used as index. Default None

df

subset of datatable with only oxides columns

Type:: pandas.DataFrame

units

units of data

Type:: str

elements

subset of datatable with only elements columns

Type:: pandas.DataFrame

others

subset of datatable with other columns

Type:: pandas.DataFrame

props

chemical properties of present oxides

Type:: pandas.DataFrame

names

list of present oxides

Type:: list

sum

total sum of oxides in current units

Type:: pandas.Series

mean

mean of oxides in current units

Type:: pandas.Series

name

name of datatable.

Type:: str

desc

description of datatable.

Type:: str

cat_number

Cations number i.e. # moles of cation in mineral

Type:: Oxides

oxy_number

Oxygen number i.e. # moles of oxygen in mineral

Type:: Oxides

Example

>>> d = Oxides(df)
>>> d = Oxides.from_clipboard()
>>> d = Oxides.from_excel('analyses.xlsx', sheet_name='Minerals', skiprows=3)
>>> d = Oxides.from_examples('minerals')

MAGEMin(H2O=-1, oxygen=0.01, db='mp', sys_in='mol')

Print oxides formatted as MAGEMin bulk file

Note

The CaO is recalculate using apatite correction based on P205 if available.

Parameters:

H2O (float) – wt% of water. When -1 the amount is calculated as 100 - Total Default -1.
oxygen (float) – value to calculate moles of ferric iron. Moles FeO = FeOtot - 2O and moles Fe2O3 = O. Default 0.01
db (str) – MAGEMin database. ‘mp’ metapelite (White et al. 2014), ‘mb’ metabasite (Green et al. 2016), ‘ig’ igneous (Holland et al. 2018), ‘um’ ultramafic (Evans & Frost 2021), ‘ume’ ultramafic extended (Evans & Frost 2021 + pl, hb and aug from Green et al. 2016), ‘mpe’ Metapelite extended (White et al. 2014, Green et al. 2016, Evans & Frost 2021), ‘mtl’ mantle (Holland et al. 2013). Default is “mp”
sys_in (str) – system comp “wt” or “mol”. Default is “mol”

Perplexbulk(H2O=-1, oxygen=0.01, system='MnNCKFMASHTO')

Print oxides formatted as PerpleX thermodynamic component list

Note

The CaO is recalculate using apatite correction based on P205 if available.

Parameters:

H2O (float) – wt% of water. When -1 the amount is calculated as 100 - Total Default -1.
oxygen (float) – value to calculate moles of ferric iron. Moles FeO = FeOtot - O and moles Fe2O3 = O. Default 0.01
system (str) – axfile to be used. One of ‘MnNCKFMASHTO’, ‘NCKFMASHTO’, ‘KFMASH’, ‘NCKFMASHTOCr’, ‘NCKFMASTOCr’. Default ‘MnNCKFMASHTO’

TCbulk(H2O=-1, oxygen=0.01, system='MnNCKFMASHTO')

Print oxides formatted as THERMOCALC bulk script

Note

The CaO is recalculate using apatite correction based on P205 if available.

Parameters:

H2O (float) – wt% of water. When -1 the amount is calculated as 100 - Total Default -1.
oxygen (float) – value to calculate moles of ferric iron. Moles FeO = FeOtot - 2O and moles Fe2O3 = O. Default 0.01
system (str) – axfile to be used. One of ‘MnNCKFMASHTO’, ‘NCKFMASHTO’, ‘KFMASH’, ‘NCKFMASHTOCr’, ‘NCKFMASTOCr’. Default ‘MnNCKFMASHTO’

apatite_correction()

Apatite correction

Note

All P2O5 is assumed to be apatite based and is removed from composition

CaO mol% = CaO mol% - (10 / 3) * P2O5 mol%

Returns:: apatite corrected datatable
Return type:: Oxides

apfu(mineral, tocat=False)

Cations calculated on the basis of mineral formula

Parameters:

mineral (Mineral) – instance of mineral
tocat (bool, optional) – when True normalized to mineral.ncat, otherwise to mineral.noxy. Default False

Returns:

a.p.f.u datatable

Return type:

APFU

cations(noxy=1, ncat=1, tocat=False)

Cations calculated on the basis of oxygens or cations

Parameters:

noxy (int, optional) – ideal number of oxygens. Default 1
ncat (int, optional) – ideal number of cations. Default 1
tocat (bool, optional) – when True normalized to ncat, otherwise to noxy. Default False

Returns:

cations datatable

Return type:

Ions

chargedef(noxy, ncat)

Calculates charge deficiency based on number of cations and oxygens

Parameters:

noxy (int) – ideal number of oxygens
ncat (int) – ideal number of cations

Returns:

charge deficiency values

Return type:

pandas.Series

charges(ncat)

Calculates charges based on number of cations

Parameters:: ncat (int) – number of cations
Returns:: charges datatable
Return type:: Oxides

check_cations(noxy, ncat, confidence=None)

Return normalized error of calculated cations

err = [ncat - #cat(noxy)]/ncat

Parameters:

noxy (int) – number of oxygens
ncat (int) – number of cations
confidence (float, optional) – if not None, returns booleans with True, where error is within confidence

Returns:

boolean or normalized errors

Return type:

pandas.Series

cnf(ncat)

Cation normalisation factor - ideal cations / sum of cations

Parameters:: ncat (int) – ideal cations
Returns:: cation normalisation factors
Return type:: pandas.Series

convert_Fe(to='FeO')

Recalculate FeO to Fe2O3 or vice-versa

Note

When only FeO exists, all is recalculated to Fe2O3. When only Fe2O3 exists, all is recalculated to FeO. When both exists, Fe2O3 is recalculated and added to FeO. Otherwise datatable is not changed.

Parameters:: to (str) – to what iron oxide Fe should be converted. Default “FeO”
Returns:: datatable with converted Fe oxide
Return type:: Oxides

drop(labels)

Drop rows based on index

Parameters:: labels – single or list of indexes to be dropped

elwt()

Convert oxides weight percents to elements weight percents

Returns:: elements weight percents datatable
Return type:: Oxides

elwt_oxy()

Convert oxides weight percents to elements weight percents incl. oxygen

Returns:: elements weight percents datatable
Return type:: Oxides

classmethod from_clipboard(**kwargs)

Parse datatable from clipboard.

Note

By default, oxides should be arranged in columns with one line header containing case-sensitive oxides formula (e.g. Al2O3). All other columns are available as Oxides.others and are not used for calculations.

Parameters:

vertical (bool, optional) – Set True when oxides are aranged in rows. Default False
**kwargs – all keyword arguments are passed to Oxides

Returns:

datatable

Return type:

Oxides

classmethod from_examples(example=None)

Get example datatable

Parameters:: example (str, optional) – Name of example. When None, available examples are printed. Default is None
Returns:: datatable
Return type:: Oxides

classmethod from_excel(filename, **kwargs)

Read datatable from Excel file.

Note

Oxides must be arranged in columns with one line header containing case-sensitive oxides formula (e.g. Al2O3). All other columns are available as Oxides.others and are not used for calculations.

Parameters:

filename (str) – string path to file. For other possibility see pandas.read_excel
units (str, optional) – units of datatable. Default is “wt%”
name (str, optional) – name of datatable. Default is “Compo”
desc (str, optional) – description of datatable. Default is “Original data”
index_col (str, optional) – name of column used as index. Default None
**kwargs – all keyword arguments are passed to pandas.read_excel

Returns:

datatable

Return type:

Oxides

head(n=5)

Return first n rows

Parameters:: n (int) – Number of rows. Default 5

iterrows(what=None)

Return row iterator yielding tuples (label, row)

Parameters:: what (str) – Which columns are included. None for all, ‘valid’ for valid, ‘elements’ for elements and ‘others’ for others. Default None

mineral_endmembers(mineral, tocat=False, force=False)

Calculate mineral end-members

Parameters:

mineral (Mineral) – instance of mineral.
tocat (bool, optional) – when True normalized to ncat, otherwise to noxy. Default False
force (bool, optional) – when True, remaining cations are added to last site

Returns:

calculated endmembers

Return type:

pandas.DataFrame

molprop()

Convert oxides weight percents to molar proportions

Returns:: molar proportions datatable
Return type:: Oxides

normalize(to=100.0)

Normalize the values

Parameters:: to (int or float) – desired sum. Default 100
Returns:: normalized datatable
Return type:: Oxides

onf(noxy)

Oxygen normalisation factor - ideal oxygens / sum of oxygens

Parameters:: noxy (int) – ideal oxygens
Returns:: oxygen normalisation factors
Return type:: pandas.Series

oxwt()

Convert oxides molar proportions to weight percents

Returns:: weight percents datatable
Return type:: Oxides

recalculate_Fe(noxy, ncat)

Recalculate Fe based on charge balance

Parameters:

noxy (int) – ideal number of oxygens. Default 1
ncat (int) – ideal number of cations. Default 1

Note

Either both FeO and Fe2O3 are present or any of then, the composition is modified to fullfil charge balance for given cations and oxygens.

Returns:: datatable with recalculated Fe
Return type:: Oxides

reset_index(): Reset index to default pandas.RangeIndex

reversed(): Return in reversed order

row(label, what='valid')

Return row as pandas Series

Parameters:

label (label) – label from index
what (str) – Which columns are included. None for valid, ‘elements’ for elements, ‘others’ for others and ‘all’ for all. Default ‘valid’

search(s, on=None)

Search subset of data from datatable containing string s in index or column

Note: Works only with non-numeric index or column

Parameters:: s (str) – Returns all data which contain string s in index.
Returns:: Selected data as datatable

select(loc)

Select rows by label(s) or a boolean array

Parameters:: loc – Single or list of labels, slice or boolean array.
Returns:: Selected data as datatable

set_index(key)

Set index of datatable

Parameters:: key (str or list like) – Either name of column (see Oxides.others) or collection of same length as datatable

tail(n=5)

Return last n rows

Parameters:: n (int) – Number of rows. Default 5

to_clipboard(add_total=True, transpose=True)

Copy table to clipboard

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

to_latex(add_total=True, transpose=True, precision=2)

Convert datatable to LaTeX representation

Parameters:

add_total (bool, optional) – Add column “Total” with total sums. Default True
transpose (bool, optional) – Place samples as columns. Default True
precision (bool, optional) – Nimber of decimal places. Default 2

epmatools.minerals

class epmatools.minerals.Feldspar

Feldspar with 3 endmembers

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Garnet

Garnet using Fe2 and Fe3 with 6 endmembers

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Garnet_Fe2

Garnet using total Fe with 4 endmembers

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Mineral

Base Mineral class to store mineral structure and endmembers calculation

noxy

number of oxygens

Type:: int

ncat

number of cations

Type:: int

needsFe

“Fe2” for only FeO oxide needed, “Fe3” for both FeO and Fe2O3 oxide needed, None for no Fe needed

Type:: str

structure

structural formula definition. Iterable collection of tuples (name, ncat, list of cations) e.g. (“T”, 4, [“Si{4+}”, “Al{3+}”]). Tuples are ordered in population order.

Type:: tuple, optional

has_structure

True when structure is defined

Type:: bool

has_endmembers

True when endmembers method is defined

Type:: bool

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Pyroxene

Pyroxene with Na-Cr with 6 endmembers

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Pyroxene_Fe2

Pyroxen using total Fe with 3 endmembers

apfu(cations, force=False)

Calculate mineral atom p.f.u based on site occupancies

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: atoms p.f.u
Return type:: pandas.Series

calculate(cations, force=False)

Calculate structural formula from cations p.f.u

Parameters:: cations (pandas.Series) – cations p.f.u
Returns:: structural formula
Return type:: StrucForm

class epmatools.minerals.Site(name, ncat, candidates)

Class to store mineral site information

Parameters:

name (str) – name of site
ncat (int) – ideal number of cations
candidates (list) – list of cations in population order

name

name of site

Type:: str

ncat

ideal number of cations

Type:: int

candidates

list of cations in population order

Type:: list

atoms

populated atoms

Type:: dict

free

remaining space in site, i.e. Ideal - Occupied

Type:: float

add(atom, amount, force=False)

Add atom to site

Parameters:

atom (str) – cation name
amount (float) – number of attoms to add
force (bool) – If False atoms are added up to ideal occupancy. When True full amount is added. Default False

get(atom, fraction=False)

Get number of given atom on site

Parameters:: atom (str) – atom name

class epmatools.minerals.StrucForm(mineral)

Class to manipulate mineral structural formula

Parameters:: mineral (Mineral) – mineral instance

mineral

mineral instance

Type:: Mineral

sites

list of sites

Type:: list

reminder

None or remainder after site population

Type:: pandas.Series

property apfu

Calculate mineral atom p.f.u based on site occupancies

Returns:: atoms p.f.u
Return type:: pandas.Series

check_stechiometry(): Calculate average missfit of populated and ideal cations on sites

get(atom)

Get total number of given atom in structure

Parameters:: atom (str) – atom name

site(name)

Get site by name

Parameters:: name (str) – site name

epmatools.plotting

epmatools.plotting.plot_grt_profile(em, **kwargs)

Plot garnet profiles.

Note

Endmembers have to be properly ordered.

Parameters:

em (pandas.DataFrame) – garnet endmembers
use_index (bool) – When True, xticks are derived from DataFrame index and SpanSelector is activated, otherwise ticks are sequential. Default False
overlap_isopleths (PTPS) – When PTPS is passed, overlap_isopleths method is invoked with SpanSelector min-max range for garnet composition. Default None
search_composition (PTPS) – When PTPS is passed, search_composition method is invoked with SpanSelector mean values for garnet composition. Default None
xticks_rotation (float, optional) – Rotation of xtick labels. Default 0
twin (bool, optional) – When True, the plot has two independent y-axes for better scaling. Endmembers must be separated into two groups using data1 and data2 args. When False both groups are plotted on same axes. Default True
data1 (list, optional) – list of endmember names in first group. Default [“Alm”]
data2 (list, optional) – list of endmember names in first group. Default [“Prp”, “Grs”, “Sps”]
markers (dict or string, optional) – matplotlib markers definition. When string, marker is used for all endmembers. When dictionary, each endmember must have defined own marker. Default o
datalim1 (tuple, optional) – y-axis limits for first axis or auto when None. Default None
datalim2 (tuple, optional) – y-axis limits for second axis or auto when None. Default None
omit (list, optional) – index or list of indexes to be omitted from plot. Default None
percents (bool) – When True y-axes scale is percents, otherwise fraction
xlabel (str, optional) – label of the x-axis. Default None
filename (str, optional) – When not None, the plot is saved to file, otherwise the plot is shown.
maxticks (int) – maximum number of ticks on x-axis. Default 20

To work with EDS maps you can use maps module. The class MapStore could be used for H5 storage of your maps, allowing quick access of yout data. Individual dataset are manipulated using Mapset class:

epmatools.maps

class epmatools.maps.MapLegend(**kwargs)

A class to store phase map legend.

Note: Legend have to be used for agglomerative clustering with exactly same number of classes as defined in legend.

Parameters:

n_clusters (int) – Number of classes used with this legend. Default 16
cmap (str) – Color map used for auto color mapping. Default ‘nipy_spectral’

n_clusters

Number of classes used in legend

Type:: int

norm

Matplotlib mapping to colors

Type:: matplotlib.colors.Normalize

cmap

Matplotlib color map used for automatic color mapping

Type:: str

store

Legend items for labelled classes

Type:: dict

unlabeled

List of unlabeled classes

Type:: list

add(phase, color, values)

Add new phase to the legend

Parameters:

phase (str) – Name of phase
color (str or tuple) – matplotlib named color or RGB tuple
values (tuple or int) – tuple of class values corresponding to given phase

class_color(value)

Return color for given class

Parameters:: value (int) – class number

property lut: Return RGB color array for all classes

remove(phase)

Remove phase from the legend

Parameters:: phase (str) – Name of phase

rename(old, new)

Rename phase to the new name

Parameters:

old (str) – Name of phase
new (str) – Name of phase

set_color(phase, color)

Set color for phase

Parameters:

phase (str) – Name of phase
color (str or tuple) – matplotlib named color or RGB tuple

class epmatools.maps.MapStore(h5file)

MapStore class provides file data storage in HDF5 format

Parameters:: h5file (str) – string representation of storage filename

samples

List of sample names stored in MapStore

Type:: list

h5file

string representation of storage filename

Type:: str

delete_sample(name)

Delete sample from MapStore

Parameters:: name (str) – Name of the sample to be deleted

classmethod from_examples(example=None)

Get example MapStore

Parameters:: example (str, optional) – Name of example. When None, available examples are printed. Default is None
Returns:: datatable
Return type:: Oxides

get_sample(name)

Retrieve sample from MapStore

Parameters:: name (str) – Name of the sample. See HStore.samples for possible values

info(): Returns pandas dataframe with storage information

rename_sample(name, newname)

RTename sample in MapStore

Parameters:

name (str) – Name of the sample to be renamed
newname (str) – New name

save_sample(sample, overwrite=False)

Store sample in MapStore

Parameters:: sample (edstools.Mapset) – Mapset instance to be stored in MapStore

overwrite (bool, optional): Whether to overwrite existing: sample. Default False

update_legend(sample)

Update stored legend to the one from the sample.

Note: Provided smaple must exists in MapStore

Parameters:: sample (edstools.Mapset) – Mapset instance to be stored in MapStore

class epmatools.maps.Mapset(maps, **kwargs)

A class to represent a collection of spatially overlapping EDS maps.

Note: All maps must have same spatial resolution. Most of the arguments: are accessible as instance properties.

Maps data could be accessed by different ways. Raw data (ignoring mask) could be obtained by name of the map used as index of sample instance:

>>> s['Si']

Masked data (i.e. np.nan values represents masked values) could be obtained by method get_map:

>>> s.get_map('Si')

Flattened array of non-masked values could be obtained by values method:

>>> s.values('Si')

Parameters:

maps (dict) – Collection of maps stored in dictionary. The key is the name of the map (e.g. element name) and map itself have to be 2D numpy.ndarray.
name (str, optional) – Name of the sample. Default is ‘default’.
aspect (float) – Aspect of the axis scaling, i.e. the ratio of y-unit to x-unit. Default 1
masks (dict) – Collection of masks stored in dictionary. All masks are 2D boolean numpy arrays. Values corresponding to True are masked.
active_mask (str) – Name of active mask or None. Default value is None.
clusters (numpy.array) – Clusters from KMeans clustering. Defaut is None
centers (numpy.array) – Centers from KMeans clustering. Defaut is None
labels (numpy.array) – Labels from Agglomerative clustering. Defaut is None
img (numpy.array) – 2D array of Agglomerative labels. Defaut is None
legend (edstool.MapLegend) – Legend for phase map. Defaut is None
default_cmap (str) – Name of default matplotlib colormap. Default is ‘inferno’.
pixelsize (str) – Size of pixel in pixelunit. Default is 1.
pixelsize – Pixel unit e.g. m, cm, um, km. Default is “um”.
figsize (tuple) – Default figure size. Default is (8, 6).
transpose (bool) – Whether to show map transposed. Default is False.

df

All nonmasked values from all maps arranged in Pandas DataFrame.

Type:: pandas.DataFrame

element_df

All nonmasked values from element maps arranged in Pandas DataFrame.

Type:: pandas.DataFrame

maps

List of all available maps in sample.

Type:: list

masks

List of all available masks in sample.

Type:: list

active_mask

Name of active mask or None.

Type:: str

cluster_mask

Name of mask used during clustering or None.

Type:: str

element_maps

List of all elemental maps in sample.

Type:: list

total_counts

2d array of total elemental count. It is sum of all elemental maps.

Type:: nump.ndarray

shape

(rows, cols) tuple of maps shape.

Type:: tuple

name

Name of the sample.

Type:: str, optional

aspect

Aspect of the axis scaling, i.e. the ratio of y-unit to x-unit.

Type:: float

mask

Active data mask as 2D boolean numpy array.

Type:: numpy.ndarray

clusters

Clusters from KMeans clustering.

Type:: numpy.array

centers

Centers from KMeans clustering.

Type:: numpy.array

labels

Labels from Agglomerative clustering.

Type:: numpy.array

img

2D array of Agglomerative labels.

Type:: numpy.array

legend

Legend for phase map.

Type:: edstool.MapLegend

default_cmap

Name of default matplotlib colormap.

Type:: str

figsize

Default figure size.

Type:: tuple

transpose

Whether to show map transposed.

Type:: bool

add_mask(name, mask, **kwargs)

Add mask to sample masks

Parameters:

name (str) – Name of the mask
mask (numpy.ndarray) – 2D boolean numpy array

Keyword Arguments:

activate (bool) – Whether the mask should be set as active. Default is True
overwrite (bool) – Allow overwrite existing mask. Default False

aggclusters(**kwargs)

Agglomerative clustering of KMeans.

Keyword Arguments:: n_clusters (int) – Number of classes to be created. Default is n_clusters defined in Mapset.legend

Note: When n_clusters is provided and is different from active legend: n_clusters value, the sample legend is re-initialized.

Additional keyword arguments are passsed for MapLegend()

autolegend(n_phases, **kwargs)

Create given number of phases from dendrogram

Parameters:

n_phases (int) – Number of phases to create

Keyword Arguments:

cmap (str) – Color map used for auto color mapping. Default ‘nipy_spectral’
zscore (bool) – Transform values to zscore before clustering. Default False
log1p (bool) – Logarithmic transform of values before clustering. Default False
metric (str) – Default euclidean
method (str) – Default ward

clear_legend(): Clear legend

clip(rmin=0, rmax=None, cmin=0, cmax=None, **kwargs)

Clip out rectangular area from sample.

Note: All existing masks are also clipped

Keyword Arguments:

rmin (int) – Minimum row to be clipped. Default 0.
rmax (int) – Maximum row to be clipped. Default is max.
cmin (int) – Minimum column to be clipped. Default 0.
cmax (int) – Maximum column to be clipped. Default is max.

Additional keyword arguments are passed to Mapset.__init__.

create_clusters(**kwargs)

Calculate KMeans clustering of elemental maps

To selects initial cluster centroids, k-means++ is used.

Note: KMeans are used for subsequent Agglomerative clustering: to create phase map.

Keyword Arguments:

n_kmeans (int) – Number of clusters to be created. Default 256
ignore (list) – List of elements to be ignored for KMeans clustering. Default []
only_elements (bool) – Use only elemental maps. Defaut True
use_total (bool) – add sum to feature. Defaut False
zscore (bool) – Transform values to zscore before clustering. Default False
log1p (bool) – Logarithmic transform of values before clustering. Default False
random_state (int) – Determines random number generation for centroid initialization. Default 42.

Additional keyword arguments are passed to aggclusters() method.

deactivate_mask(): Deactivate active mask.

dendrogram(**kwargs)

Show dendrogram of agglomerative clusters

Keyword Arguments:

zscore (bool) – Transform values to zscore before clustering. Default False
log1p (bool) – Logarithmic transform of values before clustering. Default False
metric (str) – Default euclidean
method (str) – Default ward

draw_mask(name, expr=None, **kwargs)

Create mask by drawing polygon

Parameters:

name (str) – Name of the mask

Keyword Arguments:

expr (str, optional) – Name of the map or expression using names of the map, e.g. ‘Si’, ‘Fe/(Fe+Mg)’, ‘Na+Ca+K’. If None, the total counts are used.
invert (bool) – Whether mask inside or outside of the polygon. Default is False, so inside is masked.
activate (bool) – Whether the mask should be set as active. Default is True

For additional arguments see Mapset.show

get_label_mask(*args, invert=False)

Get mask corresponding to given class(es) from Agglomerative clustering.

Parameters:: value (int) – Any number(s) of classes to be used for mask
Keyword Arguments:: invert (bool) – Invert mask. Default False

get_map(expr=None, invert_mask=False)

Returns map as 2D numpy.ndarray with np.nan as masked values.

Keyword Arguments:: expr (str, optional) – Name of the map or expression using names of the map, e.g. ‘Si’, ‘Fe/(Fe+Mg)’, ‘Na+Ca+K’. If None, the total counts are used.

get_mask(name)

Get mask by name.

Parameters:: name (str) – Name of the mask

get_phase_mask(phase, invert=False)

Get mask corresponding to given phase from legend.

Parameters:: phase (str) – Name of phase. Must be in legend
Keyword Arguments:: invert (bool) – Invert mask. Default False

invert_mask()

Invert active mask.

Note: Existing clusters will be removed

Parameters:: name (str) – Name of the mask

kde(expr=None, **kwargs)

Show Gaussian kernel density estimate of map values

Parameters:

expr (str, optional) – Name of the map or expression using names of the map, e.g. ‘Si’, ‘Fe/(Fe+Mg)’, ‘Na+Ca+K’. If None, the total counts are used.

Keyword Arguments:

vmin – Minimum value used for KDE. Default value is calculated according to cdfclip setting.
vmax – Maximum value used for KDE. Default value is calculated according to cdfclip setting.
cdfclip (tuple) – Default range of values used for KDE based on cumulative distribution range. Default is (0, 100)
zscore (bool) – Whether to transform values to z-score. Default False.
log (bool) – Whether to use logarithms of values for cdfclip. Default False.
title (str) – Figure title. Default is the expr.
figsize (tuple) – Figure size. Default is Mapset.figsize

label_df(counts=False)

Return averaged values for each label of Agglomerative clustering

Keyword Arguments:: counts (bool) – If True, Counts column is added. Default False

label_info(**kwargs)

Returns averaged values for each class of Agglomerative clustering as Pandas DataFrame.

Note: When particular class has legend label, the name of the phase is added to result.

Keyword Arguments:

sorted (bool) – Whether to sort according to class proportion. Default False
normalized (bool) – Whether to normalize the sum to 100. Default False
counts (bool) – Include total counts. Deafult True
prop (bool) – include class proportion. Deafult True

modify_mask_add(name)

Modify active mask as logical_and with mask name

Note: Existing clusters will be removed

Parameters:: name (str) – Name of the mask

modify_mask_or(name)

Modify active mask as logical_or with mask name

Note: Existing clusters will be removed

Parameters:: name (str) – Name of the mask

modify_mask_xor(name)

Modify active mask as logical_xor with mask name

Note: Existing clusters will be removed

Parameters:: name (str) – Name of the mask

phase_df(phase, counts=False)

Return averaged values for each phase in legend as pandas DataFrame.

Parameters:: phase (str) – Name of phase to be retrieved.
Keyword Arguments:: counts (bool) – If True, Counts column is added. Default False

phase_info(sorted=False, **kwargs)

Returns averaged values for each phase from legend as Pandas DataFrame.

Keyword Arguments:

sorted (bool) – Whether to sort according to phase proportion. . Default False
normalized (bool) – Whether to normalize the sum to 100. Default False
counts (bool) – Include total counts. Deafult True
prop (bool) – include phase proportion. Deafult True

phasemap(**kwargs)

Show phase map using sample legend.

Keyword Arguments:

figsize (tuple) – Figure size. Default is Mapset.figsize
legend (bool) – Whether to show phase legend
scale (bool) – Show scalebar when True. Default False
sb_kwargs (dict) – Scale bar keyword args. Default {}
transpose (bool) – Whether to transpose the map. Default is Mapset.transpose
filename (str) – If provided, the figure is saved to file. Default None.

randomclip(rows, cols, **kwargs)

Clip randomly placed rectangular area

Parameters:

rows (int) – Number of rows to be clipped
cols (int) – Number of columns to be clipped

Additional keyword arguments are passed to Mapset.__init__.

remove_mask(name)

Remove mask

Note: Existing clusters will be also removed

Parameters:: name (str) – Name of the mask

rename_mask(name): Rename active mask

set_default_mask(): Set active mask as default mask, i.e. always merged with active one

show(expr=None, **kwargs)

Show map on figure

Parameters:

expr (str, optional) – Name of the map or expression using names of the map, e.g. ‘Si’, ‘Fe/(Fe+Mg)’, ‘Na+Ca+K’. If None, the total counts are used.

Keyword Arguments:

colorbar (bool) – Wheter to show colorbar. Default True.
vmin – Minimum value mapped to lowest color in colormap. Default value is calculated according to cdfclip setting.
vmax – Maximum value mapped to lowest color in colormap. Default value is calculated according to cdfclip setting.
cdfclip (tuple) – Default colormap mapping of values based on cumulative distribution range. Default is (2, 98)
cmap (str) – Name of matplotlib colormap. Default is ‘inferno’
scale (bool) – Show scalebar when True. Default False
sb_kwargs (dict) – Scale bar keyword args. Default {}
under (str) – Name of the color used for values below vmin. Default is lowest color of active colormap.
over (str) – Name of the color used for values above vmax. Default is highest color of active colormap.
masked (str) – if provided, defines masked region color, otherwise transparent.
zscore (bool) – Whether to transform values to z-score. Default False.
log (bool) – Whether to use logarithmic mapping to color map. Default False.
background (str) – map show as background in masked region. Default None
background_cmap (str) – Name of matplotlib colormap. Default is ‘grey’
title (str) – Figure title. Default is the expr.
figsize (tuple) – Figure size. Default is Mapset.figsize
transpose (bool) – Whether to transpose the map. Default is Mapset.transpose
filename (str) – If provided, the figure is saved to file. Default None.
clip (bool) – If True, user can provide by mouse the rectangular area used for clipping. Clipped sample is returned.
ax (Axes) – use this axes for plotting. Default None.
show (bool) – When False, plot is not shown and other plot could be added. Default True.

values(expr=None)

Returns flattened array of nonmasked values.

Parameters:: expr (str, optional) – Name of the map or expression using names of the map, e.g. ‘Si’, ‘Fe/(Fe+Mg)’, ‘Na+Ca+K’. If None, the total counts are used.