.. _example-cancer-rna:

=========================
Cancer RNA Classification
=========================

This example demonstrates Tabular Classification using cancer RNA gene expression data.

.. contents:: On this page
   :local:
   :depth: 2

Problem Description
===================

**Goal:** Classify cancer types based on RNA gene expression profiles.

**Input Features:**

- RNA gene expression values (multiple genes)
- High-dimensional input space

**Output:**

- Cancer type classification (one-hot encoded)
- Multiple classes representing different cancer types

Dataset
=======

The training set ships split across two files each (to keep the high-dimensional
files manageable), plus single test files:

- ``x_train_0_.csv``, ``x_train_1_.csv`` — Training gene expression profiles (two parts)
- ``y_train_0_.csv``, ``y_train_1_.csv`` — Training labels (one-hot encoded cancer types)
- ``x_test.csv`` — Test gene expression profiles
- ``y_test.csv`` — Test labels

.. note::

   These files ship in the ``GeneExpressionCancerRnaSeq`` example folder of the
   NeurEco installation (see :doc:`index` for the location). Extract that folder
   and run the commands below from inside it. The two training parts are
   concatenated in code (and listed together in the CLI configuration).

.. important::

   Classification outputs must be one-hot encoded. Each row has exactly one ``1`` indicating the cancer type.

Building the Model
==================

.. tabs::

   .. tab:: GUI

      1. Launch NeurEco and select **Tabular Classification**
      2. Load the training inputs ``x_train_0_.csv`` and ``x_train_1_.csv``
      3. Load the training outputs ``y_train_0_.csv`` and ``y_train_1_.csv`` (must be one-hot encoded)
      4. Optionally load test files
      5. Click **BUILD**
      6. Monitor classification accuracy during training

   .. tab:: Python API

      .. code-block:: python

         from NeurEco import NeurEcoTabular as Tabular
         import numpy as np

         # Load data — the training set ships in two parts; concatenate them
         x_train = np.vstack([
             np.genfromtxt("x_train_0_.csv", delimiter=";", skip_header=True),
             np.genfromtxt("x_train_1_.csv", delimiter=";", skip_header=True),
         ])
         y_train = np.vstack([
             np.genfromtxt("y_train_0_.csv", delimiter=";", skip_header=True),
             np.genfromtxt("y_train_1_.csv", delimiter=";", skip_header=True),
         ])
         # y_train should already be one-hot encoded

         x_test = np.genfromtxt("x_test.csv", delimiter=";", skip_header=True)
         y_test = np.genfromtxt("y_test.csv", delimiter=";", skip_header=True)

         # Create and build model
         model = Tabular.Classifier()

         config = Tabular.ClassifierBuildConfig(
             input_data=x_train,
             output_data=y_train,
             write_model_to="./cancer_model/cancer.ednn",
             checkpoint_address="./cancer_model/cancer.checkpoint",
             valid_percentage=33.33,
         )

         model.build(config)

         # Evaluate
         predictions = model.evaluate(x_test)

         # compute_error returns the misclassification rate (fraction of samples
         # wrong), so test accuracy is 1 - error.
         error_rate = model.compute_error(predictions, y_test)
         accuracy = 1.0 - error_rate
         print(f"Test accuracy: {accuracy * 100:.2f}%")

         # Plot confusion matrix using built-in method
         class_names = [f"Type {i}" for i in range(y_test.shape[1])]
         cm = model.plot_confusion_matrix(
             prediction=predictions,
             reference=y_test,
             class_names=class_names,
             show_percentages=True,
             title="Cancer Classification Results",
             save_path="cancer_confusion_matrix.png"
         )

         # Cleanup
         model.delete()

   .. tab:: CLI

      Create ``build_cancer.conf``:

      .. code-block:: json

         {
             "neurecoClassification_build": {
                 "DevSettings": {
                     "valid_percentage": 33.33
                 },
                 "exc_filenames": ["x_train_0_.csv", "x_train_1_.csv"],
                 "output_filenames": ["y_train_0_.csv", "y_train_1_.csv"],
                 "test_exc_filenames": ["x_test.csv"],
                 "test_output_filenames": ["y_test.csv"],
                 "input_normalization": {
                     "normalize_per_feature": true,
                     "scale_type": "auto",
                     "shift_type": "auto"
                 },
                 "write_model_to": "./cancer_model/cancer.ednn",
                 "checkpoint_address": "./cancer_model/cancer.checkpoint"
             }
         }

      Run:

      .. code-block:: shell

         neureco Classification build build_cancer.conf

Expected Results
================

After training:

- **High classification accuracy** — Typically 99%+ on this dataset
- **Compact model** — Despite high-dimensional inputs, NeurEco creates a small network
- **Feature selection** — NeurEco may identify that only some genes are predictive

Analyzing Results
=================

**Per-class accuracy:**

.. code-block:: python

   import numpy as np

   # Convert one-hot references and probability predictions to class indices
   n_classes = y_test.shape[1]
   actual_classes = np.argmax(y_test, axis=1)
   predicted_classes = np.argmax(predictions, axis=1)

   for class_idx in range(n_classes):
       class_mask = actual_classes == class_idx
       class_accuracy = np.mean(predicted_classes[class_mask] == class_idx)
       print(f"Class {class_idx} accuracy: {class_accuracy * 100:.2f}%")

**Identifying important genes:**

Use sensitivity analysis to find which genes contribute most to classification:

.. code-block:: python

   # After training, use sensitivity analysis
   # See Advanced Features documentation

Key Takeaways
=============

This example demonstrates:

1. **High-dimensional inputs** — NeurEco handles many input features efficiently
2. **Automatic feature selection** — Unimportant inputs may be disconnected
3. **One-hot encoding requirement** — Classification outputs must be properly formatted
4. **Interpretability** — Sensitivity analysis reveals important features

Variations to Try
=================

- Use sensitivity analysis to identify key genes
- Try limiting model size and observe accuracy impact
- Compare different normalization strategies
- Analyze misclassified samples