Skip to contents

Return a list of studies for which trees match a given set of properties


  property = NULL,
  value = NULL,
  verbose = FALSE,
  exact = FALSE,
  detailed = TRUE,



The property to be searched on (character)


The property-value to be searched on (character)


Should the output include all metadata? (logical, default FALSE)


Should exact matching be used for the value? (logical, default FALSE)


Should a detailed report be provided? If TRUE (default), the output will include metadata about the study that include trees matching the property. Otherwise, only information about the trees will be provided.


additional arguments to customize the API request (see rotl package documentation).


A data frame that summarizes the trees found (and their associated studies) for the requested criteria. If a study has more than 5 trees, the tree_ids of the first ones will be shown, followed by ... to indicate that more are present.

If detailed=FALSE, the data frame will include the study ids of the study (study_ids), the number of trees in this study that match the search criteria (n_matched_trees), the tree ids that match the search criteria (match_tree_ids).

If detailed=TRUE, in addition of the fields listed above, the data frame will also contain the total number of trees associated with the study (n_trees), all the tree ids associated with the study (tree_ids), the tree id that is a potential candidate for inclusion in the synthetic tree (if any) (candidate), the year the study was published (study_year), the title of the study (title), the DOI for the study (study_doi).


The list of possible values to be used as values for the argument property can be found using the function studies_properties.

See also

studies_properties which lists properties the studies can be searched on. list_trees for listing the trees that match the query.


if (FALSE) {
res <- studies_find_trees(property="ot:ottTaxonName", value="Drosophila",
## summary of the trees and associated studies that match this criterion
## With metadata about the studies (default)
res <- studies_find_trees(property="ot:ottTaxonName", value="Drosophila",
## The list of trees for each study that match the search criteria
## the trees for a given study
list_trees(res, study_id = "pg_2769")