R语言【rgbif】——最全最详细的函数解读（occ_search)

occ_search有什么作用？

occ_search是rgbif包中非常重要的，用于获取物种发现记录的函数。在R语言【rgbif】——用rgbif下载物种分布数据（rgbif包的初步探索）中可以发现，occ_search作为获取数据的压轴步骤发挥了关键作用。

occ_search有哪些参数？

occ_search(
	taxonKey = NULL,
	scientificName = NULL,
	country = NULL,
	publishingCountry = NULL,
	hasCoordinate = NULL,
	typeStatus = NULL,
	recordNumber = NULL,
	lastInterpreted = NULL,
	continent = NULL,
	geometry = NULL,
	geom_big = "asis",
	geom_size = 40,
	geom_n = 10,
	recordedBy = NULL,
	recordedByID = NULL,
	identifiedByID = NULL,
	basisOfRecord = NULL,
	datasetKey = NULL,
	eventDate = NULL,
	catalogNumber = NULL,
	year = NULL,
	month = NULL,
	decimalLatitude = NULL,
	decimalLongitude = NULL,
	elevation = NULL,
	depth = NULL,
	institutionCode = NULL,
	collectionCode = NULL,
	hasGeospatialIssue = NULL,
	issue = NULL,
	search = NULL,
	mediaType = NULL,
	subgenusKey = NULL,
	repatriated = NULL,
	phylumKey = NULL,
	kingdomKey = NULL,
	classKey = NULL,
	orderKey = NULL,
	familyKey = NULL,
	genusKey = NULL,
	speciesKey = NULL,
	establishmentMeans = NULL,
	degreeOfEstablishment = NULL,
	protocol = NULL,
	license = NULL,
	organismId = NULL,
	publishingOrg = NULL,
	stateProvince = NULL,
	waterBody = NULL,
	locality = NULL,
	occurrenceStatus = "PRESENT",
	gadmGid = NULL,
	coordinateUncertaintyInMeters = NULL,
	verbatimScientificName = NULL,
	eventId = NULL,
	identifiedBy = NULL,
	networkKey = NULL,
	verbatimTaxonId = NULL,
	occurrenceId = NULL,
	organismQuantity = NULL,
	organismQuantityType = NULL,
	relativeOrganismQuantity = NULL,
	iucnRedListCategory = NULL,
	lifeStage = NULL,
	isInCluster = NULL,
	distanceFromCentroidInMeters = NULL,
	limit = 500,
	start = 0,
	fields = "all",
	return = NULL,
	facet = NULL,
	facetMincount = NULL,
	facetMultiselect = NULL,
	skip_validate = TRUE,
	surlopts = list(http_version = 2),
	...
)

occ_search的参数使用？

aa. 通过名称完成筛选的参数

1. taxonKey（用于检索的类群的标识符）

• 要求传递的标识符是数值型的，而且是GBIF可接受的。

• 检索时不区分接受类群和异名类群，当使用taxonKey=212来检索鸟纲时，会返回所有种类的鸟。

• 也可以同时传递多个标识符，比如：occ_search(taxonKey=c(1,212))。

2. scientificName（用于检索的类群的科学名）

• 检索时不区分接受类群和异名类群。

3. search（额外的检索条件）

• 要求传递字符型。
• 可以是一个简单的单词或短语。

4. verbatimScientificName（通过数据记录来源提供的名称进行筛选）

• 要求传递字符型。

bb. 通过位置完成筛选的参数

5. country（记录来源的国家代码）

• 要求传递的国家代码是字符型。
• ISO-3166-1规定的双字母国家代码。
• 运行**enumeration_country()**可以查看所有国家的双字母代码。或者查看enu_cty.csv。

6. publishingCountry（与country相同）

7. hasCoordinate（通过记录是否具有坐标数据进行筛选）

• 要求传递逻辑型，TRUE或FALSE（默认值）。
• 为TRUE时，只返回含有经纬度数据的记录。
• 为FALSE时，不加筛选地返回所有记录。

8. continent（通过记录的大陆信息进行筛选）

• GBIF支持的大陆包括：
  • “africa”
  • “antarctica”
  • “asia”
  • “europe”
  • “north_america”
  • “oceania”
  • “south_america”
• 记录中的大陆信息是数据集发布者添加的，所以以此参数进行筛选可能会遗漏许多记录。

9. geometry（通过自定义的地理多边形筛选）

• 要求传递字符型。

• 在Well Known Text（WKT）格式的多边形中检索记录。

• WKT形状的写法包括：

  • “POINT”
  • “LINESTRING”
  • “LINEARRING”
  • “POLYGON”
  • “MULTIPOLYGON”

• 请注意，GBIF要求WKT的逆时针绕制顺序。您可以按顺时针方向提供WKT，但GBIF将其视为排除项，因此您将获得不在WKT区域内的所有数据。

• 当处理 长WKT字符串（>1500个字符） 时，可以通过参数geom_big进行设置：

  • asis：此值为默认值。不做任何处理，只传递WKT字符串。
  • axe：这个选项将使用sf包将WKT字符串切割成数个多边形，然后根据每个多边形块单独进行数据请求，然后将所有数据组合在一起返回。请注意，如果WKT字符串不是多边形类型，将退回到asis，因为没有办法分割线字符串等。这个选项在大多数情况下会比其他两个选项慢。但是，这种多边形分割方法不会像使用bbox选项那样存在想要多少记录和实际返回多少记录之间脱节的问题。该方法使用sf::st_make_grid和sf::st_intersection，它们有两个参数cellsize和n。您可以通过调整geom_size和geom_n来调整这些参数。在切换返回的WKT字符串的数量方面，geom_size似乎更有用。请参阅wkt_parse手动从较大的WKT字符串中分解WKT边界框，或者将较大的WKT字符串分解为许多较小的WKT字符串。
  • bbox：这个选项检查您的WKT字符串是否超过1500个字符，如果是，先从WKT创建一个边界框，使用该边界框进行GBIF搜索，然后将结果数据修剪为仅在原始WKT字符串中出现的数据。但有一个注意事项。因为先从WKT创建了一个边界框，并且limit参数确定了要获取的记录子集，所以当我们将结果数据修剪到WKT时，您获得的记录数量可能少于您使用limit参数设置的记录数量。但是，您可以将限制设置得足够高，以便获得在该边界框中找到的所有记录，然后您将获得WKT中可用的所有记录。

10. geom_big（当geometry过长时，与geometry配合使用）

• 要求传递字符型，从以下三个选项中任选其一：
  • “asis”（默认值）
  • “axe”
  • “bbox”

11. geom_size（当geometry过长时，与geom_big配合使用）

• 要求传递整数型。
• 指定分割的单元格数量。默认为40。

12. geom_n（当geometry过长时，与geom_big配合使用）

• 要求传递整数型。
• 指定每个维度的分割的单元格数量。默认为10。

13. decimalLatitude（通过纬度范围进行筛选）

• 要求传递字符型。
• 基于WGS84的-90和90之间的小数纬度。
• 支持范围检索，按照 ‘低纬度，高纬度’ 格式，比如：‘25，30’。

14. decimalLongitude（通过经度范围进行筛选）

• 要求传递字符型。
• • 基于WGS84的-180和180之间的小数经度。
• • 支持范围检索，按照 ‘小经度，大经度’ 格式，比如：‘-0.4，-0.2’。

15. hasGeospatialIssue（通过检查数据记录的空间信息进行筛选）

• 要求传递逻辑型。
• 包括/排除包含空间问题的事件记录(在我们的记录解释中确定)，即hasGeospatialIssue=TRUE只返回那些有空间问题的记录，而hasGeospatialIssue=FALSE只包括没有空间问题的记录。
• 如果没有此参数，则返回任何有或没有空间问题的记录。

16. stateProvince（通过数据记录的国家小一级的行政区域进行筛选）

• 要求传递字符型。

17. waterBody（通过数据记录所在水体的名称进行筛选）

• 要求传递字符型。

18. locality（通过数据记录所在地的描述进行筛选）

• 要求传递字符型。

19. gadmGid（通过gadm标识符进行筛选）

• 要求传递字符型。
• 数据记录所期望的区域的gadm标识符。

20. coordinateUncertaintyInMeters（通过坐标的误差进行筛选）

• 0-1,000,000之间的数字或范围，用于指定所需的坐标误差。coordinateUncertaintyInMeters=1000将返回所有恰好为1000m的记录。
• 支持范围检索，按照**‘小值，大值’**的格式，比如：‘1000，10000’。

21. distanceFromCentroidInMeters

• 一个数字或范围数值“2000，*”表示距离已知质心至少2公里。值“0”表示恰好发生在已知质心上。值“0,2000”表示在质心的2公里范围内。最大值为5000。

cc. 通过状态完成筛选的参数

22. typeStatus（通过记录的模式标本状态进行筛选）

• GBIF拥有40种状态类型，可以通过加载rgbif包中的 /assets/typestatus.csv 查看它们的名称以及描述。

23. basisOfRecord（通过数据记录的自然状态进行筛选）

• 要求传递字符型。从以下选项中任选其一：
  • “FOSSIL_SPECIMEN”
  • “HUMAN_OBSERVATION”
  • “MATERIAL_CITATION”
  • “MATERIAL_SAMPLE”
  • “LIVING_SPECIMEN”
  • “MACHINE_OBSERVATION”
  • “OBSERVATION”
  • “PRESERVED_SPECIMEN”
  • “OCCURRENCE”

24. mediaType（通过媒体的类型进行筛选）

• 要求传递字符型，从以下三个选项中任选其一：
  • “MovingImage”（默认值）
  • “Sound”
  • “StillImage”

25. degreeOfEstablishment（根据生物体活动信息进行筛选）

• 要求传递字符型。
• 提供有关生物体在给定地点和时间存活、繁殖和扩展范围的程度的信息。

26. occurrenceStatus

• 要求传递字符型。
• 提供的选项包括：
  • “PRESENT”（默认值）
  • “ABSENT”

27. iucnRedListCategory（根据红色名录进行筛选）

• 要求传递字符型。
• 提供的濒危状态有：
  • “NE”：尚未评估。
  • “DD”：缺少数据。
  • “LC”：无需关注。
  • “NT”：近乎濒危。
  • “VU”：易濒危种。
  • “EN”：濒危物种。
  • “CR”：极度濒危。
  • “EX”：绝灭物种。
  • “EW”：野外绝灭。

dd. 通过编号完成筛选的参数

28. recordNumber（通过数据采集者指定的记录编号进行筛选）

• 要求传递字符型。
• 数据采集者指定的记录编号与GBIF的记录编号不是一回事。

29. eventId（通过采样事件的标识符进行筛选）

• 要求传递字符型。

30. networkKey（通过网络密钥进行筛选）

• 要求传递字符型。
• 将分类单元分配给主题的事件网络密钥(uuid)。

ee. 通过时间完成筛选的参数

31. lastInterpreted（通过数据的最新变动时间进行筛选）

• 要求传递字符型。
• GBIF中记录最后修改的日期，ISO 8601的时间格式：yyyy，yyyy-MM，yyyy-MM-dd，MM-dd。
• 支持时间段检索，按照 ‘小年份，大年份’ 格式，比如：‘1990，1991’。

32. eventDate（与lastInterpreted相同）

33. year（通过年份进行筛选）

• 要求传递字符型。
• 四位数的年份。但输入98仍可被解释为公元98年。
• 支持时间段检索，按照 ‘小年份，大年份’ 格式，比如：‘1990，1991’。

34. month（通过月份进行筛选）

• 要求传递字符型。
• 一年中的月份，以1开头表示1月。
• 支持时间段检索，按照 ‘小月份，大月份’ 格式，比如：‘1，2’。

ff. 通过人员完成筛选的参数

35. recordedBy（通过数据记录的采集者进行筛选）

• 要求传递字符型。

36. recordedByID（通过数据记录采集者的标识符进行筛选）

• 要求传递字符型。

37. identifiedByID（通过数据记录的分类鉴定者的标识符进行筛选）

• 要求传递字符型。

38. identifiedBy（通过人员、团体或机构的名称进行筛选）

• 要求传递字符型。

gg. 通过数据集完成筛选的参数

39. datasetKey（通过数据集的uuid标识符进行筛选）

• 要求传递字符型。可以在数据集页面url中找到。

40. catalogNumber（通过实物集合的标识符进行筛选）

• 要求传递字符型。
• 由记录的实物集合或数字数据集中的来源分配的任何形式的标识符，它可能不是唯一的，但与机构和集合代码结合起来应该是相当唯一的。

hh. 通过高度完成筛选的参数

41. elevation（通过数据记录的海拔信息进行筛选）

• 要求传递字符型。
• 以米为单位的海拔。
• 支持范围检索，按照**‘低海拔，高海拔’**格式，比如：‘5，30’。

42. depth（通过数据记录的海拔深度信息进行筛选）

• 要求传递字符型。
• 相对于海拔的深度，以米为单位。例如，在给定海拔的湖面下方10米处。
• • 支持范围检索，按照**‘低值，高值’**格式，比如：‘5，30’。

ii. 通过来源完成筛选的参数

43. institutionCode（通过数据记录所属的机构进行筛选）

• 要求传递字符型。
• 由来源指定的任何形式的标识符，用以标识该记录所属的机构。

44. collectionCode（通过数据记录所属的机构进行筛选）

• 要求传递字符型。
• 由来源指定的任何形式的标识符，用于在机构文本中唯一地标识物理集合或数字数据集。

45. repatriated（通过数据记录的发布地和采集地进行筛选）

• 要求传递字符型。
• 搜索出版国家与记录所在国不同的记录。

46. establishmentMeans（通过数据记录的传入途径进行筛选）

• 要求传递字符型。
• 提供关于一种或多种生物体是否通过现代人类的直接或间接活动被引入到特定地点和时间的信息。
• 提供的选项有：
  • “Introduced”
  • “Native”
  • “NativeReintroduced”
  • “Vagrant”
  • “Uncertain”
  • “IntroducedAssistedColonisation”

47. publishingOrg

• 要求传递字符型。
• 发布组织的标识符（UUID）。

48. isInCluster

• 要求传递逻辑型。
• 识别GBIF上潜在的相关记录。

jj. 通过争议完成筛选的参数

49. issue（通过数据记录的争议之处进行筛选）

• 要求传递字符型。
• 每个事件记录中可能出现的一个或多个争议之处。按争议之处筛选结果。
• 有关可以使用的选项请参阅GBIF Issues & Flags和OccurrenceIssue。

kk. 通过分类完成筛选的参数

50. subgenusKey（通过亚属的分类标识符进行筛选）

• 要求传递数值型。

51. phylumKey（通过阶元门的标识符进行筛选）

• 要求传递数值型。

52. kingdomKey（通过阶元界的标识符进行筛选）

• 要求传递数值型。

53. classKey（通过阶元纲的标识符进行筛选）

• 要求传递数值型。

54. orderKey（通过阶元目的标识符进行筛选）

• 要求传递数值型。

55. familyKey（通过阶元科的标识符进行筛选）

• 要求传递数值型。

56. genusKey（通过阶元属的标识符进行筛选）

• 要求传递数值型。

57. speciesKey（通过阶元种的标识符进行筛选）

• 要求传递数值型。

58. verbatimTaxonId（通过数据发布者提供的分类标识符进行筛选）

• 要求传递字符型。

59. occurrenceId（通过来源的数据记录标识符进行筛选）

• 要求传递字符型。

ll. 通过协议完成筛选的参数

60. protocol（通过数据记录的协议进行筛选）

• 要求传递字符型。

61. license（通过数据集或记录的许可类型进行筛选）

• 要求传递字符型。提供的选项有：
  • “CC0_1_0”
  • “CC_BY_4_0”
  • “CC_BY_NC_4_0”

mm. 通过生物体完成筛选的参数

62. organismId

• 生物体实例的标识符(相对于生物体的特定数字记录)。可以是全局唯一标识符或特定于数据集的标识标识符。

63. organismQuantity

• 指定所需生物体数量的数字或范围。organmquantity =5将解释为所有恰好为5的记录。
• 支持范围检索，按照**‘低值，高值’**格式，比如：‘5，30’。

64. organismQuantityType

• 要求传递字符型。
• 生物体的类型。比如：“individuals"或"biomass”。

65. relativeOrganismQuantity

• 要求传递数值型。

66. lifeStage

• 要求传递数值型。
• 数据记录的发育阶段。

nn. 通过返回条件进行筛选的参数

67. limit（限制返回的记录数量）

默认值:500。请注意，每个请求的最大值是300，但由于我们将该函数的最大值设置为500，因此我们执行两个请求来获得500条记录(如果有那么多)。请注意，有一个100,000的硬最大值，它被计算为limit+start，因此start=99,000和limit=2000将不起作用。

68. start（返回记录的起始位置）

与限制页面浏览结果结合使用。注意，我们在内部为您执行分页操作，但是您可以手动设置start参数。

69. fields（返回记录的条目）

• 要求传递字符型。
• Default (’ all ‘)返回所有字段。’ minimal ‘只返回分类名、标识符、datasetKey、纬度和经度。或者指定您希望通过名称返回的每个字段，例如fields = c(’ name '， ’ latitude '， ’ elevation ')。

70. facet

• 要求传递字符型。
• 长度大于等于1的字符向量。必需的。

71. facetMincount

• 要求传递数值型。
• 要包含在切面结果中的最小记录数

72. facetMultiselect

• 要求传递逻辑型。
• 设置为TRUE仍然返回当前未过滤的值的计数。

73. skip_validate

• 要求传递逻辑型。
• 是否跳过wellknown::validate_wkt调用。传递给check_wkt()。默认值：TRUE。

74. curlopts

传递给HttpClient的命名curl选项列表。有关curl选项，请参见curl::curl_options。

75. …

additional facet parameters。