update documentation of high-level and conceptarium

Author: gdefe

doc/guides/using_high_level.rst

@@ -18,167 +18,6 @@ Summary
    Annotations
 
 
-Overview
---------
-
-Annotations store metadata about concepts including names, cardinalities, distribution 
-types, and custom attributes. They are required to initialize:
-
-- **Models** (e.g., ConceptBottleneckModel): Specify concept structure and distributions
-- **ConceptLoss**: Route to appropriate loss functions based on concept types
-- **ConceptMetrics**: Organize metrics by concept and compute per-concept statistics
-
-Distribution information is critical - it tells the model how to represent each concept 
-(e.g., Bernoulli for binary, Categorical for multi-class, Normal for continuous).
-
-Distributions can be provided either:
-
-1. **In annotations metadata** (recommended): Include 'distribution' key in metadata
-2. **Via model's variable_distributions parameter**: Pass distributions at model initialization
-
-Quick Start
------------
-
-**Option 1: Distributions in metadata (recommended)**
-
-.. code-block:: python
-
-   from torch_concepts.annotations import AxisAnnotation, Annotations
-   from torch.distributions import Bernoulli, Categorical
-   
-   # Distributions included in annotations
-   ann = Annotations({
-       1: AxisAnnotation(
-           labels=['is_round', 'is_smooth', 'color', 'class_A', 'class_B'],
-           cardinalities=[1, 1, 3, 1, 1],
-           metadata={
-               'is_round': {'type': 'discrete', 'distribution': Bernoulli},
-               'is_smooth': {'type': 'discrete', 'distribution': Bernoulli},
-               'color': {'type': 'discrete', 'distribution': Categorical},
-               'class_A': {'type': 'discrete', 'distribution': Bernoulli},
-               'class_B': {'type': 'discrete', 'distribution': Bernoulli}
-           }
-       )
-   })
-   
-   # Use in model (no variable_distributions needed)
-   from torch_concepts.nn import ConceptBottleneckModel
-   model = ConceptBottleneckModel(
-       input_size=256,
-       annotations=ann,
-       task_names=['class_A', 'class_B']
-   )
-   
-   # Use in loss
-   from torch_concepts.nn import ConceptLoss
-   from torch_concepts import GroupConfig
-   from torch.nn import BCEWithLogitsLoss, CrossEntropyLoss
-   
-   loss_config = GroupConfig(
-       binary=BCEWithLogitsLoss(),
-       categorical=CrossEntropyLoss()
-   )
-   loss = ConceptLoss(annotations=ann[1], fn_collection=loss_config)
-   
-   # Use in metrics
-   from torch_concepts.nn import ConceptMetrics
-   from torchmetrics.classification import BinaryAccuracy, MulticlassAccuracy
-   
-   metrics_config = GroupConfig(
-       binary={'accuracy': BinaryAccuracy()},
-       categorical={'accuracy': MulticlassAccuracy}
-   )
-   metrics = ConceptMetrics(
-       annotations=ann[1],
-       fn_collection=metrics_config,
-       summary_metrics=True,
-       perconcept_metrics=True
-   )
-
-**Option 2: Via variable_distributions dictionary**
-
-.. code-block:: python
-
-   # Annotations without distributions
-   ann = Annotations({
-       1: AxisAnnotation(
-           labels=['is_round', 'is_smooth', 'color', 'class_A', 'class_B'],
-           cardinalities=[1, 1, 3, 1, 1],
-           metadata={
-               'is_round': {'type': 'discrete'},
-               'is_smooth': {'type': 'discrete'},
-               'color': {'type': 'discrete'},
-               'class_A': {'type': 'discrete'},
-               'class_B': {'type': 'discrete'}
-           }
-       )
-   })
-   
-   # Provide distributions at model init
-   variable_distributions = {
-       'is_round': Bernoulli,
-       'is_smooth': Bernoulli,
-       'color': Categorical,
-       'class_A': Bernoulli,
-       'class_B': Bernoulli
-   }
-   
-   model = ConceptBottleneckModel(
-       input_size=256,
-       annotations=ann,
-       variable_distributions=variable_distributions,
-       task_names=['class_A', 'class_B']
-   )
-   
-   # Distributions added internally, then used in loss/metrics
-   loss = ConceptLoss(annotations=model.concept_annotations, fn_collection=loss_config)
-   metrics = ConceptMetrics(
-       annotations=model.concept_annotations,
-       fn_collection=metrics_config,
-       summary_metrics=True,
-       perconcept_metrics=True
-   )
-
-**Option 3: Using GroupConfig for automatic type-based assignment**
-
-For models with many concepts of the same types, use ``GroupConfig`` to automatically assign distributions:
-
-.. code-block:: python
-
-   from torch_concepts import GroupConfig
-   
-   # Annotations with concept types
-   ann = Annotations({
-       1: AxisAnnotation(
-           labels=['is_round', 'is_smooth', 'color', 'shape', 'class_A', 'class_B'],
-           cardinalities=[1, 1, 3, 4, 1, 1],
-           metadata={
-               'is_round': {'type': 'discrete'},    # binary (card=1)
-               'is_smooth': {'type': 'discrete'},   # binary (card=1)
-               'color': {'type': 'discrete'},       # categorical (card=3)
-               'shape': {'type': 'discrete'},       # categorical (card=4)
-               'class_A': {'type': 'discrete'},     # binary (card=1)
-               'class_B': {'type': 'discrete'}      # binary (card=1)
-           }
-       )
-   })
-   
-   # GroupConfig automatically assigns by concept type and cardinality
-   variable_distributions = GroupConfig(
-       binary=Bernoulli,       # for cardinality=1
-       categorical=Categorical  # for cardinality>1
-   )
-   
-   model = ConceptBottleneckModel(
-       input_size=256,
-       annotations=ann,
-       variable_distributions=variable_distributions,
-       task_names=['class_A', 'class_B']
-   )
-
-This approach is ideal for large-scale datasets (e.g., CUB-200 with 312 attributes).
-
-
 Class Documentation
 -------------------
 

doc/modules/annotations.rst

@@ -1,7 +1,7 @@
 High-level API
-==============
+=====================
 
-High-level APIs allow you to quickly build and train concept-based models using pre-configured components and minimal code.
+High-level API models allow you to quickly build and train concept-based models using pre-configured components and minimal code.
 
 .. |pyc_logo| image:: https://raw.githubusercontent.com/pyc-team/pytorch_concepts/refs/heads/factors/doc/_static/img/logos/pyc.svg
    :width: 20px
@@ -156,7 +156,7 @@ Configure losses and metrics using ``GroupConfig`` to automatically handle mixed
    )
    
    concept_loss = ConceptLoss(
-       annotations=annotations[1],  # AxisAnnotation for concepts
+       annotations=annotations,
        fn_collection=loss_config
    )
 
@@ -174,7 +174,7 @@ Configure losses and metrics using ``GroupConfig`` to automatically handle mixed
    )
    
    concept_metrics = ConceptMetrics(
-       annotations=annotations[1],
+       annotations=annotations,
        fn_collection=metrics_config,
        summary_metrics=True,      # Compute average across concepts
        perconcept_metrics=True    # Compute per-concept metrics

doc/modules/high_level_api.rst

@@ -28,66 +28,6 @@ Summary
    WeightedMSELoss
 
 
-Overview
---------
-
-High-level losses automatically route to appropriate loss functions based on concept types (binary, categorical, continuous) using annotation metadata.
-
-Quick Start
------------
-
-.. code-block:: python
-
-   import torch
-   from torch.nn import BCEWithLogitsLoss, CrossEntropyLoss
-   from torch_concepts import Annotations, AxisAnnotation, GroupConfig
-   from torch_concepts.nn import ConceptLoss, ConceptBottleneckModel
-   from torch.distributions import Bernoulli, Categorical
-   
-   # Define annotations with mixed types
-   ann = Annotations({
-       1: AxisAnnotation(
-           labels=['is_round', 'is_smooth', 'color', 'class_A'],
-           cardinalities=[1, 1, 3, 1],
-           metadata={
-               'is_round': {'type': 'discrete', 'distribution': Bernoulli},
-               'is_smooth': {'type': 'discrete', 'distribution': Bernoulli},
-               'color': {'type': 'discrete', 'distribution': Categorical},
-               'class_A': {'type': 'discrete', 'distribution': Bernoulli}
-           }
-       )
-   })
-   
-   # Configure loss functions by concept type using GroupConfig
-   loss_config = GroupConfig(
-       binary=BCEWithLogitsLoss(),
-       categorical=CrossEntropyLoss()
-   )
-   
-   # Automatic routing by concept type
-   loss = ConceptLoss(annotations=ann[1], fn_collection=loss_config)
-   
-   # Use in Lightning training
-   model = ConceptBottleneckModel(
-       input_size=256,
-       annotations=ann,
-       task_names=['class_A'],
-       loss=loss,
-       optim_class=torch.optim.AdamW,
-       optim_kwargs={'lr': 0.001}
-   )
-   
-   # Manual usage
-   predictions = torch.randn(32, 6)  # batch_size=32, 2 binary + 3 categorical + 1 binary
-   targets = torch.cat([
-       torch.randint(0, 2, (32, 2)),  # binary targets
-       torch.randint(0, 3, (32, 1)),  # categorical target (class indices)
-       torch.randint(0, 2, (32, 1))   # binary target
-   ], dim=1)
-   
-   loss_value = loss(predictions, targets)
-
-
 Class Documentation
 -------------------