Difference between revisions of "Sample Queries"

Latest revision as of 19:40, 19 January 2021

These queries illustrate the power of the Semantic MediaWiki query language ("semantic search") and the Semantic MediaWiki query interfaces to extract data stored by the Flora of North America Semantic MediaWiki.

Click here to access the Semantic search query interface directly.

Query Size Limitations

Semantic MediaWiki software limits queries to 5,000 results. If you expect your query to return more than 5,000 results, you should run your query in batches. (N.B.: There are ~20,000 treatments in the FNA Online.)

To run your query in batches, we recommend splitting results by 'published volume'. You can do this by adding a volume condition to your query (e.g., "[[Volume::Volume 17]]"). Please see this page for a list of volumes that can be queried.

Queries by Subject

Taxonomy

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
All Taxa in the Online FNA	Taxon rank (see allowed values)	`[[Taxon rank::+]]`	Try it!		R script Python script
All Species in the Online FNA	Taxon rank (see allowed values)	`[[Taxon rank::species]]`	Try it!		R script Python script
List of Lower Taxa	Taxon parent	`[[Taxon parent::Carex]]`	Try it!	In the genus Carex, Carex sect. Acrocystis Carex sect. Albae ... further results	R script Python script
List of Sections	Taxon family (see allowed values) Taxon rank (see allowed values)	`[[Taxon family::Asteraceae]][[Taxon rank::section]]`	Try it!	Sections in the family Asteraceae, Chaenactis sect. Acarphaea Chaenactis sect. Chaenactis ... further results	R script Python script

Distribution

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
Taxa occurring in Non-Abbreviated State or Province (i.e., Alaska, Idaho, Iowa, Maine, Nunavut, Ohio, Yukon)	Distribution (see allowed values and Distribution Abbreviations)	`[[Distribution::Nunavut]]`	Try it!	Taxa occurring in Nunavut, Abietinella abietina Achillea millefolium ... further results	R script Python script
Taxa occurring in Abbreviated State or Province	Distribution (see allowed values and Distribution Abbreviations)	`[[Distribution::Ont.]]`	Try it!	Taxa occurring in Ontario, Abies balsamea Abietinella abietina ... further results	R script Python script

Publication Details

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
Taxa by Authority	Authority	`[[Authority::Linnaeus]]`	Try it!	Taxa described by Linnaeus, Acalypha Acalypha australis ... further results	R script Python script
Taxa by Publication Title	Publication title	`[[Publication title::Proc. Amer. Acad. Arts]]`	Try it!		R script Python script
Taxa by Publication Year	Publication year	`[[Publication year::1990]]`	Try it!		R script Python script

You can use comparators with the Publication year property. For example,

Taxa by Publication Year with Comparator	Publication year	`[[Publication year::>>1990]]`	Try it!	Taxa published after 1990, Abronia bolackii Abronia umbellata var. breviflora ... further results		R script Python script

Special Status

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
Taxa by Special Status	Special status (see allowed values)	`[[Special status::Introduced]]`	Try it!	Introduced species, Agalinis Agalinis aphylla ... further results	R script Python script

Illustrations

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
All Illustrated Taxa in the Online FNA	Illustrator (see allowed values) Illustration	`[[Illustrator::+]][[Illustration::Present]]`	Try it!		R script Python script
List of Illustrations by Person	Illustrator (see allowed values) Illustration	`[[Illustrator::Annaliese Miller]][[Illustration::Present]]`	Try it!	Illustrations by Annaliese Miller, Aeluropus littoralis Arundinaria appalachiana ... further results	R script Python script
A list of illustrations, taxon name, taxon family, volume and illustrator	Plate of taxon Note that this query employs property chains	`[[Plate of taxon::+]]\|?Plate of taxon\|?Plate of taxon.Taxon family=Taxon family\|?Plate of taxon.Volume=Volume\|?Plate of taxon.Illustrator=Illustrator`	Try it!

Volumes

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
Treatments By Volume	Volume (see allowed values)	`[[Volume::Volume 17]]`	Try it!	Treatments published in volume 17, Agalinis Agalinis aphylla ... further results	R script Python script

Contributors

	Properties Used	Query Syntax	Query Interface	Query Results	Query the API
Treatments by Author	Author	`[[Author::Bruce A. Ford]]`	Try it!	Treatments authored by Bruce A. Ford, Actaea Actaea pachypoda ... further results	R script Python script

Advanced Queries

Composite Queries

You can combine any query elements from the above subjects to create a custom search.

For example,

Taxa with authority Linnaeus that occur in Nunavut	`[[Authority::Linnaeus]][[Distribution::Nunavut]]`
Introduced species published in volume 3	`[[Special status::Introduced]][[Volume::Volume 3]]`
Taxa published before 1754 in the family Cyperaceae	`[[Publication year::<<1754]][[Taxon family::Cyperaceae]]`

Comparators

You can use comparators with the Publication year property. (e.g., >, <, ≥).

Taxonomic Filtering

To return a dataset restricted to a taxonomic group, simply add a category filter:


	Properties Used	Category Used	Query Syntax	Query Interface	Query Results
Elevation data for Carex	Elevation	Carex	`[[Category:Carex]]\|?Elevation`	Try it!	Carex aboriginum (Elevation: 700–1000 m) Carex abrupta (Elevation: 1400–3300 m) ... further results

When working with categories, precede your category request with only one colon.

Return More Information

You can return as many additional properties as you wish:

Query interface	Query the API
Add property names to the Additional data to display box	Add properties using the \|? syntax: `[[Authority::Linnaeus]][[Distribution::Nunavut]]\|?Taxon family\|?Taxon rank\|?Author`

Write Your Own Queries

Click here to access the Semantic search query interface directly.

Note that:

The limit on the number of results returned can be changed
You can only export what is displayed on the page (JSON, CSV, RSS, RDF)
- Page through the results to download each batch

Why use the API convenience scripts?

For big queries, it may be cumbersome to download each batch of 500 results separately and then merge the results.
If you are performing your analyses in R or Python, you may wish to embed the data extraction here, so that it can be easily re-run.

Access the convenience scripts here: https://github.com/jocelynpender/fna-query

Query Resources

Semantic MediaWiki Query Syntax

https://www.semantic-mediawiki.org/wiki/Help:Semantic_search

https://www.semantic-mediawiki.org/wiki/Help:Search_operators

Merging Multiple CSV Files

R script for merging multiple CSV files.

Working with APIs

@@ Line 2: / Line 2: @@
 [[Special:Ask|Click here to access the '''Semantic search query interface''' directly.]]
+== Query Size Limitations ==
+Semantic MediaWiki software limits queries to 5,000 results. If you expect your query to return more than 5,000 results, you should run your query in batches. (N.B.: There are ~20,000 treatments in the FNA Online.)
+To run your query in batches, we recommend splitting results by 'published volume'. You can do this by adding a volume condition to your query (e.g., "<code><nowiki>[[Volume::Volume 17]]</nowiki></code>"). Please see [http://beta.semanticfna.org/w/index.php?title=Special%3ASearchByProperty&property=Volume&value= this page] for a list of volumes that can be queried.
 == Queries by Subject ==
@@ Line 187: / Line 193: @@
 === Special Status ===
-Due to limitations in data capture, special status data are only available in V3, V6, V9, V12, V17, V28.
 {| class="wikitable"
 !
@@ Line 255: / Line 259: @@
 |[https://github.com/jocelynpender/fna-query/blob/master/R/demo_queries/illustrations/illustrations_by_person.R R script]
 [https://github.com/jocelynpender/fna-query/blob/master/python/demo_queries/illustrations/illustrations_by_person.py Python script]
+|-
+|A list of illustrations, taxon name, taxon family, volume and illustrator
+|[[Property:Plate of taxon|Plate of taxon]]
+Note that this query employs [https://www.semantic-mediawiki.org/wiki/Help:Subqueries_and_property_chains property chains]
+|<code><nowiki>[[Plate of taxon::+]]|?Plate of taxon|?Plate of taxon.Taxon family=Taxon family|?Plate of taxon.Volume=Volume|?Plate of taxon.Illustrator=Illustrator</nowiki></code>
+|{{#ask:
+[[Plate of taxon::+]]|?Plate of taxon|?Plate of taxon.Taxon family=Taxon family|?Plate of taxon.Volume=Volume|?Plate of taxon.Illustrator=Illustrator
+|searchlabel=Try it!
+|limit=0
+}}
+|
+|
 |}
 === Volumes ===
@@ Line 307: / Line 323: @@
 |[https://github.com/jocelynpender/fna-query/blob/master/R/demo_queries/contributors/treatments_by_author.R R script]
 [https://github.com/jocelynpender/fna-query/blob/master/python/demo_queries/contributors/treatments_by_author.py Python script]
-|}
-=== Morphology ===
-A property browser is in development to facilitate the exploration of the morphological properties. Here are a few sample queries to illustrate the power of parsed morphological data derived from FNA treatments.
-{| class="wikitable"
-!
-!Properties Used
-!Query Syntax
-!Query Interface
-!Query Results
-!Query the API
-|-
-|Taxa by corolla coloration
-|[[Property:Corolla coloration|Corolla coloration]] (explore [[Special:SearchByProperty/:Corolla coloration/|available values]])
-|<code><nowiki>[[Corolla coloration::yellow]]</nowiki></code>
-|{{#ask:
-[[Corolla coloration::yellow]]
-|searchlabel=Try it!
-|limit=0
-}}
-|Taxa with yellow corolla coloration,{{#ask:
-[[Corolla coloration::yellow]]
-|limit=2
-|format=ul
-}}
-|[https://github.com/jocelynpender/fna-query/blob/master/R/demo_queries/morphology/taxa_by_corolla_coloration.R R script]
-[https://github.com/jocelynpender/fna-query/blob/master/python/demo_queries/morphology/taxa_by_corolla_coloration.py Python script]
-|-
-|Taxa by leaf arrangement
-|[[Property:Leaf arrangement|Leaf arrangement]] (explore [[Special:SearchByProperty/:Leaf arrangement/|available values]])
-|<code><nowiki>[[Leaf arrangement::alternate]]</nowiki></code>
-|{{#ask:
-[[Leaf arrangement::alternate]]
-|searchlabel=Try it!
-|limit=0
-}}
-|Taxa with alternate leaf arrangement,{{#ask:
-[[Leaf arrangement::alternate]]
-|limit=2
-|format=ul
-}}
-|[https://github.com/jocelynpender/fna-query/blob/master/R/demo_queries/morphology/taxa_by_leaf_arrangement.R R script]
-[https://github.com/jocelynpender/fna-query/blob/master/python/demo_queries/morphology/taxa_by_leaf_arrangement.py Python script]
-|-
-|Taxa by blade shape
-|[[Property:Blade shape|Blade shape]] (explore [[Special:SearchByProperty/:Blade shape/|available values]])
-|<code><nowiki>[[Blade shape::elliptic]]</nowiki></code>
-|{{#ask:
-[[Blade shape::elliptic]]
-|searchlabel=Try it!
-|limit=0
-}}
-|Taxa with elliptic blade shape,{{#ask:
-[[Blade shape::elliptic]]
-|limit=2
-|format=ul
-}}
-|[https://github.com/jocelynpender/fna-query/blob/master/R/demo_queries/morphology/taxa_by_blade_shape.R R script]
-[https://github.com/jocelynpender/fna-query/blob/master/python/demo_queries/morphology/taxa_by_blade_shape.py Python script]
 |}
 == Advanced Queries ==
 === Composite Queries ===
 You can combine any query elements from the above subjects to create a custom search.
@@ Line 389: / Line 344: @@
 === Comparators ===
 You can use [https://www.semantic-mediawiki.org/wiki/Help:Search_operators comparators] with the [[Property:Publication year|Publication year property]]. (e.g., '''<code>></code>''', '''<code><</code>''', '''<code>≥</code>''').
+=== Taxonomic Filtering ===
+To return a dataset restricted to a taxonomic group, simply add a category filter:
+{| class="wikitable"
+|+
+!
+!Properties Used
+!Category Used
+!Query Syntax
+!Query Interface
+!Query Results
+|-
+|Elevation data for ''Carex''
+|Elevation
+|Carex
+|<code><nowiki>[[Category:Carex]]|?Elevation</nowiki></code>
+|{{#ask:
+[[Category:Carex]]|?Elevation
+|searchlabel=Try it!
+|limit=0
+}}
+|{{#ask:
+[[Category:Carex]]|?Elevation
+|limit=2
+|format=ul
+}}
+|}
+When working with categories, precede your category request with only '''one colon.'''
 === Return More Information ===