Package: goodpoints
GoodPointsA Python package for generating concise, high-quality summaries of a probability distributionGoodPoints is a collection of tools for compressing a distribution more effectively than independent sampling:Given an initial summary of n input points,kernel thinningreturns s << n output points with comparable integration error across a reproducing kernel Hilbert spaceCompress++reduces the runtime of generic thinning algorithms with minimal loss in accuracyCompress Then Testaccelerates kernel two-sample testing using high-fidelity compressionInstallationTo install thegoodpointspackage, use the following pip command:pip install goodpointsGetting startedThe primary kernel thinning function isthinin thektmodule:fromgoodpointsimportktcoreset=kt.thin(X,m,split_kernel,swap_kernel,delta=0.5,seed=None,store_K=False,meanK=None,unique=False,verbose=False)"""Returns kernel thinning coreset of size floor(n/2^m) as row indices into XArgs:X: Input sequence of sample points with shape (n, d)m: Number of halving roundssplit_kernel: Kernel function used by KT-SPLIT (often a square-root kernel, krt,or a target kernel, k); split_kernel(y,X) returns array of kernel evaluationsbetween y and each row of Xswap_kernel: Kernel function used by KT-SWAP (typically the target kernel, k);swap_kernel(y,X) returns array of kernel evaluations between y and each row of Xdelta: Run KT-SPLIT with constant failure probabilities delta_i = delta/nseed: Random seed to set prior to generation; if None, no seed will be setstore_K: If False, runs O(nd) space version which does not store kernelmatrix; if True, stores n x n kernel matrixmeanK: None or array of length n with meanK[ii] = mean of swap_kernel(X[ii], X);used to speed up computation when not Noneunique: If True, constrains the output to never contain the same row index more than onceverbose: If False, do not print intermediate time taken in thinning rounds,if True print that info"""For example uses, please refer toexamples/kt/run_kt_experiment.ipynb.The primary Compress++ function iscompressppin thecompressmodule:fromgoodpointsimportcompresscoreset=compress.compresspp(X,halve,thin,g)"""Returns Compress++(g) coreset of size sqrt(n) as row indices into XArgs:X: Input sequence of sample points with shape (n, d)halve: Function that takes in an (n', d) numpy array Y and returnsfloor(n'/2) distinct row indices into Y, identifying a halved coresetthin: Function that takes in an (2^g sqrt(n'), d) numpy array Y and returnssqrt(n') row indices into Y, identifying a thinned coresetg: Oversampling factor"""For example uses, please refer toexamples/compress/construct_compresspp_coresets.py.A more efficient convenience function is available when one wants to run Compress++ to speed up kernel thinning:fromgoodpointsimportcompresscoreset=compress.compresspp_kt(X,kernel_type,g=g,mean0=mean0)"""Returns KT-Compress++(g) coreset of size sqrt(n) as row indices into XArgs:X: Input sequence of sample points with shape (n, d)kernel_type: Byte string name of kernel to useg: Oversampling parameter, a nonnegative integermean0: If False, final KT call minimizes MMD to empirical measure overthe input points. Otherwise minimizes MMD to the 0 measure; thisis useful when the kernel has expectation zero under a target measure."""The primary Compress Then Test function iscttin thecttmodule:fromgoodpointsimportctttest_results=ctt.ctt(X1,X2,g)"""Compress Then Test two-sample test with sample sequences X1 and X2and auxiliary kernel k' = target kernel k.Args:X1: 2D array of size (n1,d)X2: 2D array of size (n2,d)g: compression level; integer >= 0B: number of permutations (int)s: total number of compression bins will be num_bins = min(2*s, n1+n2)lam: positive kernel bandwidthkernel: kernel name; valid options include "gauss" for Gaussian kernelexp(-||x-y||^2/lam^2)null_seed: seed used to initialize random number generator forrandomness in simulating nullstatistic_seed: seed used to initialize random number generator forrandomness in computing test statisticalpha: test leveldelta: KT-Compress failure probabilityReturns: TestResults object."""For example uses, please refer toexamples/mmd_test/test.py.ExamplesCode in theexamplesdirectory uses thegoodpointspackage to recreate the experiments of the following research papers.Kernel Thinning@article{dwivedi2021kernel,
  title={Kernel Thinning},
  author={Raaz Dwivedi and Lester Mackey},
  journal={arXiv preprint arXiv:2105.05842},
  year={2021}
}The scriptexamples/kt/submit_jobs_run_kt.pyreproduces the vignette experiments of Kernel Thinning  on a Slurm cluster
by executingexamples/kt/run_kt_experiment.ipynbwith appropriate parameters. For the MCMC examples, it assumes that necessary data was downloaded and pre-processed following the steps listed inexamples/kt/preprocess_mcmc_data.ipynb, where in the last code block we  report the median heuristic based bandwidth parameteters (along with the code to compute it).After all results have been generated, the notebookexamples/kt/plot_results.ipynbcan be used to reproduce the figures of Kernel Thinning.Generalized Kernel Thinning@inproceedings{dwivedi2022generalized,
  title={Generalized Kernel Thinning},
  author={Raaz Dwivedi and Lester Mackey},
  booktitle={International Conference on Learning Representations},
  year={2022}
}The scriptexamples/gkt/submit_gkt_jobs.pyreproduces the vignette experiments of Generalized Kernel Thinning on a Slurm cluster by executingexamples/gkt/run_generalized_kt_experiment.ipynbwith appropriate parameters. For the MCMC examples, it assumes that necessary data was downloaded and pre-processed following the steps listed inexamples/kt/preprocess_mcmc_data.ipynb.Once the coresets are generated,examples/gkt/compute_test_function_errors.ipynbcan be used to generate integration errors for different test functions.After all results have been generated, the notebookexamples/gkt/plot_gkt_results.ipynbcan be used to reproduce the figures of Generalized Kernel Thinning.Distribution Compression in Near-linear Time@inproceedings{shetty2022distribution,
  title={Distribution Compression in Near-linear Time},
  author={Abhishek Shetty and Raaz Dwivedi and Lester Mackey},
  booktitle={International Conference on Learning Representations},
  year={2022}
}The notebookexamples/compress/script_to_deploy_jobs.ipynbreproduces the experiments of Distribution Compression in Near-linear Time in the following manner:It generates various coresets and computes their mmds by executingexamples/compress/construct_{THIN}_coresets.pyforTHINin{compresspp, kt, st, herding}with appropriate parameters,
where the flag kt stands for kernel thinning, st stands for standard thinning (choosing every t-th point), and herding refers to kernel herding.It computes the runtimes of different algorithms by executingexamples/compress/run_time.py.For the MCMC examples, it assumes that necessary data was downloaded and pre-processed following the steps listed inexamples/kt/preprocess_mcmc_data.ipynb.The notebook currently deploys these jobs on a slurm cluster, but setting deploy_slurm = False inexamples/compress/script_to_deploy_jobs.ipynbwill submit the jobs as independent python calls on terminal.After all results have been generated, the notebookexamples/compress/plot_compress_results.ipynbcan be used to reproduce the figures of Distribution Compression in Near-linear Time.Compress Then Test: Powerful Kernel Testing in Near-linear Time@inproceedings{domingoenrich2023compress,
  title={Compress Then Test: Powerful Kernel Testing in Near-linear Time},
  author={Carles Domingo-Enrich and Raaz Dwivedi and Lester Mackey},
  booktitle={Proceedings of The 26th International Conference on Artificial Intelligence and Statistics},
  year={2023},
  series={Proceedings of Machine Learning Research},
  month={25--27 Apr},
  publisher={PMLR}
}Seeexamples/mmd_test/README.md.ContributingThis project welcomes contributions and suggestions.  Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visithttps://cla.opensource.microsoft.com.When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
provided by the bot. You will only need to do this once across all repos using our CLA.This project has adopted theMicrosoft Open Source Code of Conduct.
For more information see theCode of Conduct FAQor
contactopencode@microsoft.comwith any additional questions or comments.TrademarksThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
trademarks or logos is subject to and must followMicrosoft's Trademark & Brand Guidelines.
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.