Package: shapeGMMTorch
shapeGMMTorchOverviewThis is a package to perform Gaussian Mixture Model (GMM) clustering on particle positions (in). Like other GMM schemes, the user must specify the number of clusters and a cluster initialization scheme (defaults to random).  This is specified in the object initialization line, analagous to how it is done for the sklearn GaussianMixture package.  There are two choices for the form of the covariance  specified by thecovar_typekeyword in the object initialization.  See paper (Klem et al JCTC 2022,https://pubs.acs.org/doi/abs/10.1021/acs.jctc.1c01290) for additional details.DependenciesThis package is dependent on the following packages:Python>=3.6numpytorch>=1.11 (==1.11 if option 4 is used)Optional: torch_batch_svd available fromhttps://github.com/KinglittleQ/torch-batch-svdThe last package is for the SVD part of the alignment and is faster than the native batch torch library for certain devices. I have found it to be slower than the torch native SVD for the latest hardware and software versions.The examples are also dependent on:MDAnalysismatplotlibpyemmashapeGMMInstallationAfter the dependencies have been installed, the package can be installed from pippip install shapeGMMTorchor by downloading from github and then runningpython setup.py installInstallation on a MACI have found that PyTorch does not work on a mac using standardpip install torchor conda.  Instead, you have to create a specialnomklconda environment and install all necessary packages in there.  There are various blogs and/or stack overflow threads on this.After thenomklconda environment has been created and all dependencies have been added to that environment, shapeGMMTorch can be installed.  Only thetorch.device("cpu")device will work on a mac, however.UsageThis package is designed to mimic the usage of the sklearn package.  You first initiliaze the object and then fit.  Predict can be done once the model is fit.  Fit and ppredict functions take particle position trajectories as input in the form of a(n_frames, n_atoms, 3)numpy array.Initialize:from shapeGMMTorch import torch_sgmmUniform covariance (spherical, uncorrelated, homogeneous):usgmm = torch_sgmm.ShapeGMMTorch(n_clusters, covar_type = 'uniform', verbose=True)Kronecker product covariance (formerly call weighted covariance; spherical, correlated, heterogeneous):wsgmm = torch_sgmm.ShapeGMMTorch(n_clusters, covar_type = 'kronecker', verbose=True)During initialization, the following options are availble:- n_clusters (required)   - integer number of clusters must be input
- covar_type              - string defining the covariance type.  Options are 'kronecker' and 'uniform'.  Defualt is 'uniform'.
- log_thresh              - float threshold in log likelihood difference to determine convergence. Default value is 1e-3.
- max_steps               - integer maximum number of steps that the GMM procedure will do.  Default is 200.
- init_cluster_method     - string dictating how to initialize clusters.  Understood values are 'chunk', 'read' and 'random'.  Default is 'random'.
- sort                    - boolean dictating whether to sort the object by cluster population after fitting.  Default is True.
- kabsch_thresh           - float dictating convergence criteria for each iterative alignment (Maximization step).  Default value is 1e-1.
- dtype                   - Torch data type to be used.  Default is torch.float32.
- device                  - Torch device to be used.  Default is torch.device('cuda:0') device.
- verbose                 - boolean dictating whether to print various things at every step. Defualt is False.Fit:A standard fit can be performed in the following manner:uniform_aligned_trajectory = usgmm.fit(train_positions)kronecker_aligned_trajectory = wsgmm.fit(train_positions)wheretrain_positionsis an array of dimensions(n_train_frames, n_atoms, 3). Notice there is no difference in syntax when fitting the two covariance types.  Two additional options are available during the fit routine which may be necessary under certain situations:- cluster_ids   (optional) - (n_train_frames) integer array of initial cluster ids.  This option is necessary if init_cluster_method = 'read'
- frame_weights (optional) - (n_train_frames) float array of relative frame weights.  If none are provided the code assumes equal weights for all frames.If these options are used the fit call looks likeuniform_aligned_trajectory = usgmm.fit(train_positions, cluster_ids = initial_cluster_ids, frame_weights = train_frame_weights)kronecker_aligned_trajectory = wsgmm.fit(train_positions, cluster_ids = initial_cluster_ids, frame_weights = train_frame_weights)Predict:Once the shapeGMM object has been fit, it can be used to precict cluster IDs, aligned trajectory, and log likelihood per frame for a new, or cross validation, trajectory.  The number of atoms must remain the same.  The simple syntax is as follows:cluster_ids, aligned_traj, log_likelihood = usgmm.predict(predict_positions)clusters_ids, aligned_traj, log_likelihood = wsgmm.predict(predict_positions)wherepredict_positionsis an array of dimensions(n_predict_frames, n_atoms, 3). Notice there is no difference in syntax when precicting the two covariance types.  If the predict frames have a non-unifrom frame weight, this can be accounted for- frame_weights (optional) - (n_predict_frames) float array of relative frame weights.  If none are provided the code assumes equal weights for all frames.If this option is used the predict call will look likecluster_ids, aligned_traj, log_likelihood = usgmm.predict(predict_positions, frame_weights = predict_frame_weights)clusters_ids, aligned_traj, log_likelihood = wsgmm.predict(predict_positions, frame_weights = predict_frame_weights)AttributesAfter being properly fit, a shapeGMM object will have the following attributes:- n_clusters	             - integer of how many clusters were used in training
- n_atoms                    - integer of how many atoms were in the training data
- n_train_frames             - integer of how many frames were in the training data
- train_frame_weights        - float array of frane weights used in training 
- clusters_ids               - integer array of cluster ids for training data
- log_likelihood             - float log likelihood of training set
- train_frame_log_likelihood - float array of LLs for each frame
- weights                    - (n_clusters) float array of cluster weights
- centers	                 - (n_clusters, n_atoms, 3) float array of cluster centers/averagesUniform covariance specific attributes- vars		       	         - (n_clusters) float array of cluster variancesKronecker covariance specific attributes- precisions	   	         - (n_clusters, n_atoms, n_atoms) float array of cluster precisions (inverse covariances)
- lpdets	    	         - (n_clusters) float array of ln(det(covar))