DOC Ensures that AgglomerativeClustering passes numpydoc validation

[reshamas]

Reference Issues/PRs

Addresses #20308

What does this implement/fix? Explain your changes.

Fixes numpydoc errors on AgglomerativeClustering functions

Any other comments?

#DataUmbrella LATAM sprint

[reshamas]

I had a couple of questions:

1. I wasn't sure what to put for "See Also" section
2. line 180 is:

    return_distance : bool, default=None
        If True, return the distance between the clusters.

3. line 412 is:

    return_distance : bool, default=False
        whether or not to return the distances between the clusters.

For line 180: If it is of type bool, should that be True or False? Should the default be False, or does None imply something else?

[glemaitre]

Just marking as "Request changes" to see that we review the PR.

[glemaitre]

I resolved the conflict but I think that there is still a couple of failures associated with the validation.

[reshamas]

I resolved the conflict but I think that there is still a couple of failures associated with the validation.

This is the error, and I'm not sure where to resolve it:

E           # Errors
E           
E            - GL08: The object does not have a docstring

[ogrisel]

The full error message is:

E           ValueError: 
E           
E           None
E           
E           FeatureAgglomeration.fit_predict
E           Parsing of the method signature failed, possibly because this is a property.
E           
E           Fit the hierarchical clustering from features, or distance matrix.
E           
E           Parameters
E           ----------
E           X : array-like of shape (n_samples, n_features) or                 (n_samples, n_samples)
E               Training instances to cluster, or distances between instances if
E               ``affinity='precomputed'``.
E           
E           y : Ignored
E               Not used, present here for API consistency by convention.
E           
E           Returns
E           -------
E           labels : ndarray of shape (n_samples,)
E               Cluster labels.
E           
E           # Errors
E           
E            - GL08: The object does not have a docstring

So the problem is related to FeatureAgglomeration.fit_predict but thie GL08 error message is not consistent because this method has a docstring and is just a plain Python method (without any complex decorator or so).

@glemaitre any idea?

[ogrisel]

The None at the beginning of the error message is fishy...

[ogrisel]

Please add a short paragraph to make the difference method between the fit_predict and the fit methods explicit, for instance: "In addition to fitting, this method also return the result of the clustering assignment for each sample in the training set."

[reshamas]

This is odd, right? Instead of (n_samples, n_samples), I should have (n_samples,) ?

(not that I think that is causing the error.)

        Parameters
        ----------
        X : array-like of shape (n_samples, n_features) or \
                (n_samples, n_samples)
            Training instances to cluster, or distances between instances if
            ``affinity='precomputed'``.

[glemaitre]

This is odd, right? Instead of (n_samples, n_samples), I should have (n_samples,) ?

Nop. (n_samples, n_samples) is when we pass a distance matrix where we computed the distance between all samples and the parameter affinity="precomputed". It avoids recomputing this distance matrix internally.

[reshamas]

This is odd, right? Instead of (n_samples, n_samples), I should have (n_samples,) ?

Nop. (n_samples, n_samples) is when we pass a distance matrix where we computed the distance between all samples and the parameter affinity="precomputed". It avoids recomputing this distance matrix internally.

Ok, it's been added back. Still not sure what is causing the error. ?

[glemaitre]

The error comes from the undocumented property in line 1230:

@property
    def fit_predict(self):
        """Raise `AttributeError`."""
        raise AttributeError

[glemaitre]

LGTM. I pushed a couple of small changes. Let see if the CIs are happy.
I see that we should have a subsequent PR because FeatureAgglomeration should not accept a **params parameter at fit.

[glemaitre]

The CI for the numpydoc validation passed. So I will merge it now.

[glemaitre]

Thanks @reshamas