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 BASIS_OF_RECORD_INVALID CONTINENT_COORDINATE_MISMATCH COORDINATE_ROUNDED COORDINATE_UNCERTAINTY_METERS_INVALID COUNTRY_DERIVED_FROM_COORDINATES FIRST_OF_MONTH FIRST_OF_YEAR GEODETIC_DATUM_ASSUMED_WGS84 ID_PRE_OCCURRENCE INDIVIDUAL_COUNT_INVALID MISSING_GEODETICDATUM MISSING_GEOREFERENCEDBY MISSING_GEOREFERENCEPROTOCOL MISSING_GEOREFERENCESOURCES MISSING_GEOREFERENCEVERIFICATIONSTATUS MISSING_GEOREFERENCE_DATE MISSING_TAXONRANK MODIFIED_DATE_INVALID OCCURRENCE_STATUS_INFERRED_FROM_INDIVIDUAL_COUNT RECORDED_DATE_INVALID STATE_COORDINATE_MISMATCH TAXON_MATCH_HIGHERRANK
0 Vulpes vulpes -37.676100 146.216000 False False False False False False False False False False False False True False True False False False False True False False
1 Vulpes vulpes -33.340083 151.415916 True False True True True False False True False False True True True True True True True False False False False False
2 Vulpes vulpes -35.887480 147.883100 False False True False False False False False False False False True False True True True False False False False False False
3 Vulpes vulpes -34.982570 150.588993 False False True False False False False False False False False True True True True True False False False False False False
4 Vulpes vulpes -34.262574 150.228290 False False True False False False False False False False False True False True True True False False False False False False
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
39547 Vulpes vulpes -31.922498 116.082276 True False True True True False False True False False True True True True True True True False False False False False
39548 Vulpes vulpes -33.833912 151.234419 True False False True True True False True False False True True True True True True True False False False False False
39549 Vulpes vulpes -33.866105 151.138201 True False False True True False False True False False True True True True True True True False False False False False
39550 Vulpes vulpes -37.811627 145.147883 True False True True True False False True False False True True True True True True True False False False False False
39551 Vulpes vulpes -37.777272 145.287015 True False False True True False False True False False True True True True True True True False False False False False
[39552 rows x 25 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.