Программа BldGraph

Программа входит в состав комплекса iHCE для поиска высококонсервативных элементов (ВКЭ) в наборе геномов. Она производит уплотнение построенного программой PairHits исходного графа, преобразуя его в начальный многодольный граф, у которого каждая доля соответствует одному геному. Программа предназначена для параллельных вычислений в среде MPI на высокопроизводительном суперкомпьютере с 64-битной операционной системой Windows или Linux.

Программа BldGraph написана на С++ и имеет интерфейс командной строки. Формат командной строки:

bldgraph [options] [config_file]

(Здесь указано имя программы в Linux; вариант для Windows 64-bit c MPICH2 имеет имя bldgraph64, с Microsoft MPI — bldgraph64ms, без MPI — bldgraph64nompi).

Опции указываются в одном из форматов: /x[ значение], -x[ значение], --x…xx[=значение] (у некоторых опций значение отсутствует). В основном опции предназначены для изменения обычных значений параметров программы, которые указаны в файле конфигурации или установлены по умолчанию (значения в командной строке имеют наивысший приоритет).

Список распознаваемых опций командной строки и значения по умолчанию

-?

--help

Выдаёт подсказку о параметрах командной строки программы.

-с имя_файла

--config=имя_файла

Имя файла конфигурации программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. По умолчанию используется файл config.ini в рабочей директории программы.

-d значение

--strand=значение

Указывается значение булевского типа, которое определяет, будет ли программа различать цепи ДНК при объединении найденных слов-кандидатов с достаточным перекрытием. Если указано значение «истина» (допускается любой из вариантов: true, yes, 1, +), то будут объединяться только слова, находящиеся на одной и той же цепи ДНК. Если указано значение «ложь» (в любом из вариантов: false, no, 0, -), программа будет также объединять слова на разных цепях ДНК. В последнем случае часто строятся более плотные кластеры, но в некоторых ВКЭ привязка найденных слов к цепи может быть неправильной (в таких случаях программа FinDense выдаёт список этих ВКЭ). Значение по умолчанию — «истина».

-e значение

--statonly=значение

Указывается значение булевского типа (аналогично опции -d). Если указать значение «истина», то программа вычисляет статистику рёбер исходного графа по долям, после чего завершает работу (информационный режим). Значение по умолчанию — «ложь».

-f имя

--fastapath=имя

Общий префикс имён файлов, содержащих исходные геномные последовательности в формате FASTA или GenBank (последнее — только если геном состоит из единственной последовательности); обычно это путь к соответствующему каталогу. Переменная часть имён указывается в разделе [species] файла конфигурации. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. По умолчанию используется каталог fasta\ в рабочей директории.

-h имя_файла

--hits=имя_файла

Имя файла, содержащего список файлов результатов программы PairHits; имя может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Этот текстовый файл, каждая строка которого содержит имя и путь к одному файлу результатов, легко построить соответствующей командой операционной системы (в частности, в Windows можно использовать команду dir hits\*.txt /b /l /on /s >hits\file.lst, а в Linux — ls -1 hits/*.txt >hits/file.lst). По умолчанию используется имя hits\file.lst.

-l число

--length=число

Нижний порог длины искомых слов (длина должна быть строго больше порога). Параметр позволяет осуществить дополнительную фильтрацию по длине слов, вдобавок к уже выполненной одноимённой опцией программы PairHits. Значение по умолчанию — 60.

-n

--nompi

Заставляет мультипроцессорную версию программы работать в однопроцессорном режиме, даже в среде MPI. Иногда при отсутствии в системе среды MPI этой опции может оказаться недостаточно (программа завершается аварийно); в таких случаях следует использовать вариант программы без MPI.

-o имя_файла

--log=имя_файла

Имя файла для протокола работы программы, может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Символ # в имени файла интерпретируется как номер процессора, при условии, что в файле конфигурации задана раздельная выдача протокола каждой параллельной ветви программы. По умолчанию используется имя bld_log#.txt.

-p число

--portion=число

Размер порции записей, которыми обмениваются параллельные ветви программы. Чем крупнее порции, тем быстрее работает программа, однако при этом требуется больше буферной памяти и увеличивается риск взаимных блокировок. В таких случаях рекомендуется уменьшить принятое по умолчанию значение 1000 (например, до 100).

-r число

--ratio=число

Максимально допустимый коэффициент сжатия искомых слов алгоритмом gzip; если слово сжимается больше, оно отбрасывается. Параметр позволяет осуществить дополнительную фильтрацию по сложности слов, вдобавок к уже выполненной опцией -z программы PairHits. Значение 0 означает, что проверка сложности не выполняется. Значение по умолчанию — 2,2.

-s число

--common=число

Минимальная длина общего участка группы слов-кандидатов, объединяемых в одно слово при уплотнении исходного графа. Значение по умолчанию — 32.

-u число

--usedump=число

Указывает число разделов в выгруженном наборе промежуточных данных (дампе). Чтобы выполнить программу BldGraph за один запуск, необходимо указать значение 0. Иногда программу удобнее выполнять сначала на многих процессорах (например, раздельно по организмам), а на финальной стадии использовать один или несколько процессоров. Результаты первой стадии отдельно по каждому процессору выгружаются в специальный каталог (указанный параметром dump в файле конфигурации), после чего работу программы можно прервать. Затем программу запускают заново на другом числе процессоров, и она использует ранее выгруженные данные. Для этого с помощью данной опции необходимо указать то число процессоров, при котором производилась выгрузка данных. Значение по умолчанию — 0.

Первый же аргумент командной строки, не являющийся ни одной из вышеперечисленных опций или её значением, интерпретируется как имя файла конфигурации (аналогично значению опции -c).

Файл конфигурации программы

Файл конфигурации является обязательным; это текстовый файл со структурой, традиционной для конфигурационных файлов (образцы файла есть в составе контрольных примеров для Windows и Linux). Строки файла не могут переноситься; пустые строки игнорируются. Строки, начинающиеся символом ; или #, рассматриваются как комментарии и также игнорируются программой. Для комментариев в информационных строках может использоваться пара символов «косая черта» (//); начиная с неё, остаток строки игнорируется.

Информационные строки бывают двух видов: заголовок раздела (формат [имя_раздела]) и значение параметра (формат параметр = значение, где в качестве разделителей между левой частью, знаком равенства и правой частью может использоваться один или более пробелов или символов табуляции). Разделом конфигурации называется часть файла, начиная с заголовка раздела и вплоть до следующего заголовка раздела или до конца файла. Порядок параметров внутри раздела произвольный. Файл конфигурации может содержать несколько разделов в произвольном порядке, за исключением раздела [common], который должен стоять первым, и раздела [species], который должен стоять последним. Программа BldGraph использует только разделы [common] (если есть), [bldgraph], [species] и игнорирует прочие разделы файла конфигурации.

Список распознаваемых параметров конфигурации в разделе [bldgraph]

splitlog

Задаёт режим выдачи протокола работы параллельной версии программы. В правой части указывается булевское значение «истина» (в любом из форматов: yes, true, 1, +) или «ложь» (в любом из форматов: no, false, 0, -). Если указано истинное значение, каждая параллельная ветвь программы формирует собственный протокол работы, имя которого задаётся параметрами logname, logext или опцией -o в командной строке (последний способ имеет приоритет перед остальными). Если этот параметр отсутствует в разделе [bldgraph], используется значение из раздела [common], если нет и там, принимается значение «истина».

logname

Указывает имя файла протокола (без расширения), которое может включать путь. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если установлено splitlog=true, то к указанному имени автоматически добавляется номер параллельной ветви, начиная с 0. Если этот параметр отсутствует в разделе [bldgraph], используется значение из раздела [common], если нет и там, принимается значение bldg_log. Значение может быть изменено с помощью опции -o в командной строке, причём эта опция модифицирует сразу три параметра: splitlog, logname, logext.

logext

Указывает расширение имени файла протокола. Если этот параметр отсутствует в разделе [bldgraph], используется значение из раздела [common], если нет и там, принимается значение .txt. Значение может быть изменено с помощью опции -o в командной строке, причём эта опция модифицирует сразу три параметра: splitlog, logname, logext.

errname

Указывает имя (без расширения) файла для протокола ошибок программы, которое может включать путь. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если установлено splitlog=true, то к указанному имени автоматически добавляется номер параллельной ветви, начиная с 0. Если этот параметр отсутствует в разделе [bldgraph], используется значение из раздела [common], если нет и там, принимается значение bldg_err. Если указано пустое значение, протокол ошибок не формируется.

errext

Указывает расширение имени файла протокола. Если этот параметр отсутствует в разделе [bldgraph], используется значение из раздела [common], если нет и там, принимается значение .log.

fastapath

Указывает общий префикс имён файлов с исходными геномными последовательностями в формате либо FASTA, либо GenBank; обычно это путь к соответствующему каталогу. Если значение содержит пробелы, оно должно быть заключено в кавычки. Если параметр отсутствует, используется его значение из раздела [common], а по умолчанию — каталог fasta\ в рабочей директории. Переменная часть имён указывается в разделе [species]. Значение может быть изменено с помощью опции -f в командной строке.

hits

Указывает имя файла, содержащего список файлов результатов программы PairHits; имя может включать путь. Если имя содержит пробелы, соответствующий аргумент целиком заключается в кавычки. Этот текстовый файл, каждая строка которого содержит имя и путь к одному файлу результатов, легко построить соответствующей командой операционной системы (в частности, в Windows можно использовать команду dir hits\*.txt /b /l /on /s >hits\file.lst, а в Linux — ls -1 hits/*.txt >hits/file.lst). Значение может быть изменено с помощью опции -h в командной строке. По умолчанию используется имя hits\file.lst.

common

Указывает минимально необходимую длину общего участка группы слов-кандидатов, объединяемых в одно слово при уплотнении начального графа. Значение может быть изменено с помощью опции -s в командной строке. Значение по умолчанию — 32.

length

Указывает порог минимальной длины искомых слов (длина должна быть строго больше порога). Параметр позволяет осуществить дополнительную фильтрацию по длине слов, вдобавок к уже выполненной одноимённой опцией программы PairHits. Значение может быть изменено с помощью опции -l в командной строке. Значение по умолчанию — 60.

ratio

Указывает максимально допустимый коэффициент сжатия искомых слов алгоритмом gzip; если слово сжимается больше, оно отбрасывается. Параметр позволяет осуществить дополнительную фильтрацию по сложности слов, вдобавок к уже выполненной опцией -z программы PairHits. Значение может быть изменено с помощью опции -r в командной строке. Значение 0 означает, что проверка сложности не выполняется. Значение по умолчанию — 2,2.

strand

Указанное значение булевского типа определяет, будет ли программа различать цепи ДНК при объединении найденных слов-кандидатов с достаточным перекрытием. Если указано значение «истина» (допускается любой из вариантов: true, yes, 1, +), то будут объединяться только слова, находящиеся на одной и той же цепи ДНК. Если указано значение "ложь" (в любом из вариантов: false, no, 0, -), программа будет также объединять слова на разных цепях ДНК. В последнем случае часто строятся более плотные кластеры, но в некоторых ВКЭ привязка найденных слов к цепи может быть неправильной (в таких случаях программа FinDense выдаёт список этих ВКЭ). Значение может быть изменено с помощью опции -d в командной строке. Значение по умолчанию — «истина».

dump

Обязательный параметр, указывающий путь к существующему каталогу для записи промежуточных данных при работе программы. См. также параметр usedump и опцию командной строки -u.

usedump

Указывает число разделов в выгруженном наборе промежуточных данных (дампе). Чтобы выполнить программу BldGraph за один запуск, необходимо указать значение 0. Иногда программу удобнее выполнять сначала на многих процессорах (например, раздельно по видам), а на финальной стадии использовать один или несколько процессоров. Результаты первой стадии раздельно по каждому процессору выгружаются в специальный каталог (указанный параметром dump), после чего работу программы можно прервать. Затем программу запускают заново на другом числе процессоров, и она использует ранее выгруженные данные. Для этого в качестве значения данной опции необходимо указать число процессоров, при котором производилась выгрузка данных. Значение может быть изменено с помощью опции -u в командной строке. Значение по умолчанию — 0.

statonly

Указывается значение булевского типа (аналогично параметру strand). Значение может быть изменено с помощью опции -e в командной строке. Если указать значение «истина», то программа вычисляет статистику рёбер начального графа по долям, после чего завершает работу (информационный режим). Значение по умолчанию — «ложь».

hubname

Обязательный параметр, указывающий путь и имя первичного файла начального графа (результат программы). Если параметр отсутствует в разделе [bldgraph], он должен быть указан в разделе [common]. Возможность изменения параметра через командную строку и значение по умолчанию отсутствуют.

starname

Обязательный параметр, указывающий путь и имена вторичных файлов начального графа (результат программы). Имя должно содержать символ «звёздочка» (*), вместо которого для каждого вторичного файла будет подставлен идентификатор соответствующего организма. Если параметр отсутствует в разделе [bldgraph], он должен быть указан в разделе [common]. Возможность изменения параметра через командную строке и значение по умолчанию отсутствуют.

hcecount

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

portion

Указывает размер порции записей, которыми обмениваются параллельные ветви программы. Чем крупнее порции, тем быстрее работает программа, однако при этом требуется больше буферной памяти и увеличивается риск взаимных блокировок. В таких случаях рекомендуется уменьшить принятое по умолчанию значение 1000 (например, до 100).

Список исходных данных в разделе [species]

Этот раздел устанавливает связь между идентификатором и названием организма, присвоенным ему номером и именами файлов исходных данных. Каждая строка соответствует одному организму. Программа игнорирует пустые строки файла, а также строки, начинающиеся с символа ; или #. Пробелы и символы табуляции в начале строки игнорируются. Строка содержит по меньшей мере 5 полей, которые разделены одним или более символов табуляции. Внутри полей могут содержаться пробелы. Смысл полей следующий:

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

Образцы списка исходных данных имеются в составе контрольных примеров для Windows и Linux.

Результаты

В результате работы программы BldGraph формируется протокол (см. параметры конфигурации splitlog, logname, logext) и начальный граф в виде первичного и нескольких вторичных файлов (их принятые расширения соответственно .hub и .star), которые в дальнейшем будет использовать программа FinDense, а также промежуточные данные в каталоге, указанном параметром конфигурации dump. Детальная структура выходных файлов не описывается, хотя их образцы включены в состав контрольных примеров.

Важная информация: некоторые из этих файлов содержат числовые данные в двоичном формате, поэтому для их правильной интерпретации необходимо, чтобы программы BldGraph и FinDense в пределах одного расчёта исполнялись на системах с одинаковым порядком байтов в двоичном числе (big endian/little endian). Подчеркнём, что это не относится к программе PairHits, которая может исполняться на любой системе независимо от последующих шагов алгоритма.

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

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