Restructure examples in documentation using drop down menus

Author: pietrobarbiero

doc/guides/using_low_level.rst

@@ -85,143 +85,192 @@ clear from their name.
  )
 
 
-Step 1: Import Libraries
--------------------------
+Detailed Guides
+------------------------------
 
-.. code-block:: python
 
-   import torch
-   import torch_concepts as pyc
+.. dropdown:: Concept Bottleneck Model
+    :icon: package
 
-Step 2: Create Sample Data
----------------------------
+    **Import Libraries**
 
-Generate random inputs and targets for demonstration:
+    To get started, import |pyc_logo| PyC and |pytorch_logo| PyTorch:
 
-.. code-block:: python
+    .. code-block:: python
 
-   batch_size = 32
-   input_dim = 64
-   n_concepts = 5
-   n_tasks = 3
+       import torch
+       import torch_concepts as pyc
 
-   # Random input
-   x = torch.randn(batch_size, input_dim)
+    **Create Sample Data**
 
-   # Random concept labels (binary)
-   concept_labels = torch.randint(0, 2, (batch_size, n_concepts)).float()
+    Generate random inputs and targets for demonstration:
 
-   # Random task labels
-   task_labels = torch.randint(0, n_tasks, (batch_size,))
+    .. code-block:: python
 
-Step 3: Build a Concept Bottleneck Model
------------------------------------------
+       batch_size = 32
+       input_dim = 64
+       n_concepts = 5
+       n_tasks = 3
 
-Use a ModuleDict to combine encoder and predictor:
+       # Random input
+       x = torch.randn(batch_size, input_dim)
 
-.. code-block:: python
+       # Random concept labels (binary)
+       concept_labels = torch.randint(0, 2, (batch_size, n_concepts)).float()
 
-   # Create model using ModuleDict
-   model = torch.nn.ModuleDict({
-       'encoder': pyc.nn.LinearZC(
-           in_features=input_dim,
-           out_features=n_concepts
-       ),
-       'predictor': pyc.nn.LinearCC(
-           in_features_endogenous=n_concepts,
-           out_features=n_tasks
-       ),
-   })
+       # Random task labels
+       task_labels = torch.randint(0, n_tasks, (batch_size,))
 
-Step 4: Forward Pass
----------------------
+    **Step 3: Build a Concept Bottleneck Model**
 
-Compute concept endogenous, then task predictions:
+    Use a ModuleDict to combine encoder and predictor:
 
-.. code-block:: python
+    .. code-block:: python
 
-   # Get concept endogenous from input
-   concept_endogenous = model['encoder'](input=x)
+       # Create model using ModuleDict
+       model = torch.nn.ModuleDict({
+           'encoder': pyc.nn.LinearZC(
+               in_features=input_dim,
+               out_features=n_concepts
+           ),
+           'predictor': pyc.nn.LinearCC(
+               in_features_endogenous=n_concepts,
+               out_features=n_tasks
+           ),
+       })
 
-   # Get task predictions from concept endogenous
-   task_endogenous = model['predictor'](endogenous=concept_endogenous)
 
-   print(f"Concept endogenous shape: {concept_endogenous.shape}")  # [32, 5]
-   print(f"Task endogenous shape: {task_endogenous.shape}")        # [32, 3]
+.. dropdown:: Inference and Training
+    :icon: rocket
 
-Step 5: Compute Loss and Train
--------------------------------
+    **Step 1: Inference**
 
-Train with both concept and task supervision:
+    Once a concept bottleneck model is built, we can perform inference by first obtaining
+    concept activations from the encoder, and then task predictions from the predictor:
 
-.. code-block:: python
+    .. code-block:: python
 
-   import torch.nn.functional as F
+       # Get concept endogenous from input
+       concept_endogenous = model['encoder'](input=x)
 
-   # Compute losses
-   concept_loss = F.binary_cross_entropy(torch.sigmoid(concept_endogenous), concept_labels)
-   task_loss = F.cross_entropy(task_endogenous, task_labels)
-   total_loss = task_loss + 0.5 * concept_loss
+       # Get task predictions from concept endogenous
+       task_endogenous = model['predictor'](endogenous=concept_endogenous)
 
-   # Backpropagation
-   total_loss.backward()
+       print(f"Concept endogenous shape: {concept_endogenous.shape}")  # [32, 5]
+       print(f"Task endogenous shape: {task_endogenous.shape}")        # [32, 3]
 
-   print(f"Concept loss: {concept_loss.item():.4f}")
-   print(f"Task loss: {task_loss.item():.4f}")
+    **Step 2: Compute Loss and Train**
 
-Step 6: Perform Interventions
-------------------------------
+    Train with both concept and task supervision:
 
-Intervene using the ``intervention`` context manager which replaces the encoder layer temporarily.
-The context manager takes two main arguments: **strategies** and **policies**.
+    .. code-block:: python
 
-- Intervention strategies define how the layer behaves during the intervention, e.g., setting concept endogenous to ground truth values.
-- Intervention policies define the priority/order of concepts to intervene on.
+       import torch.nn.functional as F
 
-.. code-block:: python
+       # Compute losses
+       concept_loss = F.binary_cross_entropy(torch.sigmoid(concept_endogenous), concept_labels)
+       task_loss = F.cross_entropy(task_endogenous, task_labels)
+       total_loss = task_loss + 0.5 * concept_loss
 
-   from torch_concepts.nn import GroundTruthIntervention, UniformPolicy
-   from torch_concepts.nn import intervention
+       # Backpropagation
+       total_loss.backward()
 
-   ground_truth = 10 * torch.rand_like(concept_endogenous)
-   strategy = GroundTruthIntervention(model=model['encoder'], ground_truth=ground_truth)
-   policy = UniformPolicy(out_features=n_concepts)
+       print(f"Concept loss: {concept_loss.item():.4f}")
+       print(f"Task loss: {task_loss.item():.4f}")
 
-   # Apply intervention to encoder
-   with intervention(
-       policies=policy,
-       strategies=strategy,
-       target_concepts=[0, 2]
-   ) as new_encoder_layer:
-       intervened_concepts = new_encoder_layer(input=x)
-       intervened_tasks = model['predictor'](endogenous=intervened_concepts)
 
-   print(f"Original concept endogenous: {concept_endogenous[0]}")
-   print(f"Original task predictions: {task_endogenous[0]}")
-   print(f"Intervened concept endogenous: {intervened_concepts[0]}")
-   print(f"Intervened task predictions: {intervened_tasks[0]}")
+.. dropdown:: Interventions
+    :icon: tools
 
-Using Special Layers
---------------------
+    Intervene using the ``intervention`` context manager which replaces the encoder layer temporarily.
+    The context manager takes two main arguments: **strategies** and **policies**.
 
-Add a graph learner to discover concept relationships:
+    - Intervention strategies define how the layer behaves during the intervention, e.g., setting concept endogenous to ground truth values.
+    - Intervention policies define the priority/order of concepts to intervene on.
+
+    .. code-block:: python
+
+       from torch_concepts.nn import GroundTruthIntervention, UniformPolicy
+       from torch_concepts.nn import intervention
+
+       ground_truth = 10 * torch.rand_like(concept_endogenous)
+       strategy = GroundTruthIntervention(model=model['encoder'], ground_truth=ground_truth)
+       policy = UniformPolicy(out_features=n_concepts)
+
+       # Apply intervention to encoder
+       with intervention(
+           policies=policy,
+           strategies=strategy,
+           target_concepts=[0, 2]
+       ) as new_encoder_layer:
+           intervened_concepts = new_encoder_layer(input=x)
+           intervened_tasks = model['predictor'](endogenous=intervened_concepts)
+
+       print(f"Original concept endogenous: {concept_endogenous[0]}")
+       print(f"Original task predictions: {task_endogenous[0]}")
+       print(f"Intervened concept endogenous: {intervened_concepts[0]}")
+       print(f"Intervened task predictions: {intervened_tasks[0]}")
 
-.. code-block:: python
 
-   # Define concept and task names
-   concept_names = ['round', 'smooth', 'bright', 'large', 'centered']
+.. dropdown:: (Advanced) Graph Learning
+    :icon: workflow
 
-   # Create WANDA graph learner
-   graph_learner = pyc.nn.WANDAGraphLearner(
-       row_labels=concept_names,
-       col_labels=concept_names
-   )
+    Add a graph learner to discover concept relationships:
 
-   print(f"Learned graph shape: {graph_learner.weighted_adj}")
+    .. code-block:: python
+
+       # Define concept and task names
+       concept_names = ['round', 'smooth', 'bright', 'large', 'centered']
+
+       # Create WANDA graph learner
+       graph_learner = pyc.nn.WANDAGraphLearner(
+           row_labels=concept_names,
+           col_labels=concept_names
+       )
+
+       print(f"Learned graph shape: {graph_learner.weighted_adj}")
+
+
+    The ``graph_learner.weighted_adj`` tensor contains a learnable adjacency matrix representing relationships
+    between concepts.
+
+
+.. dropdown:: (Advanced) Verifiable Concept-Based Models
+    :icon: shield-check
+
+    To design more complex concept-based models, you can combine multiple interpretable layers.
+    For example, to build a verifiable concept-based model we can use an encoder to predict concept activations,
+    a selector to select relevant exogenous information, and a hyper-network predictor to make final predictions
+    based on both concept activations and exogenous information.
+
+    .. code-block:: python
+
+       from torch_concepts.nn import LinearZC, SelectorZU, HyperLinearCUC
+
+       memory_size = 7
+       exogenous_size = 16
+       embedding_size = 5
+
+       # Create model using ModuleDict
+       model = torch.nn.ModuleDict({
+           'encoder': LinearZC(
+               in_features=input_dim,
+               out_features=n_concepts
+           ),
+           'selector': SelectorZU(
+               in_features=input_dim,
+               memory_size=memory_size,
+               exogenous_size=exogenous_size,
+               out_features=n_tasks
+           ),
+           'predictor': HyperLinearCUC(
+               in_features_endogenous=n_concepts,
+               in_features_exogenous=exogenous_size,
+               embedding_size=embedding_size,
+           )
+       })
 
 
-The ``graph_learner.weighted_adj`` tensor contains a learnable adjacency matrix representing relationships
-between concepts.
 
 Next Steps
 ----------
@@ -230,4 +279,3 @@ Next Steps
 - Try the :doc:`Mid-Level API </guides/using_mid_level_proba>` for probabilistic modeling
 - Try the :doc:`Mid-Level API </guides/using_mid_level_causal>` for causal modeling
 - Check out :doc:`example notebooks <https://github.com/pyc-team/pytorch_concepts/tree/master/examples>`
-