Lab.6 IITP RAS logo
26/08/19
03:15:21

Лаборатория математических методов и моделей в биоинформатике
Института проблем передачи информации им. А.А. Харкевича
Российской академии наук

« back

Программа 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 полей, которые разделены одним или более символов табуляции. Внутри полей могут содержаться пробелы. Смысл полей следующий:

  1. номер организма (уникальный внутри одного набора исходных данных);
  2. краткое обозначение (идентификатор) организма, в текущей реализации короче 36 символов;
  3. наименование организма;
  4. таксономический код (см. описание параметра diversity программы FinDense);
  5. имя файла с геномом в формате FASTA или GenBank. Весь геном должен содержаться в одном файле. Путь к файлу указывается параметром fastapath в файле конфигурации или в командной строке запуска программы в соответствии с правилами используемой ОС, он может быть абсолютным или относительно рабочей директории.
  6. необязательное поле, содержащее имя файла с аннотацией генома в формате GFF; программа PairHits не использует это поле.
Образцы списка исходных данных имеются в составе контрольных примеров для Windows и Linux.

Файлы заданий и параллельное исполнение программы

Запуск программы PairHits инициирует поиск слов-кандидатов в заданных парах последовательностей из разных геномов, последовательно или параллельно в зависимости от используемого варианта программы и параметров запуска. Пары подлежащих обработке последовательностей указываются в виде набора файлов заданий, с помощью параметров конфигурации jobpath, jobext, start, stop или соответствующих опций командной строки. Примеры таких наборов файлов заданий есть в составе контрольных примеров для Windows и Linux (в каталоге jobs). Каждый файл заданий указывает одну последовательность из "первого" генома (в первой строке файла) и одну или более последовательностей из "второго" генома (во второй и последующих строках файла), причём "вторых" геномов может быть несколько; вместе они образуют столько пар, сколько указано последовательностей всех "вторых" геномов. Все строки файла заданий имеют одинаковый формат, хотя первая строка относится к "первому" геному, а последующие -- ко "вторым". В начале строки должен стоять по меньшей мере один пробел и/или символ табуляции, который заменится на звёздочку по окончании обработки строки. Далее должны идти три числовых поля, разделённые одним или более пробелом или символом табуляции. Смысл полей:

  1. номер организма (один из указанных в списке исходных данных),
  2. порядковый номер последовательности в файле генома в FASTA-формате, либо 1 в случае файла GenBank (впоследствии эти номера появятся в результатах),
  3. смещение заголовка последовательности (конкретно, символа '>') от начала данного файла генома, начиная с 0.

Каждый файл заданий всегда обрабатывается одной параллельной ветвью программы вплоть до исчерпания всех пар, затем эта ветвь переходит к следующему необработанному файлу заданий, если таковые еще остались. Обработанные последовательности второго генома отмечаются в файле заданий символом "звёздочка" (*) в первой позиции соответствующих строк (такие строки файла заданий пропускаются), что позволяет продолжить прерванную работу программы (для таких случаев предусмотрен режим дозаписи протокола и результатов программы в существующие файлы, см. опции -a, -w и параметр конфигурации append). Однопроцессорная версия программы обрабатывает файлы заданий по очереди в порядке возрастания номера в имени файла. Каждая ветвь многопроцессорной версии начинает обработку с файла заданий, который имеет номер, равный номеру процессора в запрошенном пуле; следующий номер файла заданий для этой ветви получается прибавлением к предыдущему номеру общего числа процессоров в пуле.

Если файлов заданий мало, то при запуске бессмысленно запрашивать больше процессоров, чем файлов заданий. Общее время расчётов будет определяться самым долго обрабатываемым файлом заданий. В первом приближении время обработки файла заданий пропорционально длине последовательности из первого генома и сумме длин последовательностей из всех вторых геномов, которые указаны в этом файле. Поэтому при относительно небольшом числе геномов и их последовательностей имеет смысл разделить на части те файлы заданий, обработка которых предположительно будет длиться долго, с соответствующим увеличением числа запрашиваемых процессоров. Если же файлов заданий значительно больше, чем доступных процессоров, нагрузка балансируется автоматически, если нумерация файлов заданий соответствует убыванию трудоёмкости. В частности, может помочь упорядочение последовательностей внутри каждого генома по убыванию их длины, а геномов -- по убыванию их суммарной длины.

Файлы результатов

Если в результате обработки некоторого файла заданий найдена хотя бы одна искомая пара слов, программа PairHits создает файл результатов в каталоге, указанном параметром конфигурации result; в имени файла результатов используется номер этого файла заданий. Файл результатов -- это текстовый файл, все строки которого содержат один и тот же набор из 11 полей переменной длины, разделённых одним символом табуляции (если позволяют размеры, файл результатов можно непосредственно загрузить в электронную таблицу Excel). Содержание полей следующее:

  1. номер первого генома
  2. номер последовательности в первом геноме
  3. якорь слова в последовательности первого генома ("якорь" -- это сумма начальной и конечной позиции слова в последовательности, т.е. удвоенная позиция середины слова)
  4. длина слова в первом геноме
  5. номер второго генома
  6. номер последовательности второго генома
  7. якорь слова в последовательности второго генома
  8. длина слова во втором геноме
  9. указатель цепи во втором геноме (одно из значений 1, -1 или 0)
  10. редакционное расстояние между словами (суммарный штраф за несовпадение), увеличенное в 10 раз
  11. коэффициент сжатия слова алгоритмом gzip.
Важно: в текущей реализации программы позиции на комплементарной (отрицательной) цепи нумеруются от конца последовательности. Примеры файла результатов имеются в составе контрольных примеров для Windows и Linux (в каталоге myfiles\hits).

Файлы для загрузки
« back