extend cluster function api

[andrewheusser]

Add the following to hyp.tools.cluster:

• Align flag which aligns data before running clustering alg
• model flag to specify dimensionality reduction alg used if ndims is not None
• model_params flag to specify model parameters for dimensionality reduction model

@rarredon any interest? similar to what you helped with during the moz sprint :)

[jeremymanning]

Also: we should add the normalize flag

[rarredon]

Sounds good. I should be able to get those implemented this week, maybe even today.

[jeremymanning]

awesome-- thanks @rarredon!

[rarredon]

OK, I implemented the new kwargs but I'm getting an error when align=True. It seems kmeans.fit(x) expects x to be a 1 or 2 dimensional array for example, something like,

array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])

but tools.align returns a 3 dimensional array; something like

[array([[1, 2, 3],
        [4, 5, 6],
        [7, 8, 9]])]

Do you guys have any ideas for how to handle this?

[andrewheusser]

I think you want something like this before passing the data to kmeans.fit:

    if type(x) is list:
        x = np.vstack(x)

This should work, let me know!

[jeremymanning]

Current status (1.0 update, PR #272): unchanged from the original ask. hyp.cluster(x, cluster='KMeans', n_clusters=3, format_data=True) has no align, normalize, or pre-clustering model/model_params (reduce) kwargs. cluster.py still uses the older "dict-of-sklearn-classes" pattern (like reduce.py), not the newer base-class+registry+funnel pattern used by hypertools/align/align.py and hypertools/manip/manip.py.

How this could be built on the 1.0 architecture:
All three pieces the issue asks for already exist as standalone, importable functions (hypertools.tools.normalize.normalize, hypertools.tools.align.align / hypertools.align.align, hypertools.reduce.reduce.reduce) — hyp.plot() already threads normalize → reduce → align → cluster internally, so cluster() just needs to expose the same orchestration:

def cluster(x, cluster='KMeans', n_clusters=3, format_data=True,
            normalize=None, reduce=None, ndims=None, align=None):
    ...
    if normalize: x = normalizer(x, normalize=normalize)
    if reduce:    x = reducer(x, reduce=reduce, ndims=ndims)
    if align:     x = aligner(x, model=align)
    stacked = np.vstack(x)  # cluster.py already does this at the end
    ...

The original 2018 blocker (align() returning a list of arrays that broke kmeans.fit) is a non-issue here since cluster.py already calls np.vstack(x) right before fitting, regardless of whether x is a single array or list.

Alternatives / prior art:

• No external library needed — this is pure wiring of existing hypertools functions.
• Longer-term, cluster.py/reduce.py could be migrated to the Manipulator/Aligner-style base-class+registry pattern for consistency across the package, but that's a separate, larger refactor beyond this issue's scope.

Tagging as low effort; leaving open for consideration in a future release.

[jeremymanning]

In general: all of the hypertools modules should support calls to all of the other modules.

e.g., cluster should support reduce, manip, etc. keywords

and reduce should support cluster, manip, etc. keywords

and so on