<jupyter_start><jupyter_text>Quick Start[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/beginnerSC/pyminimax/master?urlpath=/lab/tree/docs/source/quick_start.ipynb)[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/beginnerSC/pyminimax/blob/master/docs/source/quick_start.ipynb)This page is generated by a Jupyter notebook which can be opened and run in Binder or Google Colab by clicking on the above badges. **To run it in Google Colab, you need to install PyMinimax in Colab first.**  InstallationThe recommended way to install PyMinimax is using pip:<jupyter_code>pip install pyminimax<jupyter_output><empty_output><jupyter_text>Or if you have installed PyMinimax before, please update to the latest version:<jupyter_code>pip install --upgrade pyminimax<jupyter_output><empty_output><jupyter_text>PyMinimax runs on any platform with Python 3 and SciPy installed.   UsageThe most important function in PyMinimax is `pyminimax.minimax`, and by default its usage is the same as the hierarchical clustering methods in SciPy, say `scipy.cluster.hierarchy.complete`. Here we demonstrate with an example from the [SciPy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.cluster.hierarchy.complete.html). First consider a dataset of $n=12$ points:<jupyter_code>X = [[0, 0], [0, 1], [1, 0], 
     [0, 4], [0, 3], [1, 4], 
     [4, 0], [3, 0], [4, 1], 
     [4, 4], [3, 4], [4, 3]]<jupyter_output><empty_output><jupyter_text>x x    x x    x        x    x        x    x x    x x    The minimax function takes a flattened distance matrix of the data as an argument, which can be computed by `scipy.spatial.distance.pdist`. By default, the return value of minimax has the same format as that of `scipy.cluster.hierarchy.linkage`. This is an $(n-1)$ by 4 matrix keeping the clustering result, called the *linkage matrix*. A detailed explanation of its format can be found in the [SciPy documentation](https://docs.scipy.org/doc/scipy/reference/generated/scipy.cluster.hierarchy.linkage.html).<jupyter_code>from pyminimax import minimax
from scipy.spatial.distance import pdist

Z = minimax(pdist(X))
Z<jupyter_output><empty_output><jupyter_text>Given the linkage matrix, one can then utilize the methods in SciPy to present the clustering result in a more readable manner. Below are examples applying `dendrogram` and `fcluster`.<jupyter_code>from scipy.cluster.hierarchy import dendrogram
from matplotlib import pyplot as plt

fig = plt.figure(figsize=(10, 4))
dendrogram(Z)
plt.show()
from scipy.cluster.hierarchy import fcluster

fcluster(Z, t=1.8, criterion='distance')<jupyter_output><empty_output><jupyter_text>The above result says that, cutting the dendrogram at 1.8 threshold, the data has 4 clusters, with the first 3 points being in the first cluster, and the following 3 in the second cluster, and so on.   Getting PrototypesA unique advantage of minimax linkage hierarchical clustering is that in each cluster one prototype is selected from the original data. Thus the resulting clusters are better interpretable. Starting 0.1.2, PyMinimax can also compute those prototypes. Below we demonstrate how this can be done. To obtain the prototypes, first we need an *extended linkage matrix* that contains prototypes information. This is an $(n-1)$ by $5$ matrix, where the first 4 columns are in the same format as the standard linkage matrix and the 5th column keeps the indices of the prototypes of each merged cluster. The extended linkage matrix can be computed by `pyminimax.minimax` with `return_prototype=True`.<jupyter_code>Z_ext = minimax(pdist(X), return_prototype=True)
Z_ext<jupyter_output><empty_output><jupyter_text>The 5-column extended linkage matrix is no longer SciPy-compatible. Any SciPy function that takes a linkage matrix will only work if we slice the extended linkage matrix to drop the 5th column, hence the `Z_ext[:, :4]` below.<jupyter_code>fig = plt.figure(figsize=(10, 4))
dendrogram(Z_ext[:, :4])
plt.show()<jupyter_output><empty_output><jupyter_text>In PyMinimax, the prototypes are computed by `pyminimax.fcluster_prototype`. Its usage is exactly the same as `scipy.cluster.hierarchy.fcluster`, except1. it takes the 5-column extended linkage matrix instead of a standard 4-column one, and2. it returns information regarding clusters *and* prototypes.<jupyter_code>from pyminimax import fcluster_prototype

fcluster_prototype(Z_ext, t=1.8, criterion='distance')<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.09026860413914575, 'fraction_numerical': 0.013210039630118891, 'mean_word_length': 5.471509971509971, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 5, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '8', 'dir': 'jupyter-structured-clean-dedup', 'id': '206089', 'license': 'BSD-3-Clause', 'n_tokens_mistral': 1483, 'n_tokens_neox': 1402, 'n_words': 507, 'path': 'docs/source/quick_start.ipynb', 'repo_name': 'beginnerSC/pyminimax1', 'size': '4542'}