Автоматизация поиска гербарных записей в базе данных

Введение

Данный документ представляет собой описание HTTP-API (программного интерфейса по протоколу HTTP) для работы с электронным гербарием, работающим под управлением данного web-приложения.

НTTP-API не предназначено для изменения данных, а может использоваться только для их чтения.

Параметры запросов

При формировании поисковых запросов к серверу допустимы только GET-запросы (протокол HTTP(S)).

Одновременное задание полей при формировании GET-запроса приводит к поисковому запросу типа «И»: т.е. если задать одновременно colstart=2016-01-01 и collectedby=Бар, то найдутся все записи, для которых начало сбора позже 1 января 2016 г и у которых в поле «Собрали» встречается последовательность символов „бар“ (без учета регистра).

Формирование запросов типа „ИЛИ“ не реализовано в текущем HTTP-API, но может быть эмулировано серией дополнительных запросов к базе данных.

Возможны следующие параметры GET-запроса, по которым осуществляется поиск:

  • family — название семейства; название семейства с точностью до регистра записи должно совпадать с запрашиваемым;

  • genus — название рода; название рода с точностью до регистра записи должно совпадать с запрашиваемым; в случае противоречивости значений параметров family и genus выводится сообщение об ошибке – отсутствии образцов, удовлетворяющих условиям поиска;

  • species_epithet — видовой эпитет; поиск осуществляется без учета регистра; условие поиска считается выполненным, если запрашиваемая строка включается в поле «видовой эптитет» основного вида гербарного сбора;

  • place — место сбора; выполнение условия поиска: включение запрашиваемой строки без учета регистра хотя бы в одно из полей данных о гербарном сборе, поля: место сбора, регион, район, примечание.

  • collectedby — коллекторы; выполнение условия поиска: включение запрашиваемой строки без учета регистра (поиск также автоматически выполняется по транслитерированной на английский язык строке);

  • identifiedby — определители; выполнение условия поиска: включение запрашиваемой строки без учета регистра (поиск также автоматически выполняется по транслитерированной на английский язык строке);

  • country — название страны, места сбора образца; включение запрашиваемой строки без учета регистра в название страны на русском или английском языках (используются названия стран, принятые в стандартах ISO3166-1-ru или ISO3166-1-en; для Российской Федерации используется сокращенное название Россия);

  • colstart — дата начала сбора; задается в формате yyyy-mm-dd

  • colend — дата окончания сбора; формат аналогичен параметру colstart;

  • acronym — название гербарного акронима; выполнение условия поиска – точное совпадение акронима гербария без учёта регистра;

  • subdivision — название гербарного подраздела; выполнение условия поиска: включение запрашиваемой строки без учета регистра;

  • latl — минимальное значение широты сбора; допустимый диапазон значений (-90.0, 90.0); используется для поиска по прямоугольной области сбора;

  • latu — максимальное значение широты сбора; допустимый диапазон значений (-90.0, 90.0); используется для поиска по прямоугольной области сбора;

  • lonu — максимальное значение долготы сбора; допустимый диапазон значений (-180.0, 180.0); используется для поиска по прямоугольной области сбора;

  • lonl — минимальное значение долготы сбора; допустимый диапазон значений (-180.0, 180.0); используется для поиска по прямоугольной области сбора;

  • synonyms — возможные значение false или true; отсутствие параметра в GET-запросе приравнивается к false; индикатор поиска с учетом синонимов; при поиске с учетом синонимов важно задать поля genus и species_epithet; true – означает выполнять поиск по синонимам;

  • additionals — возможные значения false или true; отсутствие параметра в GET-запросе приравнивается к false; индикатор поиска по дополнительным видам внутри гербарных сборов; true – означает искать совпадения в дополнительных видах;

  • idID образца; при указании в запросе данного поля, все остальные поля игнорируются; возвращается информация только об образце с заданным ID, если такой был найден, в противном случае – выводится сообщение об ошибке;

  • fieldid — полевой номер образца;

  • itemcode — инвентарный номер образца (используется в гербарном хранилище);

  • authorship — авторство основного вида; условие выполняется, если строка авторства основного вида гербарного сбора содержит в себе значение передаваемое в данном параметре (сравнение производится без учета регистра записи);

  • imonly — возможные значения false или true;

    отсутствие параметра в GET-запросе приравнивается к его false значению; фильтр imonly=true означает, что будут выведены только записи, имеющие изображения.

Замечание При поиске по полям collectedby и identifiedby выполняется только односторонняя транслитерация: т.е. если, например, задано условие поиска **collectedby** =Бакалин, то это эквивалентно поиску **collectedby** =Бакалин или **collectedby** =Bakalin (найдутся все записи на русском и английском языках). Если задано условие поиска **collectedby** =Bakalin, то найдутся только записи, где в поле «сборщики» встречается строка «bakalin» (без учёта регистра).

Параметры ответа сервера

Ответ сервера на поисковый запрос представляет собой JSON-форматированный текст, передаваемый по протоколу HTTP, и имеющий следующие параметры:

  • errors — массив ошибок, возникших при обработке поискового запроса.

  • warnings — массив предупреждений, возникших при обработке поискового запроса. Предупреждениями являются различные поисковые ситуации: например, отсутствие данных, удовлетворяющих текущему поисковому запросу, игнорирование тех или иных поисковых параметров, при их противоречивости и т.п.

  • data — массив структурированных данных гербарных записей, удовлетворяющих текущему поисковому запросу.

Структура массива данных

Параметр data представляет собой массив данных, удовлетворяющих текущему поисковому зарпосу.

Он имеет следующую структуру, описывающую текущий гербарный сбор:

  • family — название семейства (заглавными буквами, на латыни);

  • family_authorship — автор семейства;

  • genus — название рода;

  • genus_authorship — автор рода;

  • species_epithet — видовой эпитет;

  • species_idID вида образца; не путать с ID текущей гербарной записи. ID текущей гербарной записи однозначно характеризует данную оцифрованную гербарную запись. ID вида образца, только вид. Гербарных записей, содержащих какой-либо вид может быть много.

  • species_authorship — автор вида;

  • species_status — текущий статус вида; определяет степень признанности данного вида, точнее триплета (род, видовой эпитет, авторство вида) в научном сообществе на настоящее время. Возможные значения данного параметра 1) «Recently added» — вид недавно добавлен и, скорее, не проверялся специалистом; название вида с таким статусом может быть устаревшим, либо содержатьошибки; 2) «Approved» — название вида подтверждено специалистом; 3) «Deleted» — вид имеет ошибку в записи, или его название устарело и не используется; 4) «From plantlist» — название импортировано из базы http://theplantlist.org.

  • type_status — типовой статус гербарного сбора; для мультивидовых сборов – отражает типовой статус в отношении основного вида сбора;

  • infraspecific_rank — подвидовой ранг (возможные значения: пусто, subsp., subvar., f., subf., var.);

  • infraspecific_epithet — подвидовой эпитет;

  • infraspecific_authorship — автор подвидового эпитета;

  • species_fullname — полное название вида, т.е. Род + видовой эпитет + авторство;

  • short_note — замечания к главному виду сбора (используется по необходимости в случае мультивидовых сборов);

  • significance — неопределенность знаний относительно главного вида гербарного сбора (возможные значения: пусто, aff., cf.);

  • id — уникальный идентификатор данной гербарной записи; всегда целое число;

  • gpsbased — получены ли данные о географической привязки места сбора образца с помощью GPS (значение true), либо другим способом (false); следует иметь ввиду, что у многих образцов, даже при gpsbased равном false, координаты, если таковые заданы, были получены при помощи GPS; это связано с тем, что не все отмечают соответствующее поле (gpsbased) при заполнении электронной формы образца;

  • latitude — широта, градусы; географическая координата места сбора в системе WGS-84;

  • longitude — долгота, градусы; географическая координата места сбора в системе WGS-84;

  • fieldid — полевой номер образца;

  • duplicates — перечень акронимов гербариев (из Index Herbariorum), куда были депонированы дубликаты данного гербарного листа;

  • itemcode — инвентаризационный номер, используемый в гербарном хранилище;

  • acronym — гербарный акроним, которому принадлежит данная гербарная запись (для большинства записей поле имеет значение VBGI);

  • branch — подраздел гербария внутри акронима; иногда удобно иметь подразделы внутри общей гербарной базы: например, «гербарий грибов», «биоморфологический гербарий» и т.п.;

  • collectors — текстовая строка: сборщики образца;

  • identifiers — текстовая строка: те, кто определил вид гербарного сбора;

  • devstage — стадия развития; определена для биоморфологического гербария; возможные значения: Development stage partly, Life form, или пустое поле;

  • updated — дата последнего изменения записи в базе данных;

  • created — дата создания записи (т.е. занесения её электронную базу данных);

  • identification_started — дата начала определения вида образца;

  • identification_finished — дата окончания определения вида образца; дата определения вида задана в виде интервала, поскольку не всегда может быть указана точная дата, а например,только месяц, или время проведения какой-либо экспедиции;

  • collection_started — дата начала сбора образца;

  • collection_finished — дата окончания сбора образца; дата сбора задана в виде интервала, поскольку не всегда может быть указана точная дата, а например,только месяц, или время проведения какой-либо экспедиции;

  • country — название страны сбора образца;

  • country_id — числовой идентификатор страны сбора образца;

  • altitude — высота над уровнем моря места сбора образца; значение представляется собой строку, не всегда однозначно определяющую реальную высоту сбора. Возможны, например, варианты: 100-300 м, 120 м, 400, 300-400 и т.п.

  • region — регион сбора;

  • district — район сбора;

  • details — экологические условия сбора, дополнительные уточнения не вошедшие в поля регион и район;

  • note — примечание; может содержать информацию о месте сбора, экологических условиях и т.п.;

  • dethistory — представляет собой массив — историю переопределений вида гербарного сбора;

  • additionals — некоторые гербарные сборы могут содержать более одного вида; данный массив описывает характеристики каждого из них.

  • images — перечень изображений, относящихся к гербарной записи ([] – пустой список – означает отсутствие изображений);

    каждый элемент списка — это путь до изображения, соответствующего данному гербарному сбору.

Примечание

Изображения в списке images доступны в нескольких разрешениях. В текущей реализации сервиса изображения различных разрешений размещены по директориям, имеющим названия: ts – thumbnail size (очень маленький размер); ss – small size (30% от оригинала); ms – medium size (60% от оригинала); fs – full size (оригинальное разрешение). Таким образом, в каждом url изображения есть одна из компонент пути ` /ts/ , /ss/ `, ` /ms/ ` или ` /fs/ `, указывающая изображение какого разрешения соответствует данному url.

Примечание

Все изображения сохранены в формате jpeg. Для этих целей используется редактор коммандной строки ImageMagick c параметрами:

'-strip', '-interlace', 'Plane',
'-sampling-factor', r'4:2:0',
'-quality',
r'90%'

Практика показывает, что используемый набор параметров не оказывает видимого эффекта на изображения. Вместе с тем, использование сжатия позволяет существенно сократить требуемое дисковое пространство.

Пример вида массива images:

['http://botsad.ru/herbarium/view/snapshots/VBGI/ss/VBGI32618_1.jpg',
 'http://botsad.ru/herbarium/view/snapshots/VBGI/ts/VBGI32618_1.jpg',
 'http://botsad.ru/herbarium/view/snapshots/VBGI/ms/VBGI32618_1.jpg',
 'http://botsad.ru/herbarium/view/snapshots/VBGI/fs/VBGI32618_1.jpg'
...
]

Поля region, district, details, note, altitude могут быть заполнены с поддержкой двуязычности с использованием спецсимвола «|». Например, строка, возвращаемая в поле region, может быть такой «Russian Far East|Дальний Восток России». Это означает, что относительно символа «|» даётся русско- и англоязычный варианты строки. Дальнейшая обработка значений таких строк ложится на пользователя системы, которому решать какую из компонент строки относительно символа «|» оставить, а какую – удалить. Система HTTP-API не принимает таких решений.

Структура массивов dethistory и additionals приводится ниже.

История переопределений и дополнительные сборы

История переопределений

Каждый элемент массива «История переопределений» (dethistory) представляет собой описание попытки определения (переопределения) вида в текущем гербарном сборе и имеет следующие поля (значения полей, характеризующих вид, аналогично описанным выше):

  • valid_from — дата актуальности определения;

  • valid_to — дата окончания актуальности определения; поле может быть не задано, что означает, что предполагает, что определение актуально в настоящее время;

  • family — название семейства;

  • family_authorship — авторство семейства;

  • genus — название рода;

  • genus_authorship — автор рода;

  • species_epithet — видовой эпитет;

  • species_idID вида образца;

  • species_authorship — автор вида;

  • species_status — текущий статус вида;

  • species_fullname — полное название вида;

  • infraspecific_rank — подвидовой ранг (возможные значения: пусто, subsp., subvar., f., subf., var.);

  • infraspecific_epithet — подвидовой эпитет;

  • infraspecific_authorship — автор подвидового эпитета;

  • significance — неопределенность знаний относительно вида (возможные значения: пусто, aff., cf.);

Сроки актуальности вида (valid_from, valid_to) позволяют корректно описать любые его последующие переопределения.

Примечание

Если в гербарном сборе представлен не один вид, то массив «История переопределений» представляет собой историю переопределений основного вида.

Дополнительные виды

Каждый элемент массива «Дополнительные виды» (additionals) представляет собой описание вида, находящегося в данном гербарном сборе. Каждое из таких описаний имеет поля, аналогичные записям из Истории переопределений:

  • valid_from — дата актуальности определения;

  • valid_to — дата окончания актуальности определения; поле может быть не задано, что означает, что предполагает, что определение актуально в настоящее время;

  • family — название семейства;

  • family_authorship — авторство семейства;

  • genus — название рода;

  • genus_authorship — автор рода;

  • species_epithet — видовой эпитет;

  • species_idID вида образца;

  • species_authorship — автор вида;

  • species_status — текущий статус вида;

  • species_fullname — полное название вида;

  • infraspecific_rank — подвидовой ранг (возможные значения: пусто, subsp., subvar., f., subf., var.);

  • infraspecific_epithet — подвидовой эпитет;

  • infraspecific_authorship — автор подвидового эпитета;

  • note — примечания о текущем дополнительном сборе;

  • significance — неопределенность знаний относительно вида (возможные значения: пусто, aff., cf.);

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

Примечание

Поле note поддерживает режим двуязычного заполнения, поэтому в отношении его справедливо замечание, указанное выше.

Пояснение и интерпретация

Рассмотрим для примера следующий массив «Дополнительных видов» (для краткости выписаны не все поля):

[
{'genus': 'Quercus', 'species_epithet': 'mongolica', ... ,'valid_from': '2015-05-05', 'valid_to': '2016-01-01'},
{'genus': 'Quercus', 'species_epithet': 'dentata', ... ,'valid_from': '2016-01-01', 'valid_to': ''},
{'genus': 'Betula', 'species_epithet': 'manshurica', ... ,'valid_from': '2015-05-05', 'valid_to': ''},
{'genus': 'Betula', 'species_epithet': 'davurica', ... ,'valid_from': '2015-05-05', 'valid_to': ''},
]

Если сегодня, например, 1 сентября 2015 года (2015-09-01), то массив дополнительных видов состоит из Quercus mongolica, Betula manshurica и Betula davurica, а Quercus dentata является неактуальным определением на данный момент времени.

Если сегодня 2017 год, например, 2017-01-01, то неактуальным оказывается Quercus mongolica, и, таким образом, актуальными видовыми составляющими сбора являются Quercus dentata, Betula manshurica и Betula davurica

Ограничения

Поскольку поисковому запросу пользователя может удовлетворять большой объём данных, для формирования ответа сервера может потребоваться значительное время.

Чтобы снизить нагрузку на сервер, вызванную вероятно долгими keep-alive HTTP-соединениями, действуют ограничения.

Количество одновременно возможных соединений для сервиса автоматизированного опроса гербарной базы определяется текущим значением параметра JSON_API_SIMULTANEOUS_CONN.

По превышении этого количества, сервер не обрабатывает поисковые запросы, а возвращает сообщение об ошибке.

На запросы, содержащие id, данное ограничение не действует, поскольку получение информации об объекте по его ID — не ёмкая в плане ресурсов операция.

Информация о неопубликованных образцах не выводится; при попытке получить информацию о неопубликованном образце по его ID выводится ошибка.

Примеры

Для проверки работы системы и получения json-ответа сервера достаточно передать поисковый запрос в url браузера.

Например, переход по ссылке

http://botsad.ru/hitem/json/?genus=riccardia&collectedby=bakalin

приведет к появлению на экране браузера json-ответа, содержащего информацию о всех сборах – представителей рода Riccardia, в строке, содержащей информацию о сборщиках которых встречается bakalin.

При указании id в GET запросе, все остальные поисковые поля игнорируются и выводится информация о гербарном образце с указанным id:

http://botsad.ru/hitem/json?id=500

http://botsad.ru/hitem/json?id=44

http://botsad.ru/hitem/json?id=5