### End-to-End Example with XGBoost

Source: https://context7.com/linkedin/te2rules/llms.txt

Demonstrates training an XGBoost classifier and then using ModelExplainer to explain its predictions. Requires loading data, training the model, and then initializing and running the explainer.

```python
import numpy as np
import pandas as pd
from xgboost import XGBClassifier
from te2rules.explainer import ModelExplainer

# Load data
data_train = pd.read_csv("data/adult/train.csv")
data_test  = pd.read_csv("data/adult/test.csv")
feature_names = list(data_train.columns)[:-1]

x_train = data_train[feature_names].to_numpy()
y_train = data_train.iloc[:, -1].to_numpy()
x_test  = data_test[feature_names].to_numpy()
y_test  = data_test.iloc[:, -1].to_numpy()

# Train XGBoost binary classifier
model = XGBClassifier(n_estimators=10, max_depth=3, random_state=42, eval_metric="logloss")
model.fit(x_train, y_train)

y_train_pred = model.predict(x_train)
y_test_pred  = model.predict(x_test)

# Explain
explainer = ModelExplainer(model=model, feature_names=feature_names)
rules = explainer.explain(X=x_train, y=y_train_pred, num_stages=2, min_precision=0.95)
```

--------------------------------

### Install TE2Rules Package

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Install the TE2Rules package using pip. This command fetches and installs the latest version from PyPI.

```bash
pip install te2rules
```

--------------------------------

### Local Instance-Level Explanations

Source: https://context7.com/linkedin/te2rules/llms.txt

Get a list of all rules that individually explain a positive prediction for each instance. Returns an empty list for negative instances. Set explore_all_rules=False to use only the compact rule set from explain().

```python
# Get local explanations for every test instance
explanations = model_explainer.explain_instance_with_rules(
    X=x_test,
    explore_all_rules=True   # False restricts to compact rule set
)

# Display explanations for a selection of positively predicted instances
for idx in range(len(x_test)):
    if y_test_pred[idx] == 1 and len(explanations[idx]) > 0:
        print(f"\nInstance {idx}:")
        instance_df = pd.DataFrame([x_test[idx]], columns=feature_names)
        print(instance_df.to_string(index=False))
        print("Possible reasons for positive prediction:")
        for j, rule in enumerate(explanations[idx]):
            print(f"  Reason {j+1}: {rule}")
        print("-" * 60)
        if idx > 5:   # show only first few positives
            break
```

--------------------------------

### Import Libraries for TE2Rules and XGBoost

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Imports necessary libraries including numpy, pandas, scikit-learn, and xgboost for model training and explanation. Ensure TE2Rules is installed.

```python
import numpy as np
import pandas as pd
from sklearn import metrics

# TE2Rules supports tree ensemble models from scikit-learn and xgboost   
from sklearn.ensemble import GradientBoostingClassifier
from xgboost import XGBClassifier

import te2rules
from te2rules.explainer import ModelExplainer

print("Using te2rules version: " + str(te2rules.__version__))
```

--------------------------------

### Calculate Model Fidelity

Source: https://context7.com/linkedin/te2rules/llms.txt

Get fidelity scores for training and test data. For test data, pass model predictions, not ground truth.

```python
fidelity, pos_fidelity, neg_fidelity = model_explainer.get_fidelity()
print(f"Train  — Overall: {fidelity:.2%}, Positives: {pos_fidelity:.2%}, Negatives: {neg_fidelity:.2%}")
```

```python
y_test_pred = model.predict(x_test)
fidelity_t, pos_fidelity_t, neg_fidelity_t = model_explainer.get_fidelity(
    X=x_test, y=y_test_pred
)
print(f"Test   — Overall: {fidelity_t:.2%}, Positives: {pos_fidelity_t:.2%}, Negatives: {neg_fidelity_t:.2%}")
```

--------------------------------

### Show All Explaining Rules for an Instance

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Use explain_instance_with_rules to display all rules that can explain a specific input instance. This provides flexibility for domain experts to select the most suitable rule.

```python
all_rules_for_instance = explainer.explain_instance_with_rules(X_test.iloc[0], positive_class_prediction=1)
print(all_rules_for_instance.rules)
```

--------------------------------

### Explain Instance with Rules

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Generates explanations for a given test set using the model explainer.

```python
from util import display_input

explanations = model_explainer.explain_instance_with_rules(x_test)
```

--------------------------------

### Initialize ModelExplainer

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Initialize the ModelExplainer with a trained model and feature names to prepare for rule extraction.

```python
>>> from te2rules.explainer import ModelExplainer
>>> model_explainer = ModelExplainer(model=model, feature_names=feature_names)
```

--------------------------------

### Retrieve All Possible Explanations

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Accesses and prints all possible rules found by TE2Rules, which can be used by domain experts to select a subset that aligns with their knowledge.

```python
rules = model_explainer.longer_rules
print(str(len(rules)) + " rules found:")
print()

for i in range(len(rules)):
    print("Rule " + str(i) + ": " + str(rules[i]))
```

--------------------------------

### Retrieve All Possible Explanations

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Obtain all possible explanations from the tree ensemble model, not just the subset selected by default. This allows domain experts to choose rules that align with their decision-making process.

```python
longer_rules = explainer.longer_rules(X_test.iloc[0], positive_class_prediction=1)
print(longer_rules.rules)
```

--------------------------------

### ModelExplainer Initialization

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Initialize the explainer with the trained tree ensemble model and feature names used by the model.

```APIDOC
## te2rules.explainer.ModelExplainer.__init__

### Description
Initialize the explainer with the trained tree ensemble model and feature names used by the model.

Returns a ModelExplainer object

### Parameters
#### Parameters
- **model** (*sklearn.ensemble.GradientBoostingClassifier* *or* *sklearn.ensemble.RandomForestClassifier* *or* *xgboost.XGBClassifier*) – The trained Tree Ensemble model to be explained.
  The model is expected to be a binary classifier.
- **feature_name** (*List* *[**str* *]*) – List of feature names used by the model. Only alphanumeric characters and
  underscores are allowed in feature names.
- **verbose** (*bool* *,* *optional*) – Optional boolean value to give more insights on the running of the
  explanation algorithm.
  Default = False

### Returns
- **self** – A ModelExplainer object initialized with the model to be explained.

### Return type
te2rules.explainer.ModelExplainer

### Raises
- **ValueError:** – when model is not a supported Tree Ensemble Model.
      Currently, only scikit-learn’s GradientBoostingClassifier,
      RandomForestClassifier and xgboost’s XGBClassifier are supported.
- **ValueError:** – when feature_name list contains a name that has any character other
      than alphanumeric characters or underscore.
```

--------------------------------

### Generate Data Preparation Script

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Use this script to generate the preprocessed data if it's not available. Ensure Python 3 is used.

```python
python3 data_prep/data_prep_adult.py
```

--------------------------------

### Import TE2Rules and Libraries

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Import the TE2Rules library and other necessary libraries for data analysis and model explanation.

```python
import te2rules
import pandas as pd
import xgboost
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
from te2rules.model_explainer import ModelExplainer
```

--------------------------------

### Run TE2Rules Demo Scripts

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Execute these Python scripts to generate results for the TE2Rules paper. Ensure you are in the correct directory.

```bash
python3 demo/demo/run_te2rules.py
```

```bash
python3 demo/demo/run_defrag.py
```

```bash
python3 demo/demo/run_intrees.py
```

```bash
python3 plot_performance.py
```

```bash
python3 plot_scalability.py
```

--------------------------------

### Prepare Data for Model Training

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Separates features and labels from the loaded training and testing data, converting them into NumPy arrays for model compatibility.

```python
cols = list(data_train.columns)
feature_names = cols[:-1]
label_name = cols[-1]

data_train = data_train.to_numpy()
data_test = data_test.to_numpy()
```

```python
x_train = data_train[:, :-1]
y_train = data_train[:, -1]

x_test = data_test[:, :-1]
y_test = data_test[:, -1]
```

--------------------------------

### ModelExplainer.explain_instance_with_rules

Source: https://context7.com/linkedin/te2rules/llms.txt

Provides local, instance-level explanations by returning all rules that individually explain a positive class prediction for each instance in X. Returns an empty list for negatively classified instances.

```APIDOC
## ModelExplainer.explain_instance_with_rules

### Description
Returns, for each instance in `X`, a list of all rules that individually explain why the model assigned it to the positive class. Instances classified as negative return an empty list. When `explore_all_rules=True` (default) all discovered rules are considered; set to `False` to restrict to the compact set returned by `explain()`.

### Method
`explain_instance_with_rules(X, explore_all_rules=True)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **X** (numpy.ndarray or pandas.DataFrame) - Required - The input data for which to generate explanations.
- **explore_all_rules** (bool) - Optional - Defaults to `True`. If `True`, considers all discovered rules. If `False`, restricts to the compact set returned by `explain()`.

### Request Example
```python
# Get local explanations for every test instance
explanations = model_explainer.explain_instance_with_rules(
    X=x_test,
    explore_all_rules=True   # False restricts to compact rule set
)
```

### Response
#### Success Response (200)
- **explanations** (list of lists of strings) - A list where each element corresponds to an instance in `X`. Each inner list contains strings representing the rules that explain the positive prediction for that instance.

#### Response Example
```
# Example output for a single instance:
# ['capital_gain > 5095 & education_num > 12', 'age > 42 & hours_per_week > 45 & education_num > 12']
```
```

--------------------------------

### Initialize ModelExplainer

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Instantiate the ModelExplainer with a trained tree ensemble model and its feature names. Ensure the model is a binary classifier and feature names are alphanumeric.

```python
from te2rules.explainer import ModelExplainer

# Assuming 'model' is a trained sklearn or XGBoost binary classifier
# and 'feature_names' is a list of strings
explainer = ModelExplainer(model, feature_names)
```

--------------------------------

### Initialize ModelExplainer

Source: https://context7.com/linkedin/te2rules/llms.txt

Initialize the ModelExplainer with a trained binary classification tree ensemble model and feature names. Ensure feature names are alphanumeric with underscores. Supported models include GradientBoostingClassifier, RandomForestClassifier, and XGBClassifier.

```python
import numpy as np
import pandas as pd
from sklearn.ensemble import GradientBoostingClassifier
from xgboost import XGBClassifier
from te2rules.explainer import ModelExplainer

# Load preprocessed binary classification data
data_train = pd.read_csv("data/adult/train.csv")
data_test  = pd.read_csv("data/adult/test.csv")

cols          = list(data_train.columns)
feature_names = cols[:-1]   # must be alphanumeric + underscores only
label_name    = cols[-1]

x_train = data_train[feature_names].to_numpy()
y_train = data_train[label_name].to_numpy()
x_test  = data_test[feature_names].to_numpy()
y_test  = data_test[label_name].to_numpy()

# Train a GradientBoosting model (XGBClassifier also supported)
model = GradientBoostingClassifier(n_estimators=10, max_depth=3, random_state=42)
model.fit(x_train, y_train)

y_train_pred = model.predict(x_train)  # binary 0/1 predictions fed to explainer

# Initialize the explainer — raises ValueError for unsupported models
# or feature names containing special characters
model_explainer = ModelExplainer(
    model=model,
    feature_names=feature_names,
    verbose=False   # set True for stage-by-stage debug logging
)
```

--------------------------------

### ModelExplainer Initialization

Source: https://context7.com/linkedin/te2rules/llms.txt

Initializes the ModelExplainer class, which wraps a trained binary-classification tree ensemble. Supported models include scikit-learn's GradientBoostingClassifier, RandomForestClassifier, and xgboost's XGBClassifier. Feature names must be alphanumeric with underscores.

```APIDOC
## ModelExplainer(model, feature_names, verbose=False)

### Description
Wraps a trained binary-classification tree ensemble. Supported model types are `sklearn.ensemble.GradientBoostingClassifier`, `sklearn.ensemble.RandomForestClassifier`, and `xgboost.XGBClassifier`. Feature names must contain only alphanumeric characters and underscores.

### Parameters
- **model** (object) - Required - The trained tree ensemble model.
- **feature_names** (list of str) - Required - A list of feature names.
- **verbose** (bool) - Optional - Set to True for stage-by-stage debug logging. Defaults to False.

### Request Example
```python
from te2rules.explainer import ModelExplainer
from sklearn.ensemble import GradientBoostingClassifier

# Assuming model and feature_names are already defined
model_explainer = ModelExplainer(model=model, feature_names=feature_names, verbose=False)
```
```

--------------------------------

### te2rules.explainer.ModelExplainer.explain_instance_with_rules

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Explains model output for a list of inputs using extracted rules. Returns a list of rules that explain each positive prediction, or an empty list for negative predictions.

```APIDOC
## te2rules.explainer.ModelExplainer.explain_instance_with_rules

### Description
A method to explain the model output for a list of inputs using rules. For each instance in the list, if the model output is positive, this method returns a corresponding list of rules that explain that instance. For any instance in the list, for which the model output is negative, this method returns an empty list corresponding to that instance.

Returns a list of explanations corresponding to each input. Each explanation is a list of possible rules that can explain the corresponding instance.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **X** (*2d numpy.array*) – 2 dimensional data with feature values that can be sent to the model for predicting outcome.
* **explore_all_rules** (*boolean* *,* *optional*) – optional boolean variable guiding the algorithm’s behavior. When set to True, the algorithm considers all possible rules (longer_rules) extracted by the explain() function before employing set cover to select a condensed subset of rules. When set to False, the algorithm considers only the condensed subset of rules returned by explain(). By default, the function utilizes all possible rules (longer_rules) obtained through explain().

### Returns
*list of explaining rules for each instance, with each explanation presented as a list of rules each of which can independently explain the instance.*

### Request Example
```python
model_explainer.explain_instance_with_rules(X=x_train, explore_all_rules=True)
```

### Response
#### Success Response (200)
- **fidelity** (float) - Fidelity is the fraction of data for which the rule list agrees with the tree ensemble. Returns the fidelity on overall data, positive predictions and negative predictions by the model.

#### Response Example
```json
{
  "example": "[[rule1, rule2], [], [rule3]]"
}
```
```

--------------------------------

### Display Local Explanations

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Iterates through test data to display local explanations for instances with positive model predictions. Requires `display_input` function and pre-computed `y_test_pred` and `explanations`.

```python
print("Local Explanations of a particular model decision")
print()
for i in range(140, 155):
    if(y_test_pred[i] == 1):
        print("Index:", i)
        print()
        print("Model Input:")
        display_input(x_test[i], feature_names)
        print()
        print("Model Prediction:", y_test_pred[i])
        print()
        print("Possible Reasons:")
        rules = explanations[i]
        for j in range(len(rules)):
            print("Rule", j+1, ":", rules[j])   
        print("--------------------------------")
```

--------------------------------

### Initialize TE2Rules Model Explainer

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Initializes the ModelExplainer from TE2Rules with the trained model and feature names. This object is used for rule extraction.

```python
model_explainer = ModelExplainer(
    model=model, 
    feature_names=feature_names
)
```

--------------------------------

### Train XGBoost Model

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Trains a Gradient Boosting Classifier model using scikit-learn. An alternative XGBoost model training is commented out.

```python
# Scikit-Learn Model
model = GradientBoostingClassifier(n_estimators=10, max_depth=3)
model.fit(x_train, y_train)

# XGBoost Model
# model = XGBClassifier(n_estimators=10, max_depth=3)
# model.fit(x_train, y_train)
```

--------------------------------

### ModelExplainer.explain

Source: https://context7.com/linkedin/te2rules/llms.txt

Extracts a compact list of human-readable rule strings that cover the model's positive-class predictions. This method uses the Apriori algorithm and returns a minimal greedy set-cover subset of rules.

```APIDOC
## ModelExplainer.explain(X, y, num_stages=None, min_precision=0.95, jaccard_threshold=0.20)

### Description
Runs the TE2Rules Apriori algorithm to return a compact list of human-readable rule strings that cover the model's positive-class predictions. `X` and `y` are the training features and the model's own binary predictions. The returned list is the minimal greedy set-cover subset; `model_explainer.longer_rules` holds the full set of all discovered rules.

### Parameters
- **X** (numpy.ndarray or pandas.DataFrame) - Required - Training features.
- **y** (numpy.ndarray) - Required - Model's binary predictions (0/1).
- **num_stages** (int) - Optional - Number of stages to run the algorithm. Fewer stages result in faster execution and shorter rules. Defaults to the number of estimators in the model.
- **min_precision** (float) - Optional - Minimum fraction of positives a rule must cover correctly. Defaults to 0.95.
- **jaccard_threshold** (float) - Optional - Controls the trade-off between speed and rule discovery. Lower values may miss some rules. Defaults to 0.20.

### Response
- **rules** (list of str) - A list of human-readable rule strings.

### Request Example
```python
# Assuming model_explainer, x_train, and y_train_pred are defined
rules = model_explainer.explain(
    X=x_train,
    y=y_train_pred,
    num_stages=3,
    min_precision=0.95,
    jaccard_threshold=0.20
)

print(f"{len(rules)} rules extracted:")
for i, rule in enumerate(rules):
    print(f"  Rule {i}: {rule}")
```

### Accessing All Rules
- **model_explainer.longer_rules** (list of str) - Holds the full set of all discovered rules before set-cover selection.
```

--------------------------------

### ModelExplainer.explain Method

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Extract a list of rules from the tree ensemble model using input features and predicted class outputs.

```APIDOC
## te2rules.explainer.ModelExplainer.explain

### Description
A method to extract rule list from the tree ensemble model.
This method takes in input features used by the model and predicted class
output by the model.

Returns a List of rule strings.

### Parameters
#### Parameters
- **X** (*2d numpy.array*) – 2 dimensional input data used by the model
- **y** (*1d numpy.array*) – 1 dimensional model class predictions (0 or 1) from the model
- **num_stages** (*int* *,* *optional*) – The algorithm runs in stages starting from stage 1, stage 2 to all the way
  till stage n where n is the number of trees in the ensemble.
  Stopping the algorithm at an early stage  results in a few short rules
  (with quicker run time, but less coverage in data). By default,
  the algorithm explores all stages before terminating.
- **min_precision** (*float* *,* *optional*) – This parameter controls the minimum precision of extracted rules.
  Setting it to a smaller threshold, allows extracting shorter
  (more interpretable, but less faithful) rules.
  By default, the algorithm uses a minimum precision threshold of 0.95.
- **jaccard_threshold** (*float* *,* *optional*) – This parameter (between 0 and 1) controls how rules from different node
  combinations are combined. Setting it to a smaller threshold, ensures that
  only rules that are very different from one another are combined, speeding
  up the algorithm at the cost of missing some rules that can potentially
  explain the model. Combining similar rules that cover very similar set of
  instances do not provide any new information for the explainer algorithm.
  By default, the algorithm uses a jaccard threshold of 0.20.

### Returns
- **rules** – A List of human readable rules.

### Return type
List[str]

### Raises
- **ValueError:** – when X and y are of different length.
- **ValueError:** – when entries in y are other than 0 and 1. Only binary
      classification is supported.
```

--------------------------------

### Apply Rule List for Inference

Source: https://context7.com/linkedin/te2rules/llms.txt

Apply the extracted rule list to new data for binary class predictions. Instances satisfying any rule are positive (1); others are negative (0). Must be called after explain().

```python
# Apply the rule list to test data
y_pred_rules = model_explainer.predict(X=x_test)

# Compare rule-based predictions to original model predictions
from sklearn.metrics import accuracy_score, classification_report
print("Rule-list vs. model agreement:", accuracy_score(y_test_pred, y_pred_rules))
print(classification_report(y_test_pred, y_pred_rules, target_names=["Negative", "Positive"]))

# Calling predict() before explain() raises AttributeError:
# AttributeError: rules to explain the tree ensemble are not set.
#                 Call explain() before calling apply()
```

--------------------------------

### Extract Global Rule List

Source: https://context7.com/linkedin/te2rules/llms.txt

Extract a compact list of human-readable rules covering the model's positive-class predictions using the Apriori algorithm. Provide the training features (X) and the model's binary predictions (y). Tune `num_stages`, `min_precision`, and `jaccard_threshold` to balance speed, rule length, and coverage. Access all discovered rules via `model_explainer.longer_rules`.

```python
# rules = list of str, e.g. ["age > 40 & capital_gain > 5000", ...]
rules = model_explainer.explain(
    X=x_train,
    y=y_train_pred,          # model predictions, NOT ground-truth labels
    num_stages=3,            # 1–n_estimators; fewer stages = faster + shorter rules
    min_precision=0.95,      # minimum fraction of positives a rule must cover correctly
    jaccard_threshold=0.20   # lower = faster but may miss some rules
)

print(f"{len(rules)} rules extracted:")
for i, rule in enumerate(rules):
    print(f"  Rule {i}: {rule}")
# Example output:
#   Rule 0: capital_gain > 5095 & education_num > 12
#   Rule 1: hours_per_week > 45 & marital_status_Married_civ_spouse == 1
#   Rule 2: age > 42 & occupation_Exec_managerial == 1 & education_num > 10

# Access all possible (longer) rules before set-cover selection
print(f"\nAll possible rules ({len(model_explainer.longer_rules)} total):")
for rule in model_explainer.longer_rules[:5]:
    print(f"  {rule}")
```

--------------------------------

### Explain Tree Ensemble Model

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Extract a list of human-readable rules from a tree ensemble model using input data and model predictions. Adjust parameters like num_stages, min_precision, and jaccard_threshold for desired rule characteristics.

```python
from te2rules.explainer import ModelExplainer

# Assuming 'explainer' is an initialized ModelExplainer object
# and 'X' and 'y' are numpy arrays for input features and predictions

rules = explainer.explain(X, y, num_stages=None, min_precision=0.95, jaccard_threshold=0.2)
```

--------------------------------

### Load Adult Income Data

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Loads the pre-processed training and testing data for the Adult Income dataset from CSV files. The data is expected to be cleaned and one-hot encoded.

```python
np.random.seed(123)

training_path = "../data/adult/train.csv"
testing_path = "../data/adult/test.csv"

data_train = pd.read_csv(training_path)
data_test = pd.read_csv(testing_path)
```

--------------------------------

### Explain Model Predictions

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Extract rules to explain the positive class predictions of a tree ensemble model for training data.

```python
>>> rules = model_explainer.explain(X=x_train, y=y_train_pred)
```

--------------------------------

### Evaluate Rule List Fidelity

Source: https://context7.com/linkedin/te2rules/llms.txt

After extracting rules, use get_fidelity to quantify how faithfully the rule list mirrors the model's predictions. This helps in understanding the accuracy of the generated explanations.

```python
fidelity, pos_fid, neg_fid = explainer.get_fidelity(X=x_test, y=y_test_pred)

print(f"Rules extracted: {len(rules)}")
for i, r in enumerate(rules):
    print(f"  [{i}] {r}")
print(f"\nTest fidelity  — Overall: {fidelity:.2%}, Pos: {pos_fid:.2%}, Neg: {neg_fid:.2%}")
```

--------------------------------

### Inspect Extracted Rules

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Prints the number of rules found and iterates through them to display each rule.

```python
print(str(len(rules)) + " rules found:")
print()
for i in range(len(rules)):
    print("Rule " + str(i) + ": " + str(rules[i]))
```

--------------------------------

### Generate Model Predictions

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Generates predictions and prediction probabilities for both training and testing datasets using the trained model.

```python
y_train_pred = model.predict(x_train)
y_train_pred_score = model.predict_proba(x_train)[:, 1]

y_test_pred = model.predict(x_test)
y_test_pred_score = model.predict_proba(x_test)[:, 1]
```

--------------------------------

### te2rules.explainer.ModelExplainer.get_fidelity

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Evaluates the rule list extracted by the explain method, returning fidelity on positives, negatives, and overall data.

```APIDOC
## te2rules.explainer.ModelExplainer.get_fidelity

### Description
A method to evaluate the rule list extracted by the explain method.

Returns a fidelity on positives, negative, overall.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **X** (*2d numpy.array* *,* *optional*) – 2 dimensional data with feature values used for calculating fidelity. Defaults to data used by the model for rule extraction.
* **y** (*1d numpy.array* *,* *optional*) – 1 dimensional model class predictions (0 or 1) from the model on X. Defaults to model class predictions on the data used by the model for rule extraction.

### Returns
**fidelity** – Fidelity is the fraction of data for which the rule list agrees with the tree ensemble. Returns the fidelity on overall data, positive predictions and negative predictions by the model.
* **Return type:**
[float, float, float]

### Request Example
```python
(fidelity, fidelity_pos, fidelity_neg) = model_explainer.get_fidelity()
```

### Response
#### Success Response (200)
- **fidelity** (float) - Fidelity is the fraction of data for which the rule list agrees with the tree ensemble. Returns the fidelity on overall data, positive predictions and negative predictions by the model.

#### Response Example
```json
{
  "example": "(0.9, 0.85, 0.95)"
}
```
```

--------------------------------

### Explain Positive Class Prediction

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Use ModelExplainer to explain positive class predictions from an XGBoost model. Default values for min_precision (0.95) and num_stages (10) are used, suitable for smaller models.

```python
explainer = ModelExplainer(model=xgb_model, data=X_train, mode='classification')
explanation = explainer.explain_instance(X_test.iloc[0], positive_class_prediction=1)
print(explanation.rules)
```

--------------------------------

### Access Full Set of Discovered Rules

Source: https://context7.com/linkedin/te2rules/llms.txt

Access all valid rules found before greedy set-cover reduction via `longer_rules`. Useful for domain experts to select custom rule subsets.

```python
rules = model_explainer.explain(X=x_train, y=y_train_pred, num_stages=3)

compact_rules = model_explainer.rules        # same as returned by explain()
all_rules     = model_explainer.longer_rules # full rule universe

print(f"Compact set:  {len(compact_rules)} rules")
print(f"Full rule set: {len(all_rules)} rules")

# Manual selection example: pick rules involving 'capital_gain'
domain_selected = [r for r in all_rules if "capital_gain" in r]
print("\nDomain-selected rules involving capital_gain:")
for rule in domain_selected:
    print(f"  {rule}")
```

--------------------------------

### Extract Explanatory Rules

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Extracts a set of rules to explain the model's positive predictions using the training data. Parameters like num_stages, min_precision, and jaccard_threshold control the rule extraction process.

```python
rules = model_explainer.explain(
    X=x_train, y=y_train_pred,
    num_stages = 10,               # stages can be between 1 and max_depth 
    min_precision = 0.95,          # higher min_precision can result in rules with more terms overfit on training data 
    jaccard_threshold = 0.4        # lower jaccard_threshold speeds up the rule exploration, but can miss some good rules
)
```

--------------------------------

### ModelExplainer.predict

Source: https://context7.com/linkedin/te2rules/llms.txt

Applies the extracted rule list to new data for binary classification. Instances satisfying any rule are labeled positive (1), others negative (0). Must be called after explain().

```APIDOC
## ModelExplainer.predict

### Description
Applies the extracted rule list to new data and returns binary class predictions. Any instance satisfying at least one rule is labelled positive (1); all others are labelled negative (0). Must be called after `explain()`.

### Method
`predict(X)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **X** (numpy.ndarray or pandas.DataFrame) - Required - The input data for which to generate predictions.

### Request Example
```python
# Apply the rule list to test data
y_pred_rules = model_explainer.predict(X=x_test)
```

### Response
#### Success Response (200)
- **predictions** (numpy.ndarray) - Binary class predictions (0 or 1) for each instance in X.

#### Response Example
```
# Example output:
# [1 0 1 1 0 ...]
```

### Error Handling
- **AttributeError**: Raised if `explain()` has not been called prior to `predict()`.
```

--------------------------------

### Evaluate Rule Fidelity

Source: https://github.com/linkedin/te2rules/blob/main/docs/source/usage.md

Calculate the fidelity of the extracted rules against the model's predictions on overall, positive, and negative instances.

```python
>>> (fidelity, fidelity_pos, fidelity_neg) = model_explainer.get_fidelity()
```

--------------------------------

### Calculate Rule Fidelity

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Computes and prints the overall, positive, and negative fidelity of the extracted rules, indicating how well they explain the model's predictions.

```python
fidelity, positive_fidelity, negative_fidelity = model_explainer.get_fidelity()

print("The rules explain " + str(round(fidelity*100, 2)) + "% of the overall predictions of the model" )
print("The rules explain " + str(round(positive_fidelity*100, 2)) + "% of the positive predictions of the model" )
print("The rules explain " + str(round(negative_fidelity*100, 2)) + "% of the negative predictions of the model" )
```

--------------------------------

### ModelExplainer.longer_rules

Source: https://context7.com/linkedin/te2rules/llms.txt

Provides access to the full set of all valid rules discovered before the greedy set-cover reduction, allowing domain experts to select custom subsets.

```APIDOC
## ModelExplainer.longer_rules

### Description
Exposes every valid rule found before the greedy set-cover reduction. Domain experts can inspect this list to select a custom subset that aligns with their domain knowledge. This attribute is available after calling `explain()`.

### Method
Access via attribute: `model_explainer.longer_rules`

### Parameters
None

### Request Example
```python
# Assuming explain() has been called previously
all_rules = model_explainer.longer_rules

# Manual selection example: pick rules involving 'capital_gain'
domain_selected = [r for r in all_rules if "capital_gain" in r]
print("Domain-selected rules involving capital_gain:")
for rule in domain_selected:
    print(f"  {rule}")
```

### Response
#### Success Response (200)
- **longer_rules** (list of strings) - A list containing all discovered rules as strings.

#### Response Example
```
# Example output:
# ['age <= 30 & hours_per_week > 40', 'capital_gain > 5095 & education_num > 12', ...]
```
```

--------------------------------

### Evaluate Model Accuracy

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Calculates and prints the accuracy of the trained model on the test dataset.

```python
accuracy = model.score(x_test, y_test)
print("Accuracy")
print(accuracy)
```

--------------------------------

### Evaluate Rule List Faithfulness

Source: https://context7.com/linkedin/te2rules/llms.txt

Evaluate the faithfulness of the extracted rule list to the tree ensemble model. Returns a tuple of overall, positive, and negative fidelity scores. By default, uses the training data provided to `explain()`; pass new `X` and `y` to evaluate on held-out data.

```python
fidelity_scores = model_explainer.get_fidelity()
print(f"Overall fidelity: {fidelity_scores[0]:.4f}")
print(f"Positive class fidelity: {fidelity_scores[1]:.4f}")
print(f"Negative class fidelity: {fidelity_scores[2]:.4f}")
```

--------------------------------

### ModelExplainer.get_fidelity

Source: https://context7.com/linkedin/te2rules/llms.txt

Evaluates the faithfulness of the extracted rule list to the tree ensemble model. It calculates the fraction of data points for which the rule list agrees with the model's predictions.

```APIDOC
## ModelExplainer.get_fidelity(X=None, y=None)

### Description
Returns a 3-tuple `(overall_fidelity, positive_fidelity, negative_fidelity)` representing the fraction of data points for which the extracted rule list agrees with the tree ensemble. By default, it uses the training data provided to `explain()`. New `X` and `y` can be passed to evaluate on held-out data.

### Parameters
- **X** (numpy.ndarray or pandas.DataFrame) - Optional - Features to evaluate on. If None, uses the training data from `explain()`.
- **y** (numpy.ndarray) - Optional - Model's binary predictions (0/1) for the provided `X`. If None, uses the training predictions from `explain()`.

### Response
- **(overall_fidelity, positive_fidelity, negative_fidelity)** (tuple of floats) - The fidelity scores.

### Request Example
```python
# Assuming model_explainer is initialized and rules have been extracted
fidelity_scores = model_explainer.get_fidelity()
print(f"Overall Fidelity: {fidelity_scores[0]}")
print(f"Positive Fidelity: {fidelity_scores[1]}")
print(f"Negative Fidelity: {fidelity_scores[2]}")

# Evaluate on held-out data (assuming x_test and y_test_pred are available)
# fidelity_scores_test = model_explainer.get_fidelity(X=x_test, y=y_test_pred)
```
```

--------------------------------

### TE2Rules Citation

Source: https://github.com/linkedin/te2rules/blob/main/README.md

Use this BibTeX entry when citing TE2Rules in your publications. It includes title, authors, journal, and year.

```bibtex
@article{te2rules2022,
  title={TE2Rules: Explaining Tree Ensembles using Rules},
  author={Lal, G Roshan and Chen, Xiaotong and Mithal, Varun},
  journal={arXiv preprint arXiv:2206.14359},
  year={2022}
}
```

--------------------------------

### Calculate ROC AUC

Source: https://github.com/linkedin/te2rules/blob/main/notebooks/demo-adult-income.ipynb

Computes and prints the Area Under the ROC Curve (AUC) for the model's performance on the test dataset.

```python
fpr, tpr, thresholds = metrics.roc_curve(y_test, y_test_pred_score)
auc = metrics.auc(fpr, tpr)
print("AUC")
print(auc)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.