Программа 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).

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

См. соответствующий раздел страницы iHCE.