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 181071285
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 144482409
1 Archaea 15109
2 Bacteria 458470
3 Chromista 1070297
4 Fungi 1986529
5 Plantae 31467065
6 Protista 482338
7 Viruses 13782
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/07c52a7f-f529-4137-b41f-3052aeca60b5 Zyzomys argurus (Thomas, 1889) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Common Rock-rat
1 https://biodiversity.org.au/afd/taxa/c1063f9b-5a3b-4dc4-a430-6568b5088579 Notomys alexis Thomas, 1922 species Animalia Chordata Mammalia Rodentia Muridae Notomys Spinifex Hopping-mouse
2 https://biodiversity.org.au/afd/taxa/4797cf4c-db5c-48d6-9524-3330cb78cfda Mesembriomys gouldii (J.E. Gray, 1843) species Animalia Chordata Mammalia Rodentia Muridae Mesembriomys Black-footed Tree-rat
3 https://biodiversity.org.au/afd/taxa/b6045bad-6c5e-46ba-8644-15c0bd6320bb Pseudomys delicatulus (Gould, 1842) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Delicate Mouse
4 https://biodiversity.org.au/afd/taxa/c7a6c8d8-ab20-456e-bc9c-538720409b70 Pseudomys hermannsburgensis (Waite, 1896) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Sandy Inland Mouse
5 https://biodiversity.org.au/afd/taxa/5b6226c0-b579-4d59-8d66-f23bd328b9dd Melomys burtoni (Ramsay, 1887) species Animalia Chordata Mammalia Rodentia Muridae Melomys Grassland Melomys
6 https://biodiversity.org.au/afd/taxa/90c13414-5069-4125-8b56-0b5c59a752e3 Zyzomys pedunculatus (Waite, 1896) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Central Rock-rat
7 https://biodiversity.org.au/afd/taxa/0a444981-cf13-484c-81b5-9313d5851c4e Mus musculus Linnaeus, 1758 species Animalia Chordata Mammalia Rodentia Muridae Mus House Mouse
8 https://biodiversity.org.au/afd/taxa/9bb1445f-39e4-417e-b384-60a277447a4a Conilurus penicillatus (Gould, 1842) species Animalia Chordata Mammalia Rodentia Muridae Conilurus Brush-tailed Tree-rat
9 https://biodiversity.org.au/afd/taxa/575ddf45-3127-4e8f-bb75-efdd6468a571 Rattus rattus (Linnaeus, 1758) species Animalia Chordata Mammalia Rodentia Muridae Rattus Black Rat
10 https://biodiversity.org.au/afd/taxa/958c426a-21be-4389-84c5-9c227a0ce8a6 Rattus tunneyi (Thomas, 1904) species Animalia Chordata Mammalia Rodentia Muridae Rattus Pale Field-rat
11 https://biodiversity.org.au/afd/taxa/e7703da0-c258-413b-8578-e2dfade1591f Pseudomys desertor Troughton, 1932 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Desert Mouse
12 https://biodiversity.org.au/afd/taxa/93b9afae-579d-4181-9fae-501230f0b0d8 Pseudomys nanus (Gould, 1858) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Western Chestnut Mouse
13 https://biodiversity.org.au/afd/taxa/5733f8c9-38f9-4a17-a2ee-f793fa70ed98 Rattus villosissimus (Waite, 1898) species Animalia Chordata Mammalia Rodentia Muridae Rattus Long-haired Rat
14 https://biodiversity.org.au/afd/taxa/4e9a6d73-a015-4aea-948c-8fc3eae46c1c Rattus colletti (Thomas, 1904) species Animalia Chordata Mammalia Rodentia Muridae Rattus Dusky Rat
15 https://biodiversity.org.au/afd/taxa/dab6e02d-b4a5-4009-81ea-14b9f139b910 Zyzomys maini Kitchener, 1989 species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Arnhem Land Rock-rat
16 https://biodiversity.org.au/afd/taxa/7f791f55-1d6f-4448-91a0-996daa72081c Hydromys chrysogaster Geoffroy, 1804 species Animalia Chordata Mammalia Rodentia Muridae Hydromys Water-rat
17 https://biodiversity.org.au/afd/taxa/cc2d4c74-8072-487e-a47f-9747806dc34a Leggadina lakedownensis Watts, 1976 species Animalia Chordata Mammalia Rodentia Muridae Leggadina Lakeland Downs Mouse
18 https://biodiversity.org.au/afd/taxa/2595dcfd-30f7-48f6-a50e-af3551bd9cc8 Zyzomys palatalis Kitchener, 1989 species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Carpentarian Rock-rat
19 https://biodiversity.org.au/afd/taxa/e985914e-3435-4f6b-9978-2cbb19d29fee Pseudomys australis J.E. Gray, 1832 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Plains Rat
20 https://biodiversity.org.au/afd/taxa/4b5e599e-70af-40a6-b4bb-13cfdb98c23f Leggadina forresti (Thomas, 1906) species Animalia Chordata Mammalia Rodentia Muridae Leggadina Forrest's Mouse
21 https://biodiversity.org.au/afd/taxa/b5981535-b6c0-41e3-b573-9e383b91a9a4 Notomys aquilo Thomas, 1921 species Animalia Chordata Mammalia Rodentia Muridae Notomys Northern Hopping-mouse
22 https://biodiversity.org.au/afd/taxa/f44806fd-7802-45d7-bb10-774ecc577c7d Pseudomys johnsoni Kitchener, 1985 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Central Pebble-mound Mouse
23 https://biodiversity.org.au/afd/taxa/e59c9613-14d2-4d2f-8b19-3b165a6ed11e Pseudomys calabyi Kitchener & Humphreys, 1987 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Kakadu Pebble-mound Mouse
24 https://biodiversity.org.au/afd/taxa/356745c1-ce6d-42f1-935c-9098261cd81f Pseudomys mimulus Thomas, 1926 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys NaN
25 https://biodiversity.org.au/afd/taxa/ff0f2d1f-3abf-4288-8365-ee6c6be17b38 Rattus sordidus (Gould, 1858) species Animalia Chordata Mammalia Rodentia Muridae Rattus Canefield Rat
26 https://biodiversity.org.au/afd/taxa/66b0dc84-12dd-4aca-a7b8-82d1ae89bc18 Notomys longicaudatus (Gould, 1844) species Animalia Chordata Mammalia Rodentia Muridae Notomys Long-tailed Hopping-mouse
27 https://biodiversity.org.au/afd/taxa/9daf14f2-931d-44a6-8537-5127c56ab950 Leporillus apicalis (Gould, 1853) species Animalia Chordata Mammalia Rodentia Muridae Leporillus Lesser Stick-nest Rat
28 https://biodiversity.org.au/afd/taxa/2da4cbaa-005f-4346-8e11-6a1e5ddd0444 Notomys amplus Brazenor, 1936 species Animalia Chordata Mammalia Rodentia Muridae Notomys Short-tailed Hopping-mouse
29 https://biodiversity.org.au/afd/taxa/77c6c9f3-40d3-48da-96f5-d80e402ad18d Notomys cervinus (Gould, 1853) species Animalia Chordata Mammalia Rodentia Muridae Notomys Fawn Hopping-mouse
30 https://biodiversity.org.au/afd/taxa/c4bfec0f-0137-49a1-84bb-c088e99844b8 Notomys mitchellii (Ogilby, 1838) species Animalia Chordata Mammalia Rodentia Muridae Notomys Mitchell's Hopping-mouse
31 https://biodiversity.org.au/afd/taxa/b042c17d-27fd-4154-8bdf-519aeb952836 Xeromys myoides Thomas, 1889 species Animalia Chordata Mammalia Rodentia Muridae Xeromys False Water-rat
32 https://biodiversity.org.au/afd/taxa/c0e8f4ca-3c7e-4b71-9d8f-992e3e3b07b9 Notomys fuscus (Jones, 1925) species Animalia Chordata Mammalia Rodentia Muridae Notomys Dusky Hopping-mouse
33 https://biodiversity.org.au/afd/taxa/f6168080-2649-4d2e-ad43-5b852bc5913d Pseudomys gracilicaudatus (Gould, 1845) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Eastern Chestnut Mouse
34 https://biodiversity.org.au/afd/taxa/3694beb2-9b22-4e79-9373-5d0d887be69b Mesembriomys macrurus (Peters, 1876) species Animalia Chordata Mammalia Rodentia Muridae Mesembriomys Golden-backed Tree-rat
35 https://biodiversity.org.au/afd/taxa/e5b3ef22-25f4-48f6-95f2-2bd384b8efe7 Rattus norvegicus (Berkenhout, 1769) species Animalia Chordata Mammalia Rodentia Muridae Rattus Brown Rat
36 https://biodiversity.org.au/afd/taxa/59b21252-19fe-4fc3-85d4-ddb6a7e49e78 Melomys cervinipes (Gould, 1852) species Animalia Chordata Mammalia Rodentia Muridae Melomys Fawn-footed Melomys
37 https://biodiversity.org.au/afd/taxa/2eef1990-96e3-498a-887a-f1dfa334b218 Rattus leucopus (J.E. Gray, 1867) species Animalia Chordata Mammalia Rodentia Muridae Rattus Cape York Rat
38 https://biodiversity.org.au/afd/taxa/b9b253e9-a56c-4a72-8ce3-15de06ef8417 Pseudomys gouldii (Waterhouse, 1839) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Shark Bay Mouse (djoongari)
39 https://biodiversity.org.au/afd/taxa/cce5d053-414a-40e0-87bd-ab8012287068 Leporillus conditor (Sturt, 1848) species Animalia Chordata Mammalia Rodentia Muridae Leporillus Greater Stick-nest Rat
40 https://biodiversity.org.au/afd/taxa/91a0d84f-4ce9-4009-9dc7-ee7057f1f57c Pseudomys pilbarensis Roycroft, Breed & Ford, 2024 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Western Delicate Mouse
41 ALA_DR30477_78 Cavia porcellus NaN species Animalia Chordata Mammalia Rodentia Caviidae Cavia Guinea Pig
42 https://biodiversity.org.au/afd/taxa/35a0671a-e449-4581-aeac-510ea2f251ea Zyzomys woodwardi (Thomas, 1909) species Animalia Chordata Mammalia Rodentia Muridae Zyzomys Kimberley Rock-rat
43 https://biodiversity.org.au/afd/taxa/3b31abbc-6b8a-4fbf-aed6-f614dbb51cb8 Rattus lutreolus (J.E. Gray, 1841) species Animalia Chordata Mammalia Rodentia Muridae Rattus Swamp Rat
44 https://biodiversity.org.au/afd/taxa/83049628-f180-4a3f-9f48-af5cee08d818 Pseudomys occidentalis Tate, 1951 species Animalia Chordata Mammalia Rodentia Muridae Pseudomys Western Mouse
45 https://biodiversity.org.au/afd/taxa/0058f9b2-a9c1-49a2-811b-9b2efcc8e279 Pseudomys novaehollandiae (Waterhouse, 1843) species Animalia Chordata Mammalia Rodentia Muridae Pseudomys New Holland Mouse
46 https://biodiversity.org.au/afd/taxa/07e98c03-3739-4779-bfbd-ae4d930dad7a Uromys caudimaculatus (Krefft, 1867) species Animalia Chordata Mammalia Rodentia Muridae Uromys White-tailed Uromys
47 https://biodiversity.org.au/afd/taxa/6a5c25e0-3b06-4ae2-8069-b4c1350c4365 Mastacomys fuscus Thomas, 1882 species Animalia Chordata Mammalia Rodentia Muridae Mastacomys Broad-toothed Rat
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.196110 149.005830 2013-01-10T00:00:00Z Eolophus roseicapilla albiceps https://biodiversity.org.au/afd/taxa/a38ac5ac-3049-4fde-8391-faf8bf7aeb7f 64b0bfdf-a85d-49e0-a81e-5cdc38f3579b BirdLife Australia, Birdata PRESENT
1 NaN -35.317036 149.079250 2020-05-23T16:04:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 759717d4-8178-4e3d-94fd-518767168b60 eBird Australia PRESENT
2 NaN -35.299753 149.115322 2022-11-21T14:24:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea f2ee12b8-957a-4aa2-ae8e-66a47694ee28 eBird Australia PRESENT
3 NaN -35.605580 148.953340 2015-12-06T11:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea d644275f-9ac7-4863-b625-d37d391528d0 eBird Australia ABSENT
4 NaN -35.242780 149.020830 2011-11-01T00:00:00Z Eolophus roseicapilla albiceps https://biodiversity.org.au/afd/taxa/a38ac5ac-3049-4fde-8391-faf8bf7aeb7f 18952e22-a082-49b2-8c5f-58a9e70e8476 BirdLife Australia, Birdata PRESENT
... ... ... ... ... ... ... ... ... ...
113480 in1033 -35.341263 149.091202 2013-06-23T02:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 1039e81d-c4a1-448e-abc9-59388f40dbe7 ALA species sightings and OzAtlas PRESENT
113481 in1033 -35.751461 148.964401 2015-01-06T02:55:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 326e6431-6ea5-45a8-82dd-53ad9ad85a9b ALA species sightings and OzAtlas PRESENT
113482 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
113483 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
113484 in550 -35.322672 149.092483 2021-02-16T00:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 738123d4-dd65-4fe8-b449-796598a2233a Entangled Wildlife Australia PRESENT
[113485 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 taxonConceptID recordID dataResourceName occurrenceStatus multimedia images videos sounds creator license mimeType width height imageUrl
0 -35.327922 149.102528 2020-08-30T07:08:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 89b44608-edbc-450e-aea5-c68b2b84a804 NatureMapr PRESENT Image 9e68c004-118c-4b37-b945-e19b81662051 NaN NaN image/jpeg 1920 2877 https://images.ala.org.au/store/1/5/0/2/9e68c004-118c-4b37-b945-e19b81662051/original
1 -35.317800 149.146261 2020-01-06T12:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea b03e670c-29d4-44e4-b0b4-d698b7a00581 Earth Guardians Weekly Feed PRESENT Image 3e220765-bdec-4804-8015-4763e3b36bb3 NaN NaN image/jpeg 1001 750 https://images.ala.org.au/store/3/b/b/6/3e220765-bdec-4804-8015-4763e3b36bb3/original
2 -35.317737 149.161550 2020-05-01T13:40:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea ca1f9727-9d8e-4e79-b92c-d10e285b2c15 iNaturalist Australia PRESENT Image 7b95197f-2520-4167-980a-7b8dfc395952 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/2/5/9/5/7b95197f-2520-4167-980a-7b8dfc395952/original
3 -35.316870 149.160586 2020-07-20T14:28:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 4426ea86-f5f3-4c92-97fb-9f6afc25e1c5 iNaturalist Australia PRESENT Image f84a964a-0eb8-4eb5-9c67-e5bcd50e0d64 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/4/6/d/0/f84a964a-0eb8-4eb5-9c67-e5bcd50e0d64/original
4 -35.316857 149.162818 2020-10-23T10:51:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea e0c904f7-ad62-46da-973e-f948bd36d8f5 iNaturalist Australia PRESENT Image cb82294a-cd01-4ca5-b841-5d6f6f853d2f NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/f/2/d/3/cb82294a-cd01-4ca5-b841-5d6f6f853d2f/original
.. ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
128 -35.407152 149.128183 2020-03-31T14:07:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea e6d0fb25-2aa8-48ff-8d97-e096b4e191ac iNaturalist Australia PRESENT Image 45104753-89bc-4e62-a430-1145efa13788 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/8/8/7/3/45104753-89bc-4e62-a430-1145efa13788/original
129 -35.407145 149.128423 2020-05-08T16:56:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 373cb486-bc70-4ac0-9818-e4966b88518e iNaturalist Australia PRESENT Image 3adab649-e9fa-4dac-b40e-cde5d44e34c6 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/6/c/4/3/3adab649-e9fa-4dac-b40e-cde5d44e34c6/original
130 -35.529228 149.078437 2020-04-28T14:26:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 383dc9f1-ef24-43f9-a4eb-6e93f3d1f9b4 iNaturalist Australia PRESENT Image 583ef5f9-956e-43a3-8d36-e69291ae3aea NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/a/e/a/3/583ef5f9-956e-43a3-8d36-e69291ae3aea/original
131 -35.390885 149.065395 2020-05-19T00:00:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 167578a6-9fd8-4642-8b4b-ce0419d4be2d iNaturalist Australia PRESENT Image f5ade747-668a-4fc0-a23b-6bb8f30ea02a NaN NaN Namadgi Y7 Ms Boadle http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1536 2048 https://images.ala.org.au/store/a/2/0/a/f5ade747-668a-4fc0-a23b-6bb8f30ea02a/original
132 -35.532558 149.062855 2020-08-26T11:53:00Z Eolophus roseicapilla https://biodiversity.org.au/afd/taxa/9b4ad548-8bb3-486a-ab0a-905506c463ea 28684160-f9eb-42b2-8491-b99d36528d77 iNaturalist Australia PRESENT Image 1295c202-f7d2-4030-ad4b-339e6eb110a7 NaN NaN deborod http://creativecommons.org/licenses/by-nc/4.0/ image/jpeg 1800 1200 https://images.ala.org.au/store/7/a/0/1/1295c202-f7d2-4030-ad4b-339e6eb110a7/original
[133 rows x 18 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.