.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/003_constrain.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        Click :ref:`here <sphx_glr_download_auto_examples_003_constrain.py>`
        to download the full example code

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_003_constrain.py:


Constrain
=========

A simple example that demonstrates the constrain method of mass-composition.

It is possible that a MassComposition object is created from a Machine Learning Model estimation.
If either the ML model is over-fitted, or the features supplied to create the estimation are out of range,
improbable results can be generated. The constrain method will provide a way to manage these outliers.

.. GENERATED FROM PYTHON SOURCE LINES 12-18

.. code-block:: default


    import pandas as pd

    from elphick.mass_composition import MassComposition
    from elphick.mass_composition.datasets.sample_data import sample_data








.. GENERATED FROM PYTHON SOURCE LINES 19-23

Create a MassComposition object
-------------------------------

We get some demo data in the form of a pandas DataFrame

.. GENERATED FROM PYTHON SOURCE LINES 24-28

.. code-block:: default


    df_data: pd.DataFrame = sample_data()
    df_data






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>wet_mass</th>
          <th>mass_dry</th>
          <th>FE</th>
          <th>SIO2</th>
          <th>al2o3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>57.0</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>80.0</td>
          <td>59.0</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>110.0</td>
          <td>90.0</td>
          <td>61.0</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 29-30

Construct a MassComposition object

.. GENERATED FROM PYTHON SOURCE LINES 30-34

.. code-block:: default


    obj_mc: MassComposition = MassComposition(df_data)
    obj_mc.data.to_dataframe()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>57.0</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>80.0</td>
          <td>11.111111</td>
          <td>59.0</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>110.0</td>
          <td>90.0</td>
          <td>18.181818</td>
          <td>61.0</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 35-40

Constraining by Clip
--------------------

Constraining by clip simpy clips the mass or composition values.  The simplest way to constrain is with
a tuple of the limits.

.. GENERATED FROM PYTHON SOURCE LINES 41-46

.. code-block:: default



    obj_1: MassComposition = obj_mc.constrain(clip_mass=(85, 100))
    obj_1.data.to_dataframe()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>57.0</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>85.0</td>
          <td>5.555556</td>
          <td>59.0</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>61.0</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 47-50

Notice that the mass has been constrained for some records and the H2O has been modified accordingly.

More granularity is possible by passing a dict[variable: tuple_of_limits]

.. GENERATED FROM PYTHON SOURCE LINES 52-55

.. code-block:: default

    obj_2: MassComposition = obj_mc.constrain(clip_mass={'mass_wet': (0, 100)})
    obj_2.data.to_dataframe()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>57.0</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>80.0</td>
          <td>11.111111</td>
          <td>59.0</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>61.0</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 56-64

Constraining Relative to Another Object
---------------------------------------

Sometimes constraining relative to another object is useful.  This can be described as "constraining by recovery".
The object is converted to absolute mass (where components are converted to mass units) and divided by the
reference (other) object, also converted to mass units.  In mineral processing, this is known as recovery.

First we'll make another object to act as our reference.

.. GENERATED FROM PYTHON SOURCE LINES 67-72

.. code-block:: default

    obj_other: MassComposition = obj_mc.add(obj_mc, name='feed')

    obj_3: MassComposition = obj_mc.constrain(relative_mass=(0.0, 0.1), other=obj_other)
    obj_3.data.to_dataframe()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>20.0</td>
          <td>18.0</td>
          <td>10.000000</td>
          <td>57.0</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>18.0</td>
          <td>16.0</td>
          <td>11.111111</td>
          <td>59.0</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>22.0</td>
          <td>18.0</td>
          <td>18.181818</td>
          <td>61.0</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 73-74

Here we constrain Fe to 10% recovery of 2 x the original object...

.. GENERATED FROM PYTHON SOURCE LINES 74-78

.. code-block:: default


    obj_4: MassComposition = obj_mc.constrain(relative_composition={'Fe': (0.0, 0.1)}, other=obj_other)
    obj_4.data.to_dataframe()






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>11.4</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>80.0</td>
          <td>11.111111</td>
          <td>11.8</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>110.0</td>
          <td>90.0</td>
          <td>18.181818</td>
          <td>12.2</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 79-80

Arguments can be combined to perform multiple constraints in one call.

.. GENERATED FROM PYTHON SOURCE LINES 80-84

.. code-block:: default


    obj_5: MassComposition = obj_mc.constrain(clip_mass=(85, 100),
                                              relative_composition={'Fe': (0.0, 0.1)}, other=obj_other)
    obj_5.data.to_dataframe()





.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }

        .dataframe tbody tr th {
            vertical-align: top;
        }

        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th>mass_wet</th>
          <th>mass_dry</th>
          <th>H2O</th>
          <th>Fe</th>
          <th>SiO2</th>
          <th>Al2O3</th>
          <th>LOI</th>
          <th>group</th>
        </tr>
        <tr>
          <th>index</th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>100.0</td>
          <td>90.0</td>
          <td>10.000000</td>
          <td>11.4</td>
          <td>5.2</td>
          <td>3.0</td>
          <td>5.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>1</th>
          <td>90.0</td>
          <td>80.0</td>
          <td>11.111111</td>
          <td>11.8</td>
          <td>3.1</td>
          <td>1.7</td>
          <td>4.0</td>
          <td>grp_1</td>
        </tr>
        <tr>
          <th>2</th>
          <td>110.0</td>
          <td>90.0</td>
          <td>18.181818</td>
          <td>12.2</td>
          <td>2.2</td>
          <td>0.9</td>
          <td>3.0</td>
          <td>grp_2</td>
        </tr>
      </tbody>
    </table>
    </div>
    </div>
    <br />
    <br />


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** ( 0 minutes  0.260 seconds)


.. _sphx_glr_download_auto_examples_003_constrain.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example


    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 003_constrain.py <003_constrain.py>`

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 003_constrain.ipynb <003_constrain.ipynb>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_