XPSA(5)

✨ NAME ✨

xpsa — the extended psa header, bestie 💖

---

🌸 DESCRIPTION 🌸

okay so xpsa is literally an extension of the psa(5) file format that the pftools package uses to describe and store biological sequences. it's giving glow-up but for a header. ✨

xpsa uses keyword=value pairs in the header to sneak in info about the sequence, or about the alignment between the sequence and a PROSITE profile (or honestly any other kind of motif). the syntax is therefore super easily extensible, which is the whole point. in this man page we're focusing on the keywords that the pftools package itself defines and uses. 🎀

heads up: in the text below we use the more general term 'motif' even when we're actually talking specifically about PROSITE profiles. but fr fr, the keywords defined here can be used by any kind of sequence analysis tool to store and transfer information. no gatekeeping. 💅

also — none of the defined keywords are mandatory, and analysis tools often have a length limit imposed on the header line. so to keep the header line reasonably short and user readable, those tools can easily just remove individual keyword=value pairs that aren't important to the specific task at hand. slay, minimalism. 🦋

---

🧚 SYNTAX 🧚

here's the general syntax of the xpsa header. for examples, pls refer to the corresponding examples section below. 👑

the biological sequence itself starts on the next line following the header and may extend over several lines. if several sequences are contained in the same file, each must be preceded by a header line. no skipping. 🙈

syntax of the header line:

>seq_id/seq_pos { [ keyword=value | free_text ] }

the header must start with a '>' followed by the fields detailed below:

• seq_id — typically the accession number and identifier of the sequence. this text field should not contain any spaces.

Note: if the input sequences have a well defined accession number and identifier (as is the case with SWISS-PROT entries), pfsearch(1) and pfscan(1) will use as seq_id the accession number separated by a '|' from the identifier. if the input sequences are in FASTA format, no guess can be made about the accession number or the identifier. therefore pfsearch(1) and pfscan(1) will use as seq_id all text following the '>' character up to the first whitespace.

• seq_pos — this field describes the sequence coordinates where a motif matches. the positions are generally given as start_pos-end_pos pairs. if present, this field is separated from the seq_id by a '/' character.
• keyword=value — an optional list of defined keyword=value pairs. each pair should be separated from the next, or from free text, by whitespaces. the keyword is case sensitive in the current implementation of the pftools package. it should not exceed 24 characters in length. the value can be numeric or alphanumeric. values containing whitespaces should be enclosed in either single quotes or double quotes. if the same type of quote appears inside the value it must be escaped using the '\' character.

Note: the pftools do not currently produce quote enclosed values.

• free_text — typically this is a description of the sequence. it should not contain any of the defined keyword=value pairs.

🌈 Keywords 🌈

💜 Keywords used by the pfsearch(1) and pfscan(1) programs

• level — the highest cut-off level (as a value) exceeded by the alignment. the characters 'NA' indicate that the alignment score does not exceed any of the cut-off levels defined in the motif.
• level_tag — the highest cut-off level (as a character string) exceeded by the alignment. the characters 'NA' indicate that the alignment score does not exceed any of the cut-off levels defined in the motif.

Note: pfsearch(1) and pfscan(1) only report the first 2 characters of the level text string.

• match_nb — if the motif matches several times on the same sequence, each alignment is numbered incrementally. if the motif is circular, each single repeat is numbered incrementally with the key repeat_nb (see below).
• match_parent — for each single match of a circular motif, this key references the number of the parental total match of the circular motif.

Note: if a circular motif matches only once on a given sequence, pfsearch(1) and pfscan(1) do not report this key.

• match_type — identifies the type of match. either region for a complete match of a motif to a sequence, or repeat for a single repeat of a circular motif.
• motif — the name and/or identifier of the motif.
• motif_start — the motif position where the alignment begins.
• motif_end — negative offset from the end of the alignment to the end of the motif.
• norm_score — the normalized score of the alignment.
• raw_score — the raw score of the alignment.
• repeat_nb — if the motif is circular, each individual repeat is numbered incrementally with this keyword.
• seq_end — negative offset from the end of the alignment to the end of the sequence. in combination with the information given by seq_pos this allows to deduce the length of the query sequence.
• strand — the sequence strand on which the motif matches, when the search includes the reverse complement of a DNA sequence. the value is either s for the sens or r for the reverse strand.

🫶 Keywords used by the pfmake(1) and pfw(1) programs

• weight — the weight of a given sequence in a multiple alignment.

---

⭐ EXAMPLES ⭐

(1)

>O00628|PEX7/73-315 motif=PS50294|WD_REP raw_score=1336
match_nb=1 match_type=region seq_end=-491
VTW[...]IYD
>O00628|PEX7/540-801 motif=PS50294|WD_REP raw_score=1378
match_nb=2 match_type=region seq_end=-5
SFD[...]PAS

the 2 headers above describe 2 matches of the motif called 'WD_REP' onto the sequence 'PEX7'. each of the matches onto this single sequence is numbered using the the match_nb keyword. these matches are not individual repeats of a circular motif, as can be seen with the region value of the match_type keyword. the first match starts at position 73 of the sequence and ends at position 315. this position is 491 residues away from the end of the input sequence (seq_end). the next line following the xpsa(5) header line is the sequence of the match (it has been truncated here to help readability). the second match begins at position 540 of the sequence and terminates 5 residues before the end of the input sequence, that is at position 801. 😌

(2)

>O00628|PEX7/540-582 motif=PS50294|WD_REP norm_score=7.437
raw_score=180 match_parent=2 repeat_nb=1 match_type=repeat
level=-1 seq_end=-224 motif_start=1 motif_end=-1
SFD[...]PLQ

this example illustrates the kind of header you get when aligning a circular motif to a sequence. each match of this motif (which we will call total match) can be composed of several individual repeats of the motif. tools like pfsearch(1) and pfscan(1) can output each total match followed by all its individual repeats. in this example we only show one of the indiviual repeats that is part of a total match between a circular profile and a sequence. 🌀

the xpsa(5) header above describes a single repeat of a match between a circular motif called 'WD_REP' and the sequence 'PEX7'. this is the first individual repeat of a match of the circular motif, as identified by the repeat_nb keyword. the other individual repeats have not been listed in this example.

the total circular motif has at least 2 distinct matches on the 'PEX7' sequence, because this single repeat is part of the second match as described by the match_parent keyword. the parental matches have been omitted from this example, they would be numbered using the match_nb keyword.

the normalized score of this motif exceeds the cut-off level number -1 (level keyword) which is specified in the motif.

this match starts at position 1 of the profile (motif_start) and position 540 of the sequence, it ends at the end of the motif (motif_end=-1) and position 582 of the sequence.

the next line following the xpsa(5) header line is the sequence of the match (it has been truncated here to help readability). ✨

---

🔥 SEE ALSO 🔥

psa(5), pfsearch(1), pfscan(1), pfw(1), pfmake(1), psa2msa(1)

---

👑 AUTHOR 👑

this manual page was originally written by Volker Flegel.

the pftools package was developed by Philipp Bucher.

any comments or suggestions should be addressed to <pftools@sib.swiss>. 🫶

---

okay that's the whole page bestie, go forth and align 💖 this was pftools version 2.3, dated July 2003, and yes she's an icon, she's a legend, and she IS the moment. mwah 💅✨