Package: hawks
HAWKS is a tool for generating controllably difficult synthetic data,
used primarily for clustering.Thisrepois associated with the following paper:Shand, C.,Allmendinger, R.,Handl, J.,Webb, A., & Keane, J. (2019, July). Evolving controllably difficult datasets for clustering. In Proceedings of the Genetic and Evolutionary Computation Conference (pp. 463-471).https://doi.org/10.1145/3321707.3321761(Nominated for best paper on the evolutionary machine learning track at GECCO’19)The academic/technical details can be found there. What follows here is
a practical guide to using HAWKS to generate synthetic data.If you use HAWKS to generate data that forms part of a paper, please
cite the paper above and link to this repo.InstallationInstallation is available through pip by:pip install hawksor by cloning this repo (and installing locally usingpip install .). HAWKS was written for Python 3.6+. Other dependencies are specified in thesetup.pyfile.Running HAWKSThe parameters of hawks are configured via a config file system. Details
of the parameters are found in thedocumentation. For any parameters
that are not specified, default values will be used (as defined inhawks/defaults.json).The example below illustrates how to runhawks. Either a dictionary
or a path to a JSON config can be provided to override any of the
default values. Further examples can be foundhere."""Single, simple HAWKS run, with KMeans applied to the best dataset
"""importnumpyasnpfromsklearn.clusterimportKMeansfromsklearn.metricsimportadjusted_rand_scoreimporthawks# Set the magic seed numberSEED_NUM=42# Set the seed number in the configconfig={"hawks":{"folder_name":"simple_example","seed_num":SEED_NUM},"dataset":{"num_clusters":5},"objectives":{"silhouette":{"target":0.9}}}# Any missing parameters will take from hawks/defaults.jsongenerator=hawks.create_generator(config)# Run the generatorgenerator.run()# Let's plot the best individual foundgenerator.plot_best_indivs(show=True)# Get the best dataset found and it's labelsdatasets,label_sets=generator.get_best_dataset()# Stored as a list for multiple runsdata,labels=datasets[0],label_sets[0]# Run KMeans on the datakm=KMeans(n_clusters=len(np.unique(labels)),random_state=SEED_NUM).fit(data)# Plot the output of KMeanshawks.plotting.scatter_prediction(data,km.labels_)# Get the Adjusted Rand Index for KMeans on the dataari=adjusted_rand_score(labels,km.labels_)print(f"ARI:{ari}")DocumentationFor further information about how to use HAWKS, including examples, please see thedocumentation.IssuesAs this work is still in development, plain sailing is not guaranteed.
If you encounter an issue, first ensure thathawksis running as
intended by navigating to the tests directory, and runningpython tests.py. If any test fails, please add details of this
alongside your original problem to an issue on theGitHub repo.ContributingAt present, this is primarily academic work, so future developments will be released here after they have been published. If you have any suggestions or simple feature requests for HAWKS as a tool to use, please raise that on theGitHub repo.I have various directions for HAWKS at present, and can only work on a subset of them, and so involvement with more people would be great. If you would like to extend this work or collaborate, pleasecontact me.