elphick.geomet.base.MassComposition

class elphick.geomet.base.MassComposition(data=None, name=None, moisture_in_scope=True, mass_wet_var=None, mass_dry_var=None, moisture_var=None, component_vars=None, composition_units='%', components_as_symbols=True, ranges=None, config_file=None)

__init__(data=None, name=None, moisture_in_scope=True, mass_wet_var=None, mass_dry_var=None, moisture_var=None, component_vars=None, composition_units='%', components_as_symbols=True, ranges=None, config_file=None)

Parameters:

• data (Optional[DataFrame]) – The input data

• name (Optional[str]) – The name of the sample

• moisture_in_scope (bool) – Whether the moisture is in scope. If False, only dry mass is processed.

• mass_wet_var (Optional[str]) – The name of the wet mass column

• mass_dry_var (Optional[str]) – The name of the dry mass column

• moisture_var (Optional[str]) – The name of the moisture column

• component_vars (Optional[list[str]]) – The names of the chemical columns

• components_as_symbols (bool) – If True, convert the composition variables to symbols, e.g. Fe

• ranges (Optional[dict[str, list]]) – The range of valid data for each column in the data

• config_file (Optional[Path]) – The configuration file

Methods

__init__([data, name, moisture_in_scope, ...])
add(other[, name, include_supplementary_data])	Add two objects together
balance_composition()	Balance the composition data
clip_composition([ranges])	Clip the components
clip_recovery(other[, recovery_bounds, ...])	Clip the recovery to the specified bounds and recalculate the estimate.
create_congruent_object(name[, ...])	Create an object with the same attributes
div(other[, name, include_supplementary_data])	Divide two objects
filter_by_index(index)	Update the data by index
from_mass_dataframe(mass_df[, mass_wet, ...])	Class method to create a MassComposition object from a mass dataframe.
get_mass_data([include_moisture])	Get the mass data
plot_comparison(other[, color, ...])	Create an interactive parallel plot
plot_parallel([color, vars_include, ...])	Create an interactive parallel plot
plot_ternary(variables[, color, title])	Plot a ternary diagram
query(expr[, name])	Reduce the data by a query expression
reset_index(index_name)
set_moisture(moisture[, mass_to_adjust])	Set the moisture to the specified value
split(fraction[, name_1, name_2, ...])	Split the object by mass
sub(other[, name, include_supplementary_data])	Subtract other from self
to_stream()
update_mass_data(value)
weight_average([group_by])

Attributes

aggregate
composition_columns
data
data_columns
mass_columns
mass_data
moisture_column
supplementary_columns
variable_map	A map from lower case standard names to the actual column names

__add__(other)

Add two objects

Perform the addition with the mass-composition variables only and then append any attribute variables. Presently ignores any attribute vars in other :type other: TypeVar(MC, bound= MassComposition) :param other: object to add to self

Returns:

Return type:

Stream

add(other, name=None, include_supplementary_data=False)

Add two objects together

Parameters:

• other (TypeVar(MC, bound= MassComposition)) – The other object

• name (Optional[str]) – The name of the new object

• include_supplementary_data (bool) – Whether to include the supplementary data

Return type:

Stream

Returns:

The new object

balance_composition()

Balance the composition data

For records where the component mass exceeds the dry mass, the component masses are reduced proportionally to equal the dry mass. Records where the component mass is less than the dry mass are left unchanged.

Return type:

TypeVar(MC, bound= MassComposition)

clip_composition(ranges=None)

Clip the components

Clip to the components to within the range provided or the default range for each component. This method does not clip moisture - see set_moisture and solve_moisture for that.

Parameters:

• ranges (Optional[dict[str, list[float]]]) – An optional dict defining a list of [lo, hi] floats for each component. If not provided,

• used. (the default range from the config file will be)

Return type:

TypeVar(MC, bound= MassComposition)

Returns:

The object with clipped composition.

clip_recovery(other, recovery_bounds=(0.01, 0.99), allow_moisture_coercion=True)

Clip the recovery to the specified bounds and recalculate the estimate.

Parameters:

• other (TypeVar(MC, bound= MassComposition)) – The other MassComposition object, from which the recovery of self is calculated.

• recovery_bounds (tuple[float, float]) – The bounds for the recovery between 0.0 and 1.0

• allow_moisture_coercion (bool) – if True, allow the wet mass to be modified to maintain the moisture (in the

• recovery) (case that dry mass is clipped to manage)

Return type:

TypeVar(MC, bound= MassComposition)

Returns:

The MassComposition object with the recovery clipped to the bounds.

create_congruent_object(name, include_mc_data=False, include_supp_data=False)

Create an object with the same attributes

Return type:

TypeVar(MC, bound= MassComposition)

div(other, name=None, include_supplementary_data=False)

Divide two objects

Divides self by other, with optional name of the returned object :type other: TypeVar(MC, bound= MassComposition) :param other: the denominator (or reference) object :type name: Optional[str] :param name: name of the returned object :type include_supplementary_data: bool :param include_supplementary_data: Whether to include the supplementary data

Returns:

Return type:

TypeVar(MC, bound= MassComposition)

filter_by_index(index)

Update the data by index

classmethod from_mass_dataframe(mass_df, mass_wet='mass_wet', mass_dry='mass_dry', moisture_column_name=None, component_columns=None, composition_units='%', **kwargs)

Class method to create a MassComposition object from a mass dataframe.

Parameters:

• mass_df (DataFrame) – DataFrame with mass data.

• **kwargs – Additional arguments to pass to the MassComposition constructor.

Return type:

TypeVar(MC, bound= MassComposition)

Returns:

A new MassComposition object.

get_mass_data(include_moisture=True)

Get the mass data

Parameters:

include_moisture (bool) – If True (and moisture is in scope), include the moisture mass column

Return type:

DataFrame

Returns:

plot_comparison(other, color=None, vars_include=None, vars_exclude=None, facet_col_wrap=3, trendline=False, trendline_kwargs=None, title=None)

Create an interactive parallel plot

Useful to compare the difference in component values between two objects.

Parameters:

• other (TypeVar(MC, bound= MassComposition)) – the object to compare with self.

• color (Optional[str]) – Optional color variable

• vars_include (Optional[list[str]]) – Optional List of variables to include in the plot

• vars_exclude (Optional[list[str]]) – Optional List of variables to exclude in the plot

• trendline (bool) – If True and trendlines

• trendline_kwargs (Optional[dict]) – Allows customising the trendline: ref: https://plotly.com/python/linear-fits/

• title (Optional[str]) – Optional plot title

• facet_col_wrap (int) – The number of subplot columns per row.

Return type:

Figure

Returns:

plot_parallel(color=None, vars_include=None, vars_exclude=None, title=None, include_dims=True, plot_interval_edges=False)

Create an interactive parallel plot

Useful to explore multidimensional data like mass-composition data

Parameters:

• color (Optional[str]) – Optional color variable

• vars_include (Optional[list[str]]) – Optional list of variables to include in the plot

• vars_exclude (Optional[list[str]]) – Optional list of variables to exclude in the plot

• title (Optional[str]) – Optional plot title

• include_dims (Union[bool, list[str], None]) – Optional boolean or list of dimension to include in the plot. True will show all dims.

• plot_interval_edges (bool) – If True, interval edges will be plotted instead of interval mid

Return type:

Figure

Returns:

plot_ternary(variables, color=None, title=None)

Plot a ternary diagram

variables: List of 3 components to plot color: Optional color variable title: Optional plot title

Return type:

Figure

query(expr, name=None)

Reduce the data by a query expression

Parameters:

• expr (str) – A pandas query expression

• name (Optional[str]) – name of the new object

Return type:

TypeVar(MC, bound= MassComposition)

Returns:

A new object with the reduced data

set_moisture(moisture, mass_to_adjust='wet')

Set the moisture to the specified value

A convenience method for an mc object that modifies the concrete mass to deliver the specified moisture.

Parameters:

• moisture (Union[Series, float, int]) – The moisture value to set. Can be a constant or series.

• mass_to_adjust (Literal['wet', 'dry']) – The mass to adjust, either ‘wet’ or ‘dry’.

Return type:

TypeVar(MC, bound= MassComposition)

Returns:

split(fraction, name_1=None, name_2=None, include_supplementary_data=False)

Split the object by mass

A simple mass split maintaining the same composition

Parameters:

• fraction (float) – A constant in the range [0.0, 1.0]

• name_1 (Optional[str]) – The name of the reference object created by the split

• name_2 (Optional[str]) – The name of the complement object created by the split

• include_supplementary_data (bool) – Whether to inherit the supplementary variables

Return type:

tuple[Stream, Stream]

Returns:

tuple of two objects, the first with the mass fraction specified, the other the complement

sub(other, name=None, include_supplementary_data=False)

Subtract other from self

Parameters:

• other (TypeVar(MC, bound= MassComposition)) – The other object

• name (Optional[str]) – The name of the new object

• include_supplementary_data (bool) – Whether to include the supplementary data

Return type:

Stream

Returns:

The new object

property variable_map: dict[str, str] | None

A map from lower case standard names to the actual column names