DOC merge dbscan, hdbcan, optics gallery examples into one example #31102

daustria · 2025-03-28T21:28:24Z

Reference Issues/PRs

What does this implement/fix? Explain your changes.

I have done my best to merge the three user gallery examples in the above issue into one readable and cohesive document.

Any other comments?

I am relatively new to writing technical documents and to the ideas of these clustering algorithms, and would appreciate any feedback from others on how I can improve this document. I also think there is a UI bug with the bookmarks on the right hand side when viewing the example on a web browser on a desktop. It seems like the section titles are not being highlighted at the correct time, HDBSCAN sections are highlighted as the user scrolls through the OPTICS section. I'm not sure how to fix it that so I would like some advice on how to proceed on that part.

github-actions · 2025-03-28T21:29:40Z

✔️ Linting Passed

All linting checks passed. Your pull request is in excellent shape! ☀️

_{Generated for commit: e9ae604. Link to the linter CI: here}

adrinjalali

I quite like the new example. It's tells a very nice story.

Maybe @lucyleeow could have a look?

adrinjalali · 2025-04-30T14:19:01Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+import numpy as np
+
+
+def cluster_colours(labels):


a little docstring for these functions to explain what they try to do would be nice

adrinjalali · 2025-05-05T09:45:25Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# DBSCAN
+# -------


Suggested change

# DBSCAN

# -------

# DBSCAN

# ------

They need to be the same length, otherwise sphinx complains

adrinjalali · 2025-05-05T09:45:49Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# Tuning DBSCAN
+# ++++++++++++++


Suggested change

# Tuning DBSCAN

# ++++++++++++++

# Tuning DBSCAN

# +++++++++++++

adrinjalali · 2025-05-05T09:47:02Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# default values for `eps` and `min_samples` they usually will not provide good
+# results, as these sensitive to the shape of the dataset you are working with.
+# Larger values of `min_samples` yield more robustness to noise, but


there's been discussions about providing an "auto" version for eps, which would sample distances from the dataset and then decide on a reasonable default. In case you're interested in pushing that forward, could be a separate PR.

adrinjalali · 2025-05-05T09:48:35Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# plot. However, finding good values of `eps` and `min_samples` is not always
+# as easy as this. It may require specialized knowledge of the dataset
+# one is working with. While standardizing the dataset with
+# `StandardScaler` may help with this problem, great care must be taken for


Suggested change

# `StandardScaler` may help with this problem, great care must be taken for

# :class:`~sklearn.preprocessingStandardScaler` may help with this problem, great care must be taken for

and of course to trim the now long line

adrinjalali · 2025-05-05T09:51:36Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# Tuning HDBSCAN
+# ++++++++++++++++


Suggested change

# Tuning HDBSCAN

# ++++++++++++++++

# Tuning HDBSCAN

# ++++++++++++++

adrinjalali · 2025-05-05T09:53:17Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# generally tuned to larger values as needed. Smaller values will likely to
+# lead to results with fewer points labeled as noise. However values which too
+# small will lead to false sub-clusters being picked up and preferred. Larger


Suggested change

# generally tuned to larger values as needed. Smaller values will likely to

# lead to results with fewer points labeled as noise. However values which too

# small will lead to false sub-clusters being picked up and preferred. Larger

# generally tuned to larger values as needed. Smaller values will likely

# lead to results with fewer points labeled as noise. However too small

# values will lead to false sub-clusters being picked up and preferred. Larger

adrinjalali · 2025-05-05T09:55:13Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# clustering of all points across all values of DBSCAN’s `eps` parameter. We
+# can efficiently obtain these DBSCAN like clusterings efficiently without
+# fully recomputing intermediate values required for an HDBSCAN fit, such as
+# core-distances, mutual-reachability, and the minimum spanning tree This is


Suggested change

# core-distances, mutual-reachability, and the minimum spanning tree This is

# core-distances, mutual-reachability, and the minimum spanning tree. This is

adrinjalali · 2025-05-05T09:55:58Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# OPTICS
+# -------


Suggested change

# OPTICS

# -------

# OPTICS

# ------

adrinjalali · 2025-05-05T11:11:55Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+    if k == -1:
+        continue


Suggested change

if k == -1:

continue

if k == -1:

# skip points labeled as outliers

continue

lucyleeow

This is a great improvement to the previous 3 examples, and it's nice that we can reduce the number of examples.

My only comment is that it is on the longer side, though I have not suggestions as how to make it shorter. I've tried to remove redundant sentences (e.g., things that are explained in the docstring of the model)

I've only got minor grammar nits.
I noticed we used both 'labelled' (UK spelling) and 'labeled' (US spelling), maybe we could pick one and make it consistent ?

The other thing to note is that the deleted examples may have been referenced in the docs / docstrings. I would search for the title of the deleted examples to find references to them. You can replace with the a reference to the new example. I think this should be sphx_glr_auto_examples_cluster_plot_dbscan_hdbscan_optics.py

lucyleeow · 2025-05-12T11:43:47Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+=======================================================
+Demo of DBSCAN, HDBSCAN, OPTICS clustering algorithms
+=======================================================


The over/under-lining should be the same length as the title

lucyleeow · 2025-05-12T11:45:37Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+=======================================================
+.. currentmodule:: sklearn
+
+In this demo we will take a look at DBSCAN, HDBSCAN, and OPTICs clustering


Suggested change

In this demo we will take a look at DBSCAN, HDBSCAN, and OPTICs clustering

In this demo we will take a look at DBSCAN, HDBSCAN, and OPTICS clustering

Also I may be inclined to give what the acronyms stand for at the start, when you first mention the acronyms, instead of later on.

lucyleeow · 2025-05-14T04:21:27Z

examples/cluster/plot_dbscan_hdbscan_optics.py

Suggested change

# To gain some intuition about how DBSCAN works, we

# need to discuss the concept of core points. We will also discuss neighborhoods.

# To gain some intuition about how DBSCAN works, we

# need to discuss the concept of core points and neighborhoods.

lucyleeow · 2025-05-14T04:22:34Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# need to discuss the concept of core points. We will also discuss neighborhoods.
+# Generally speaking, when we talk about the neighborhood of a point, we are
+# referring to a collection of points in the dataset that are within a certain
+# distance from it. The size of the neighborhood will depend on the context. A


"The size of the neighborhood will depend on the context"

Not sure exactly what context means here?

lucyleeow · 2025-05-14T04:24:11Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+can be viewed as generalizations of DBSCAN, and efficiently extract DBSCAN
+clusterings from the results of running these algorithms.
+
+We start by defining helper functions to visualize a dataset and the resulting


nit, as we are mostly taking about the plot function and we use singular below in "use this function".

Suggested change

We start by defining helper functions to visualize a dataset and the resulting

We start by defining a helper function to visualize a dataset and the resulting

lucyleeow · 2025-05-14T05:09:10Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# The Xi clustering method uses the steep slopes within the reachability
+# plot to determine which points are in the same cluster. One can specify
+# this by setting the `xi` parameter. More details on this parameter
+# may be found the :ref:`User Guide <OPTICS>`.


Suggested change

# may be found the :ref:`User Guide <OPTICS>`.

# may be found the :ref:`User Guide <optics>`.

lucyleeow · 2025-05-14T05:10:52Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# clustering. The user can choose which method by setting the `cluster_method`
+# parameter to either `xi` (default) or `dbscan`.


Suggested change

# clustering. The user can choose which method by setting the `cluster_method`

# parameter to either `xi` (default) or `dbscan`.

# clustering.

lucyleeow · 2025-05-14T05:14:11Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# `cluster_optics_dbscan()`. This function takes the reachability, ordering,
+# and core distances produced from running OPTICS, and an `eps` parameter
+# analogous to its counterpart in DBSCAN. It produces a clustering with results
+# similar if one were to run DBSCAN on the same dataset with similar settings


Suggested change

# similar if one were to run DBSCAN on the same dataset with similar settings

# similar to if one were to run DBSCAN on the same dataset with similar settings

lucyleeow · 2025-05-14T05:14:51Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+# for `eps` and `min_samples`. The runtime is efficient, it is linear in the
+# number of samples whereas running DBSCAN from scratch is quadratic in its


Suggested change

# for `eps` and `min_samples`. The runtime is efficient, it is linear in the

# number of samples whereas running DBSCAN from scratch is quadratic in its

# for `eps` and `min_samples`. The runtime is efficient, it is linear to the

# number of samples whereas running DBSCAN from scratch is quadratic in its

lucyleeow · 2025-05-14T05:15:41Z

examples/cluster/plot_dbscan_hdbscan_optics.py

+
+
+for idx, eps in enumerate(eps_values):
+    plot_optics_dbscan(optics, eps, axes[idx])


It would be nice to have a very short summary of the 3 methods here.

daustria · 2025-05-14T15:10:48Z

thanks for the comments and your time, i will address them in the next few work days
edit: some things in life came up, might be a while longer, hopefully this month

merge dbscan, hdbcan, optics examples into one example

e9ae604

daustria changed the title ~~merge dbscan, hdbcan, optics gallery examples into one example~~ DOC merge dbscan, hdbcan, optics gallery examples into one example Mar 31, 2025

github-actions bot added the Documentation label Mar 31, 2025

adrinjalali reviewed May 5, 2025

View reviewed changes

lucyleeow mentioned this pull request May 14, 2025

DOC Minor updates to OPTICS docstring #31363

Merged

lucyleeow reviewed May 14, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

DOC merge dbscan, hdbcan, optics gallery examples into one example #31102

DOC merge dbscan, hdbcan, optics gallery examples into one example #31102

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	# `StandardScaler` may help with this problem, great care must be taken for
	# :class:`~sklearn.preprocessingStandardScaler` may help with this problem, great care must be taken for

	# core-distances, mutual-reachability, and the minimum spanning tree This is
	# core-distances, mutual-reachability, and the minimum spanning tree. This is

	In this demo we will take a look at DBSCAN, HDBSCAN, and OPTICs clustering
	In this demo we will take a look at DBSCAN, HDBSCAN, and OPTICS clustering

-# To gain some intuition about how DBSCAN works, we
-# need to discuss the concept of core points. We will also discuss neighborhoods.
+# To gain some intuition about how DBSCAN works, we
+# need to discuss the concept of core points and neighborhoods.

	We start by defining helper functions to visualize a dataset and the resulting
	We start by defining a helper function to visualize a dataset and the resulting

	# may be found the :ref:`User Guide <OPTICS>`.
	# may be found the :ref:`User Guide <optics>`.

		# clustering. The user can choose which method by setting the `cluster_method`
		# parameter to either `xi` (default) or `dbscan`.

	# clustering. The user can choose which method by setting the `cluster_method`
	# parameter to either `xi` (default) or `dbscan`.
	# clustering.

	# similar if one were to run DBSCAN on the same dataset with similar settings
	# similar to if one were to run DBSCAN on the same dataset with similar settings

		# for `eps` and `min_samples`. The runtime is efficient, it is linear in the
		# number of samples whereas running DBSCAN from scratch is quadratic in its

		import numpy as np


		def cluster_colours(labels):



		for idx, eps in enumerate(eps_values):
		plot_optics_dbscan(optics, eps, axes[idx])

Uh oh!

DOC merge dbscan, hdbcan, optics gallery examples into one example #31102

Are you sure you want to change the base?

DOC merge dbscan, hdbcan, optics gallery examples into one example #31102

Uh oh!

Conversation

Uh oh!

Reference Issues/PRs

What does this implement/fix? Explain your changes.

Any other comments?

Uh oh!

✔️ Linting Passed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!