View source for Examples using Python/Learning a Decision Tree with Python example

'''Coming soon...'''

== Learning a Decision tree with Python ==

This example shows how to use Analytica's Python integration to load data from Python, fit a machine-learning classifier, make predictions, and return useful results to Analytica. It uses scikit-learn's built-in Iris data set and its <code>DecisionTreeClassifier</code> implementation.

'''Download:''' [[media:Python Decision Tree Example.ana|Python Decision Tree Example.ana]]

== What this example does ==

The model classifies Iris flowers as ''setosa'', ''versicolor'', or ''virginica'' from four measurements in centimeters:

* Sepal length
* Sepal width
* Petal length
* Petal width

The data set contains 150 flower observations: 50 of each species. The model selects a reproducible, stratified 20% holdout sample (10 flowers of each species), trains the classifier on the remaining 120 observations, and reports the percentage of holdout observations classified correctly. You can also enter the four measurements for a new flower and view its predicted species.

== What is CART? ==

'''CART''' stands for '''Classification and Regression Trees'''. It is a family of decision-tree methods that can predict either a category (classification) or a number (regression). This example is a classification problem.

A CART classifier starts with all training observations and repeatedly chooses a question that separates their classes well, for example:

<pre>
Is petal length (cm) <= 2.45?
</pre>

Each answer sends an observation to a different branch. The process continues until a branch becomes a leaf, which predicts the most common training class in that leaf. This model uses scikit-learn's <code>DecisionTreeClassifier</code> with the Gini criterion. The '''Maximum tree depth''' input limits how many levels of splits the fitted tree may have: a smaller value produces a simpler tree, while a larger value can fit more detailed patterns.

== Requirements and setup ==

Python integration requires Analytica 7.0 or later with a Python-capable edition, plus a supported Python installation. This example is configured to use a Conda environment named <code>Analytica_Iris_Tree</code> containing Python, NumPy, and scikit-learn.

# Open the '''Iris decision tree''' diagram.
# In '''1. Python setup: Analytica_Iris_Tree''', click '''Create Python environment'''.
# The button checks whether the environment already exists. If necessary, it uses Anaconda or Miniconda to create it with Python 3.12, NumPy, and scikit-learn.
# If Analytica has already loaded Python from a different environment during the current session, close and reopen Analytica before running the model. Switching Python environments after Python has been loaded is not reliable.

If the setup button reports that Anaconda or Miniconda is unavailable, install one of them and run the button again. The model does not store a machine-specific Python path; it stores only the environment name.

== Using the model ==

The top-level diagram is arranged as a short workflow.

# '''Python setup''': Create or confirm the required Conda environment.
# '''Training controls''': Set '''Maximum tree depth''' and '''Random seed'''. The seed controls the reproducible holdout selection and the tree fitting process.
# '''View Iris data''': Open '''Iris measurements''' or '''Actual species''' to inspect the data read from scikit-learn.
# '''Train''': Open '''Fitted decision tree''' to inspect the native Analytica representation of the fitted tree. '''Fitted Python decision tree''' is an optional technical view of the underlying scikit-learn object.
# '''Classify a new Iris flower''': Enter four values in '''New measurements''', in the order shown by the '''Measurement''' index, and calculate '''Predicted species'''.
# '''Holdout test performance''': Calculate '''Test classification accuracy''' to evaluate predictions for the 30 observations withheld from training. You can also compare '''Predicted test species code''' with '''Actual test species code'''.

The reported test accuracy is useful as a demonstration of the workflow, not as a definitive estimate of model performance. The Iris data set is small, so accuracy can vary when the random seed changes.

== How Python and Analytica work together ==

The model demonstrates several ways to move information between Analytica and Python.

=== Loading Python data into Analytica ===

The Iris measurements and species codes come from scikit-learn's <code>code>load_iris()</code> function. Python returns NumPy arrays, which the model converts into native Analytica arrays using [[PyExplode]]:


 [[PyExplode]](
    [[PyEval]]('load_iris().data'),
    Observation,
    Feature
 )


The <code>Observation</code> index has 150 elements and the <code>Feature</code> index names the four measurements. This makes the data available as an ordinary Analytica array for tables, calculations, and diagrams.

=== Passing Analytica arrays to Python ===

Before fitting or predicting, the model converts labeled Analytica arrays into NumPy arrays using <code>PyArray</code>. For example, the fitted tree receives the measurement matrix and integer species codes:


 Tree_template -> Fit(
    [[PyArray]](Iris_measurements, Observation, Feature),
    [[PyArray]](Iris_species_code, Observation, dtype:'int64'),
    Tree_max_depth,
    Random_seed,
    [[PyList]](Test_observation),
    'Iris CART tree'
 )


[[PyList]] converts the selected test observations to a Python list. The fitting function removes these observations before training, preventing the holdout data from being used to fit the tree.

=== Defining reusable Python functions ===

The model uses [[Callable]] nodes for Python functions that are reused by the Analytica model. For example, the <code>Fit_tree</code> Callable imports NumPy and <code>DecisionTreeClassifier</code>, then defines a Python function that creates and fits the CART classifier. Its Python definition is stored using [[PyExec]].

The other [[Callable]]s predict holdout classes, score the holdout sample, and export the fitted tree to JSON. Keeping reusable Python code in Callable nodes avoids repeatedly compiling the same Python function and makes the Python-specific parts of the model easier to find.

=== Keeping a fitted Python object ===

A fitted scikit-learn classifier is a complex Python object. It is retained in the <code>python_model</code> member of the native <code>Decision_tree</code> Struct. Analytica can pass this opaque Python object back to Python methods for prediction and scoring without attempting to turn it into an Analytica array.

For a readable Analytica view, the model also converts selected tree metadata to JSON in Python and uses <code>ParseJSON</code> to construct native Analytica Struct members. The resulting <code>Tree_as_struct</code> contains the fitted tree's classes and a nested root-node representation, including split feature, threshold, sample count, class counts, and leaf prediction.

== Model structure ==

The top-level diagram contains these modules:

{| class="wikitable"
! Module
! Purpose
|-
| '''Iris data'''
| Defines the <code>Observation</code> and <code>Feature</code> indexes and loads the Iris measurements, species codes, and species names from scikit-learn.
|-
| '''Train decision tree'''
| Defines the Python Callables, the <code>Decision_tree</code> Struct, training controls, and the fitted classifier.
|-
| '''Classify new flower'''
| Accepts four new measurements and uses the fitted tree to predict a species.
|-
| '''Holdout validation'''
| Selects the reproducible test observations, obtains predictions, and calculates accuracy.
|}

== Key Python-integration functions ==

{| class="wikitable"
! Function
! Role in this example
|-
| [[PyExec]]
| Executes Python statements and defines the Python functions held by Callable nodes.
|-
| [[PyEval]]
| Evaluates a Python expression and returns its value to Analytica.
|-
| [[PyArray]]
| Converts an Analytica array into a NumPy array, preserving the specified index order.
|-
| [[PyList]]
| Converts an Analytica array or list into a Python list.
|-
| [[PyExplode]]
| Converts a Python or NumPy result into a native Analytica array with named indexes.
|-
| [[ParseJSON]]
| Converts the JSON tree description returned by Python into inspectable Analytica Struct data.
|}

== Ideas for extension ==

You can adapt the example by replacing the Iris data with your own labeled data, adding predictor features, changing <code>max_depth</code>, or comparing several classifiers. For a realistic predictive model, use a suitable train/test or cross-validation design and ensure that all preprocessing is learned from the training data only.

== See also ==

* [[Using Python from Analytica]]
* [[PyExec]]
* [[PyEval]]
* [[PyArray]]
* [[PyExplode]]
* [[Callable|Callable nodes]]
* [[Struct]]s