Программа PairHits
Программа входит в состав комплекса iHCE для поиска высококонсервативных элементов (ВКЭ) в наборе геномов. Она находит все пары приближённо совпадающих слов-кандидатов в двух последовательностях из разных геномов и тем самым формирует рёбра исходного графа. Программа предназначена для параллельных вычислений в среде MPI на высокопроизводительном кластере с 64-битной операционной системой Windows или Linux.
Программа PairHits написана на С++ и имеет интерфейс командной строки. Формат командной строки:
pairhits [options] [config_file]
(Здесь указано имя программы в Linux; вариант для Windows 64-bit c MPICH2 имеет имя pairhits64, с Microsoft MPI -- pairhits64ms, без MPI -- pairhits64nompi).
Опции указываются в одном из форматов: /x[ значение] -x[ значение] --x...xx[=значение] (у некоторых опций значение отсутствует). В основном опции предназначены для изменения обычных значений параметров программы, которые указаны в файле конфигурации или установлены по умолчанию (значения в командной строке имеют наивысший приоритет).
Список распознаваемых опций командной строки и значения по умолчанию
| -? --help |
Выдает подсказку о параметрах командной строки программы. |
| -a --append |
Осуществляется дозапись в конец выходного файла, если он уже существует (по умолчанию -- как указано в файле конфигурации; если не указано ничего, то файл перезаписывается). |
| -b число --belt=число |
Максимально допустимое число подряд идущих делеций, а также общее число делеций при отсутствии инсерций (0 означает, что делеции вообще запрещены). Значение -1 указывает, что ограничений на число делеций нет. Значение по умолчанию 2. |
| -с имя_файла --config=имя_файла |
Имя файла конфигурации программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. По умолчанию используется файл "config.ini" в рабочей директории программы. |
| -d число --score_del=число |
Величина штрафа за делецию (неотрицательная цена операции вставки/удаления буквы). Округляется до одного знака после запятой. Значение по умолчанию 2,1. |
| -e число --minletter=число |
Указывается двухзначное число, у которого старшая цифра указывает минимально допустимое число разных букв в искомом слове (максимум 4), а младшая -- в ключе поиска. Значение 0 указывает, что ограничений на встречаемость букв нет. Значение по умолчанию 43. |
| -f имя --fastapath=имя |
Общий префикс имён файлов, содержащих исходные геномные последовательности в формате FASTA или GenBank (последнее только если геном состоит из единственной последовательности); обычно это путь к соответствующему каталогу. Переменная часть имён указывается в разделе [species] файла конфигурации. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. По умолчанию используется каталог "fasta\" в рабочей директории. |
| -i число --score_mis=число |
Величина штрафа за несовпадение (неотрицательная цена операции замены одной буквы на другую). Округляется до одного знака после запятой. Значение по умолчанию 1. |
| -j имя_файла --job=имя_файла |
Имя файлов заданий для программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Символ '#' в имени файла интерпретируется как порядковый номер, с тем условием, что файлы заданий пронумерованы без пропусков, начиная с некоторого значения (по умолчанию с 0, но может задаваться опцией -t). По умолчанию используется значение "jobs\#.txt". Заметим, что номер файла должен состоять из постоянного числа цифр (при необходимости слева добавляются незначащие нули); разрядность задаётся опцией -y или определяется автоматически. |
| -k число --key=число |
Минимальная длина точно совпадающего участка искомой пары слов. Значение по умолчанию 16. |
| -l число --length=число |
Нижний порог длины искомых слов (рассматриваются только слова с длиной строго больше порога). Значение по умолчанию 60. |
| -n --nompi |
Заставляет мультипроцессорную версию программы работать в однопроцессорном режиме, даже в среде MPI. Иногда при отсутствии в системе среды MPI этой опции может оказаться недостаточно (программа завершается аварийно); в таких случаях следует использовать вариант программы без MPI. |
| -o имя_файла --log=имя_файла |
Имя файла для протокола работы программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Символ '#' в имени файла интерпретируется как номер процессора, при условии, что в файле конфигурации задана раздельная выдача протокола каждой параллельной ветви программы. По умолчанию используется имя "phs_log#.txt". |
| -p число --step=число |
Шаг выбора ключей из первой последовательности при её индексации. Значение по умолчанию 1. |
| -q число --frequency=число |
Порог числа повторений ключа в первой последовательности, при превышении которого ключ не рассматривается. Значение 0 означает отсутствие такого порога. Значение по умолчанию 200. |
| -r имя_файла --result=имя_файла |
Имя файлов результатов программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Символ '#' в имени файла указывает место, где будет указан номер задания (см. опцию -j). По умолчанию используется значение "results\#.txt". |
| -s число --maxscore=число |
Максимально допустимая суммарная величина штрафа за несовпадение слов. Округляется до одного знака после запятой. Значение по умолчанию 17,5. |
| -t число --start=число |
Номер файла заданий, с которого программа должна начать работу (см. также опции -j, -u). Значение по умолчанию 0. |
| -u число --use=число |
Максимальное число файлов заданий, которое программа будет пытаться выполнить, в текущей реализации не более 100000 (см. также опции -j, -t). Значение по умолчанию 10000. |
| -w --rewrite |
Осуществляется перезапись выходного файла, если он уже существует (см. также опцию -a). По умолчанию выбирается режим, указанный в файле конфигурации; если не указано ничего, файл перезаписывается. |
| -y число --width=число |
Число цифр в номере файла задания, в текущей реализации не более 5 (см. также опцию -j). Значение по умолчанию 0 указывает, что разрядность номера будет определяться автоматически (это возможно не всегда, см. ниже описание параметра width файла конфигурации). |
| -z число --ratio=число |
Максимально допустимый коэффициент сжатия искомых слов алгоритмом gzip; если слово сжимается больше, оно отбрасывается. Значение 0 означает, что такая проверка достаточной сложности найденных слов не выполняется. Значение по умолчанию 2,2. |
Первый же аргумент командной строки, не являющийся ни одной из вышеперечисленных опций или её значением, интерпретируется как имя файла конфигурации (аналогично значению опции -c).
Файл конфигурации программы
Файл конфигурации является обязательным; это текстовый файл со структурой, традиционной для конфигурационных файлов (примеры файла есть в составе контрольных примеров для Windows и Linux). Строки файла не могут переноситься; пустые строки игнорируются. Строки, начинающиеся символом ';' или '#', рассматриваются как комментарии и также игнорируются программой. Для комментариев в информационных строках может использоваться пара символов "косая черта" (//); начиная с неё, остаток строки игнорируется.
Информационные строки бывают двух видов: заголовок раздела (формат [имя_раздела]) и значение параметра (формат параметр = значение, где в качестве разделителей между левой частью, знаком равенства и правой частью может использоваться один или более пробелов или символов табуляции). Разделом конфигурации называется часть файла, начиная с заголовка раздела и вплоть до следующего заголовка раздела или до конца файла. Порядок параметров внутри раздела произвольный. Файл конфигурации может содержать несколько разделов в произвольном порядке, за исключением раздела [common], который должен стоять первым, и раздела [species], который должен стоять последним. Программа PairHits использует только разделы [common] (если есть), [pairhits], [species], и игнорирует прочие разделы файла конфигурации.
Список распознаваемых параметров конфигурации в разделе [pairhits]
| splitlog | Задаёт режим выдачи протокола работы параллельной версии программы. В правой части указывается булевское значение "истина" (в любом из форматов yes true 1 +) или "ложь" (в любом из форматов no false 0 -). Если указано истинное значение, каждая параллельная ветвь программы формирует собственный протокол работы, имя которого задаётся параметрами logname, logext или опцией -o в командной строке (последний способ имеет приоритет перед остальными). Если этот параметр отсутствует в разделе [pairhits], используется значение из раздела [common], если нет и там, принимается значение "истина". |
| logname | Указывает имя файла протокола (без расширения), которое может включать путь. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если установлено splitlog = true, то к указанному имени автоматически добавляется номер параллельной ветви, начиная с 0. Если этот параметр отсутствует в разделе [pairhits], используется значение из раздела [common], если нет и там, принимается значение "phs_log". Значение может быть изменено с помощью опции -o в командной строке, причём эта опция модифицирует сразу три параметра splitlog, logname, logext. |
| logext | Указывает расширение имени файла протокола. Если этот параметр отсутствует в разделе [pairhits], используется значение из раздела [common], если нет и там, принимается значение ".txt". Значение может быть изменено с помощью опции -o в командной строке, причём эта опция модифицирует сразу три параметра splitlog, logname, logext. |
| errname | Указывает имя (без расширения) файла для протокола ошибок программы, которое может включать путь. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если установлено splitlog=true, то к указанному имени автоматически добавляется номер параллельной ветви, начиная с 0. Если этот параметр отсутствует в разделе [pairhits], используется значение из раздела [common], если нет и там, принимается значение "phs_err". Если указано пустое значение, протокол ошибок не формируется. |
| errext | Указывает расширение имени файла протокола. Если этот параметр отсутствует в разделе [pairhits], используется значение из раздела [common], если нет и там, принимается значение ".log". |
| jobpath | Указывает имя файлов заданий для программы, которое может включать путь. Если имя содержит пробелы, соответствующее значение целиком заключается в кавычки. Если параметр не указан, используется значение "jobs\". К имени автоматически добавляется номер задания, начиная с 0 (или иного значения, указанного параметром start). Номер дополняется слева незначащими нулями до фиксированного числа разрядов, которое задаётся параметром width (или определяется автоматически). Значение параметра может быть изменено с помощью опции -j в командной строке, причём эта опция модифицирует сразу два параметра jobpath, jobext. |
| jobext | Указывает расширение имени файлов заданий. Если параметр не указан, используется значение ".txt". Значение может быть изменено с помощью опции -j в командной строке, причём эта опция модифицирует сразу два параметра jobpath, jobext. |
| fastapath | Указывает общий префикс имён файлов с исходными геномными последовательностями в формате либо FASTA, либо GenBank; обычно это путь к соответствующему каталогу. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если параметр отсутствует, используется его значение из раздела [common], а по умолчанию -- каталог "fasta\" в рабочей директории. Переменная часть имён указывается в разделе [species]. Значение может быть изменено с помощью опции -f в командной строке. |
| result | Указывает имя файла результатов программы (без расширения), которое может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. К указанному имени автоматически добавляется номер файла заданий, для которого получены содержащиеся в файле результаты. Для каждого файла заданий формируется один либо ни одного файла результатов. Значение может быть изменено с помощью опции -r в командной строке, причём эта опция модифицирует сразу два параметра result, resext. По умолчанию используется значение "results\" (т.е. результаты записываются в поддиректорию results рабочей директории и имя файла совпадает с номером файла заданий). |
| resext | Указывает расширение имени файла результатов, по умолчанию ".txt". Значение может быть изменено с помощью опции -r в командной строке, причём эта опция модифицирует сразу два параметра result, resext. |
| append | Задаёт режим записи файлов протокола и/или результатов в случаях, когда файл с таким именем уже существует. В правой части указывается булевское значение "истина" (в любом из форматов yes true 1 +) или "ложь" (в любом из форматов no false 0 -). Если указано истинное значение, производится дозапись в конец файла (старое содержимое сохраняется). В противном случае или если параметр не указан, файл перезаписывается заново (старое содержимое теряется). Заданный режим может быть изменён с помощью опций командной строки -a, -w. Если этот параметр не указан, файлы перезаписываются. |
| width | Задаёт число цифр в номере файла заданий (в текущей реализации максимум 5). Значение по умолчанию 0 указывает, что разрядность номера должна определяться автоматически (это возможно лишь в том случае, если в каталоге, указанном параметром jobpath, присутствует файл задания с первым подлежащим выполнению номером, т.е. указанным в параметре start или принятым по умолчанию нулевым). Заданное значение может быть изменено с помощью опции -y в командной строке. |
| keysize | Указывает минимальную длину точно совпадающего участка для искомой пары слов. Рекомендуется выбирать кратное 4 значение в интервале от 16 до 48. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 16. Заданное значение параметра можно изменить с помощью опции -k в командной строке. |
| keystep | Задаёт шаг выбора ключей из первой последовательности при её индексации. Заданное значение можно изменить с помощью опции -p в командной строке. Значение по умолчанию 1. |
| frequency | Указывает порог числа повторений ключа в первой последовательности, при превышении которого ключ не рассматривается. Значение 0 означает отсутствие такого порога. Заданное значение можно изменить с помощью опции -q в командной строке. Значение по умолчанию 200. |
| length | Указывает нижний порог длины искомых слов (рассматриваются только слова с длиной строго больше порога). Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 60. Значение параметра можно изменить с помощью опции -l в командной строке. |
| ratio | Указывает максимально допустимый коэффициент сжатия искомых слов алгоритмом gzip; если слово сжимается больше, оно отбрасывается. Ноль означает, что такая проверка достаточной сложности найденных слов не выполняется. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 2,2. Значение может быть изменено опцией -r в командной строке. |
| serial_del | Задаёт максимально допустимое число подряд идущих делеций, а также общее число делеций при отсутствии инсерций (0 означает, что делеции вообще запрещены). Значение -1 указывает, что ограничений на число делеций нет. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 2. Значение может быть изменено опцией -b в командной строке. |
| maxscore | Задаёт максимально допустимую суммарную величину штрафа за несовпадение слов. Округляется до одного знака после запятой. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 17,5. Значение может быть изменено опцией -s в командной строке. |
| score_del | Задаёт величину штрафа за делецию (неотрицательная цена операции вставки/удаления буквы). Округляется до одного знака после запятой. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 2,1. Заданное значение может быть изменено опцией -d в командной строке. |
| score_mis | Задаёт величину штрафа за несовпадение (неотрицательная цена операции замены буквы). Округляется до одного знака после запятой. Если параметр не указан в разделе [pairhits], берётся значение из раздела [common], если нет и там, то по умолчанию принимается 1. Заданное значение может быть изменено опцией -i в командной строке. |
| start | Указывает номер файла заданий, с которого программа должна начать работу. При отсутствии файла заданий с таким номером, программа проверяет следующий номер, и т.д. Заданное значение может быть изменено опцией -t в командной строке. Значение по умолчанию 0. |
| stop | Указывает максимальное число файлов заданий, которые программа будет пытаться выполнить, начиная с указанного параметром start. Заданное значение может быть изменено опцией -u в командной строке. Значение по умолчанию 10000, ограничение текущей реализации 100000. |
| minletter | Задаёт двухзначное число, у которого старшая цифра указывает минимально допустимое число разных букв в искомом слове (максимум 4), а младшая -- в ключе поиска. Значение 0 указывает, что ограничений на встречаемость букв нет. Заданное значение может быть изменено опцией -e в командной строке. Значение по умолчанию 43. |
Список исходных данных в разделе [species]
Этот раздел устанавливает связь между идентификатором и названием организма, присвоенным ему номером и именами файлов исходных данных. Каждая строка соответствует одному организму. Программа игнорирует пустые строки файла, а также строки, начинающиеся с символа ';' или '#'. Пробелы и символы табуляции в начале строки игнорируются. Строка содержит по меньшей мере 5 полей, которые разделены одним или более символов табуляции. Внутри полей могут содержаться пробелы. Смысл полей следующий:
- номер организма (уникальный внутри одного набора исходных данных);
- краткое обозначение (идентификатор) организма, в текущей реализации короче 36 символов;
- наименование организма;
- таксономический код (см. описание параметра diversity программы FinDense);
- имя файла с геномом в формате FASTA или GenBank. Весь геном должен содержаться в одном файле. Путь к файлу указывается параметром fastapath в файле конфигурации или в командной строке запуска программы в соответствии с правилами используемой ОС, он может быть абсолютным или относительно рабочей директории.
- необязательное поле, содержащее имя файла с аннотацией генома в формате GFF; программа PairHits не использует это поле.
Файлы заданий и параллельное исполнение программы
Запуск программы PairHits инициирует поиск слов-кандидатов в заданных парах последовательностей из разных геномов, последовательно или параллельно в зависимости от используемого варианта программы и параметров запуска. Пары подлежащих обработке последовательностей указываются в виде набора файлов заданий, с помощью параметров конфигурации jobpath, jobext, start, stop или соответствующих опций командной строки. Примеры таких наборов файлов заданий есть в составе контрольных примеров для Windows и Linux (в каталоге jobs). Каждый файл заданий указывает одну последовательность из "первого" генома (в первой строке файла) и одну или более последовательностей из "второго" генома (во второй и последующих строках файла), причём "вторых" геномов может быть несколько; вместе они образуют столько пар, сколько указано последовательностей всех "вторых" геномов. Все строки файла заданий имеют одинаковый формат, хотя первая строка относится к "первому" геному, а последующие -- ко "вторым". В начале строки должен стоять по меньшей мере один пробел и/или символ табуляции, который заменится на звёздочку по окончании обработки строки. Далее должны идти три числовых поля, разделённые одним или более пробелом или символом табуляции. Смысл полей:
- номер организма (один из указанных в списке исходных данных),
- порядковый номер последовательности в файле генома в FASTA-формате, либо 1 в случае файла GenBank (впоследствии эти номера появятся в результатах),
- смещение заголовка последовательности (конкретно, символа '>') от начала данного файла генома, начиная с 0.
Каждый файл заданий всегда обрабатывается одной параллельной ветвью программы вплоть до исчерпания всех пар, затем эта ветвь переходит к следующему необработанному файлу заданий, если таковые еще остались. Обработанные последовательности второго генома отмечаются в файле заданий символом "звёздочка" (*) в первой позиции соответствующих строк (такие строки файла заданий пропускаются), что позволяет продолжить прерванную работу программы (для таких случаев предусмотрен режим дозаписи протокола и результатов программы в существующие файлы, см. опции -a, -w и параметр конфигурации append). Однопроцессорная версия программы обрабатывает файлы заданий по очереди в порядке возрастания номера в имени файла. Каждая ветвь многопроцессорной версии начинает обработку с файла заданий, который имеет номер, равный номеру процессора в запрошенном пуле; следующий номер файла заданий для этой ветви получается прибавлением к предыдущему номеру общего числа процессоров в пуле.
Если файлов заданий мало, то при запуске бессмысленно запрашивать больше процессоров, чем файлов заданий. Общее время расчётов будет определяться самым долго обрабатываемым файлом заданий. В первом приближении время обработки файла заданий пропорционально длине последовательности из первого генома и сумме длин последовательностей из всех вторых геномов, которые указаны в этом файле. Поэтому при относительно небольшом числе геномов и их последовательностей имеет смысл разделить на части те файлы заданий, обработка которых предположительно будет длиться долго, с соответствующим увеличением числа запрашиваемых процессоров. Если же файлов заданий значительно больше, чем доступных процессоров, нагрузка балансируется автоматически, если нумерация файлов заданий соответствует убыванию трудоёмкости. В частности, может помочь упорядочение последовательностей внутри каждого генома по убыванию их длины, а геномов -- по убыванию их суммарной длины.
Файлы результатов
Если в результате обработки некоторого файла заданий найдена хотя бы одна искомая пара слов, программа PairHits создает файл результатов в каталоге, указанном параметром конфигурации result; в имени файла результатов используется номер этого файла заданий. Файл результатов -- это текстовый файл, все строки которого содержат один и тот же набор из 11 полей переменной длины, разделённых одним символом табуляции (если позволяют размеры, файл результатов можно непосредственно загрузить в электронную таблицу Excel). Содержание полей следующее:
- номер первого генома
- номер последовательности в первом геноме
- якорь слова в последовательности первого генома ("якорь" -- это сумма начальной и конечной позиции слова в последовательности, т.е. удвоенная позиция середины слова)
- длина слова в первом геноме
- номер второго генома
- номер последовательности второго генома
- якорь слова в последовательности второго генома
- длина слова во втором геноме
- указатель цепи во втором геноме (одно из значений 1, -1 или 0)
- редакционное расстояние между словами (суммарный штраф за несовпадение), увеличенное в 10 раз
- коэффициент сжатия слова алгоритмом gzip.