Download Data#
The atlas_
functions are used to return data from the atlas chosen using galah_config()
. They are:
atlas_counts()
atlas_occurrences()
atlas_species()
atlas_media()
Record counts#
galah.atlas_counts()
provides summary counts on records in the specified atlas, without needing to download all the records.
>>> galah.galah_config(atlas="Australia")
>>> galah.atlas_counts()
totalRecords
0 133620113
In addition to filters
arguments, galah.atlas_counts()
has an optional group_by
argument, which provides counts grouped
by the requested field.
>>> galah.atlas_counts(group_by="kingdom")
kingdom count
0 Animalia 102150407
1 Archaea 4119
2 Bacteria 113089
3 Bamfordvirae 205
4 Chromista 1049592
5 Fungi 2343762
6 Orthornavirae 153
7 Plantae 26455372
8 Protista 311457
9 Shotokuvirae 39
10 Viroid 104
11 Virus 2319
Species lists#
A common use case of atlas data is to identify which species occur in a specified region, time period,
or taxonomic group. galah.atlas_species()
is similar to search_taxa, in that it returns taxonomic information and
unique identifiers in a dataframe. It differs in not being able to return information on taxonomic levels other
than the species; but also in being more flexible by supporting filtering:
>>> galah.atlas_species(taxa="Rodentia",filters="stateProvince=Northern Territory")
Species Species Name Scientific Name Authorship Taxon Rank Kingdom Phylum Class Order Family Genus Vernacular Name
0 https://biodiversity.org.au/afd/taxa/a6a91fbd-77f4-4440-ba66-7d043f27a297 Pseudomys delicatulus (Gould, 1842) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Delicate Mouse
1 https://biodiversity.org.au/afd/taxa/d3d03db1-3305-4f09-9f3f-64d8c512ee8c Mesembriomys gouldii (J.E. Gray, 1843) species Animalia Chordata Mammalia Rodentia Muridae Mesembriomys Black-footed Tree-rat
2 https://biodiversity.org.au/afd/taxa/936ee591-1e1a-4f9e-934e-4bc174c54414 Zyzomys argurus (Thomas, 1889) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Common Rock-rat
3 https://biodiversity.org.au/afd/taxa/635a8ab7-774e-4676-9e75-8dc31333cab1 Pseudomys hermannsburgensis (Waite, 1896) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Sandy Inland Mouse
4 https://biodiversity.org.au/afd/taxa/20ca6a48-09d2-4f05-ba8e-bbae4fa40175 Melomys burtoni (Ramsay, 1887) species Animalia Chordata Mammalia Rodentia Muridae Melomys Grassland Melomys
5 https://biodiversity.org.au/afd/taxa/53115180-4024-4d50-baf7-edc4556b89f7 Notomys alexis Thomas, 1922 species Animalia Chordata Mammalia Rodentia Muridae Notomys Spinifex Hopping-mouse
6 https://biodiversity.org.au/afd/taxa/952ae705-57e2-43d1-9a06-b35498202469 Mus musculus Linnaeus, 1758 species Animalia Chordata Mammalia Rodentia Muridae Mus House Mouse
7 https://biodiversity.org.au/afd/taxa/6a01d711-2ac6-4928-bab4-a1de1a58e995 Conilurus penicillatus (Gould, 1842) species Animalia Chordata Mammalia Rodentia Muridae Conilurus Brush-tailed Tree-rat
8 https://biodiversity.org.au/afd/taxa/ffcb9f84-c70f-4bc3-af9d-4f37a5a07e3f Rattus tunneyi (Thomas, 1904) species Animalia Chordata Mammalia Rodentia Muridae Rattus Pale Field-rat
9 https://biodiversity.org.au/afd/taxa/c1817333-9c62-4a05-af03-fe5fb9c9a0ce Rattus rattus (Linnaeus, 1758) species Animalia Chordata Mammalia Rodentia Muridae Rattus Black Rat
10 https://biodiversity.org.au/afd/taxa/cbaf1515-df15-49ec-be06-36058183644b Rattus villosissimus (Waite, 1898) species Animalia Chordata Mammalia Rodentia Muridae Rattus Long-haired Rat
11 https://biodiversity.org.au/afd/taxa/1c2e0a49-5530-48a2-83f3-2d853c89ab03 Pseudomys desertor Troughton, 1932 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Desert Mouse
12 https://biodiversity.org.au/afd/taxa/eb140ad3-776d-4294-bd33-6464097bfff3 Pseudomys nanus (Gould, 1858) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Western Chestnut Mouse
13 https://biodiversity.org.au/afd/taxa/da75e4fd-b02b-4f5c-9f7c-e835633b18a2 Rattus colletti (Thomas, 1904) species Animalia Chordata Mammalia Rodentia Muridae Rattus Dusky Rat
14 https://biodiversity.org.au/afd/taxa/d02be481-91a1-4b33-a7a5-0e73f995c71c Zyzomys maini Kitchener, 1989 species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Arnhem Land Rock-rat
15 https://biodiversity.org.au/afd/taxa/25ad81dd-0bd0-4fe5-94d7-1ec605bbf8b0 Zyzomys palatalis Kitchener, 1989 species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Carpentarian Rock-rat
16 https://biodiversity.org.au/afd/taxa/5e54144e-c15e-4906-a20c-ab076696c35c Leggadina lakedownensis Watts, 1976 species Animalia Chordata Mammalia Rodentia Muridae Leggadina Lakeland Downs Mouse
17 https://biodiversity.org.au/afd/taxa/298a7b7a-96c0-4b48-8746-ea9ad8590fe5 Pseudomys australis J.E. Gray, 1832 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Plains Rat
18 https://biodiversity.org.au/afd/taxa/2843e4d8-931a-41f0-875e-f6756f44088f Hydromys chrysogaster Geoffroy, 1804 species Animalia Chordata Mammalia Rodentia Muridae Hydromys Water-rat
19 https://biodiversity.org.au/afd/taxa/dd6aca04-8169-46e4-955b-06cbe831efdf Zyzomys pedunculatus (Waite, 1896) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Central Rock-rat
20 https://biodiversity.org.au/afd/taxa/e56ebe66-5dbd-4b63-b8fc-95b67ac9411a Leggadina forresti (Thomas, 1906) species Animalia Chordata Mammalia Rodentia Muridae Leggadina Forrest's Mouse
21 https://biodiversity.org.au/afd/taxa/43ef1334-3aba-483f-ba1f-c0407e3cc847 Pseudomys johnsoni Kitchener, 1985 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Central Pebble-mound Mouse
22 https://biodiversity.org.au/afd/taxa/39ea6204-ab1b-469e-b107-b64d24c4903f Pseudomys calabyi Kitchener & Humphreys, 1987 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Kakadu Pebble-mound Mouse
23 https://biodiversity.org.au/afd/taxa/ac8c37b1-2543-4bc2-b55d-b97cbbefefbf Notomys aquilo Thomas, 1921 species Animalia Chordata Mammalia Rodentia Muridae Notomys Northern Hopping-mouse
24 https://biodiversity.org.au/afd/taxa/327e0ec3-8efa-43c5-9bc9-867d3082ed88 Notomys longicaudatus (Gould, 1844) species Animalia Chordata Mammalia Rodentia Muridae Notomys Long-tailed Hopping-mouse
25 https://biodiversity.org.au/afd/taxa/61403a2b-8537-46e1-91cf-672d02be62b3 Leporillus apicalis (Gould, 1853) species Animalia Chordata Mammalia Rodentia Muridae Leporillus Lesser Stick-nest Rat
26 https://biodiversity.org.au/afd/taxa/3a840ca2-936e-4075-a622-f0d628bace31 Notomys amplus Brazenor, 1936 species Animalia Chordata Mammalia Rodentia Muridae Notomys Short-tailed Hopping-mouse
27 https://biodiversity.org.au/afd/taxa/1745e7b1-6f91-47a9-baf4-c56f0643cb05 Notomys cervinus (Gould, 1853) species Animalia Chordata Mammalia Rodentia Muridae Notomys Fawn Hopping-mouse
28 https://biodiversity.org.au/afd/taxa/958ed049-9bca-4c65-a720-9e16e1b7434c Rattus sordidus (Gould, 1858) species Animalia Chordata Mammalia Rodentia Muridae Rattus Canefield Rat
29 https://biodiversity.org.au/afd/taxa/e169b779-e4e4-411f-95e0-b21d4b4c6060 Notomys fuscus (Jones, 1925) species Animalia Chordata Mammalia Rodentia Muridae Notomys Dusky Hopping-mouse
30 https://biodiversity.org.au/afd/taxa/0553a58d-450b-455a-8844-62d5e5d14774 Xeromys myoides Thomas, 1889 species Animalia Chordata Mammalia Rodentia Muridae Xeromys False Water-rat
31 https://biodiversity.org.au/afd/taxa/15e09f34-5033-424e-a37c-d6bb55f30b26 Rattus norvegicus (Berkenhout, 1769) species Animalia Chordata Mammalia Rodentia Muridae Rattus Brown Rat
32 https://biodiversity.org.au/afd/taxa/1d179abb-b688-4242-989f-9a1a6d90f0b4 Mesembriomys macrurus (Peters, 1876) species Animalia Chordata Mammalia Rodentia Muridae Mesembriomys Golden-backed Tree-rat
33 https://biodiversity.org.au/afd/taxa/54222852-0af1-4e1f-b45b-175ed441d015 Notomys mitchellii (Ogilby, 1838) species Animalia Chordata Mammalia Rodentia Muridae Notomys Mitchell's Hopping-mouse
34 https://biodiversity.org.au/afd/taxa/d9528b07-2a62-4120-b946-edab67821b44 Melomys cervinipes (Gould, 1852) species Animalia Chordata Mammalia Rodentia Muridae Melomys Fawn-footed Melomys
35 https://biodiversity.org.au/afd/taxa/288dcc0f-822d-43e4-b31d-82edd9b11f00 Pseudomys gouldii (Waterhouse, 1839) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Shark Bay Mouse (djoongari)
36 https://biodiversity.org.au/afd/taxa/3ca6b7e9-9862-48ac-b457-0e705dda1c75 Rattus leucopus (J.E. Gray, 1867) species Animalia Chordata Mammalia Rodentia Muridae Rattus Cape York Rat
37 https://biodiversity.org.au/afd/taxa/dcf73c10-5e05-4b59-9d4e-2682ef369e5e Zyzomys woodwardi (Thomas, 1909) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Kimberley Rock-rat
38 ALA_DR24112_241 Cavia porcellus NaN species Animalia Chordata Mammalia Rodentia Caviidae Cavia Animals
39 https://biodiversity.org.au/afd/taxa/6983ebaa-1c9d-4b4d-a0fa-8c673d0248ef Pseudomys occidentalis Tate, 1951 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Western Mouse
40 https://biodiversity.org.au/afd/taxa/2910ea05-7539-434c-bcc8-ca48d038b82b Rattus lutreolus (J.E. Gray, 1841) species Animalia Chordata Mammalia Rodentia Muridae Rattus Swamp Rat
41 https://biodiversity.org.au/afd/taxa/9a9f3fa9-ca3b-4a15-b25b-d291c9f504b5 Uromys caudimaculatus (Krefft, 1867) species Animalia Chordata Mammalia Rodentia Muridae Uromys Giant White-tailed Rat
42 https://biodiversity.org.au/afd/taxa/9f22993a-86b0-4003-9df4-4565d66de008 Pseudomys gracilicaudatus (Gould, 1845) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Eastern Chestnut Mouse
Occurrence data#
To download occurrence data you will need to specify your email in galah.galah_config()
. This email must be
associated with an active account on your chosen atlas. See more information in the config section.
>>> galah_config(email = "your_email@email.com", atlas = "Australia")
After specifying your email, you can download occurrence records of, for example, Eolophus roseicapilla:
>>> galah.atlas_occurrences(taxa="Eolophus roseicapilla",filters=["stateProvince=Australian Capital Territory","year>=2010"],fields=["institutionID","basic"])
institutionID decimalLatitude decimalLongitude eventDate scientificName taxonConceptID recordID dataResourceName occurrenceStatus
0 NaN -35.232280 149.156280 2021-02-18T18:02:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 7cf7130d-1812-459b-9251-f4478075387f eBird Australia PRESENT
1 NaN -35.160920 149.107570 2022-03-19T06:57:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea bbd8621b-ad09-4b88-a7b6-7c28de76b580 eBird Australia PRESENT
2 NaN -35.227600 149.143790 2015-10-29T15:33:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 98f928b4-e375-4a44-8854-a6313337fd7f eBird Australia PRESENT
3 NaN -35.280710 149.148940 2021-01-07T15:30:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea eea0d468-18d2-498d-8f65-695b2416f0fc eBird Australia PRESENT
4 NaN -35.340917 149.028600 2012-10-02T00:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea e0959b51-5bb3-4e1c-a421-6444b91f3e96 Garden Bird Surveys PRESENT
... ... ... ... ... ... ... ... ... ...
86514 NaN -35.228062 149.071945 2013-01-07T00:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 8b762308-cc9c-453a-aaab-a73ca3accfbf BirdLife Australia, Birdata PRESENT
86515 NaN -35.154449 149.161964 2022-10-03T16:43:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea c634eee5-9cbc-4e86-926f-cb4db5434767 eBird Australia PRESENT
86516 in1033 -35.226993 149.020481 2017-06-25T14:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 32735c4a-bb78-4ffe-b7c1-7a7b7cc599ce ALA species sightings and OzAtlas PRESENT
86517 in1033 -35.276619 149.112914 2017-07-25T21:34:37Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 150d3252-111e-41ec-ab32-7f0567ac0330 ALA species sightings and OzAtlas PRESENT
86518 in1033 -35.160122 149.140961 2018-07-05T06:30:46Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 59d49f01-33d2-46e2-92cb-f4c5f9ecd4fa ALA species sightings and OzAtlas PRESENT
[86519 rows x 9 columns]
Media metadata#
In addition to text data describing individual occurrences and their attributes, ALA stores images, sounds and videos
associated with a given record. Metadata on these records can be downloaded using galah.atlas_media()
and the same set of
filters as the other data download functions.
>>> galah.atlas_media(taxa="Eolophus roseicapilla",filters=["year=2020","stateProvince=Australian Capital Territory"])
decimalLatitude decimalLongitude eventDate scientificName recordID dataResourceName occurrenceStatus multimedia images videos sounds creator license mimetype width height imageUrl
0 -35.166122 149.166048 2020-11-07T01:29:00Z Eolophus roseicapilla c91faaef-1df3-41e6-a12e-c0dcd13e47b0 iNaturalist Australia PRESENT Image 9889254d-2a57-41dc-bc85-def7b8d3f0e0 NaN NaN David Cunningham http://creativecommons.org/licenses/by-nd/4.0/ image/jpeg 1947 1947 https://images.ala.org.au/store/0/e/0/f/9889254d-2a57-41dc-bc85-def7b8d3f0e0/original
1 -35.278123 149.177378 2020-10-10T00:55:00Z Eolophus roseicapilla 5006c14b-00e7-4967-9091-2b413b1d7d63 iNaturalist Australia PRESENT Image d668e506-0f3b-4d70-98d9-e35034c260b4 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/4/b/0/6/d668e506-0f3b-4d70-98d9-e35034c260b4/original
2 -35.327922 149.102528 2020-08-30T07:08:00Z Eolophus roseicapilla 89b44608-edbc-450e-aea5-c68b2b84a804 NatureMapr PRESENT Image 4fcf0397-8dc2-4647-b53c-48582c458852 NaN NaN None None image/jpeg 800 1199 https://images.ala.org.au/store/2/5/8/8/4fcf0397-8dc2-4647-b53c-48582c458852/original
3 -35.276720 149.178877 2020-10-12T21:21:00Z Eolophus roseicapilla 3e1dd883-f0c3-4d58-bc7a-7af5a7b97887 NatureMapr PRESENT Image 266513f2-6d22-488b-847f-45fceb838393 NaN NaN None None image/jpeg 800 600 https://images.ala.org.au/store/3/9/3/8/266513f2-6d22-488b-847f-45fceb838393/original
4 -35.328299 149.101087 2020-04-02T06:06:00Z Eolophus roseicapilla 14e3c386-a204-4221-88fe-2a71c3335fd8 NatureMapr PRESENT Image 5f4b7510-6c44-4e97-ad37-38177d85c75e NaN NaN None None image/jpeg 800 600 https://images.ala.org.au/store/e/5/7/c/5f4b7510-6c44-4e97-ad37-38177d85c75e/original
.. ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
327 -35.408187 149.131098 2020-01-17T07:09:00Z Eolophus roseicapilla 2a78518b-7c0f-485b-be6b-61cc877cfd41 iNaturalist Australia PRESENT Image 016246bf-9e7e-4318-8753-6ddda30f1d40 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/0/4/d/1/016246bf-9e7e-4318-8753-6ddda30f1d40/original
328 -35.408187 149.131098 2020-01-17T07:09:00Z Eolophus roseicapilla 2a78518b-7c0f-485b-be6b-61cc877cfd41 iNaturalist Australia PRESENT Image 3e1598ee-a859-4c63-ac32-9437eabe8a4c NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/c/4/a/8/3e1598ee-a859-4c63-ac32-9437eabe8a4c/original
329 -35.408187 149.131098 2020-01-17T07:09:00Z Eolophus roseicapilla 2a78518b-7c0f-485b-be6b-61cc877cfd41 iNaturalist Australia PRESENT Image 78b0b7f0-b2a4-4646-b59b-4a6d1a91a6f4 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/4/f/6/a/78b0b7f0-b2a4-4646-b59b-4a6d1a91a6f4/original
330 -35.408187 149.131098 2020-01-17T07:09:00Z Eolophus roseicapilla 2a78518b-7c0f-485b-be6b-61cc877cfd41 iNaturalist Australia PRESENT Image 79e5ad3d-dfad-44f7-83ba-b576a91742b7 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/7/b/2/4/79e5ad3d-dfad-44f7-83ba-b576a91742b7/original
331 -35.408187 149.131098 2020-01-17T07:09:00Z Eolophus roseicapilla 2a78518b-7c0f-485b-be6b-61cc877cfd41 iNaturalist Australia PRESENT Image f7fbae15-aa1a-4010-9f11-88232588e59b NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/b/9/5/e/f7fbae15-aa1a-4010-9f11-88232588e59b/original
[332 rows x 17 columns]
To actually download the media files to your computer, add the argument collect
. By default, it downloads the data to your
current working directory, but you can specify the folder to download to with the path
argument.
Configuring galah#
Various aspects of the galah package can be customized.
To download occurrence records, you will need to provide an email address registered with the ALA. You can create an account here. Once an email is registered with the ALA, it should be stored in the config:
>>> galah.galah_config(email = "myemail@gmail.com")
Setting a download reason
ALA requires that you provide a reason when downloading occurrence data (via the galah.atlas_occurrences()
function).
The reason is set to 4 (scientific research) by default, but you can change this using galah_config()
. See galah.show_all(reasons=True)
for valid download reasons.
>>> galah.galah_config(reason = 5)
Debugging#
If things aren’t working as expected, more detail (particularly about web requests)
can be obtained by setting the verbose
option in many functions.