CLMMATE(1)

💖 clm mate — bestie edition 💖

okay so this is the manual page for clm mate(1), which lives in the USER COMMANDS corner of the universe, and no cap it's a whole vibe. it's part of the clm family and it's here to help you find the best matches between two clusterings. slay.

---

✨ NAME ✨

clm_mate — compute best matches between two clusterings

okay so first thing's first, bestie, and this is important: clmmate is not in actual fact a program. 😭 it's not a lil binary you run, it's a mode. this manual page documents the behaviour and options of the clm program when it's invoked in mate mode.

also, heads up: the options -h, --apropos, --version, -set, and --nop are accessible in all clm modes — like, every single one. they're described over in the clm manual page, so go peek there if you need the tea on those. 🫖

---

🌸 SYNOPSIS 🌸

clm mate [-o fname (output file name)] [-b (omit headers)] [--one-to-many
(require multiple hits in <clfile1>)] [-h (print synopsis, exit)]
[--apropos (print synopsis, exit)] [--version (print version, exit)]
<clfile1> <clfile2>

she's giving "two files, one dream." 🦋

---

👑 DESCRIPTION 👑

so here's the whole entire point: clm mate computes, for each cluster X in clfile1, all the clusters Y in clfile2 that have a non-empty intersection with it. and then it outputs a line with all the data points listed below. periodt. 💅

here's the lineup of what you get on each line, in order:

overlap(X,Y)               # 2 * size(meet(X,Y)) / (size(X)+size(Y))
index(X)                   # name of cluster
index(Y)                   # name of cluster
size(meet(X,Y))
size(X-Y)                  # size of left difference
size(Y-X)                  # size of right difference
size(X)
size(Y)
projection(X, clfile2)     # see below
projection(Y, clfile1)     # see below

okay so let's talk about that projected size real quick because it's lowkey the main character here. the projected size of a cluster X relative to a clustering K is simply the sum of all the nodes shared between any cluster Y in K and X — and yes, duplications are allowed. 🙈

for example, the projected size of (0,1) relative to {(0,2,4), (1,4,9), (1,3,5)} equals 3. there you go, math ate. 🍓

now, the overlap between X and Y is exactly 1.0 if the two clusters are literally identical — iconic — and for nearly identical clusterings the score will be close to 1.0. so close! so near! 🥹

---

🌈 the contingency matrix tea 🌈

ngl bestie, all of this information can also be obtained from the contingency matrix defined for two clusterings. let me explain.

the [i,j] row-column entry in a contigency matrix between to clusterings gives the number of entries in the intersection between cluster i and cluster j from the respective clusterings. (yes, that's how the original spells it — "contigency" — and I'm keeping it fr fr. ✍️)

the other information is implicitly present — like it's all just vibing in there. for example, the total number of nodes in clusters i and j can be obtained as the sum of entries in row i and column j respectively, and the difference counts can then be obtained by subtracting the intersection count. easy math, no stress. 💅

and the contingency matrix can easily be computed using mcx. e.g.

mcx /clfile2 lm /clfile1 lm tp mul /ting wm

this will create the contingency matrix in mcl matrix format in the file ting, where columns range over the clusters in clfile1. (yes, the file is called ting. we love her. 💖)

---

🎀 using the output 🎀

the output can be put to good use by sorting it numerically on that first score field. and listen — it is advisable to use a stable sort routine (use the -s option for UNIX sort). don't skip that part, bestie, it matters. 🫶

from this information one can quickly extract the closest clusters between two clusterings. obsessed. 🔥

---

💅 OPTIONS 💅

• -o fname (output file name) — specify the name of the output file. that's it. that's the whole thing.
• -b (omit headers) — batch mode, omit column names. no headers, just vibes. 🙈
• --one-to-many (require multiple hits in <clfile1>) — do not output information for clusters in the first file that are subset of a cluster in the second file. like, if it's fully contained in one thing over there? we're not doing that today. ✋

---

🦋 AUTHOR 🦋

Stijn van Dongen. (the icon, the legend, the moment. 👑)

---

🌟 SEE ALSO 🌟

mclfamily(7) for an overview of all the documentation and the utilities in the mcl family. go read it, it's giving encyclopedia but make it cute. 📚✨

---

and that's the whole page, bestie!! 🥰 this was clm mate version 22-282, dated 9 Oct 2022. mwah. 💋 🎀🦋🌸💖