API Docs#
- galah.atlas_counts(taxa=None, scientific_name=None, filters=None, group_by=None, total_group_by=False, expand=True, use_data_profile=False, verbose=False, polygon=None, bbox=None, simplify_polygon=False)#
Prior to downloading data, it is often valuable to have some estimate of how many records are available, both for deciding if the query is feasible, and for estimating how long it will take to download. Alternatively, for some kinds of reporting, the count of observations may be all that is required, for example for understanding how observations are growing or shrinking in particular locations, or for particular taxa.
To this end,
galah.atlas_counts()takes arguments in the same format asgalah.atlas_occurrences(), and provides either a total count of records matching the criteria, or a pandas dataframe of counts matching the criteria supplied to the group_by argument. It can also return the total number of groups by using the total_group_by argument.- Parameters:
taxa (string) – one or more scientific names. Use
galah.search_taxa()to search for valid scientific names.filters (pandas.DataFrame) – filters, in the form
fieldlogicalvalue(e.g."year=2021")group_by (string) – zero or more individual column names (i.e. fields) to include. See
galah.show_all()andgalah.search_all()to see valid fields.total_group_by (logical) – If
True, galah gives total number of groups in data. Defaults toFalse.expand (logical) – When using the
group_byargument ofgalah.atlas_counts(), controls whether counts for each row value are combined or calculated separately. Defaults toTrue.verbose (logical) – If
True, galah gives more information like progress bars. Defaults toFalse.use_data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using
galah.show_all(profiles=True)polygon (shapely Polygon) – A polygon object denoting a geographical region. Defaults to
None.bbox (dict or shapely Polygon) – A polygon or dictionary object denoting four points, which are the corners of a geographical region. Defaults to
None.simplify_polygon (logical) – When using the
polygonargument ofgalah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults toFalse.
- Return type:
An object of class
pandas.DataFrame.
Examples
Return total records in your chosen atlas
galah.atlas_counts()totalRecords 0 133620113
Return records from 2020 onwards, grouped by year
galah.atlas_counts(filters="year>2019",group_by="year",expand=False)year count 0 2020 7156697 1 2021 8288673 2 2022 8479723 3 2023 3771579 4 2024 540931
- galah.atlas_media(taxa=None, scientific_name=None, filters=None, fields=None, verbose=False, multimedia=None, assertions=None, use_data_profile=False, polygon=None, bbox=None, simplify_polygon=False, collect=False, path=None)#
In addition to text data describing individual occurrences and their attributes, ALA stores images, sounds and videos associated with a given record.
galah.atlas_media()displays metadata for any and all of the media types.- Parameters:
taxa (string / list) – one or more scientific names. Use
galah.search_taxa()to search for valid scientific names.filters (string / list) – filters, in the form
fieldlogicalvalue(e.g."year=2021")fields (string / list) –
Name of one or more column groups to include. Valid options are “basic”, “event” and “assertions” Default is set to
"fields=basic", which returns:decimalLatitude, decimalLongitude, eventDate, scientificName, taxonConceptID, recordID, dataResourceName, occurrenceStatus
Using
"fields="event"returns:eventRemarks, eventTime, eventID, eventDate, samplingEffort, samplingProtocol
Using
fields="media"returns:multimedia, multimediaLicence, images, videos, sounds
See
galah.show_all()andgalah.search_all()to see all valid fields.verbose (logical) – If
True, galah gives more information like URLs queried. Defaults toFalsemultimedia (string / list) – This is for specifying what types of multimedia you would like, i.e “images”. Defaults to [‘images’,’videos’,’sounds’]
assertions (string) – Using “assertions” returns all quality assertion-related columns. These columns are data quality checks run by each living atlas. The list of assertions is shown by
galah.show_all(assertions=True).use_data_profile (logical) – if
True, uses data profile set ingalah_config(). Valid values can be seen usinggalah.show_all(profiles=True). Default isFalsepolygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to
None.bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to
None.simplify_polygon (logical) – When using the
polygonargument ofgalah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults toFalse.collect (logical) – if
True, downloads full-sized images and media files returned to a local directory.path (string) – path to directory where downloaded media will be stored. Defaults to current directory.
- Return type:
An object of class
pandas.DataFrame. Ifcollect=True, available image & media files are downloaded to a user local directory.
Examples
galah.galah_config(atlas="Australia",email="youremail@example.com") galah.atlas_media(taxa="Ornithorhynchus anatinus",filters=["year=2020","decimalLongitude>153.0")
decimalLatitude decimalLongitude eventDate \ 0 -30.311448 153.015910 2020-09-08T07:26:47Z 1 -30.300649 153.006628 2020-08-30T08:37:43Z 2 -30.298361 153.007479 2020-08-30T08:35:00Z 3 -30.298183 153.005912 2020-09-04T08:28:00Z 4 -30.297841 153.005873 2020-09-26T07:39:00Z 5 -28.678673 153.297699 2020-08-13T00:00:00Z 6 -28.661653 153.300439 2020-10-12T06:20:00Z 7 -28.661653 153.300439 2020-10-12T06:20:00Z 8 -28.213785 153.386929 2020-01-17T07:09:00Z 9 -28.213785 153.386929 2020-01-17T07:09:00Z scientificName recordID \ 0 Ornithorhynchus anatinus 6882dfe3-5295-493d-a005-66f8392e9d5b 1 Ornithorhynchus anatinus 72ad295f-112d-442f-83e1-fd385ef9163a 2 Ornithorhynchus anatinus 42912016-2409-4125-a61f-13ffd4c32fcb 3 Ornithorhynchus anatinus dd885218-bdb9-404a-8441-e5cd329f6605 4 Ornithorhynchus anatinus 072bc4f0-7581-44c6-b0ec-e3fe58d251fc 5 Ornithorhynchus anatinus 12d8c7f9-9d66-4312-9245-87a0a1021557 6 Ornithorhynchus anatinus 2a701513-b21d-4baa-bac4-5e6a3a65252b 7 Ornithorhynchus anatinus 2a701513-b21d-4baa-bac4-5e6a3a65252b 8 Ornithorhynchus anatinus 808b0c19-9616-45f1-994e-e3b33fc32836 9 Ornithorhynchus anatinus 808b0c19-9616-45f1-994e-e3b33fc32836 dataResourceName occurrenceStatus multimedia \ 0 iNaturalist Australia PRESENT Image 1 iNaturalist Australia PRESENT Image 2 iNaturalist Australia PRESENT Image 3 iNaturalist Australia PRESENT Image 4 iNaturalist Australia PRESENT Image 5 iNaturalist Australia PRESENT Image 6 iNaturalist Australia PRESENT Image 7 iNaturalist Australia PRESENT Image 8 Earth Guardians Weekly Feed PRESENT Image 9 Earth Guardians Weekly Feed PRESENT Image images videos sounds creator \ 0 792a93d4-6436-4222-9a00-00cda0ec1f14 NaN NaN kerrycameron 1 1aad7125-c6c0-4557-b9a2-112c03ac6709 NaN NaN Brett Vercoe 2 09efd0a0-aa51-4d00-80f9-4e78e19aa89e NaN NaN Brett Vercoe 3 40aadbde-3918-4bba-9dc9-13fa1da3809b NaN NaN Brett Vercoe 4 14374712-1c37-4e2d-af28-4572f64e7d3a NaN NaN Brett Vercoe 5 393df479-5fbb-464e-82ed-4d6fd19dd863 NaN NaN julespetroff 6 7424399a-f327-4ea1-9ffa-aa7a2b69f82b NaN NaN julespetroff 7 cee7bb9f-6b2e-4c47-8ba8-c9a3bdf92fa0 NaN NaN julespetroff 8 66904cee-f8ca-4e3a-b7d5-d738f4bd0978 NaN NaN None 9 dfdbd258-d90a-484b-af19-2070705f166c NaN NaN None license mimetype width height \ 0 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 927 701 1 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1365 2048 2 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 2048 1238 3 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 2048 1365 4 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 2048 1365 5 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 638 426 6 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 713 401 7 http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 661 500 8 None image/jpeg 2988 5312 9 None image/jpeg 2988 5312 imageUrl 0 https://images.ala.org.au/store/4/1/f/1/792a93... 1 https://images.ala.org.au/store/9/0/7/6/1aad71... 2 https://images.ala.org.au/store/e/9/8/a/09efd0... 3 https://images.ala.org.au/store/b/9/0/8/40aadb... 4 https://images.ala.org.au/store/a/3/d/7/143747... 5 https://images.ala.org.au/store/3/6/8/d/393df4... 6 https://images.ala.org.au/store/b/2/8/f/742439... 7 https://images.ala.org.au/store/0/a/f/2/cee7bb... 8 https://images.ala.org.au/store/8/7/9/0/66904c... 9 https://images.ala.org.au/store/c/6/6/1/dfdbd2...
- galah.atlas_occurrences(taxa=None, scientific_name=None, filters=None, test=False, verbose=False, fields=None, assertions=None, use_data_profile=False, species_list=False, status_accepted=True, polygon=None, bbox=None, simplify_polygon=False)#
The most common form of data stored by living atlases are observations of individual life forms, known as ‘occurrences’. This function allows the user to search for occurrence records that match their specific criteria, and return them as a
pandas.DataFramefor analysis. Optionally, the user can also request a DOI for a given download to facilitate citation and re-use of specific data resources.- Parameters:
taxa (string) – one or more scientific names. Use
galah.search_taxa()to search for valid scientific names.filters (string / list) – filters, in the form
fieldlogicalvalue(e.g."year=2021")test (logical) – Test if the API is up and running correctly. Prints status of Atlas and returns.
verbose (logical) – If
True, galah gives more information like URLs of your queries. Defaults toFalsefields (string / list) –
Name of one or more column groups to include. Valid options are “basic”, “event” and “assertions” Default is set to
"fields=basic", which returns:decimalLatitude, decimalLongitude, eventDate, scientificName, taxonConceptID, recordID, dataResourceName, occurrenceStatus
Using
"fields="event"returns:eventRemarks, eventTime, eventID, eventDate, samplingEffort, samplingProtocol
Using
fields="media"returns:multimedia, multimediaLicence, images, videos, sounds
See
galah.show_all()andgalah.search_all()to see all valid fields.assertions (string / list) – Using “assertions” returns all quality assertion-related columns. These columns are data quality checks run by each living atlas. The list of assertions is shown by
galah.show_all(assertions=True).use_data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using
galah.show_all(profiles=True)species_list (logical) – Denotes whether or not you want a species list for GBIF. Default to
False. For species lists, refer toatlas_speciesstatus_accepted (logical) – Denotes whether or not you want only accepted taxonomic ranks for GBIF. Default to
True. For species lists, refer toatlas_speciespolygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to
None.bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to
None.simplify_polygon (logical) – When using the
polygonargument ofgalah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults toFalse.
- Return type:
An object of class
pandas.DataFrame.
Examples
Download records of Vulpes vulpes in 2023
import galah galah.galah_config(atlas="Australia",email="your-email@example.com") galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year=2023")
decimalLatitude decimalLongitude eventDate scientificName \ 0 -39.083564 146.383184 2023-02-02T00:00:00Z Vulpes vulpes 1 -39.055892 146.448243 2023-09-26T02:58:13Z Vulpes vulpes 2 -39.029077 146.323238 2023-01-12T19:16:00Z Vulpes vulpes 3 -39.026141 146.332604 2023-07-16T00:00:00Z Vulpes vulpes 4 -39.021544 146.443742 2023-03-14T04:40:48Z Vulpes vulpes ... ... ... ... ... 5591 39.300000 -75.400000 2023-11-02T04:54:00Z Vulpes vulpes 5592 40.000000 -81.500000 2023-07-14T11:15:00Z Vulpes vulpes 5593 42.100000 -71.600000 2023-12-18T13:33:00Z Vulpes vulpes 5594 43.600000 145.300000 2023-08-09T10:50:47Z Vulpes vulpes 5595 51.100000 -0.500000 2023-03-17T12:04:54Z Vulpes vulpes taxonConceptID \ 0 https://biodiversity.org.au/afd/taxa/2869ce8a-... 1 https://biodiversity.org.au/afd/taxa/2869ce8a-... 2 https://biodiversity.org.au/afd/taxa/2869ce8a-... 3 https://biodiversity.org.au/afd/taxa/2869ce8a-... 4 https://biodiversity.org.au/afd/taxa/2869ce8a-... ... ... 5591 https://biodiversity.org.au/afd/taxa/2869ce8a-... 5592 https://biodiversity.org.au/afd/taxa/2869ce8a-... 5593 https://biodiversity.org.au/afd/taxa/2869ce8a-... 5594 https://biodiversity.org.au/afd/taxa/2869ce8a-... 5595 https://biodiversity.org.au/afd/taxa/2869ce8a-... recordID dataResourceName \ 0 572341b6-94ca-4d96-bf4f-889cbd5e26f0 FeralScan 1 c9e41540-1253-4db8-b13a-25b353dc93b5 iNaturalist Australia 2 cab54c0e-c06a-4998-8788-f918cf104154 iNaturalist Australia 3 147fbb76-92b6-460c-bb12-4f9fc5f353b0 FeralScan 4 e82ec752-fbcc-40e4-97e4-41adbfdee088 iNaturalist Australia ... ... ... 5591 531ca541-8c12-4bdd-834d-31980cd127ab Earth Guardians Weekly Feed 5592 4065886d-ce29-48d2-b8b3-9bc4195ba8b3 Earth Guardians Weekly Feed 5593 d35e6a68-ca70-42d2-beae-e6747d1138cf Earth Guardians Weekly Feed 5594 47b6921d-3891-4e52-b1aa-9fbd57e76823 Earth Guardians Weekly Feed 5595 65fc1040-5675-4f6c-8c92-40f8de159bed Earth Guardians Weekly Feed occurrenceStatus 0 PRESENT 1 PRESENT 2 PRESENT 3 PRESENT 4 PRESENT ... ... 5591 PRESENT 5592 PRESENT 5593 PRESENT 5594 PRESENT 5595 PRESENT [5596 rows x 8 columns]Download records of Vulpes vulpes in 2023, returning only
eventDatefieldimport galah galah.galah_config(atlas="Australia",email="your-email@example.com") galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year=2023",fields="eventDate")
eventDate 0 2022-12-31T14:56:00Z 1 2022-12-31T21:21:27Z 2 2023-01-01T00:00:00Z 3 2023-01-01T00:00:00Z 4 2023-01-01T00:00:00Z ... ... 5591 2023-12-31T00:00:00Z 5592 2023-12-31T00:00:00Z 5593 2023-12-31T00:00:00Z 5594 2023-12-31T03:01:00Z 5595 2023-12-31T05:56:00Z [5596 rows x 1 columns]
- galah.atlas_species(taxa=None, scientific_name=None, rank='species', filters=None, verbose=False, status_accepted=True, use_data_profile=False, counts=False, polygon=None, bbox=None, simplify_polygon=False)#
While there are reasons why users may need to check every record meeting their search criteria (i.e. using
galah.atlas_occurrences()), a common use case is to simply identify which species occur in a specified region, time period, or taxonomic group. This function returns apandas.DataFramewith one row per species, and columns giving associated taxonomic information.- Parameters:
taxa (string / list) – one or more scientific names. Use
galah.search_taxa()to search for valid scientific names.rank (string) – the rank you ultimately want to get names for, i.e. “genus” or “species”. Default is
species.filters (string) – filters, in the form
fieldlogicalvalue(e.g."year=2021")verbose (logical) – If
True, galah gives you the URLs used to query all the data. Default toFalse.status_accepted (logical) – If
True, galah gives you only the accepted taxonomic ranks. Default isFalse. **FOR GBIF ONLYpolygon (shapely Polygon) – A polygon shape denoting a geographical region. Defaults to
None.bbox (dict or shapely Polygon) – A polygon or dictionary type denoting four points, which are the corners of a geographical region. Defaults to
None.simplify_polygon (logical) – When using the
polygonargument ofgalah.atlas_counts(), specifies whether or not to draw a bounding box around the polygon and use this instead. Defaults toFalse.
- Return type:
An object of class
pandas.DataFrame.
Examples
galah.atlas_species(taxa="Heleioporus")Species \ 0 https://biodiversity.org.au/afd/taxa/8bbafeb6-... 1 https://biodiversity.org.au/afd/taxa/894e0593-... 2 https://biodiversity.org.au/afd/taxa/7683b712-... 3 https://biodiversity.org.au/afd/taxa/dfae4fa3-... 4 https://biodiversity.org.au/afd/taxa/c77dbdfb-... 5 https://biodiversity.org.au/afd/taxa/d147024b-... Species Name Scientific Name Authorship Taxon Rank Kingdom \ 0 Heleioporus eyrei (Gray, 1845) species Animalia 1 Heleioporus australiacus (Shaw & Nodder, 1795) species Animalia 2 Heleioporus albopunctatus Gray, 1841 species Animalia 3 Heleioporus psammophilus (Lee & Main, 1954) species Animalia 4 Heleioporus barycragus Lee, 1967 species Animalia 5 Heleioporus inornatus (Lee & Main, 1954) species Animalia Phylum Class Order Family Genus \ 0 Chordata Amphibia Anura Limnodynastidae Heleioporus 1 Chordata Amphibia Anura Limnodynastidae Heleioporus 2 Chordata Amphibia Anura Limnodynastidae Heleioporus 3 Chordata Amphibia Anura Limnodynastidae Heleioporus 4 Chordata Amphibia Anura Limnodynastidae Heleioporus 5 Chordata Amphibia Anura Limnodynastidae Heleioporus Vernacular Name 0 Moaning Frog 1 Giant Burrowing Frog 2 Western Spotted Frog 3 Sand Frog 4 Hooting Frog 5 Plains Frog
- galah.galah_config(email=None, email_notify=None, atlas=None, data_profile=None, ranks=None, reason=None, usernameGBIF=None, passwordGBIF=None)#
The galah package supports large data downloads, and also interfaces with the ALA which requires that users of some services provide a registered email address and reason for downloading data. The
galah_config()function provides a way to manage these issues as simply as possible.- Parameters:
email (string) – An email address that has been registered with the chosen atlas. For the ALA, you can register here.
email_notify (string) – Used to receive an email for each query to
galah.atlas_occurrences(). Defaults toNone, but can be useful in some instances, for example for tracking DOIs assigned to specific downloads for later citation.atlas (string) – Living Atlas to point to,
Australiaby default. Can be an organisation name, acronym, or region (seeshow_all(atlases=True)for admissible values)data_profile (string) – A profile name. Should be a string - the name or abbreviation of a data quality profile to apply to the query. Valid values can be seen using
galah.show_all(profiles=True)ranks (string) – A string letting galah know what taxonomic ranks to show. Use “all” to see all 69 possible ranks, and “gbif” to see the 9 most common ranks.
reason (integer) – A number (integer) providing the reason you are downloading data. Default is set to 4 (scientific research). For a list of all possible reasons run
galah.show_all_reasons()usernameGBIF (string) – Your username for GBIF atlas. Default is “”.
passwordGBIF (string) – Your password for GBIF atlas. Default is “”.
- Returns:
- No arguments (A
pandas.DataFrameof all current configuration options.)- >=1 arguments (None)
Examples
import galah galah.galah_config(email="yourname@example.com")
- galah.search_all(assertions=None, atlases=None, apis=None, collection=None, datasets=None, fields=None, licences=None, lists=None, profiles=None, providers=None, ranks=None, reasons=None, column_name=None)#
The living atlases store a huge amount of information, above and beyond the occurrence records that are their main output. In galah, one way that users can investigate this information is by searching for a specific option or category for the type of information they are interested in.
search_all()is a helper function that can do searches within multiple types of information.- Parameters:
assertions (string) – Search for results of data quality checks run by each atlas
atlases (string) – Search for what atlases are available
apis (string) – Search for what APIs & functions are available for each atlas
collection (string) – Search for the specific collections within those institutions
datasets (string) – Search for the data groupings within those collections
fields (string) – Search for fields that are stored in an atlas
licences (string) – Search for copyright licences applied to media
lists (string) – Search for what species lists are available
profiles (string) – Search for what data profiles are available
providers (string) – Search for which institutions have provided data
ranks (string) – Search for valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.)
reasons (string) – Search for what values are acceptable as ‘download reasons’ for a specified atlas
column_name (string) – Determines what column in the table this function will search for the string specified as the argument
- Return type:
An object of class
pandas.DataFramecontaining all data of interest.
Examples
import galah galah.search_all(apis="Australia")
atlas system api_name \ 0 Australia collections collections_collections 1 Australia species species_children 2 Australia spatial spatial_layers 3 Australia records records_species 4 Australia records records_query 5 Australia records records_occurrences 6 Australia records records_fields 7 Australia records records_facets 8 Australia records records_counts 9 Australia records records_assertions 10 Australia name-matching names_search_single 11 Australia name-matching names_search_multiple 12 Australia species names_search_bulk_species 13 Australia name-matching names_lookup 14 Australia logger logger_reasons 15 Australia lists lists_lookup 16 Australia lists lists_all 17 Australia images image_metadata 18 Australia images image_licences 19 Australia doi doi_download 20 Australia data-quality profiles_lookup 21 Australia data-quality profiles_all 22 Australia collections collections_providers 23 Australia collections collections_datasets 24 Australia species species_lookup 25 Australia occurrences occurrences_qid api_url \ 0 https://collections.ala.org.au/ws/collection 1 https://api.ala.org.au/species/childConcepts/{id} 2 https://spatial.ala.org.au/ws/layers 3 https://biocache-ws.ala.org.au/ws/occurrences/... 4 https://biocache-ws.ala.org.au/ws/webportal/pa... 5 https://biocache-ws.ala.org.au/ws/occurrences/... 6 https://biocache-ws.ala.org.au/ws/index/fields 7 https://biocache-ws.ala.org.au/ws/occurrence/f... 8 https://biocache-ws.ala.org.au/ws/occurrences/... 9 https://biocache-ws.ala.org.au/ws/assertions/c... 10 https://api.ala.org.au/namematching/api/search... 11 https://api.ala.org.au/namematching/api/search... 12 https://bie-ws.ala.org.au/ws/species/lookup/bulk 13 https://namematching-ws.ala.org.au/api/getByTa... 14 https://api.ala.org.au/logger/service/logger/r... 15 https://lists.ala.org.au/ws/speciesListItems/{... 16 https://lists.ala.org.au/ws/speciesList 17 https://api.ala.org.au/images/ws/getImageInfoF... 18 https://images.ala.org.au/ws/licence 19 https://doi.ala.org.au/doi/{doi_string}/download 20 https://data-quality-service.ala.org.au/api/v1... 21 https://data-quality-service.ala.org.au/api/v1... 22 https://collections.ala.org.au/ws/dataProvider 23 https://collections.ala.org.au/ws/dataResource 24 https://bie-ws.ala.org.au/ws/species/{id} 25 https://biocache-ws.ala.org.au/ws/webportal/pa... called_by functional method 0 show_all-collections True GET 1 atlas_taxonomy True GET 2 show_all-fields True GET 3 atlas_species True GET 4 atlas_occurrences False GET 5 atlas_occurrences True GET 6 show_all-fields True GET 7 atlas_counts, show_values-fields True GET 8 atlas_counts True GET 9 show_all-assertions True GET 10 search_taxa True GET 11 search_taxa True GET 12 atlas_species True POST 13 search_identifiers True GET 14 show_all-reasons True GET 15 show_values-lists True GET 16 show_all-lists True GET 17 media_metadata True POST 18 show_all-licences True GET 19 doi_download True GET 20 show_values-profiles True GET 21 show_all-profiles True GET 22 show_all-providers True GET 23 show_all-datasets True GET 24 atlas_taxonomy True GET 25 atlas_occurrences True POST
- galah.search_taxa(taxa=None, identifiers=None, specific_epithet=None, scientific_name=None, verbose=False)#
Look up taxonomic names before downloading data from the ALA, using
atlas_occurrences(),atlas_species()oratlas_counts(). Taxon information returned bysearch_taxa()may be passed to thetaxaargument ofatlasfunctions.search_taxa()allows users to disambiguate homonyms (i.e. where the same name refers to taxa in different clades) prior to downloading data.- Parameters:
taxa (string) – one or more scientific names to search.
identifiers (string / list) – one or more taxonomic identifiers (such as guid or taxonConceptID) to search.
specific_epithet (list) – search taxonomic levels by using the argument “specificEpithet”.
scientific_name (dictionary) – search taxonomic levels by using the argument “scientificName”.
verbose (logical) – If
True, galah gives more information like URLs of your queries. Defaults toFalse
- Return type:
An object of class
pandas.DataFrame.
Examples
Get taxonomic identifiers for “Vulpes vulpes”
import galah galah.search_taxa(taxa="Vulpes vulpes")
scientificName scientificNameAuthorship ... vernacularName issues 0 Vulpes vulpes Linnaeus, 1758 ... Fox noIssue [1 rows x 12 columns]
Get the species name from a taxonomic identifier
import galah galah.search_taxa(identifiers="https://id.biodiversity.org.au/node/apni/2914510")
scientificName scientificNameAuthorship \ 0 Eucalyptus blakelyi Maiden taxonConceptID rank kingdom \ 0 https://id.biodiversity.org.au/node/apni/2914510 species Plantae phylum order family genus species \ 0 Charophyta Myrtales Myrtaceae Eucalyptus Eucalyptus blakelyi vernacularName issues 0 White-budded Red-gum noIssueSearch taxonomic levels by using the key word “specificEpithet”
import galah galah.search_taxa(specific_epithet=["class=aves","family=pardalotidae","genus=pardalotus","specificEpithet=punctatus"])
scientificName scientificNameAuthorship \ 0 Pardalotus (Pardalotus) punctatus (Shaw, 1792) taxonConceptID rank kingdom \ 0 https://biodiversity.org.au/afd/taxa/5254fe03-... species Animalia phylum order family genus species \ 0 Chordata Passeriformes Pardalotidae Pardalotus Pardalotus punctatus vernacularName issues 0 Spotted Pardalote noIssueSearch taxonomic levels by using the key word “scientificName”
import galah galah.search_taxa(scientific_name={"family": ["pardalotidae","maluridae"],"scientificName": ["pardolatus striatus","malurus cyaneus"]})
scientificName scientificNameAuthorship \ 0 Pardalotus (Pardalotinus) striatus (Gmelin, 1789) 0 Malurus (Malurus) cyaneus (Ellis, 1782) taxonConceptID rank kingdom \ 0 https://biodiversity.org.au/afd/taxa/e3103245-... species Animalia 0 https://biodiversity.org.au/afd/taxa/ae56080e-... species Animalia phylum order family genus species \ 0 Chordata Passeriformes Pardalotidae Pardalotus Pardalotus striatus 0 Chordata Passeriformes Maluridae Malurus Malurus cyaneus vernacularName issues 0 Striated Pardalote noIssue 0 Superb Fairy-wren noIssue
- galah.search_values(field=None, value=None, column_name=None)#
Users may wish to see the specific values within a chosen field, profile or list to narrow queries or understand more about the information of interest.
search_values()allows users for search for specific values within a specified field.- Parameters:
field (string) – A string to specify what type of parameters should be searched.
value (string) – A string specifying a search term. Not case sensitive.
verbose (logical) – This option is available for users who want to know what URLs this function is using to get the value. Default to False.
- Return type:
An object of class
pandas.DataFrame.
Examples
import galah galah.search_values(field="basisOfRecord",value="OBS")
field category 0 basisOfRecord OBSERVATION 1 basisOfRecord HUMAN_OBSERVATION 2 basisOfRecord MACHINE_OBSERVATION
- galah.show_all(assertions=False, atlases=False, apis=False, collection=False, datasets=False, fields=False, licences=False, lists=False, profiles=False, providers=False, ranks=False, reasons=False)#
The living atlases store a huge amount of information, above and beyond the occurrence records that are their main output. In galah, one way that users can investigate this information is by showing all the available options or categories for the type of information they are interested in.
show_all()is a helper function that can display multiple types of information, displaying all valid options for the information specified.- Parameters:
assertions (logical) – Show results of data quality checks run by each atlas
atlases (logical) – Show what atlases are available
apis (logical) – Show what APIs & functions are available for each atlas
collection (logical) – Show the specific collections within those institutions
datasets (logical) – Shows all the data groupings within those collections
fields (logical) – Show fields that are stored in an atlas
licences (logical) – Show what copyright licenses are applied to media
lists (logical) – Show what species lists are available
profiles (logical) – Show what data profiles are available
providers (logical) – Show which institutions have provided data
ranks (logical) – Show valid taxonomic ranks (e.g. Kingdom, Class, Order, etc.)
reasons (logical) – Show what values are acceptable as ‘download reasons’ for a specified atlas
- Return type:
An object of class
pandas.DataFramecontaining all data of interest.
Examples
import galah galah.show_all(datasets=True)
name \ 0 ALA Taxonomy List for Species Missing from Co... 1 "A" Flora EPBC 2 "H to O" flora EPBC 3 "P to Z" flora EPBC 4 10 year trend of levels of organochlorine poll... ... ... 5923 Zooplankton abundance in the Kerguelen Axis re... 5924 Zooplankton Abundance_Umbrella net_sea ice zon... 5925 Zooplankton samples from Heron net trawls alon... 5926 Zooplankton sampling in the coastal waters of ... 5927 Zoos Victoria Moth Tracker uri uid 0 https://collections.ala.org.au/ws/dataResource... dr23929 1 https://collections.ala.org.au/ws/dataResource... dr24170 2 https://collections.ala.org.au/ws/dataResource... dr24172 3 https://collections.ala.org.au/ws/dataResource... dr24173 4 https://collections.ala.org.au/ws/dataResource... dr16247 ... ... ... 5923 https://collections.ala.org.au/ws/dataResource... dr16244 5924 https://collections.ala.org.au/ws/dataResource... dr16265 5925 https://collections.ala.org.au/ws/dataResource... dr23120 5926 https://collections.ala.org.au/ws/dataResource... dr15943 5927 https://collections.ala.org.au/ws/dataResource... dr22371 [5928 rows x 3 columns]
- galah.show_values(field=None, verbose=False)#
Users may wish to see the specific values within a chosen field, profile or list to narrow queries or understand more about the information of interest.
show_values()provides users with these values.- Parameters:
field (string) – A string to specify what type of parameters should be shown.
verbose (logical) – This option is available for users who want to know what URLs this function is using to get the value. Default is False.
- Return type:
An object of class
pandas.DataFrame.
Examples
import galah galah.show_values(field="basisOfRecord")
field category 0 basisOfRecord HUMAN_OBSERVATION 1 basisOfRecord PRESERVED_SPECIMEN 2 basisOfRecord OBSERVATION 3 basisOfRecord OCCURRENCE 4 basisOfRecord MACHINE_OBSERVATION 5 basisOfRecord MATERIAL_SAMPLE 6 basisOfRecord LIVING_SPECIMEN 7 basisOfRecord MATERIAL_CITATION 8 basisOfRecord FOSSIL_SPECIMEN