{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Basic usage"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Go to:\n",
" \n",
" - [Notebook configuration](basic_usage.ipynb#Notebook-configuration)\n",
" - [Getting started](basic_usage.ipynb#Getting-started)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Notebook configuration"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.214273Z",
"start_time": "2022-10-17T12:45:03.676498Z"
}
},
"outputs": [],
"source": [
"import sys\n",
"\n",
"# Optional dependencies\n",
"import matplotlib as mpl\n",
"import matplotlib.pyplot as plt\n",
"\n",
"import commonnn\n",
"from commonnn import cluster"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.222621Z",
"start_time": "2022-10-17T12:45:06.217513Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Python: 3.9.0 | packaged by conda-forge | (default, Nov 26 2020, 07:57:39) [GCC 9.3.0]\n",
"Packages:\n",
" matplotlib: 3.9.4\n",
" commonnn: 0.0.3\n"
]
}
],
"source": [
"# Version information\n",
"print(\"Python: \", *sys.version.split(\"\\n\"))\n",
"\n",
"print(\"Packages:\")\n",
"for package in [mpl, commonnn]:\n",
" print(f\" {package.__name__}: {package.__version__}\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We use [Matplotlib](https://matplotlib.org/) to create plots. The `matplotlibrc` file in the root directory of the `CommonNNClustering` repository is used to customize the appearance of the plots."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.240695Z",
"start_time": "2022-10-17T12:45:06.236437Z"
}
},
"outputs": [],
"source": [
"# Matplotlib configuration\n",
"mpl.rc_file(\"../../matplotlibrc\", use_default_template=False)"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.247485Z",
"start_time": "2022-10-17T12:45:06.243108Z"
}
},
"outputs": [],
"source": [
"# Axis property defaults for the plots\n",
"ax_props = {\n",
" \"aspect\": \"equal\"\n",
"}\n",
"\n",
"# Property defaults for plotted lines\n",
"dot_props = {\n",
" \"marker\": \"o\",\n",
" \"markeredgecolor\": \"k\"\n",
"}"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Getting started"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `commonnn.cluster` main module provides a `Clustering` class. An instance of this class is used to bundle input data (e.g. data points) with cluster results (cluster label assignments) alongside the clustering method (a fitter with a set of building blocks) and convenience functions for further analysis (not only in a Molecular Dynamics context). As a guiding principle, a `Clustering` object is always associated with one particular data set (possibly hierarchically decomposed) and allows varying cluster parameters."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"
\n",
"\n",
"**Info:** Refer also to the [__scikit-learn-extra__ project](https://github.com/scikit-learn-contrib/scikit-learn-extra) for an alternative API following a parameter centered approach to clustering as `sklearn_extra.cluster.CommonNNClustering`.\n",
"\n",
"
"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A `Clustering` can be initialized by passing *raw* input data to it. By default, this is expected to be a nested sequence, e.g. a list of lists. It will be understood as the coordinates of a number of data points in a feature space. Similar data structures, like a 2-dimensional NumPy array would be acceptable, as well. It is possible to use different kinds of input data formats instead, like for example pre-computed pairwise distances, and it is described later how to do it (refer to tutorials [__Clustering of scikit-learn toy data sets__](scikit_learn_datasets.ipynb) and [__Advanced usage__](advanced_usage.ipynb))."
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.261233Z",
"start_time": "2022-10-17T12:45:06.249279Z"
}
},
"outputs": [],
"source": [
"# 2D Data points (list of lists, 12 points in 2 dimensions)\n",
"data_points = [ # Point index\n",
" [0, 0], # 0\n",
" [1, 1], # 1\n",
" [1, 0], # 2\n",
" [0, -1], # 3\n",
" [0.5, -0.5], # 4\n",
" [2, 1.5], # 5\n",
" [2.5, -0.5], # 6\n",
" [4, 2], # 7\n",
" [4.5, 2.5], # 8\n",
" [5, -1], # 9\n",
" [5.5, -0.5], # 10\n",
" [5.5, -1.5], # 11\n",
" ]\n",
"\n",
"clustering = cluster.Clustering(data_points)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When we cluster data points, we are essentially interested in cluster label assignments for these points. The labels will be exposed as the `labels` attribute on the `Clustering` instance, which is currently `None` because no clustering has been done yet."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.278900Z",
"start_time": "2022-10-17T12:45:06.262884Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"True"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"clustering.labels is None"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To cluster the points, we will use the `Clustering.fit` method. CommonNN clustering depends on two parameters:\n",
" \n",
" - `radius_cutoff`: Points are considered neighbours if the distance between them is not larger than this cutoff radius $r$.\n",
" - `similarity_cutoff`: Points are assigned to the same cluster if they share at least this number of $n_\\mathrm{c}$ common neighbours.\n",
" \n",
"For the clustering procedure, we ultimately need to compute the neighbouring points with respect to the `radius_cutoff` for each point in the data set. Then we can determine if two points fulfill the criterion of being part of the same cluster. How this is done, can be controlled in detail but by default the input data points are assumed to be given in euclidean space and the neighbours are computed brute force. For larger data sets, it makes sense to use a different approach."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.287308Z",
"start_time": "2022-10-17T12:45:06.280475Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"-----------------------------------------------------------------------------------------------\n",
"#points r nc min max #clusters %largest %noise time \n",
"12 2.000 1 None None 2 0.583 0.167 00:00:0.000\n",
"-----------------------------------------------------------------------------------------------\n",
"\n"
]
}
],
"source": [
"clustering.fit(radius_cutoff=2.0, similarity_cutoff=1)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A clustering attempt returns and prints a comprehensive record of the cluster parameters and the outcome. You can suppress the recording with the keyword argument `record=False` and the printing with `v=False`:\n",
"\n",
" - **#points**: Number of data points in the data set.\n",
" - **r**: Radius cutoff *r*.\n",
" - **nc**: Common-nearest-neighour similarity cutoff $n_\\mathrm{c}$.\n",
" - **min**: Member cutoff (valid clusters need to have at least this many members).\n",
" - **max**: Maximum cluster count (keep only the *max* largest clusters and disregard smaller clusters).\n",
" - **#clusters**: Number of identified clusters.\n",
" - **%largest**: Member share on the total number of points in the largest cluster.\n",
" - **%noise**: Member share on the total number of points identified as noise (not part of any cluster).\n",
" \n",
"The `min` (keyword argument `member_cutoff`) and `max` (keyword argument `max_clusters`) only take effect in an optional post processing step when `sort_by_size=True` (default). In this case, the clusters are sorted by their size, so that the first cluster (cluster 1) has the highest member count. Optionally, they are trimmed such that valid clusters have a minimum number of members (`member_cutoff`) and only the largest clusters are kept (`max_clusters`)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The outcome of the clustering are cluster label assignments for each point. Points classified as *noise* (not part of any cluster) are labeled 0. Integer labels larger than 0 indicate the membership of each point to one of the identified clusters. If clusters were sorted (`sort_by_size=True`), cluster 1 has the highest member count."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.301233Z",
"start_time": "2022-10-17T12:45:06.289239Z"
}
},
"outputs": [
{
"data": {
"text/plain": [
"array([1, 1, 1, 1, 1, 1, 1, 0, 0, 2, 2, 2])"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"clustering.labels"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `labels` attribute of a cluster object always holds the result of the latest fit. All cluster results (from fits where `record=True`) are collected in a summary without storing the actual labels."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.316957Z",
"start_time": "2022-10-17T12:45:06.302912Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"-----------------------------------------------------------------------------------------------\n",
"#points r nc min max #clusters %largest %noise time \n",
"12 2.000 1 None None 2 0.583 0.167 00:00:0.000\n",
"-----------------------------------------------------------------------------------------------\n",
"\n",
"-----------------------------------------------------------------------------------------------\n",
"#points r nc min max #clusters %largest %noise time \n",
"12 1.500 1 None None 2 0.417 0.333 00:00:0.000\n",
"-----------------------------------------------------------------------------------------------\n",
"\n"
]
}
],
"source": [
"clustering.fit(radius_cutoff=1.5, similarity_cutoff=1, v=False)\n",
"print(*clustering.summary, sep=\"\\n\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If you have [Pandas](https://pandas.pydata.org/) installed, the summary can be transformed into a handy `pandas.DataFrame`."
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"ExecuteTime": {
"end_time": "2022-10-17T12:45:06.352985Z",
"start_time": "2022-10-17T12:45:06.319638Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"
\n",
"\n",
"**Info:** The *raw* data points that we passed here to create the `Clustering` object are internally wrapped into a specific input data type. `Clustering.input_data` is a shortcut for `Clustering._bundle._input_data.to_components_array()`. Depending on the used type, the data may, however, actually be stored in any possible format under `InputData._data`.\n",
"See [__Advanced usage__](advanced_usage.ipynb) for more information.\n",
"