Skip to content

[BUG]: Clustering Metrics Documentation Errors #14

@piterand

Description

@piterand

Description of the bug

Issue Summary
The clustering metrics documentation table contains two critical errors with contradictory descriptions and incorrect value ranges that could mislead users when interpreting clustering quality results.

URL: https://permetrics.readthedocs.io/en/latest/pages/clustering.html
File: docs/source/pages/clustering.rst

Errors Found
Current Documentation (Incorrect)

17 | DBCVI | Density-based Clustering Validation Index | Bigger is better (Best=0), Range = [0, 1]
18 | HI | Hartigan Index | Bigger is better (best=0), Range = [0, +inf)

Should Be (Corrected)

17 | DBCVI | Density-based Clustering Validation Index | Bigger is better (Best=1), Range = [-1, 1]
18 | HI | Hartigan Index | Smaller is better (best=0), Range = [0, +inf)

Changes Required
Row 17 (DBCVI):

Change: Bigger is better (Best=0), Range = [0, 1]

To: Bigger is better (Best=1), Range = [-1, 1]

Row 18 (HI):

Change: Bigger is better (best=0), Range = [0, +inf)

To: Smaller is better (best=0), Range = [0, +inf)

Steps To Reproduce

  1. Visit the permetrics documentation page: https://permetrics.readthedocs.io/en/latest/pages/clustering.html

  2. Locate the clustering metrics table

  3. Find Row 17 (DBCVI):

Current text shows: "Bigger is better (Best=0), Range = [0, 1]"
This contradicts itself: best value of 0 cannot be bigger
Range [0, 1] is incorrect; should be [-1, 1]

  1. Find Row 18 (HI - Hartigan Index):

Current text shows: "Bigger is better (best=0), Range = [0, +inf)"
This contradicts itself: best value of 0 is the smallest, not bigger
Should state "Smaller is better (best=0)" instead

  1. Expected Behavior

All metrics should have consistent documentation where:

If "best=0", then "Smaller is better" must be stated
If "Bigger is better", then best value must be the maximum in the range
Ranges must match the metric's actual value domain

Additional Information

No response

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions