Package: onion-clustering
timeseries_analysisCode for unsupervised clustering of time-series data. Reference tohttps://arxiv.org/abs/2402.07786for further details.Input dataA one-dimensional time-series, computed onNparticles forTframes. The input files must contain an array with shape(N, T)Supported formats: .npy, .npz, .txt. Also .xyz trajectories are supported, with the fifth column containing the data values.UsageInstall the package usingpip install onion_clustering.Theexamples/folder contains an example of usage. Runpython3 example_script.py, this will create the following files:A text file calledinput_parameters.txt, whose format is explained below;A text file calleddata_directory.txtcontaining one line with the path to the input data file (including the input data file name).
and run the code.input_parameters.txttau_window(int): the length of the time window (in number of frames).t_smooth(int, optional): the length of the smoothing window (in number of frames) for the moving average. A value oft_smooth = 1correspond to no smoothing. Default is 1.t_delay(int, optional): is for ignoring the first tau_delay frames of the trajectory. Default is 0.t_conv(int, optional): converts number of frames in time units. Default is 1.time_units(str, optional): a string indicating the time units. Default is'frames'.example_ID(int, optional): plots the trajectory of the molecule with this ID, colored according to the identified states. Default is 0.bins(int, optional): the number of bins used to compute histograms. This should be used only if all the fits fail with the automatic binning.num_tau_w(int, optional): the number of different tau_window values tested. Default is 20.min_tau_w(int, optional): the smaller tau_window value tested. It has to be larger that 1. Default is 2.max_tau_w(int, optional): the larger tau_window value tested. It has to be larger that 2. Default is the largest possible window.min_t_smooth(int, optional): the smaller t_smooth value tested. It has to be larger that 0. Default is 1.max_t_smooth(int, optional): the larger t_smooth value tested. It has to be larger that 0. Default is 5.step_t_smooth(int, optional): the step in the t_smooth values tested. It has to be larger that 0. Default is 1.OutputThe algorithm will attempt to perform the clustering on the input data, using differentt_smooth(frommin_t_smoothframes tomax_t_smoothframes, with steps ofstep_t_smooth) and differenttau_window(logarithmically spaced between 2 frames and the entire trajectory length, unless differently specified in the input parameters). The results are saved in the folowing files:number_of_states.txtcontains the number of clusters for each combination oftau_windowandt_smoothtested.fraction_0.txtcontains the fraction of unclassified data points for each combination oftau_windowandt_smoothtested.Figures with all the Gaussian fittings are saved in the folderoutput_figureswith the formatt_smooth_tau_window_Fig1_iteration.png.Then, the analysis with the values oftau_windowandt_smoothspecified ininput_parameters.txtwill be performed. The results are saved in the folowing files:states_output.txtcontains information about the recursive fitting procedure, useful for debugging.output_figures/Fig1_iteration.pngplot the histograms and best fits for each iteration.final_states.txtcontains the list of the states, for which central value, width and relevance are listed.final_tresholds.txtcontains the list of the tresholds between states.The analisys returns aClusteringObject, which contains methods for plotting all the results. They are listed in the example scripts.Multivariate time-series versionThemain_2d.pyalgorithm works in a similar fashion, taking as input 2D or 3D data. The input file contained indata_directory.txtmust contain an array of shape(D, N, T)whereDis the number of components. Only.npy, .npzare supported. You can find an example of usage inexamples/example_script_2d.pyRequired Python 3 packagesmatplotlib,numpy,plotly,scipy.Gaussian fitting procedureThe histogram of the time-series is computed, using thebins='auto'numpy option (unless a differentbinsis passed as imput parameter).The histogram is smoothed with moving average withwindow_size=3(unless there are less that 50 bins, in wich case no smoothing occurs).The absolute maximum of the histogram is found.Two Gaussian fits are performed:The first one inside the interval between the two minima surrounding the maximum.The second one inside the interval where the peak around the maxima has its half height.Both fits, if converged, are evaluated according to the following points:muis contained inside the fit interval;sigmais smaller than the fit interval;the height of the peak is at least half the value of the maximum;the relative uncertanty over the fit parameters is smaller than 0.5.Finally, the fit with the best score is chosen. If only one of the two converged, that one is chosen. If none of the fits converges, the iterative procedure stops, returning a warning message.AknowledgementsThanks to Andrew Tarzia for all the help with the code formatting and documentation, and to Domiziano Doria, Chiara Lionello and Simone Martino for the beta-testing. Writing all this code wouldn't have been possible without the help of ChatGPT.