elphick.mass_composition.mass_composition.MassComposition

class elphick.mass_composition.mass_composition.MassComposition(data=None, name=None, mass_wet_var=None, mass_dry_var=None, moisture_var=None, chem_vars=None, mass_units=None, composition_units=None, constraints=None, config_file=None)

__init__(data=None, name=None, mass_wet_var=None, mass_dry_var=None, moisture_var=None, chem_vars=None, mass_units=None, composition_units=None, constraints=None, config_file=None)

Parameters:

• data (Optional[DataFrame]) –

• name (Optional[str]) –

• mass_wet_var (Optional[str]) –

• mass_dry_var (Optional[str]) –

• moisture_var (Optional[str]) –

• chem_vars (Optional[List[str]]) –

• mass_units (Optional[str]) –

• constraints (Optional[Dict[str, List]]) –

• config_file (Optional[Path]) –

Methods

__init__([data, name, mass_wet_var, ...])	type data: Optional[DataFrame]
add(other[, name])	Add two objects
aggregate([group_var, group_bins, ...])	Calculate the weight average.
binned_mass_composition(cutoff_var, bin_width)	A.K.A "The Grade-Tonnage" curve.
calculate_partition(ref)	Calculate the partition of the ref stream relative to self
compare(other[, comparisons, ...])	rtype: Union[DataFrame, Dataset]
constrain([clip_mass, clip_composition, ...])	Constrain the mass-composition
div(other[, name])	Divide two objects
from_xarray(ds[, name])
get_common_prefix(columns)	rtype: str
get_constraint_bounds(constraints)	rtype: Dict[str, List]
ideal_incremental_composition([discard_from])	Incrementally separate a fractionated sample.
ideal_incremental_recovery([discard_from, ...])	Incrementally separate a fractionated sample.
ideal_incremental_separation([discard_from])	Incrementally separate a fractionated sample.
plot_amenability(target_analyte[, ...])	The yield-recovery plot.
plot_bins(variables, cutoff_var, bin_width)	Plot "The Grade-Tonnage" curve.
plot_comparison(other[, color, ...])	Create an interactive parallel plot
plot_grade_recovery(target_analyte[, ...])	The grade-recovery plot.
plot_intervals(variables[, cumulative, ...])	Plot "The Grade-Tonnage" curve.
plot_parallel([color, vars_include, ...])	Create an interactive parallel plot
plot_ternary(variables[, color, title])	Plot a ternary diagram
query(queries)	rtype: MassComposition
rename(new_name)	rtype: MassComposition
resample_1d(interval_edges[, precision, ...])	Resample a 1D fractional dim/index
set_child_node(child)	rtype: MassComposition
set_data(data[, constraints])
set_parent_node(parent)	rtype: MassComposition
set_stream_nodes(nodes)	rtype: MassComposition
split(fraction[, name_1, name_2])	Split the object by mass
split_by_estimator(estimator[, name_1, ...])	Split an object using a sklearn estimator.
split_by_function(split_function[, name_1, ...])	Split an object using a function.
split_by_partition(partition_definition[, ...])	Partition the object along a given dimension.
sub(other[, name])	Subtract two objects
to_xarray()	Returns the mc compliant xr.Dataset
update_data(values)

Attributes

data
name

__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: MassComposition :param other: object to add to self

Returns:

Return type:

MassComposition

add(other, name=None)

Add two objects

Adds other to self, with optional name of the returned object :type other: MassComposition :param other: object to add to self :type name: Optional[str] :param name: name of the returned object

Returns:

Return type:

MassComposition

aggregate(group_var=None, group_bins=None, as_dataframe=True, original_column_names=False)

Calculate the weight average.

Parameters:

• group_var (Optional[str]) – Optional grouping variable

• group_bins (Union[int, Iterable, None]) – Optional bins to apply to the group_var

• as_dataframe (bool) – If True return a pd.DataFrame

• original_column_names (bool) – If True, and as_dataframe is True, will return with the original column names.

Return type:

Union[DataFrame, Dataset]

Returns:

binned_mass_composition(cutoff_var, bin_width, cumulative=True, direction='descending', as_dataframe=True)

A.K.A “The Grade-Tonnage” curve.

Mass and grade by bins for a cut-off variable.

Parameters:

• cutoff_var (str) – The variable that defines the bins

• bin_width (float) – The width of the bin

• cumulative (bool) – If True, the results are cumulative weight averaged.

• direction (str) – ‘ascending’|’descending’, if cumulative is True, the direction of accumulation

• as_dataframe (bool) – If True return a pd.DataFrame

Return type:

Union[Dataset, DataFrame]

Returns:

calculate_partition(ref)

Calculate the partition of the ref stream relative to self

Return type:

DataFrame

constrain(clip_mass=None, clip_composition=None, relative_mass=None, relative_composition=None, other=None)

Constrain the mass-composition

It is possible that a MassComposition object is created from a source that has improbable results. In this case this method can help improve the integrity of the mass-composition.

Parameters:

• clip_mass (Union[Tuple, Dict, None]) – Limit the minimum and maximum values of the mass between a minimum and maximum absolute value.

• clip_composition (Union[Tuple, Dict, None]) – Limit the minimum and maximum values of the composition between a minimum and maximum absolute value.

• relative_mass (Union[Tuple, Dict, None]) – Constrain the mass recovery of the object to the other object

• relative_composition (Union[Tuple, Dict, None]) – Constrain the component recovery of the object to the other object

• other (Optional[MassComposition]) – The other object used for recovery calculation. Must be provided if relative_mass or

• provided. (relative_composition are) –

Return type:

MassComposition

Returns:

Returns the new object constrained per the provided arguments.

div(other, name=None)

Divide two objects

Divides self by other, with optional name of the returned object :type other: MassComposition :param other: the denominator (or reference) object :type name: Optional[str] :param name: name of the returned object

Returns:

Return type:

MassComposition

ideal_incremental_composition(discard_from='lowest')

Incrementally separate a fractionated sample.

This method sorts by the provided direction prior to incrementally removing and discarding the first fraction

(of the remaining fractions) and recalculating the mass-composition of the portion remaining. This is equivalent to incrementally applying a perfect separation (partition) at every interval edge.

This method is only applicable to a 1D object where the single dimension is a pd.Interval type.

See also: ideal_incremental_separation, ideal_incremental_recovery.

Parameters:

discard_from (Literal['lowest', 'highest']) – Defines the discarded direction. discard_from = “lowest” will discard the lowest value first, then the next lowest, etc.

Return type:

DataFrame

Returns:

A pandas DataFrame

ideal_incremental_recovery(discard_from='lowest', apply_closure=True)

Incrementally separate a fractionated sample.

This method sorts by the provided direction prior to incrementally removing and discarding the first fraction

(of the remaining fractions) and recalculating the recovery of the portion remaining. This is equivalent to incrementally applying a perfect separation (partition) at every interval edge.

This method is only applicable to a 1D object where the single dimension is a pd.Interval type.

See also: ideal_incremental_separation, ideal_incremental_composition.

Parameters:

• discard_from (Literal['lowest', 'highest']) – Defines the discarded direction. discard_from = “lowest” will discard the lowest value first, then the next lowest, etc.

• apply_closure (bool) – If True, Add the missing record (zero recovery) that closes the recovery envelope.

Return type:

DataFrame

Returns:

A pandas DataFrame

ideal_incremental_separation(discard_from='lowest')

Incrementally separate a fractionated sample.

This method sorts by the provided direction prior to incrementally removing and discarding the first fraction

(of the remaining fractions) and recalculating the mass-composition and recovery of the portion remaining. This is equivalent to incrementally applying a perfect separation (partition) at every interval edge.

This method is only applicable to a 1D object where the single dimension is a pd.Interval type.

See also: ideal_incremental_composition, ideal_incremental_recovery.

Parameters:

discard_from (Literal['lowest', 'highest']) – Defines the discarded direction. discard_from = “lowest” will discard the lowest value first, then the next lowest, etc.

Return type:

DataFrame

Returns:

A pandas DataFrame

plot_amenability(target_analyte, discard_from='lowest', gangue_analytes=None, title=None)

The yield-recovery plot.

The yield recovery curve provides an understanding of the amenability of a sample.

This method is only applicable to a 1D object where the single dimension is a pd.Interval type.

Parameters:

• target_analyte (str) – The analyte of value.

• discard_from (Literal['lowest', 'highest']) – Defines the discarded direction. discard_from = “lowest” will discard the lowest value first, then the next lowest, etc.

• gangue_analytes (Optional[str]) – The analytes to be rejected

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

Return type:

Figure

Returns:

A plotly.GraphObjects figure

plot_bins(variables, cutoff_var, bin_width, cumulative=True, direction='descending')

Plot “The Grade-Tonnage” curve.

Mass and grade by bins for a cut-off variable.

Parameters:

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

• cutoff_var (str) – The variable that defines the bins

• bin_width (float) – The width of the bin

• cumulative (bool) – If True, the results are cumulative weight averaged.

• direction (str) – ‘ascending’|’descending’, if cumulative is True, the direction of accumulation

Return type:

Figure

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 (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_grade_recovery(target_analyte, discard_from='lowest', title=None)

The grade-recovery plot.

The grade recovery curve is generated by assuming an ideal separation (for the chosen property, or dimension) at each fractional interval. It defines the theoretical maximum performance, which can only be improved if liberation is improved by comminution.

This method is only applicable to a 1D object where the single dimension is a pd.Interval type.

Parameters:

• target_analyte – The analyte of value.

• discard_from (Literal['lowest', 'highest']) – Defines the discarded direction. discard_from = “lowest” will discard the lowest value first, then the next lowest, etc.

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

Return type:

Figure

Returns:

A plotly.GraphObjects figure

plot_intervals(variables, cumulative=True, direction='descending', show_edges=True, min_x=None)

Plot “The Grade-Tonnage” curve.

Mass and grade by bins for a cut-off variable.

Parameters:

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

• cumulative (bool) – If True, the results are cumulative weight averaged.

• direction (str) – ‘ascending’|’descending’, if cumulative is True, the direction of accumulation

• show_edges (bool) – If True, show the edges on the plot. Applicable to cumulative plots only.

• min_x (Optional[float]) – Optional minimum value for the x-axis, useful to set reasonable visual range with a log

• data (scaled x-axis when plotting size) –

Return type:

Figure

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

resample_1d(interval_edges, precision=None, include_original_edges=False)

Resample a 1D fractional dim/index

Parameters:

• interval_edges (Union[Iterable, int]) – The values of the new grid (interval edges). If an int, will up-sample by that factor, for example the value of 10 will automatically define edges that create 10 x the resolution (up-sampled).

• precision (Optional[int]) – Optional integer for the number of decimal places to round the grid values to.

• include_original_edges (bool) – If True include the original edges in the grid.

Return type:

MassComposition

Returns:

A new object interpolated onto the new grid

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

Split the object by mass

A simple mass split maintaining the same composition

See also: split_by_partition, split_by_function, split_by_estimator

Parameters:

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

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

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

Return type:

Tuple[MassComposition, MassComposition]

Returns:

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

split_by_estimator(estimator, name_1=None, name_2=None, extra_features=None, allow_prefix_mismatch=False, mass_recovery_column=None, mass_recovery_max=1.0)

Split an object using a sklearn estimator.

This method applies the function to self, resulting in two new objects. The object returned with name_1 is the result of the estimator.predict() method. The object returned with name_2 is the complement.

See also: split, split_by_function, split_by_partition

Parameters:

• estimator (PandasPipeline) – Any sklearn estimator that transforms the dataframe from a MassComposition object into a new dataframe with values representing a new (output) stream using the predict method. The returned dataframe structure must be identical to the input dataframe.

• name_1 (Optional[str]) – The name of the stream created by the estimator.

• name_2 (Optional[str]) – The name of the complement stream created by the split, which is calculated automatically.

• extra_features (Optional[DataFrame]) – Optional additional features to pass to the estimator as features.

• allow_prefix_mismatch (bool) – If True, allow feature names to be different and log an info message. If False, raise an error when feature names are different.

• mass_recovery_column (Optional[str]) – If provided, this indicates that the model has estimated mass recovery, not mass explicitly. This will execute a transformation of the predicted dry mass recovery to dry mass.

• mass_recovery_max (float) – The maximum mass recovery value, used to scale the mass recovery to mass. Only applicable if mass_recovery_column is provided. Should be either 1.0 or 100.0.

Return type:

Tuple[MassComposition, MassComposition]

Returns:

tuple of two MassComposition objects, the first the output of the estimator, the other the complement

split_by_function(split_function, name_1=None, name_2=None)

Split an object using a function.

This method applies the function to self, resulting in two new objects. The object returned with name_1 is the result of the function. The object returned with name_2 is the complement.

See also: split, split_by_estimator, split_by_partition

Parameters:

• split_function (Callable) – Any function that transforms the dataframe from a MassComposition object into a new dataframe with values representing a new (output) stream. The returned dataframe structure must be identical to the input dataframe.

• name_1 (Optional[str]) – The name of the stream created by the function

• name_2 (Optional[str]) – The name of the complement stream created by the split, which is calculated automatically.

Return type:

Tuple[MassComposition, MassComposition]

Returns:

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

split_by_partition(partition_definition, name_1=None, name_2=None)

Partition the object along a given dimension.

This method applies the defined separation resulting in two new objects.

See also: split, split_by_function, split_by_estimator

Parameters:

• partition_definition (Callable) – A partition function that defines the efficiency of separation along a dimension

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

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

Return type:

Tuple[MassComposition, MassComposition]

Returns:

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

sub(other, name=None)

Subtract two objects

Subtracts other from self, with optional name of the returned object :type other: MassComposition :param other: object to subtract from self :type name: Optional[str] :param name: name of the returned object

Returns:

Return type:

MassComposition

to_xarray()

Returns the mc compliant xr.Dataset

Returns:

Return type:

Dataset