Автоматизация поиска гербарных записей в базе данных¶
Введение¶
Данный документ представляет собой описание 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 – означает искать совпадения в дополнительных видах;
id — ID образца; при указании в запросе данного поля, все остальные поля игнорируются; возвращается информация только об образце с заданным 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_id — ID вида образца; не путать с 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_id — ID вида образца;
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_id — ID вида образца;
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
