Package: pyleiden
pyLeidenA CLI tool for clustering with theLeidenalgorithm.Installation# pip:pipinstallpyleiden# pipx:pipxinstallpyleiden# conda:condainstall-cconda-forgepyleiden# mamba:mambainstall-cconda-forgepyleidenOptionsusage: pyleiden [-h] [-v] [-o {CPM,modularity}] [-r RESOLUTION_PARAMETER]
                [-b BETA] [-n NUMBER_ITERATIONS] [-s SEED] [-q]
                INPUT OUTPUT

pyLeiden: a CLI tool for clustering with the Leiden algorithm.

positional arguments:
  INPUT                 Tabular file containing the edges of the network.
                        The first two columns should be elelemnts that
                        are connected via an edge in the graph. A third
                        column may be provided with numerical values that
                        represent the weight of the edge.
  OUTPUT                Cluster membership. Each line contains all the
                        members of a given cluster separated by a tab.

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -o {CPM,modularity}, --objective-function {CPM,modularity}
                        Whether to use the Constant Potts Model (CPM) or
                        modularity. (default: CPM)
  -r RESOLUTION_PARAMETER, --resolution-parameter RESOLUTION_PARAMETER
                        The resolution parameter to use. Higher
                        resolutions lead to more smaller clusters, while
                        lower resolutions lead to fewer larger clusters.
                        (default: 1.0)
  -b BETA, --beta BETA  Parameter affecting the randomness in the Leiden
                        algorithm. This affects only the refinement step
                        of the algorithm. (default: 0.01)
  -n NUMBER_ITERATIONS, --number-iterations NUMBER_ITERATIONS
                        The number of iterations to iterate the Leiden
                        algorithm. Each iteration may improve the
                        partition further. Using a negative number of
                        iterations will run until a stable iteration is
                        encountered (i.e. the quality was not increased
                        during that iteration). (default: 2)
  -s SEED, --seed SEED  Seed for the random number generator. (default:
                        1953)
  -q, --quiet           Run quietly (will not print output to stout).
                        (default: False)ExampleTo showcase the pyLeiden's functionality, we will cluster plasmid sequences retrieved from thePLSDBdatabase into PTUs. These PTUs correspond to distinct groups of plasmids sharing a minimum of 95% average nucleotide identity (ANI) and 85% aligned fraction (AF) among their members.First we download the plasmid DNA sequences from PLSDB and useSeqKitto format the FASTA file by leaving only the sequence accessions in the headers:curl-Lhttps://ccb-microbe.cs.uni-saarland.de/plsdb/plasmids/download/plsdb.fna.bz2\|seqkitseq--only-id--upper-case\>plsdb.fnaNext, we will estimate the ANI and AF between pairs of plasmids withskani:skanidist-t16-c80-s70--qiplsdb.fna--riplsdb.fna-oskani_output.tsvskani's output will look like this:Ref_file    Query_file   ANI      Align_fraction_ref   Align_fraction_query   Ref_name        Query_name
---------   ----------   ------   ------------------   --------------------   -------------   ----------
plsdb.fna   plsdb.fna    100.00   97.78                97.78                  AB063523.1      AB063523.1
plsdb.fna   plsdb.fna    100.00   99.60                99.60                  AB244976.1      AB244976.1
plsdb.fna   plsdb.fna    99.85    73.12                97.91                  NZ_CP005192.1   AB244976.1
plsdb.fna   plsdb.fna    99.43    17.38                23.08                  NZ_CP005087.1   AB244976.1
plsdb.fna   plsdb.fna    97.62    30.27                15.22                  NC_020563.2     AB244976.1
plsdb.fna   plsdb.fna    97.35    3.90                 17.27                  NZ_CP005190.1   AB244976.1
plsdb.fna   plsdb.fna    96.86    82.16                8.60                   NZ_CP060130.1   AB244976.1
plsdb.fna   plsdb.fna    95.74    5.37                 15.52                  NC_014007.1     AB244976.1
plsdb.fna   plsdb.fna    94.39    48.82                46.12                  NZ_CP009296.1   AB244976.1To use pyLeiden, a tabular file listing pairwise relationships between plasmids (edges) is required as input. This file should have a minimum of two columns indicating the connected plasmids, but a third column indicating the strength of the connection is also accepted. This allows the similarity levels of pairs of plasmids to be considered during clustering.To generate the input file for pyLeiden from skani's output we can useawk:awk'NR>1 && $3>=95 && ($4>=85 || $5>=85) {printf("%s\t%s\t%.4f\n", $6, $7, $3 * ($4 > $5 ? $4 : $5) / 10000)}'skani_output.tsv>edges.tsvThis command performs three actions: (1) removes the header that was present in skani's output; (2) filters out edges that do not meet the minimum ANI or AF criteria (ANI ≥ 95% and AF ≥ 85%); (3) computes edge weights using the following formula: $Weight = \frac{ANI \times \max(AF_{query}, AF_{target})}{10000}$.Theedges.tsvfile will look like this:AB063523.1      AB063523.1   1.0000
AB244976.1      AB244976.1   1.0000
NZ_CP005192.1   AB244976.1   0.9796
NZ_CP060130.1   AB244976.1   0.8365
AB576781.2      AB576781.2   0.9993
JF274991.1      AB576781.2   0.9993
JF274992.1      AB576781.2   0.9999
NZ_CP040565.1   AB576781.2   0.8565
NZ_CP039596.1   AB576781.2   0.8512
NZ_CP043905.1   AB576781.2   0.8544Finally, we can run pyLeiden to cluster the plasmids into PTUs:pyleidenedges.tsvclusters.txt[1/3]Readinginputfileandbuildingthegraph.[2/3]Clusteringnodes.[3/3]Writingoutputfile.Totalnumberofnodes:34,511Totalnumberofclusters:14,794In the output file (clusters.txt), plasmids that were clustered together will be in the same line and separated by tab characters.NZ_CP042577.1	NZ_CP073307.1	NZ_CP056765.1	NZ_CP047764.1	NZ_CP058117.1	NZ_CP068289.1	NZ_CP056154.1
NZ_CP056221.1	NZ_CP056383.1	NZ_CP056363.1	NZ_CP056898.1	NZ_CP056900.1	NZ_CP056353.1	NZ_CP056825.1
NZ_CP073733.1	NZ_CP073724.1	NZ_CP073739.1	NZ_CP073727.1	NZ_CP073730.1	NZ_CP073742.1	NZ_CP073736.1
NZ_LC586266.1	NZ_LC586264.1	NZ_LC586263.1	NZ_LC586268.1	NZ_LC586265.1	NZ_LC586267.2	NZ_LC586262.1
AP018702.1	NZ_CP065814.1	NZ_CP020461.1	NZ_MF383377.1	NZ_LT960792.1	NZ_CP075332.1
NZ_CP075287.1	NZ_CP064176.1	NZ_CP039605.1	NZ_CP070552.1	NZ_MN543574.1	NZ_CP047338.1
AP022387.1	NZ_AP022395.1	NZ_AP022400.1	NZ_AP022514.1	NZ_AP022495.1	NZ_KY014464.1
AP022442.1	NZ_CP067387.1	NZ_AP024180.1	NZ_CP055455.1	LR890443.1	LR890483.1
NZ_CP041424.1	NZ_CP032799.1	NZ_CP041430.1	NZ_CP041434.1	NZ_CP041432.1	CP049610.1
CP049186.1	CP049172.1	CP045525.2	CP049170.1	NZ_CP042338.1	NZ_MW646303.1You can control the granularity of the clustering using--resolution-parameter:pyleiden--resolution-parameter0.2edges.tsvclusters.txt[1/3]Readinginputfileandbuildingthegraph.[2/3]Clusteringnodes.[3/3]Writingoutputfile.Totalnumberofnodes:34,511Totalnumberofclusters:13,135When decreasing the--resolution-parameterfrom the default value of1.0to0.2, the number of clusters decreased from 14,794 to 13,135. In practice, lower values of--resolution-parameterwill result in larger clusters whose members are more loosely connected.