.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "user-guide/general/customizations/examples/plot_configure_check_conditions.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

        Click :ref:`here <sphx_glr_download_user-guide_general_customizations_examples_plot_configure_check_conditions.py>`
        to download the full example code

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

.. _sphx_glr_user-guide_general_customizations_examples_plot_configure_check_conditions.py:


Configure Check Conditions
**************************

The following guide includes different options for configuring a check's condition(s):

* `Add Condition <#add-condition>`__
* `Remove / Edit a Condition <#remove-edit-a-condition>`__
* `Add a Custom Condition <#add-a-custom-condition>`__
* `Set Custom Condition Category <#set-custom-condition-category>`__

Add Condition
=============
In order to add a condition to an existing check, we can use any of the pre-defined
conditions for that check. The naming convention for the methods that add the
condition is ``add_condition_...``.

If you want to create and add your custom condition logic for parsing the check's
result value, see `Add a Custom Condition <#add-a-custom-condition>`__.

.. GENERATED FROM PYTHON SOURCE LINES 24-26

Add a condition to a new check
------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 26-32

.. code-block:: default


    from deepchecks.tabular.checks import DatasetsSizeComparison

    check = DatasetsSizeComparison().add_condition_test_size_not_smaller_than(1000)
    check





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    DatasetsSizeComparison
    	Conditions:
    		0: Test dataset size is not smaller than 1000



.. GENERATED FROM PYTHON SOURCE LINES 33-37

Conditions are used mainly in the context of a Suite, and displayed in the
Conditions Summary table. For example how to run in a suite you can look at
`Add a Custom Condition <#add-a-custom-condition>`__ or if you would like to
run the conditions outside of suite you can execute:

.. GENERATED FROM PYTHON SOURCE LINES 37-49

.. code-block:: default


    import pandas as pd

    from deepchecks.tabular import Dataset

    # Dummy data
    train_dataset = Dataset(pd.DataFrame(data={'x': [1,2,3,4,5,6,7,8,9]}))
    test_dataset = Dataset(pd.DataFrame(data={'x': [1,2,3]}))

    condition_results = check.conditions_decision(check.run(train_dataset, test_dataset))
    condition_results





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    [{'details': 'Test dataset size is 3', 'category': <ConditionCategory.FAIL: 'FAIL'>, 'name': 'Test dataset size is not smaller than 1000'}]



.. GENERATED FROM PYTHON SOURCE LINES 50-60

Add a condition to a check in a suite
-------------------------------------
If we want to add a conditon to a check within an existing suite, we should first
find the Check's ID within the suite, and then add the condition to it, by running
the relevant ``add_condition_`` method on that check's instance. See the next section
to understand how to do so.

The condition will then be appended to the list of conditions on that check (or be
the first one if no conditions are defined), and each condition will be evaluated
separately when running the suite.

.. GENERATED FROM PYTHON SOURCE LINES 62-70

Remove / Edit a Condition
=========================
Deepchecks provides different kinds of default suites, which come with pre-defined
conditions. You may want to remove a condition in case it isn't needed for you, or
you may want to change the condition's parameters (since conditions functions are immutable).

To remove a condition, start by printing the Suite and identifing the Check's ID,
and the Condition's ID:

.. GENERATED FROM PYTHON SOURCE LINES 70-76

.. code-block:: default


    from deepchecks.tabular.suites import train_test_leakage

    suite = train_test_leakage()
    suite





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Train Test Leakage Suite: [
    	0: DateTrainTestLeakageDuplicates
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	1: DateTrainTestLeakageOverlap
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	2: SingleFeatureContributionTrainTest(ppscore_params={})
    		Conditions:
    			0: Train-Test features' Predictive Power Score difference is not greater than 0.2
    			1: Train features' Predictive Power Score is not greater than 0.7
    	3: TrainTestSamplesMix
    		Conditions:
    			0: Percentage of test data samples that appear in train data not greater than 10%
    	4: IdentifierLeakage(ppscore_params={})
    		Conditions:
    			0: Identifier columns PPS is not greater than 0
    	5: IndexTrainTestLeakage
    		Conditions:
    			0: Ratio of leaking indices is not greater than 0%
    ]



.. GENERATED FROM PYTHON SOURCE LINES 77-78

After we found the IDs we can remove the Condition:

.. GENERATED FROM PYTHON SOURCE LINES 78-86

.. code-block:: default


    # Access check by id
    check = suite[2]
    # Remove condition by id
    check.remove_condition(0)

    suite





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Train Test Leakage Suite: [
    	0: DateTrainTestLeakageDuplicates
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	1: DateTrainTestLeakageOverlap
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	2: SingleFeatureContributionTrainTest(ppscore_params={})
    		Conditions:
    			1: Train features' Predictive Power Score is not greater than 0.7
    	3: TrainTestSamplesMix
    		Conditions:
    			0: Percentage of test data samples that appear in train data not greater than 10%
    	4: IdentifierLeakage(ppscore_params={})
    		Conditions:
    			0: Identifier columns PPS is not greater than 0
    	5: IndexTrainTestLeakage
    		Conditions:
    			0: Ratio of leaking indices is not greater than 0%
    ]



.. GENERATED FROM PYTHON SOURCE LINES 87-89

Now if we want we can also re-add the Condition using the built-in methods on the check,
with a different parameter.

.. GENERATED FROM PYTHON SOURCE LINES 89-95

.. code-block:: default


    # Re-add the condition with new parameter
    check.add_condition_feature_pps_difference_not_greater_than(0.01)

    suite





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    Train Test Leakage Suite: [
    	0: DateTrainTestLeakageDuplicates
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	1: DateTrainTestLeakageOverlap
    		Conditions:
    			0: Date leakage ratio is not greater than 0%
    	2: SingleFeatureContributionTrainTest(ppscore_params={})
    		Conditions:
    			1: Train features' Predictive Power Score is not greater than 0.7
    			2: Train-Test features' Predictive Power Score difference is not greater than 0.01
    	3: TrainTestSamplesMix
    		Conditions:
    			0: Percentage of test data samples that appear in train data not greater than 10%
    	4: IdentifierLeakage(ppscore_params={})
    		Conditions:
    			0: Identifier columns PPS is not greater than 0
    	5: IndexTrainTestLeakage
    		Conditions:
    			0: Ratio of leaking indices is not greater than 0%
    ]



.. GENERATED FROM PYTHON SOURCE LINES 96-102

Add a Custom Condition
======================
In order to write conditions we first have to know what value a given check produces.

Let's look at the check ``DatasetsSizeComparison`` and see it's return value in
order to write a condition for it.

.. GENERATED FROM PYTHON SOURCE LINES 102-115

.. code-block:: default


    import pandas as pd

    from deepchecks.tabular import Dataset
    from deepchecks.tabular.checks import DatasetsSizeComparison

    # We'll use dummy data for the purpose of this demonstration
    train_dataset = Dataset(pd.DataFrame(data={'x': [1,2,3,4,5,6,7,8,9]}))
    test_dataset = Dataset(pd.DataFrame(data={'x': [1,2,3]}))

    result = DatasetsSizeComparison().run(train_dataset, test_dataset)
    result.value





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none


    {'Train': 9, 'Test': 3}



.. GENERATED FROM PYTHON SOURCE LINES 116-126

Now we know what the return value looks like. Let's add a new condition that validates
that the ratio between the train and test datasets size is inside a given range. To
create condition we need to use the ``add_condition`` method of the check which accepts
a condition name and a function. This function receives the value of the ``CheckResult``
that we saw above and should return either a boolean or a ``ConditionResult`` containing
a boolean and optional extra info that will be displayed in the Conditions Summary table.

*Note: When implementing a condition in a custom check, you may want to add a method
``add_condition_x()`` to allow any consumer of your check to apply the condition
(possibly with given parameters). For examples look at implemented Checks' source code*

.. GENERATED FROM PYTHON SOURCE LINES 126-148

.. code-block:: default


    from deepchecks.core import ConditionResult

    # Our parameters for the condition
    low_threshold = 0.4
    high_threshold = 0.6

    # Create the condition function
    def custom_condition(value: dict, low=low_threshold, high=high_threshold): 
        ratio = value['Test'] / value['Train']
        if low <= ratio <= high:
            return ConditionResult(ConditionCategory.PASS)
        else:
            # Note: if you doesn't care about the extra info, you can return directly a boolean
            return ConditionResult(ConditionCategory.FAIL, f'Test-Train ratio is {ratio:.2}')

    # Create the condition name
    condition_name = f'Test-Train ratio is between {low_threshold} to {high_threshold}'

    # Create check instance with the condition 
    check = DatasetsSizeComparison().add_condition(condition_name, custom_condition)








.. GENERATED FROM PYTHON SOURCE LINES 149-152

Now we will use a Suite to demonstrate the action of the condition, since the suite
runs the condition for us automatically and prints out a Conditions Summary table
(for all the conditions defined on the checks within the suite):

.. GENERATED FROM PYTHON SOURCE LINES 152-162

.. code-block:: default


    from deepchecks import Suite

    # Using suite to run check & condition
    suite = Suite('Suite for Condition',
        check
    )

    suite.run(train_dataset, test_dataset)





.. rst-class:: sphx-glr-script-out

 Out:

 .. code-block:: none

    Ability to import base tabular functionality from the `deepchecks` package directly is deprecated, please import from `deepchecks.tabular` instead

    Suite for Condition:   0%| | 0/1 [00:00<?, ? Check/s]
    Suite for Condition:   0%| | 0/1 [00:00<?, ? Check/s, Check=Datasets Size Comparison]
                                                                                     

.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">

    <script
        src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"
        integrity="sha512-c3Nl8+7g4LMSTdrm621y7kf9v3SDPnhxLNhcjFJbKECVnmZHTdo+IRO05sNLTH/D3vA6u1X32ehoLC7WFVdheg=="
        crossorigin="anonymous"
        referrerpolicy="no-referrer">
    </script>

    <script type="text/javascript">window.PlotlyConfig = {MathJaxConfig: 'local'};</script>
    <script type="text/javascript">if (window.MathJax) {MathJax.Hub.Config({SVG: {font: "STIX-Web"}});}</script>
    <script type="text/javascript">
        if (typeof require !== 'undefined') {
            require.undef("plotly");
            requirejs.config({
                paths: {'plotly': ['https://cdn.plot.ly/plotly-2.8.3.min']}
            });
            require(
                ['plotly'],
                function(Plotly) {
                    window._Plotly = Plotly;
                    window.Plotly = Plotly;
                    console.log('Loaded plotly successfully');
                },
                function() {console.log('Failed to load plotly')}
            );
        } else {
            console.log('requirejs is not present');
        }
    </script>

                <h1 id="summary_091C795RLQIOB0NLW0VS52SQ3">Suite for Condition</h1>
                <p>
                    The suite is composed of the following checks: Datasets Size Comparison.<br>
                    Each check may contain conditions (which will result in pass / fail / warning / error
                    , represented by 
    <span style="color: green;display:inline-block">✓</span> /
    <span style="color: red;display:inline-block">✖</span> /
    <span style="color: orange;font-weight:bold;display:inline-block">!</span> /
    <span style="color: firebrick;font-weight:bold;display:inline-block">⁈</span>
    ) as well as other outputs such as plots or tables.<br>
                    Suites, checks and conditions can all be modified. Read more about
                    <a href=https://docs.deepchecks.com/en/stable/examples/guides/create_a_custom_suite.html?utm_source=display_output&utm_medium=referral&utm_campaign=suite_link target="_blank">custom suites</a>.
                </p>

    <hr style="background-color: black;border: 0 none;color: black;height: 1px;"><h2>Conditions Summary</h2><style type="text/css">
    #T_f6ea7 table {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_f6ea7 thead {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_f6ea7 tbody {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_f6ea7 th {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_f6ea7 td {
      text-align: left;
      white-space: pre-wrap;
    }
    </style>
    <table id="T_f6ea7">
      <thead>
        <tr>
          <th id="T_f6ea7_level0_col0" class="col_heading level0 col0" >Status</th>
          <th id="T_f6ea7_level0_col1" class="col_heading level0 col1" >Check</th>
          <th id="T_f6ea7_level0_col2" class="col_heading level0 col2" >Condition</th>
          <th id="T_f6ea7_level0_col3" class="col_heading level0 col3" >More Info</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td id="T_f6ea7_row0_col0" class="data row0 col0" ><div style="color: firebrick;text-align: center;font-weight:bold">⁈</div></td>
          <td id="T_f6ea7_row0_col1" class="data row0 col1" ><a href=#DatasetsSizeComparison_091C795RLQIOB0NLW0VS52SQ3>Datasets Size Comparison</a></td>
          <td id="T_f6ea7_row0_col2" class="data row0 col2" >Test-Train ratio is between 0.4 to 0.6</td>
          <td id="T_f6ea7_row0_col3" class="data row0 col3" >Exception in condition: NameError: name 'ConditionCategory' is not defined</td>
        </tr>
      </tbody>
    </table>
    <hr style="background-color: black;border: 0 none;color: black;height: 1px;"><h2>Check With Conditions Output</h2><h4 id="DatasetsSizeComparison_091C795RLQIOB0NLW0VS52SQ3"><b>Datasets Size Comparison</b></h4><p>Verify test dataset size comparing it to the train dataset size.</p><h5><b>Conditions Summary</b></h5><style type="text/css">
    #T_6b194 table {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_6b194 thead {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_6b194 tbody {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_6b194 th {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_6b194 td {
      text-align: left;
      white-space: pre-wrap;
    }
    </style>
    <table id="T_6b194">
      <thead>
        <tr>
          <th id="T_6b194_level0_col0" class="col_heading level0 col0" >Status</th>
          <th id="T_6b194_level0_col1" class="col_heading level0 col1" >Condition</th>
          <th id="T_6b194_level0_col2" class="col_heading level0 col2" >More Info</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td id="T_6b194_row0_col0" class="data row0 col0" ><div style="color: firebrick;text-align: center;font-weight:bold">⁈</div></td>
          <td id="T_6b194_row0_col1" class="data row0 col1" >Test-Train ratio is between 0.4 to 0.6</td>
          <td id="T_6b194_row0_col2" class="data row0 col2" >Exception in condition: NameError: name 'ConditionCategory' is not defined</td>
        </tr>
      </tbody>
    </table>
    <h5><b>Additional Outputs</b></h5><style type="text/css">
    #T_400e1 table {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_400e1 thead {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_400e1 tbody {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_400e1 th {
      text-align: left;
      white-space: pre-wrap;
    }
    #T_400e1 td {
      text-align: left;
      white-space: pre-wrap;
    }
    </style>
    <table id="T_400e1">
      <thead>
        <tr>
          <th class="blank level0" >&nbsp;</th>
          <th id="T_400e1_level0_col0" class="col_heading level0 col0" >Train</th>
          <th id="T_400e1_level0_col1" class="col_heading level0 col1" >Test</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th id="T_400e1_level0_row0" class="row_heading level0 row0" >Size</th>
          <td id="T_400e1_row0_col0" class="data row0 col0" >9</td>
          <td id="T_400e1_row0_col1" class="data row0 col1" >3</td>
        </tr>
      </tbody>
    </table>
    <br><a href="#summary_091C795RLQIOB0NLW0VS52SQ3" style="font-size: 14px">Go to top</a><hr style="background-color: black;border: 0 none;color: black;height: 1px;"><h2>Check Without Conditions Output</h2><br><a href="#summary_091C795RLQIOB0NLW0VS52SQ3" style="font-size: 14px">Go to top</a>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 163-168

Set Custom Condition Category
=============================
When writing your own condition logic, you can decide to mark a condition result
as either fail or warn, by passing the category to the ConditionResult object.
For example we can even write condition which sets the category based on severity of the result:

.. GENERATED FROM PYTHON SOURCE LINES 168-184

.. code-block:: default


    from deepchecks.core import ConditionCategory, ConditionResult

    # Our parameters for the condition
    low_threshold = 0.3
    high_threshold = 0.7

    # Create the condition function for check `DatasetsSizeComparison`
    def custom_condition(value: dict): 
        ratio = value['Test'] / value['Train']
        if low_threshold <= ratio <= high_threshold:
            return ConditionResult(ConditionCategory.PASS)
        elif ratio < low_threshold:
            return ConditionResult(ConditionCategory.FAIL, f'Test-Train ratio is {ratio:.2}', ConditionCategory.FAIL)
        else:
            return ConditionResult(ConditionCategory.FAIL, f'Test-Train ratio is {ratio:.2}', ConditionCategory.WARN)








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

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


.. _sphx_glr_download_user-guide_general_customizations_examples_plot_configure_check_conditions.py:


.. only :: html

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



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

     :download:`Download Python source code: plot_configure_check_conditions.py <plot_configure_check_conditions.py>`



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

     :download:`Download Jupyter notebook: plot_configure_check_conditions.ipynb <plot_configure_check_conditions.ipynb>`


.. only:: html

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

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