Программа 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 полей, которые разделены одним или более символов табуляции. Внутри полей могут содержаться пробелы. Смысл полей следующий:
- номер организма (уникальный внутри одного набора исходных данных);
- краткое обозначение (идентификатор) организма, в текущей реализации короче 36 символов;
- наименование организма;
- таксономический код (см. описание параметра diversity программы FinDense);
- имя файла с геномом в формате FASTA или GenBank. Весь геном должен содержаться в одном файле. Путь к файлу указывается параметром fastapath в файле конфигурации или в командной строке запуска программы в соответствии с правилами используемой ОС, он может быть абсолютным или относительно рабочей директории.
- необязательное поле, содержащее имя файла с аннотацией генома в формате GFF; программа BldGraph не использует это поле.
Результаты
В результате работы программы BldGraph формируется протокол (см. параметры конфигурации splitlog, logname, logext) и начальный граф в виде первичного и нескольких вторичных файлов (их принятые расширения соответственно .hub и .star), которые в дальнейшем будет использовать программа FinDense, а также промежуточные данные в каталоге, указанном параметром конфигурации dump. Детальная структура выходных файлов не описывается, хотя их образцы включены в состав контрольных примеров.
Важная информация: некоторые из этих файлов содержат числовые данные в двоичном формате, поэтому для их правильной интерпретации необходимо, чтобы программы BldGraph и FinDense в пределах одного расчёта исполнялись на системах с одинаковым порядком байтов в двоичном числе (big endian/little endian). Подчеркнём, что это не относится к программе PairHits, которая может исполняться на любой системе независимо от последующих шагов алгоритма.