full documentation of high-level and conceptarium

Author: gdefe

conceptarium/README.md

@@ -12,21 +12,12 @@
 
 - **Experiment tracking**: Integrated <img src="../doc/_static/img/logos/wandb.svg" width="20px" align="center"/> [Weights & Biases](https://wandb.ai/) logging for monitoring and reproducibility
 
-- [Quick Start](#quick-start)
-  - [Installation](#installation)
-  - [Configuration](#configuration)
-  - [Running Experiments](#running-experiments)
-  - [Custom configurations](#custom-configurations)
-  - [Output Structure](#output-structure)
-- [Configuration Details](#configuration-details)
-  - [Configuration Structure](#configuration-structure)
-  - [Dataset Configuration](#dataset-configuration-datasetyaml)
-  - [Model Configuration](#model-configuration-modelyaml)
-- [Implementation](#implementation)
-  - [Implementing Your Own Model](#implementing-your-own-model)
-  - [Implementing Your Own Dataset](#implementing-your-own-dataset)
-- [Contributing](#contributing)
-- [Cite this library](#cite-this-library)
+📚 **Full Documentation**: See the [comprehensive Conceptarium guide](../doc/guides/using_conceptarium.rst) for detailed documentation on:
+- Configuration system and hierarchy
+- Dataset and model configuration
+- Custom losses and metrics
+- Advanced usage patterns
+- Troubleshooting
 
 ---
 
@@ -63,20 +54,21 @@ hydra:
     name: my_experiment
   sweeper:
     params:
-      model: cbm            # One or more models (blackbox, cbm, cem, cgm, c2bm, etc.)
-      dataset: celeba, cub  # One or more datasets (celeba, cub, MNIST, alarm, etc.)
-      seed: 1,2,3,4,5       # sweep over multiple seeds for robustness
+      seed: 1,2,3,4,5               # Sweep over multiple seeds for robustness
+      dataset: cub,celeba            # One or more datasets
+      model: cbm_joint               # One or more models (blackbox, cbm_joint)
 
 model:
   optim_kwargs:
-    lr: 0.001
+    lr: 0.01
+
+metrics:
   summary_metrics: true
-  perconcept_metrics: false
+  perconcept_metrics: true
 
 trainer:
-  max_epochs: 500
-  patience: 30
-  monitor: "val_loss"
+  max_epochs: 200
+  patience: 20
 ```
 
 ## Running Experiments
@@ -97,13 +89,13 @@ python run_experiment.py --config-name your_sweep.yaml
 On top of this, you can also override configurations from command line:
 ```bash
 # Change dataset
-python run_experiment.py dataset=alarm
+python run_experiment.py dataset=cub
 
 # Change learning rate
-python run_experiment.py model.optim_kwargs.lr=0.001
+python run_experiment.py model.optim_kwargs.lr=0.01
 
 # Change multiple configurations
-python run_experiment.py model=cbm dataset=asia,alarm seed=1,2,3
+python run_experiment.py model=cbm_joint dataset=cub,celeba seed=1,2,3
 ```
 
 ## Output Structure
@@ -133,57 +125,44 @@ Configuration files are organized in `conceptarium/conf/`:
 
 ```
 conf/
-├── _default.yaml      # Base configuration with defaults
-├── sweep.yaml         # Experiment sweep configuration
-├── dataset/           # Dataset configurations
-│   ├── _commons.yaml      # Common dataset parameters
-│   ├── celeba.yaml
-│   ├── cub.yaml
-│   ├── sachs.yaml
-│   └── ...
-└── model/             # Model architectures
-    ├── loss/              # Loss function configurations
-    │   ├── _default.yaml  # Type-aware losses (BCE, CE, MSE)
-    │   └── weighted.yaml  # Weighted type-aware losses
-    ├── metrics/           # Metric configurations
-    │   ├── _default.yaml  # Type-aware metrics (Accuracy, MAE, MSE)
-    │   └── ...
-    ├── _commons.yaml      # Common model parameters
-    ├── blackbox.yaml      # Black-box baseline
-    ├── cbm_joint.yaml     # Concept Bottleneck Model (Joint)
-    ├── cem.yaml           # Concept Embedding Model
-    ├── cgm.yaml           # Concept Graph Model
-    └── c2bm.yaml          # Causally Reliable CBM
-```
-    │   ├── default.yaml   # Type-aware metrics (Accuracy, MAE, MSE)
-    │   └── ...
-    ├── _commons.yaml      # Common model parameters
-    ├── blackbox.yaml      # Black-box baseline
-    ├── cbm.yaml           # Concept Bottleneck Model
-    ├── cem.yaml           # Concept Embedding Model
-    ├── cgm.yaml           # Concept Graph Model
-    └── c2bm.yaml          # Causally Reliable CBM
+├── _default.yaml          # Base configuration with defaults
+├── sweep.yaml             # Example sweep configuration
+├── dataset/               # Dataset configurations
+│   ├── _commons.yaml          # Common dataset parameters
+│   ├── cub.yaml               # CUB-200-2011 birds dataset
+│   ├── celeba.yaml            # CelebA faces dataset
+│   └── ...                    # More datasets
+├── loss/                  # Loss function configurations
+│   ├── standard.yaml          # Standard type-aware losses
+│   └── weighted.yaml          # Weighted type-aware losses
+├── metrics/               # Metric configurations
+│   └── standard.yaml          # Type-aware metrics (Accuracy)
+└── model/                 # Model architectures
+    ├── _commons.yaml          # Common model parameters
+    ├── blackbox.yaml          # Black-box baseline
+    ├── cbm.yaml               # Alias for CBM Joint
+    └── cbm_joint.yaml         # Concept Bottleneck Model (Joint)
 ```
 
 
 ## Dataset Configuration (`dataset/*.yaml`)
 
-Dataset configurations specify the dataset class to instantiate, all data-specific parameters, and all necessary preprocessing parameters. An example configuration for the CUB dataset is provided below:
+Dataset configurations specify the dataset class to instantiate, all data-specific parameters, and all necessary preprocessing parameters. An example configuration for the CUB-200-2011 birds dataset is provided below:
 
 ```yaml
 defaults:
   - _commons
   - _self_
 
-_target_: torch_concepts.data.datamodules.CUBDataModule   # the path to your datamodule class  
+_target_: torch_concepts.data.datamodules.CUBDataModule
 
 name: cub
 
 backbone: 
-  _target_: "path.to.your.backbone.ClassName"
-  # ... (backbone arguments)
+  _target_: torchvision.models.resnet18
+  pretrained: true
 
-precompute_embs: true  # precompute input to speed up training
+precompute_embs: true  # precompute embeddings to speed up training
 
 default_task_names: [bird_species]
 
@@ -197,7 +176,8 @@ label_descriptions:
 
 ### Common Parameters
 
-Default parameters, common to all dataset, are in `_commons.yaml`:
+Default parameters, common to all datasets, are in `_commons.yaml`:
+
 - **`batch_size`**: Training batch size (default: 256)
 - **`val_size`**: Validation set fraction (default: 0.15)
 - **`test_size`**: Test set fraction (default: 0.15)
@@ -212,38 +192,37 @@ Model configurations specify the architecture, loss, metrics, optimizer, and inf
 ```yaml
 defaults:
   - _commons
-  - loss: _default
-  - metrics: _default
   - _self_
 
-_target_: "torch_concepts.nn.ConceptBottleneckModel_Joint"
+_target_: torch_concepts.nn.ConceptBottleneckModel_Joint
 
 task_names: ${dataset.default_task_names}
 
 inference: 
-  _target_: "torch_concepts.nn.DeterministicInference"
+  _target_: torch_concepts.nn.DeterministicInference
   _partial_: true
 
 summary_metrics: true       # enable/disable summary metrics over concepts
 perconcept_metrics: false   # enable/disable per-concept metrics
 ```
 
-### Common Parameters
+### Model Common Parameters
 
 From `_commons.yaml`:
+
 - **`encoder_kwargs`**: Encoder architecture parameters
   - **`hidden_size`**: Hidden layer dimension in encoder
   - **`n_layers`**: Number of hidden layers in encoder
   - **`activation`**: Activation function (relu, tanh, etc.) in encoder
   - **`dropout`**: Dropout probability in encoder
-- **`variable_distributions`**: Probability distributions with which concepts are modeled:
+- **`variable_distributions`**: Probability distributions with which concepts are modeled
 - **`optim_class`**: Optimizer class
 - **`optim_kwargs`**:
   - **`lr`**: 0.00075
 
 and more...
 
-### Loss Configuration (`model/loss/_default.yaml`)
+### Loss Configuration (`loss/standard.yaml`)
 
 Type-aware losses automatically select appropriate loss functions based on variable types:
 
@@ -264,7 +243,7 @@ fn_collection:
   # ... not supported yet
 ```
 
-### Metrics Configuration (`model/metrics/_default.yaml`)
+### Metrics Configuration (`metrics/standard.yaml`)
 
 Type-aware metrics automatically select appropriate metrics based on variable types:
 
@@ -306,32 +285,40 @@ This involves the following steps:
 - Run experiments using your model. 
 
 If your model is compatible with the default configuration structure, you can run experiments directly as follows:
+
 ```bash
-python run_experiment.py model=your_model dataset=...
+python run_experiment.py model=your_model dataset=cub
 ```
-Alernatively, create your own sweep file `conf/your_sweep.yaml` containing your mdoel and run:
+
+Alternatively, create your own sweep file `conf/your_sweep.yaml` containing your model and run:
+
 ```bash
-python run_experiment.py --config-file your_sweep.yaml
+python run_experiment.py --config-name your_sweep
 ```
 
 ---
 
 ## Implementing Your Own Dataset
+
 Create your dataset in Conceptarium by following the guidelines given in [torch_concepts/examples/contributing/dataset.md](../examples/contributing/dataset.md).
 
 This involves the following steps:
+
 - Create the dataset (`your_dataset.py`).
 - Create the datamodule (`your_datamodule.py`) wrapping the dataset.
 - Create configuration file in `conceptarium/conf/dataset/your_dataset.yaml`, targeting the datamodule class.
-- Run experiments using your dataset. 
+- Run experiments using your dataset.
 
 If your dataset is compatible with the default configuration structure, you can run experiments directly as follows:
+
 ```bash
-python run_experiment.py dataset=your_dataset model=...
+python run_experiment.py dataset=your_dataset model=cbm_joint
 ```
+
 Alternatively, create your own sweep file `conf/your_sweep.yaml` containing your dataset and run:
+
 ```bash
-python run_experiment.py --config-name your_sweep.yaml
+python run_experiment.py --config-name your_sweep
 ```
 
 ---

doc/guides/using.rst

@@ -78,7 +78,7 @@ Pick the best entry point based on your experience:
         Start from the High-Level API to use pre-defined models with one line of code.
 
     .. grid-item-card::  :octicon:`beaker;1em;sd-text-primary` No experience with programming?
-        :link: modules/conceptarium
+        :link: using_conceptarium
         :link-type: doc
         :shadow: lg
         :class-card: sd-border-primary
@@ -138,3 +138,4 @@ Need Help?
    using_mid_level_proba
    using_mid_level_causal
    using_high_level
+   using_conceptarium