FREECONTACT(1)

✨ NAME ✨

freecontact(1) — your new bestie for fast protein contact prediction 🧬💖 it's a User Command, it's iconic, it's here to slay.

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe, copy-paste style:

freecontact [OPTION]

freecontact --parprof [evfold|psicov|psicov-sd] < alignment.aln >
contacts.out

/usr/share/freecontact/a2m2aln --query '^RASH_HUMAN/(\d+)' <
alignment.fa | freecontact --parprof evfold > contacts.out

the big long one with all the flags:

freecontact --ali=ALIFILE --apply-gapth=BOOL --clustpc=NUM --density=NUM
--cov20=BOOL --estimate-ivcov=BOOL --gapth=NUM --icme-timeout=NUM
--input-format=[flat|xml] --mincontsep=NUM
--output-format=[evfold|pfrmat_rr|bioxsd] --pseudocnt=NUM
--pscount-weight=NUM --rho=NUM --threads=NUM --veczw=BOOL

and the ✨basic girl✨ invocations:

freecontact --help --debug --quiet --version

---

💅 DESCRIPTION 💅

FreeContact is a protein residue contact predictor optimized for speed. no cap. it can function as an accelerated drop-in for the published contact predictors EVfold-mfDCA of DS. Marks et al. (2011) [1], and PSICOV of D. Jones et al. (2011) [2]. so you get the same energy, but faster 🏃‍♀️💨

how is it fast tho? a combination of vector instructions, multiple threads, and faster implementation of key parts. depending on the alignment, 8-fold or higher speedups are possible. it's giving main character energy, honestly. 👑

⚠️ bestie, listen. a sufficiently large alignment is required for meaningful results. as a minimum, use an alignment with an effective (after-weighting) sequence count bigger than the length of the query sequence. alignments with tens of thousands of (effective) sequences are considered good input. small alignment? small slay. so go get the big one. 🫶

jackhmmer(1) or hhblits(1) can be used to generate the alignments, for example. (iykyk 💫)

the receipts, bestie, so you can cite correctly:

[1] PLoS One. 2011;6(12):e28766. doi: 10.1371/journal.pone.0028766. Epub 2011 Dec 7. Protein 3D structure computed from evolutionary sequence variation. Marks DS, Colwell LJ, Sheridan R, Hopf TA, Pagnani A, Zecchina R, Sander C.

[2] Bioinformatics. 2012 Jan 15;28(2):184-90. Epub 2011 Nov 17. PSICOV: precise structural contact prediction using sparse inverse covariance estimation on large multiple sequence alignments. Jones DT, Buchan DW, Cozzetto D, Pontil M.

🎀 Input

these are the formats it eats, nom nom:

• flat — the following simple input file format is used:

 # querystart=5
 # query=QUERYwithinsertionSEQUENCEWITHNOGAPSORINSERTIONS
 QUERYSEQUENCEWITHNOGAPSORINSERTIONS
 -ALIGNED---SEQUENCE--WITH-GAPS-----
 ANOTHER-ALIGNED------------SEQUENCE

the # header lines are optional. header lines are used to calculate contact residue numbers and to look up respective query residues for certain output formats.

if no query is defined, the first sequence in the alignment is used as the query sequence. and bestie — the query sequence must not contain gaps in the alignment. fr fr. 🚫

all alignment rows must be the same length, and may contain only [ABCDEFGHIJKLMNOPQRSTUVWXYZ-]. [B] is mapped to [D], [Z] is mapped to [E], [JOUX] are mapped to [X]. [X] matches only itself for the entire program. that last bit matters, don't come for me. 💀

A2M input alignments can be converted to the above format using /usr/share/freecontact/a2m2aln. and cute thing: a2m2aln can be used to pipe the alignment directly into freecontact. pipes are literally the love language of unix. 🥰

• xml — XML document with one <fc:alignment xmlns:fc="http://rostlab.org/freecontact/xsd"/> element, defined in the FreeContact schema [4] derived from BioXSD [5].

example: /usr/share/doc/freecontact/examples/PF00071_v25_1000.xml.

🦋 Output

the original EVfold-mfDCA or PSICOV output format is used by default when the respective parameter profile is selected. so it just knows. 💅

evfold (EVfold-mfDCA)

5 K 6 L 0.332129 3.59798
| | | | |        + corrected norm (CN) contact score
| | | | + mutual information (MI) score
| | | + contact amino acid residue code
| | + contact residue number
| + contact amino acid residue code
+ contact residue number

contacts are sorted on residue number.

pfrmat_rr (PSICOV)

CASP residue-residue separation prediction (PFRMAT RR) format [3]:

55 67 0 8 10.840280
|  |  | | + contact score
|  |  +-+ range [Å] of Cb-Cb distance predicted for the residue pair
|  |      (C-alpha for glycines)
|  |      These two fields are invariant in the output.
|  + contact residue number
+ contact residue number

contacts are sorted on score, descending. 📉

[3] <http://predictioncenter.org/casp10/index.cgi?page=format>

bioxsd

XML document with one <fc:contactMap xmlns:fc="http://rostlab.org/freecontact/xsd"/> element, defined in the FreeContact schema [4] derived from BioXSD [5].

example: /usr/share/doc/freecontact/examples/PF00071_v25_1000.evfold.50.xml.

📌 note: as BioXSD is under active development in collaboration with FreeContact, the FreeContact schema may actually be derived from a version not yet available at [5]. so don't be weird about it.

[4] <file:///usr/share/freecontact/freecontact.xsd>

[5] <http://bioxsd.org>

heads up: the output may not list all possible contacts. 👀 not a bug, just how it is.

---

🌈 REFERENCES 🌈

Submitted. FreeContact: fast and free direct residue-residue contact prediction. Kaján L, Sustik MA, Marks DS, Hopf TA, Kalaš M, Rost B.

---

💖 OPTIONS 💖

here's the whole menu, bestie, every single one, no skipping:

• -a [ --threads ] arg — threads to use [0-). 0 means as many as cores. let it cook on all cores 🔥
• --apply-gapth arg — when true, exclude residue columns and rows with a weighted gap frequency > --gapth from the covariance matrix [Boolean].
• -c [ --clustpc ] arg — BLOSUM clustering percentage [0-100].
• --cov20 arg — if true, leave one amino acid off the covariance matrix, making it non-overdetermined [Boolean]. one amino acid said "not today" 🙈
• -d [ --density ] arg — target precision matrix density [0-1]. set 0 to not control density. (so 0 = hands off 👋)
• --debug — turn on debugging.
• --estimate-ivcov arg — use inverse covariance matrix estimation instead of matrix inversion [Boolean].
• -f [ --ali ] arg (=-) — alignment file [path]. if -, standard input. default: -.
• -g [ --gapth ] arg — weighted gap frequency threshold (0-1].
• -h [ --help ] — produce this help message. the classic 🥹
• -i [ --input-format ] arg (=flat) — input format [flat|xml].
• --icme-timeout arg (=1800) — inverse covariance matrix estimation timeout in seconds [0-). applied to each iversion call independently. if a timeout occurs, the program exits with status 2. so, y'know, be aware ⏰
• --mincontsep arg — minimum sequence-wise contacting residue pair separation given in amino acids as (j-i>=arg). 1 for adjacent residues. [1-).
• -o [ --output-format ] arg — output format [evfold|pfrmat_rr|bioxsd].
• --parprof arg (=default) — parameter profile (optional) [default|evfold|psicov]. the default profile is evfold.

command line arguments can be used to override profile values. yes queen, override her 👑

• evfold — triggers EVfold-mfDCA [1] compatibility mode.
• psicov — triggers PSICOV [2] compatibility mode.
• psicov-sd — triggers PSICOV [2] sensible default mode: fixed default rho, no density control. sensible! we love a sensible default 💅

• -w [ --pscount-weight ] arg — pseudocount weight [0-1].
• -p [ --pseudocnt ] arg — pseudocount [0-).
• --pep — print effective parameters on standard error. use this option to see what parameters freecontact(1) is run with in detail. this is especially useful when the --parprof option is used in combination with other options. peek behind the curtain, it's your right 🫶
• --rho arg — initial value of Glasso regularization parameter [0-). if negative, choose value automatically.
• --quiet arg (=0) — print nothing but error messages on standard error. does not affect --debug. 🤫
• --veczw arg — use vectorized sequence weighting when available [Boolean].
• --version — print version.

---

😭 EXIT STATUS 😭

• 0 — no error - success. slay! 🎉
• 1 — unspecified error. 💀
• 2 — a timeout (see --icme-timeout) occurred. ⏰

---

⭐ EXAMPLES ⭐

steal these, they're tested:

 /usr/share/freecontact/a2m2aln --query '^RASH_HUMAN/(\d+)' < '/usr/share/doc/freecontact/examples/PF00071_v25_1000.fa' | \
 freecontact --parprof evfold > PF00071_v25_1000.evfold

 freecontact --parprof evfold -i xml -o bioxsd < '/usr/share/doc/freecontact/examples/PF00071_v25_1000.xml' > PF00071_v25_1000.evfold.xml

 freecontact --parprof psicov < /usr/share/doc/freecontact/examples/demo_1000.aln > demo_1000.psicov

---

🧚 NOTES 🧚

for optimal performance, use the Automatically Tuned Linear Algebra Software (ATLAS) library compiled on the machine where freecontact is run. compile it where you run it, bestie, it's bespoke 🎀

---

💜 AUTHOR 💜

László Kaján <lkajan@rostlab.org>

---

🌈 SEE ALSO 🌈

jackhmmer(1), hhblits(1), blastpgp(1)

---

okay that's literally the whole page 💖 this was version 1.0.21, dated 2026-02-04, from the freecontact(1) manual — go forth and predict those contacts, bestie, you're gonna eat 🫶✨👑