Ctrl+K

Tutorial#

Note: You will need to register your email address at the atlas you want to download data for, otherwise you will get no data!

Now that you have successfully installed galah-python, we’ll provide a quick introduction on the functions you will mainly be using to get data. If you’re looking for a quick reference guide for commands, the User Guide collates all the available commands with examples. This tutorial serves as an initial method to get you used to using different commands.

Configuring galah#

First, you will need to set some stored parameters to get full use out of the galah package. There are two key parameters that you will need to set, especially to get occurrences: atlas and email.

Choosing an Atlas

First, you will need to choose an atlas to get information from. If you’re not sure what atlases galah-python has on offer, run the command

>> import galah
>> galah.show_all(atlases=True)

and a list like this will appear:

To choose an atlas, select the region that the atlas represents. By default, the atlas is set to Australia, which is what we will sue for this example. However, for those interested in the other atlases on offer, say the Brazilian atlas, type

>>> galah.galah_config(atlas="Brazil")

Storing Your Email

To download data from the atlases, you will need a registered email address. For the ALA, go to https://auth.ala.org.au/userdetails/registration/createAccount. Once you have registered your email, you can store it in galah like so:

>>> import galah
>>> galah.galah_config(email="youremail@example.com")

This will not return anything. No error messages means it is configured correctly. To see what your configuation settings are, type

>>> galah.galah_config()

Building queries#

Now that galah is configured, we will get counts of records, so you know how many you are downloading. To see how many records are currently in the ALA, type

>>> galah.atlas_counts()

If you are not interested in a specific species, but in the number of records in the atlas from the year 2020 onwards, you can add this to the filters argument of atlas_counts().

>>> galah.atlas_counts(filters="year>=2020")

If you are wondering how the number of records for all species in the ALA changed over each year from 2020 onwards, you can tell galah to group your results by year, to get yearly counts.

>>> galah.atlas_counts(filters="year>=2020",group_by="year",expand=False)

To narrow down your search by a specific species, you can use the search_taxa() function to check whether or not the taxonomic information for the species you are wanting to search. For this example, lLet’s choose the taxa Vulpes vulpes, or the red fox.

>>> galah.search_taxa(taxa="Vulpes vulpes")

Now that we can see we indeed have the red fox, we can see how many records the ALA has of the red fox.

>>> import galah
>>> galah.atlas_counts(taxa="Vulpes vulpes")

Now, we can put our filters query together with our red fox query, to see how many occurrences of red foxes in the ALA were seen each year from 2020 onwards.

>>> import galah
>>> galah.atlas_counts(taxa="Vulpes vulpes",filters="year>=2020",group_by="year",expand=False)

Downloading records#

Now that we know the number of red fox occurrences in each year starting with 2020, we will now download these records. To do this, we will take the query from above and change the function name from atlas_counts() to atlas_occurrences().

>>> import galah
>>> galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year>=2020")

If you are only interested in the scientific name, as well as latitude and longitude, use the fields option as follows:

import galah
galah.atlas_occurrences(taxa="Vulpes vulpes",filters="year>=2020",fields=["scientificName","decimalLatitude","decimalLongitude"])

      scientificName  decimalLatitude  decimalLongitude
0      Vulpes vulpes       -37.962520        141.552330
1      Vulpes vulpes       -35.061657        138.650843
2      Vulpes vulpes       -30.634992        149.231293
3      Vulpes vulpes       -36.900000        142.461700
4      Vulpes vulpes       -28.626971        153.424660
...              ...              ...               ...
36598  Vulpes vulpes       -30.545839        149.124897
36599  Vulpes vulpes       -33.430853        151.381126
36600  Vulpes vulpes       -37.855405        145.329463
36601  Vulpes vulpes       -33.834816        151.192393
36602  Vulpes vulpes       -35.205865        138.471293

[36603 rows x 3 columns]

Check out other vignettes and the API docs for more information on how to use each of these functions, as well as to learn more about searching for information on how to filter your data.

On this page