SMILE(1)

SMILE(1) 💅✨

okay bestie, this is a General Commands Manual page and we're calling her by her government name up top: SMILE(1). the actual star of the show is mlv-smile. let's go 🫶

---

✨ NAME ✨

mlv-smile — inference of structured signals in multiple sequences 🌸

---

🎀 SYNOPSIS 🎀

mlv-smile <parameter_file>
mlv-smile [-g number]

---

💖 DESCRIPTION 💖

okay so real talk, this manual page is just the quick lil rundown of the mlv-smile command, fr fr. if you want the whole tea — more details, examples, all of it — you gotta go peep the documentation files that come installed with it. 📚

mlv-smile is a program that was primarily made to extract promoter sequences from DNA sequences. the way this is iconic is that it infers several motifs at the same time — those are called boxes btw — and they all have to respect distance constraints. so you, the user, write out a parameter_file listing all the criteria you want the signal to respect.

then it happens in two steps, bestie:

1. first step of extraction: all signals respecting those criteria get found. all of them.
2. second step: they all get statistically evaluated, and the goal is to detect the ones that are exceptionally represented in the original sequences. 👑

and since the 1.4 version, mlv-smile lets you extract such signals on any alphabet in any kind of sequences. not just DNA. she's versatile like that. 💅

---

🌈 OPTIONS 🌈

usually the program is just sitting there waiting for a parameter file that has all the criteria in it. and the only option is:

• -g number — produces on the standard output a generic parameter file to extract number boxes signals. yep that's the whole list. one option. minimal. clean. slay. ✨

---

🦋 HOW TO 🦋

🌸 How to use mlv-smile?

the only command you'll ever use is 'mlv-smile'. you give it just one parameter: the name of a parameters file that should contain the characteristics of the motifs you wanna extract. that's it. one job. she does it. 💅

🌸 How to start?

first you gotta write an alphabet file, which contains the alphabet used to describe the motifs. then you write a parameter file. and then?? you're literally ready to use mlv-smile. no cap. 🫶

🌸 What should I write in the alphabet file?

okay so the first line should contain the type of the alphabet's elements, and you choose between "Nucleotides", "Proteins", or "Others". this is so mlv-smile can do stuff like change, for instance, the "A or G" symbol into an R in DNA sequences. cute right?

then, on each line, you write the elements of the motif's alphabet.

Example: if you wanna extract simple motifs (A,C,G,T) from clean DNA sequences written with a four letters alphabet (A,C,G,T), then you may write an alphabet file containing:

Type:Nucleotides
A
C
G
T

let's call this file 'alpha'. 💖

🌸 How to write a simple parameter file?

first, write an alphabet file (yes again, it's the prerequisite bestie). you also need a sequence file, at the FASTA format. then you can create a parameter file, using the "mlv-smile -g number_of_boxes" command to help you out. 🎀

Example: let's write a parameter file to extract simple motifs. if you don't already have one, let's first create a small DNA file in FASTA format, containing several sequences:

> Seq A
AGGCTAGTCAGGGCATGCGATCAGCAGGCATCAGGCGAGCATCGACAGCA
> Seq B
GGAGAGCGCAGAGCGAGCATCATCATGCAGCATCAGAGATCTTTCT

let's call this file 'seq'. 🦋

our purpose is now to extract from these sequences all motifs of length 13 that appears at least one time in 100% of the sequences, allowing one substitution. we may write the following parameter file (helped with the 'mlv-smile -g 1' command):

FASTA file          seq     // previously created
Output file         results

Alphabet file       alpha   //previously created
Quorum              100
Total min length    13
Total max length    13
Total substitutions 1
Boxes               1

let's call this file 'param'. ✨

🌸 How to extract a simple motif?

you can launch "mlv-smile" after having created the alphabet and parameter files. easy.

Example: with the previous alphabet, sequences and parameter files, you can now launch mlv-smile: "mlv-smile param". you will obtain the following motifs in the "results" file:

GCGAGCATCAACA 2120210310010 2
Seq     1   Pos    12
Seq     0   Pos    34
2
GCGAGCATCGTCA 2120210312310 2
Seq     1   Pos    12
Seq     0   Pos    34
2

the first motif found, GCGAGCATCAACA, appears at position 12 in the second sequence and position 34 in the first one. and heads up bestie — all positions or sequences counts starts at zero. periodt. 💅

🌸 How to evaluate the significance of the motifs found?

you have to add some evaluation lines at the end of the parameter file. that's the whole trick. 👑

Example: at the bottom of the previous "param" parameter file, you can add:

Shufflings  100
Size k-mer  2

which means that the original sequences will be shuffled 100 times, conserving dinucleotides. the significance of the motifs found previously will be computed from their frequency of apparition in the shuffled sequences. and lowkey important: the more number of shuffling you do, the more stable are the results — but it's longer to compute. 😭

for this example, you may find such results (in the "results.shuffle"):

STATISTICS ON THE NUMBER OF SEQUENCES HAVING AT LEAST ONE OCCURRENCE
Model          %right  #right %shfl. #shfl. Sigma Chi2 Z-score
==============================================================
GCGAGCATCGTCA  100.00%    2   0.50%   0.01  0.10  3.96   19.90
GCGAGCATCAACA  100.00%    2   1.00%   0.02  0.14  3.92   14.07

STATISTICS ON THE TOTAL NUMBER OF OCCURRENCES
Model            #right  #shfl. Sigma   Chi2    Z-score
=======================================================
GCGAGCATCGTCA        2   0.01   0.10    1.99    19.90
GCGAGCATCAACA        2   0.02   0.14    1.96    14.07

the first block of results shows the statistics on the number of sequences having at least one occurrence. you can read, for each motif found, the frequency of apparition in the original and shuffled sequences, and two statistical scores (Chi2 and Z-score) deduced. motifs are sorted according to the highest Z-scores. a high Z-score means that the motif appears in a surprising way in the original sequences. she's special and the math said so. 💖

🌸 How to extract structured motifs?

the parameter file should be modified to indicate the characteristics of the structured motifs to infer. you have to write global parameters for the whole motif, and local parameters for each box of it. two layers, very main character energy. 👑

Example: let's extract from the previous "seq" sequences structured motifs composed of 2 boxes of length 5 to 6, but the whole motif must have a length 11. the two boxes may be separated by 10 to 15 nucleotides. you allow at most one substitution in each box, and at least one occurrence of a motif must appear in 100% of the sequences, you may write the following parameter file:

FASTA file          seq
Output file         results

Alphabet file       alpha
Quorum              100
Total min length    11
Total max length    11
Total substitutions 2
Boxes               2

BOX 1 ================
Min length          5
Max length          6
Substitutions       1
Min spacer length   10
Max spacer length   15

BOX 2 ================
Min length          5
Max length          6
Substitutions       1

💖 PARAMETER FILE CRITERIA 💖

okay bestie, this is the part where you tell mlv-smile what you actually want. it's giving "fill out the form, but make it motif discovery." every line here matters, so let's go one by one. ✨

• FASTA File <filename> — the name of the file with the sequences you're using for inference. these sequences must be in FASTA format. and bestie, it must have at least two sequences, because you literally cannot detect motifs that are common to several sequences in just one sequence! 😭 no cap.
• Output file <filename> — the name of the file where the results of extraction will be written. that's where the magic lands. 💅
• Alphabet file <filemane> — the name of the file where you tell mlv-smile which alphabet it'll infer motifs on. (yes, the original says filemane, we're keeping it, it's iconic in a typo way 🫶.) the first line contains "Type:" followed by the type of symbols you use: choose between "Nucleotides", "Proteins" or "Others". then, on each line of the file, you write the symbols of the sequence that may be matched by a symbol of a motif. a line containing "ANR" means there's a symbol in the motif's alphabet which matches A, N or R in the sequences. if Type is defined with Nucleotides, mlv-smile will change this ANR symbol into an A to make it more readable. these associations will be printed at the beginning of the execution. ✨
• Quorum <number> — the percentage of sequences where at least one occurrence of a motif must appear to make it valid. 100 means a motif must have occurrences in every sequence. so if you set 100, it's all or nothing, periodt. 👑
• Total min length <number> — the minimal length of the whole motif, i.e. the sum of minimal lengths of each box. ⚠️ warning: the length of the gaps between boxes mustn't be taken into account. (original typo says "mustn't me taken into account", but we got you.) the total minimal length may differ from the sum of boxes' minimal length: you can, for instance, infer motifs made of two boxes, with min length of boxes equal to 4 and a total min length equal to 10. so yeah, it's not always just addition. 🧠
• Total max length <number> — same explanation as Total min length, except that a 0 length means "infinity". so 0 = no cap, literally. 🌈
• Total substitutions <number> — total maximum number of substitutions for the whole motif. as for the total length, this is not necessarily the sum of each box's substitution number. so don't just add them up, bestie. 💅
• Boxes <number> — the number of boxes that compose the motifs to infer. when inferring simple one-box motifs, it's not necessary to use local criteria as global and local criteria will be the same. so if you're doing one box, you can chill on the local stuff. 😌
• Composition in <symbol> <number> [OPTIONAL] — the number of a given symbol of the motif's alphabet may be restrained to a maximum by this criteria. optional, but it's giving "keep that symbol in check." 🎀
• BOX <number> — begin the description of the criteria of a given box of the motif. this is your "okay, next box, let's talk about it" moment. 📦
• Min length <number> — minimum length for the current box.
• Max length <number> — same explanation as Min length, except that a 0 length means "infinity". again, 0 = infinity, no cap. 🦋
• Substitution <number> — maximum number of substitutions allowed for the current box.
• Composition in <symbol> <number> [OPTIONAL] — same as the global composition, but for the current box. optional, but useful if one box is being extra. 🙈
• Min spacer length <number> — minimum number of symbols between the end of the current box and the beginning of the next one. this parameter mustn't appear in the last box's criteria, which has no next box! so don't put it there, bestie, it literally has no next box to space from. 🚫
• Max spacer length <number> — same explanation as Max spacer length. (yes, it references itself in the original, and we're not about to fix that typo. iconic self-reference, we move. 💅)
• Delta <number> [OPTIONAL] — this criteria allows one to infer motifs composed of several boxes without really knowing the distance between these boxes. the min and max spacer length will be used as a "large" interval, and the delta's value will define the size of small intervals into this large one. an inference of two-box motifs with a [10-20] range of distance between the boxes will produce motifs whose occurrences respect this range. a "Delta" criteria fixed to 2, for instance, will realize the same inference in all the possible ranges [i-delta, i+delta] (here: [10-14], [11-15], ...). as many output files as different ranges will be produced. so yes, multiple files, multiple vibes. 📂
• Palindrome of box <number> [OPTIONAL] — indicate that the concerned box must be the biological palindrome of one of the previous boxes. optional, but if you need that mirror moment, here it is. 🪞
• Shufflings <number> [OPTIONAL] — the number of shufflings of the original sequences to realize for the evaluation of the statistical significance of the motifs found. optional, but it's the "let's see if this is actually significant" button. 🔥
• Size k-mer <number> [OPTIONAL, always with shuffling] — length of the words to conserve during shufflings (usually 2). so if you're shuffling, this comes along. always with shuffling, bestie. 🧚
• Against wrong sequences <filename> [OPTIONAL] — another method to evaluate the significance of the motifs (not compatible with the shuffling method). in the case where you have a sequence file where you believe that the motifs you look for in the first sequences set won't appear, you can give to mlv-smile such a sequence file. the statistical evaluation of motifs found will be made by computing their frequency in the "wrong sequences". (original says theit, we keep it, typo and all. 😭) also, not compatible with shuffling, so pick your fighter. 💀

⚠️ WARNING ⚠️

mlv-smile is an exact combinatorial algorithm. it is not made to infer any kind of motifs. the amount of data where the extraction is made can be very large, but some criteria (in particular the number of substitutions) must be restrained to reasonable values: one or two substitutions allowed in a 10 length motif is ok, but not 6 or 8 substitutions. the notion of spacers is made to avoid the use of too much substitutions. (original says "to much", we keep it.) so don't go feral with substitutions, bestie, the algorithm will not have a good time. 💀

🐛 BUGS 🐛

a bug has been found in the 1.46 version, which could generate wrong results in some particular cases. in particular, results may be wrong for incoherent length criteria. there are still probably a lot of bugs in mlv-smile. this 1.47 version is quite stable, but do not hesitate to report any bug to <lama AT prism.uvsq DOT fr>. so yeah, if you find something cursed, email them. 📧

👀 SEE ALSO 👀

this software has been implemented from an algorithm proposed in

L. Marsan and M.-F. Sagot, Algorithms for extracting structured motifs using a suffix tree with application to promoter and regulatory site consensus identification", J. of Comput. Biol. 7, 2001, 345-360

you should refer to these paper for algorithmic details. if bored by such things, just notice that the extraction step of mlv-smile is exact, which means that all motifs respecting the given criteria are found. please quote this article if you produce some results given by mlv-smile. (original says "these paper", we keep it.)

for some examples of applications we made on biological datas (with good results), refer to

A. Vanet and L. Marsan and M.-F. Sagot,"Promoter sequences and algorithmically methods for identifying them", Research in Microbiology 150, 1999, 779-799

and

A. Vanet and L. Marsan and A. Labigne and M.-F. Sagot, Inferring regulatory elements from a whole genome. An application to the analysis of genome of Helicobacter Pylori Sigma 80 family of promoter signals", J. Mol. Biol. 297, 2000, 335-353

✍️ AUTHOR ✍️

this manual page was written by Laurent Marsan <lama AT prism.uvsq DOT fr>, for the Debian GNU/Linux system (but may be used by others). so shoutout to Laurent for writing this whole thing. 👑

---

and that's the whole vibe, bestie. this page signs off as SMILE(1) — version 1.47 is the stable one mentioned, and the date is whatever the manpage footer says (it's not printed here, so consider it timeless ✨). go infer some motifs, and remember: exact combinatorial algorithm, not a magic wand. 💖