delma User Guide#
Using delma to turn markdown into EML will require only two steps, with two optional
steps for troubleshooting.
Create your initial markdown file#
First, you will need to have a markdown metadata file. delma comes with a default, recommended
one for the Atlas of Living Australia. To generate this, simply type
>>> import delma
>>> delma.create_md()
What this will do is create a file, titled metadata.md, in your current directory. If you want
to change either the name of the metadata file, or where it is placed, you can edit the following
two variables:
metadata_md: this will change the name of the markdown file.working_dir: this will change where the markdown file is written.
Note
If you have a template xml that you would like to use instead, delma will accept that too.
Just provide a link/file to the create_md() function, like so:
>>> delma.create_md(xml_url="https://collections.ala.org.au/ws/eml/dr368")
Editing your markdown file#
Now comes the more involved part: editing your markdown. We have a boilerplate metadata markdown statement, which is the minimum amount of metadata the ALA requires. When editing, remember two things:
Don’t add anything to the words with hashes (#) in front of them. These are headings, and will therefore be formatted in the XML file
Leave a space between your added text and the next word with a hash in front of it.
Note
Checking your markdown file
delma has a function where you can check if your markdown is formatted correctly, and all
metadata values are consistent. To do this, run
>>> delma.display_as_dataframe(metadata_md = 'metadata.md')
There is already a metadata file.
level label text
0 1 DATASET
1 2 TITLE Your Title
2 2 CREATOR
3 3 INDIVIDUALNAME
4 4 GIVENNAME Firstname
5 4 SURNAME Lastname
6 3 ADDRESS
7 4 DELIVERYPOINT 215 Road Street
8 4 CITY Canberra
9 4 ADMINISTRATIVEAREA ACT
10 4 POSTALCODE 2601
11 4 COUNTRY Australia
12 3 ELECTRONICMAILADDRESS firstname.lastname@email.com
13 3 USERID
14 4 DIRECTORY This is optional; however, if you would like to include ORCIDs, this is great
15 2 PUBDATE 2025-06-12
16 2 LANGUAGE EN
17 2 ABSTRACT A brief overview of the resource. This should provide enough information to help potential users of the data to understand if it may be of interest. Example content may include what the study was designed to investigate, what taxa were observed, and over what time period.
18 2 KEYWORDSET
19 3 KEYWORD Occurrence
20 3 KEYWORDTHESAURUS https://ipt.gbif.org/manual/en/ipt/latest/dwca-guide#dwc-a-components
21 2 LICENSED
22 3 LICENSENAME Creative Commons Attribution 4.0 International
23 3 URL https://creativecommons.org/licenses/by/4.0/
24 3 IDENTIFIER CC-BY 4.0 (Int) 4.0
25 2 INTRODUCTION This section can include any methods you like, but should, at minimum, give a simple description of how the data were collected. To link to a publication with more complete information, add a level-2 heading called `Reference Publication` and add the citation to your paper.
26 2 CONTACT
27 3 INDIVIDUALNAME
28 4 GIVENNAME Firstname
29 4 SURNAME Lastname
30 3 ADDRESS
31 4 DELIVERYPOINT 215 Road Street
32 4 CITY Canberra
33 4 ADMINISTRATIVEAREA ACT
34 4 POSTALCODE 2601
35 4 COUNTRY Australia
36 3 ELECTRONICMAILADDRESS firstname.lastname@email.com
Writing your metadata file#
After you have successfully edited your markdown file, it is time to write your metadata xml file. To do so, run
>>> import delma
>>> delma.write_eml(metadata_md="metadata.md", working_dir="./", eml_xml="eml.xml")
These are all the possible arguments for write_eml(). What is shown is the default values
for these arguments, so if you decide to go with all the defaults, you do not have to include these
arguments.
Validating your xml file#
If you are concerned about the formatting of your eml.xml file, we have an in-built function
that will validate its formatting again a GBIF template. To run this check, type
>>> delma.check_eml_xml(eml_xml="eml.xml", working_dir="./")
If it is a valid eml.xml, you will not get an error message. Various error messages will
appear if something is not formatted correctly.