Wrap up

NOTICE.txt

@@ -6,4 +6,18 @@ Technische Universität Darmstadt
 -------------------------------------------------------------------------------
 Third party legal information
 
+docs/notebooks/world_cities_continents.csv
+
+  This file is a DERIVATIVE WORK of the simplemaps World Cities Database,
+  Basic edition (https://simplemaps.com/data/world-cities), which is licensed
+  under the Creative Commons Attribution 4.0 International licence
+  (https://creativecommons.org/licenses/by/4.0/).
+
+  Changes made to the original: the city list was filtered to administrative
+  centres (plus US and Canadian cities above 100,000 inhabitants); a
+  "continent" column was added by joining on country name and, for cities the
+  join did not cover, by majority vote over the three nearest labelled cities;
+  duplicate city names were collapsed to the most populous entry; and only the
+  city, country, continent, lat, lon and population columns were retained.
+
 

README.md

@@ -1,16 +1,15 @@
 <p  align="center">
-  <img src='logo.png' width='200'>
+  <img src='docs/assets/logo.png' width='200'>
 </p>
 
 # Supervised Multi-Dimensional Scaling
 
-[![Arxiv](https://img.shields.io/badge/Arxiv-2510.01025-red?style=flat-square&logo=arxiv&logoColor=white)](https://arxiv.org/abs/2510.01025)
+[![Paper](https://img.shields.io/badge/paper-Transactions%20on%20Machine%20Learning%20Research%20(TMLR)-112467?style=flat-square&logoColor=white)](https://openreview.net/forum?id=vCKZ40YYPr)
 [![License](https://img.shields.io/github/license/UKPLab/supervised-multidimensional-scaling)](https://opensource.org/licenses/Apache-2.0)
 [![Python Versions](https://img.shields.io/badge/Python-3.12-blue.svg?style=flat&logo=python&logoColor=white)](https://www.python.org/)
 [![CI](https://github.com/UKPLab/supervised-multidimensional-scaling/actions/workflows/main.yml/badge.svg)](https://github.com/UKPLab/supervised-multidimensional-scaling/actions/workflows/main.yml)
 
-This is a stand-alone implementation of Supervised Multi-Dimensional Scaling (SMDS) from the paper "Shape Happens:
-Automatic Feature Manifold Discovery in LLMs". It contains a plug-and-play class written with the
+This is a stand-alone implementation of Supervised Multi-Dimensional Scaling (SMDS) from the paper "Hypothesis-Driven Feature Manifold Analysis in LLMs via Supervised Multi-Dimensional Scaling". It contains a plug-and-play class written with the
 familiar [scikit-learn](https://scikit-learn.org) interface. SMDS supports several template shapes to discover manifolds
 of various shape.
 
@@ -37,7 +36,7 @@ pip install smds
 ## Usage
 
 The `SupervisedMDS` class provides a scikit-learn style interface that is straightforward to use. Unlike standard MDS,
-it requires selecting a stage-1 strategy and target `manifold` by name (for example: `"cluster"`, `"circular"`).
+it requires selecting a parametrization strategy and target `manifold` by name (for example: `"cluster"`, `"circular"`).
 
 ### Fit & Transform
 
@@ -52,17 +51,17 @@ X = np.random.randn(100, 20)  # 100 samples, 20 features
 y = np.random.randint(0, 5, size=100)  # Discrete labels (clusters)
 
 # Instantiate and fit
-# stage_1: "computed" (default) or "user_provided"
+# parametrization: "computed" (default) or "user_provided"
 # manifold: one of the built-in shape names, e.g. "cluster", "circular", "log_linear"
-smds = SupervisedMDS(stage_1="computed", manifold="cluster", alpha=0.1)
+smds = SupervisedMDS(parametrization="computed", manifold="cluster", alpha=0.1)
 smds.fit(X, y)
 
 # Transform to low-dimensional space
 X_proj = smds.transform(X)
 print(X_proj.shape)  # (100, 2)
 ```
 
-If you set `stage_1="user_provided"`, `manifold` is ignored and a warning is raised.
+If you set `parametrization="user_provided"`, `manifold` is ignored and a warning is raised.
 
 ### Manifold Discovery
 
@@ -206,13 +205,15 @@ mkdocs serve
 Please use the following citation:
 
 ```
-@misc{tiblias2025shapehappensautomaticfeature,
-      title={Shape Happens: Automatic Feature Manifold Discovery in LLMs via Supervised Multi-Dimensional Scaling}, 
-      author={Federico Tiblias and Irina Bigoulaeva and Jingcheng Niu and Simone Balloccu and Iryna Gurevych},
-      year={2025},
-      eprint={2510.01025},
-      archivePrefix={arXiv},
-      primaryClass={cs.AI},
-      url={https://arxiv.org/abs/2510.01025}, 
+@article{tibliasHypothesisDrivenFeatureManifold2025,
+  title = {Hypothesis-Driven Feature Manifold Analysis in LLMs via Supervised Multi-Dimensional Scaling},
+  author = {Tiblias, Federico and Bigoulaeva, Irina and Niu, Jingcheng and Balloccu, Simone and Gurevych, Iryna},
+  year = 2025,
+  month = oct,
+  journal = {Transactions on Machine Learning Research},
+  issn = {2835-8856},
+  urldate = {2026-04-26},
+  url={https://openreview.net/forum?id=vCKZ40YYPr},
+  langid = {english},
 }
 ```

docs/api/core.md

@@ -0,0 +1,52 @@
+# Core Estimators
+
+## SupervisedMDS
+
+::: smds.smds.SupervisedMDS
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## HybridSMDS
+
+::: smds.hsmds.HybridSMDS
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## Parametrization Strategies
+
+### SMDSParametrization
+
+::: smds.smds.SMDSParametrization
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### ComputedSMDSParametrization
+
+::: smds.smds.ComputedSMDSParametrization
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### UserProvidedSMDSParametrization
+
+::: smds.smds.UserProvidedSMDSParametrization
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true

docs/api/shapes.md

@@ -0,0 +1,169 @@
+# Shapes
+
+All shapes inherit from `BaseShape` and implement the same callable interface:
+calling an instance with an array of labels returns a pairwise distance matrix.
+
+## Base
+
+::: smds.shapes.base_shape.BaseShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## Continuous Shapes
+
+### CircularShape
+
+::: smds.shapes.continuous_shapes.circular.CircularShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### SemicircularShape
+
+::: smds.shapes.continuous_shapes.semicircular.SemicircularShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### EuclideanShape
+
+::: smds.shapes.continuous_shapes.euclidean.EuclideanShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### LogLinearShape
+
+::: smds.shapes.continuous_shapes.log_linear.LogLinearShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### SpiralShape
+
+::: smds.shapes.continuous_shapes.spiral_shape.SpiralShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### KleinBottleShape
+
+::: smds.shapes.continuous_shapes.klein_bottle.KleinBottleShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### TorusShape
+
+::: smds.shapes.continuous_shapes.torus.TorusShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## Discrete Shapes
+
+### ClusterShape
+
+::: smds.shapes.discrete_shapes.cluster.ClusterShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### ChainShape
+
+::: smds.shapes.discrete_shapes.chain.ChainShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### DiscreteCircularShape
+
+::: smds.shapes.discrete_shapes.discrete_circular.DiscreteCircularShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### HierarchicalShape
+
+::: smds.shapes.discrete_shapes.hierarchical.HierarchicalShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### GraphGeodesicShape
+
+::: smds.shapes.discrete_shapes.graph_geodesic.GraphGeodesicShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### PolytopeShape
+
+::: smds.shapes.discrete_shapes.polytope.PolytopeShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## Spatial Shapes
+
+### SphericalShape
+
+::: smds.shapes.spatial_shapes.spherical.SphericalShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### CylindricalShape
+
+::: smds.shapes.spatial_shapes.cylindrical.CylindricalShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true
+
+### GeodesicShape
+
+::: smds.shapes.spatial_shapes.geodesic.GeodesicShape
+    options:
+      members_order: source
+      show_bases: true
+      show_signature_annotations: true
+      separate_signature: true

docs/api/stress.md

@@ -0,0 +1,47 @@
+# Stress Metrics
+
+## StressMetrics
+
+::: smds.stress.stress_metrics.StressMetrics
+    options:
+      show_signature_annotations: true
+      separate_signature: true
+
+---
+
+## Functions
+
+### scale_normalized_stress
+
+::: smds.stress.scale_normalized_stress.scale_normalized_stress
+    options:
+      show_signature_annotations: true
+      separate_signature: true
+
+### normalized_stress
+
+::: smds.stress.normalized_stress.normalized_stress
+    options:
+      show_signature_annotations: true
+      separate_signature: true
+
+### non_metric_stress
+
+::: smds.stress.non_metric_stress.non_metric_stress
+    options:
+      show_signature_annotations: true
+      separate_signature: true
+
+### shepard_goodness_stress
+
+::: smds.stress.shepard_goodness_score.shepard_goodness_stress
+    options:
+      show_signature_annotations: true
+      separate_signature: true
+
+### kl_divergence_stress
+
+::: smds.stress.kl_divergence.kl_divergence_stress
+    options:
+      show_signature_annotations: true
+      separate_signature: true