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.