Package: pong
This document serves as a quick-start guide and reference card for installing and using pong. Please refer to thesoftware manualfor comprehensive information.Installing pongpong has been tested on macOS (10.8-11), Linux (Ubuntu 15.04, Linux Mint 17.2), and Windows 7.pong is hosted onPyPIand can thus be easily installed withpip. In order to run pong, you need Python 3 (version 3.6 or newer) and a modern web browser.To install pong, run:pip3installpongNote to Python 2 users:Older versions of pong run on Python 2.7. The latest version of pong compatible with Python 2 can be installed withpip install pong==1.4.9Linux-specific tipsOn some Linux systems, the install command may fail due to a permissions error. In that case, try runningsudo pip install ponginstead. You will be prompted to enter in your computer login password. If that doesn't work either, try running the command as the super user:su# you will be prompted to enter an administrator passwordpipinstallpongexitMac-specific tipsNote that the Apple system default Python cannot run pong. Python 3 andpipcan be installed manually, but we find that setup is easiest if you use(mini)condaorHomebrew. For example:# If you have Miniconda (or Anaconda)condainstallpython
condainstallpip
pipinstallpong# Or, if you don't want to install pong in your base environmentcondacreate-nmy-pong-envpythonpip
condaactivatemy-pong-env
pipinstallpong# Or, using Homebrewbrewinstallpython[brewupgradepython]pipinstallpip[pipinstall--upgradepip]pipinstallpong[pipinstall--upgradepong]Running pongpong is executed through the command line. To see a complete list of options, run:pong-hNote to Windows users:On some Windows systems, pong may not be installed as an executable, and thus cannot be run using this command. Instead, replacepongwithpython3 \path\to\pong.We have provided an example dataset on which you can run pong (available onGitHubor theRamachandran Lab website). Using data from the1000 Genomes ProjectPhase3 (2,426 individuals), we performed 8 runs of ADMIXTURE at each value ofKfromK=2 toK=8. To analyze the example dataset with pong, navigate to the unzipped example directory and run:pong-mpong_filemap-iind2pop.txt-npop_order_expandednames.txtInformation regarding pong's application to the input data will be displayed to your terminal window. After its algorithms complete, pong initializes a web server onlocalhost:4000(you can change the port on which pong operates with the command line option--port). Once you navigate tolocalhost:4000on your web browser, pong will detect a new browser connection and begin rendering the visualization.Example screenshot:Tip:Click on the question mark at the top of the screen for a quick tutorial on how to interact with pong's web app (including highlighting multimodality and downloading plots).Running pong on your own datapong's setup is designed to be low-hassle. This section details the required and optional input files that pong handles.Clustering outputpong accepts clustering output files, orQmatrices, from a variety of clustering inference programs. The command line option-c, or--ignore_cols, tells pong how many leading columns of each row of the inputQmatrix files to skip before parsing individual membership coefficients. For example, use-c 5for some versions ofStructureindiv output to ignore covariate metadata. In the case that no leading columns should be skipped (e.g. for ADMIXTURE output), it is not necessary to provide-c 0because the default value of-cis 0.A few related notes:Don't worry about trailing columns; they will not be parsed (after-cleading columns are ignored, only the firstKcolumns are used).pong parsesQmatrix files as whitespace-delimited by default. If, for some reason, this is not the case with your input data, you can specify any column delimiter with the option--col_delim(e.g.--col_delim ","for CSV files, or--col_delim "\t"for tab-delimited files).While pong does handle leading/trailing columns inQmatrices, it does not handle leading/trailing rows. These rows must be stripped prior to analysis with pong (i.e. for a dataset withnsamples, everyQmatrix file should havenlines).filemapfileA bit of information about the inputQmatrices must be provided, in the form of afilemap. Afilemapis a three-column, tab-delimited file. Each line contains the following information about a singleQmatrix:A unique ID (e.g.iter5_K=7; this must contain at least one letter, and cannot contain a hashmark/hashtag or a period. Integers, spaces, and other special characters are accepted.)TheKvalueTheQmatrix file path, relative to thefilemap. Thus, if thefilemapis in the same directory as theQmatrix files, this is just the name of theQmatrix file.It is important that the columns of yourfilemapare in the right order and that the file is tab-delimited. Use thefilemapprovided with the example dataset for reference. Use the command line option-m, or--filemap, to pass pong the path to your yourfilemap.Population labels (optional)ind2popdata:It is common forQmatrices to be annotated with population metadata. In many datasets, individuals are assigned a population code/label/number; we refer to this asind2popdata. If provided with this information, pong's visualization will sort individuals by population, partition populations with black lines, and sort individuals within each population by their membership in the population's major cluster.* Other covariates, such as continent or language spoken, can also be used asind2popin place of population metadata.You can provideind2popdata with the command line option-i, or--ind2pop. The argument to this option can be either of the following:An integer, representing theQmatrix column number that containsind2popdata. For example, use-i 4for standardStructureoutput.The path to anind2popfile, where lineiof this file contains theind2popdata (i.e. population code/label/number) for the individual represented by lineiof theQmatrix files.Note that the population codes/labels/numbers provided asind2popdata should not contain any whitespace.Population order and detailed names:If you provideind2popdata, you may provide an additional file specifying the desired order in which to display the populations (as the argument to the command line option-n). This file should have one population code/label/number per line; the top-to-bottom order of the file corresponds with the left-to-right display order of the populations.You may want to more descriptive population names to be displayed (e.g. if the inputind2popdata are numbers, cryptic three-letter codes, etc.); in this case, you can add a second column (tab-delimited) to the population order file containing population names. Space charactersareallowed in these names. See the filepop_order_expandednames.txtin the example dataset for reference.Custom colors for visualization (optional)pong provides default colors (unlessK_max> 26), but it is possible to provide pong with a file containing a set of colors to use for visualization (using the command line option-l). This file must contain at leastK_maxcolors, with one color per line. Because pong's visualization is web-based, colors can be provided in any format that is accepted by CSS (e.g.#ff0000,rgb(255,0,0),red).Additional resourcesThe example dataset, software manual, and other relevant materials can be found at theRamachandran Lab website.ContactAaron BehrorSohini Ramachandranfor more information.*We have found that this sorting operation makes it much easier to understand the distribution of cluster membership within each population. Note that pong performs this sorting operation on a singleQmatrix (the bottom-most plot in the main visualization, which is the representative run of the major mode of the highestK-value) and propagates that order through all the other visualizedQmatrices, such that the ordering of individuals is consistent across all plots.