Difference between revisions of "Dataset Tutorial"
(→Basic annotation level) |
(→Adding and extending concepts (e.g., how do I refer to the instrument used in my lab?)) |
||
| Line 97: | Line 97: | ||
=== Adding and extending concepts (e.g., how do I refer to the instrument used in my lab?) === | === Adding and extending concepts (e.g., how do I refer to the instrument used in my lab?) === | ||
| − | Sometimes one may want to extend some of the concepts that already exist in the wiki. For example, imagine that I have measured a variable of a table (d18Og.rub-w) with the stable isotope ratio mass spectrometer instrument of my lab. If I state that the variable d18Og.rub-w was measured by a mass spectrometer instrument | + | Sometimes one may want to extend some of the concepts that already exist in the wiki. For example, imagine that I have measured a variable of a table (d18Og.rub-w) with the stable isotope ratio mass spectrometer instrument of my lab. If I state that the variable d18Og.rub-w was measured by a "stable isotope mass spectrometer instrument" (under the "instrument" category) I would be losing information: are all stable isotope mass spectrometer instruments the same? |
| − | + | We need to state which stable isotope mass spectrometer was used. In this case, the one at my lab. | |
| − | + | ||
| − | + | Hence, we need to create the concept "StableIsotopeRatioMassSpectrometerOfMyLab", a special type of "Instrument" that allows creating new annotations on the data. Following the example shown in the previous section, we would need to create the StableIsotopeRatioMassSpectrometerOfMyLab page and annotate it with the category "StableIsotopeRatioMassSpectrometer". This category would become a new category in the wiki. | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | Hence, we need to create the concept " | + | |
'''Exercise: create a new instrument that doesn't exist in the ontology, and use it to annotate a variable of a dataset.''' | '''Exercise: create a new instrument that doesn't exist in the ontology, and use it to annotate a variable of a dataset.''' | ||
Revision as of 23:08, 21 June 2016
This page describes a tutorial for using the Linked Earth wiki. The tutorial is structured in an incremental way, getting more complex as you progress. There are four main levels of difficulty, which allow you to perform different tasks in the Linked Earth wiki:
- Trivial level: how request an account and log in the wiki.
- Basic annotation level: how to upload LiPD datasets and update basic metadata fields.
- Advanced annotation level: how to create and reuse properties for annotation, including cases like dataset location annotation.
- Advanced wiki functionality: create and edit wiki pages, special pages and uploading materials (pdfs, images).
Finally, we list a set of best practices for creating wiki materials.
Contents
Trivial level
Getting a Linked Earth wiki account
To get an account in the Linked Earth wiki, fill in the membership form.
Logging in the Wiki
To log in, just click on the link at top right of the wiki and insert your user/password. Figure 1 indicates where the log in option is located with more detail.
Basic annotation level
Uploading a LiPD file
After logging in, use this link to update a LiPD file: http://wiki.linked.earth/Special:WTLiPD, a special page for managing datasets already in the LiPD format. Select the browse button and choose the .lpd file you want to upload as shown in Figure 2:
The page will be created and your dataset will appear on the "Current LiPD Dataset list". By clicking on the dataset link, you will be able to see the automatically extracted metadata from the LiPD file, as shown in Figure 3.
Congratulations! Your LiPD file has been successfully added to the Linked Earth wiki.
Exercise: upload your own LiPD file through the "manage dataset" page in the wiki.
Annotation of a LiPD file
Once a LiPD file is uploaded, the metadata about that file is shown in a table with two columns. The column on the left of each table contains the properties describing the LiPD file, while the column on the right states the value associated with each property. Figure 3 shows an example, where the "archive type" of CAN9Neukom2014 is "Tree".
Now that the metadata about the file is published, we have to review whether it is correct or not, and edit it if appropriate. For example, the first thing we notice for the CAN9Neukom2014 dataset in Figure 3 is that there are no investigators associated with the dataset. In order to edit a property value (whether existing or not defined) we have to click on its corresponding row as indicated in Figure 4. For instance, in Figure 4 we can add "Daniel" as an investigator.
Each annotated values can be edited or removed. If we want to remove "Daniel" from the investigators of the dataset, click on the row and on the red cross button of the left as shown in Figure 5:
Each property added to the page is tracked on the page history. The page history is accessible through the "View history" button at the top of any wiki page (see Figure 1 for more details). This way, everyone can check the edits done by other collaborators. Figure 6 illustrates the edits done to the CAN9Neukom 2014 dataset: the latest change added a propertyValue adding "Daniel" as an investigator.
If there is a disagreement between two researchers, a discussion may be started on the "Discussion" page, as depicted on Figure 7.
Each contribution deserves credit. The wiki pages of the Linked Earth wiki track the authors who have contributed automatically. Figure 8 shows the "Credit" table, at the bottom of the wiki page.
Dataset versioning
An important detail to pay attention to is the version of the dataset. In LiPD all the uploaded datasets should follow a x.y.z notation, where "x" refers to important changes in the dataset's metadata (e.g., the creation of a new age model using a different code), "y" refers to changes to the data following a publication (e.g., adding data further back in time without changing the model underlying the interpretation) and z refers to minor changes not associated with a publication (e.g., typos). For example, the first official release of a dataset would be 1.0.0. If I fix a small typo, I would create version 1.0.1.
Exercise: Annotate the version of the dataset in the recently created page, following the x.y.z notation and using the property "datasetVersion".
Concept annotation in a LiPD file
As shown in Figure 4 and Figure 5, some of the annotated values like "Tree" already have links to other pages. These pages can be further populated and annotated by domain experts. For example, Figure 9 shows the Tree definition made in the Linked Earth wiki, which was created as a stub. Domain experts can contribute to the page, gathering field knowledge.
By linking to other existing pages we can connect different LiPD datasets (e.g., if two different datasets are of the same archive type, they will link to the same page).
When a link appears in red, it means that the page has not been defined yet. Anyone can click on these red links to associate a new page with its documentation. An example can be seen on Figure 10.
Exercise: edit the page "Tree ring width", which does not have a definition at the moment, and add a test definition. Use this link as the "Archive Type" value on your uploaded LiPD dataset .
Advanced annotation level
Property annotation in a LiPD file
Until now we have covered how to annotate property values and associate them to concepts and existing pages in the wiki. In this next step we will see how to create new properties on our LiPD datasets, i.e., adding new annotations to our dataset outside of the standard properties shown in Figure 3.
The "Properties" box, placed under the "Standard Properties" table, allows users to edit and create new properties and values. An example is shown in Figure 11. By clicking on the "plus" sign in the title, a new row will appear on the table. The row has two fields, one for adding the property name we want to use to describe the dataset (e.g., title, description, name, etc.) and another row for inserting the property value.
Before adding a new property name, it is important to note that a similar property may already exist in the ontology to describe the result as we aim to do. For example, imagine that we want to add a "description" to the dataset. If we start typing the property, we see that it already exists, and we can select it for our purposes. Selecting existing properties is important, as it helps to structure and control the content uploaded to the wiki.
Exercise: create a "title" property and use it to annotate your uploaded dataset. Check if the property already exists. If it doesn't, create it.
Adding location to a dataset
One of the requirements for your dataset to appear in a map is to add the coordinates where it was located. For that, you need to follow three main steps, as illustrated on Figure 24. The first step consists on linking the location used to collect the data. Any location is valid, from a single point (e.g., the dataset was collected from point x,y of mountain z) to a polyline (e.g., a river), or even a polygon (e.g., a mountain, a city or even a country). In the example, we are linking the dataset to the location "Central Andes composite 9", where the data was collected.
Once the location page has been created (step 1), we can annotate its name and its associated geometry with the property "hasGeometry" (step2). This is represented in this way because a location may change over time (e.g., a river could change its course), and hence the geometry would change without affecting the location itself.
Finally in step 3 we add the coordinates to the Geometry (if the page doesn't exist already). For this we use the AsWKT property, which indicates to the system that the coordinates are in Well Known Text format (https://en.wikipedia.org/wiki/Well-known_text). Since in this case we are representing a point, we also add type "Point" as property for the geometry.
Adding and extending concepts (e.g., how do I refer to the instrument used in my lab?)
Sometimes one may want to extend some of the concepts that already exist in the wiki. For example, imagine that I have measured a variable of a table (d18Og.rub-w) with the stable isotope ratio mass spectrometer instrument of my lab. If I state that the variable d18Og.rub-w was measured by a "stable isotope mass spectrometer instrument" (under the "instrument" category) I would be losing information: are all stable isotope mass spectrometer instruments the same?
We need to state which stable isotope mass spectrometer was used. In this case, the one at my lab.
Hence, we need to create the concept "StableIsotopeRatioMassSpectrometerOfMyLab", a special type of "Instrument" that allows creating new annotations on the data. Following the example shown in the previous section, we would need to create the StableIsotopeRatioMassSpectrometerOfMyLab page and annotate it with the category "StableIsotopeRatioMassSpectrometer". This category would become a new category in the wiki.
Exercise: create a new instrument that doesn't exist in the ontology, and use it to annotate a variable of a dataset.
Advanced wiki functionality
Creating a personal page
The Linked Earth wiki allows to create different types of pages. Personal pages are a special type of wiki pages, and we will use them to illustrate how to create a new wiki page in general. After logging in on the wiki, click on your name. You can find it on the top of any wiki page, as shown in Figure 12:
Clicking your name will take you to a new page, which you can complete with your personal information, by clicking on any of the "edit options" in the page, as depicted in Figure 13:
And adding your personal information on the form (Figure 14):
After you are done, just hit the "Update" button at the bottom of the page (Figure 15):
Exercise: Create your personal page and add a personal website and an "about me" description.
Creating a new wiki page
Just go to http://organicdatacuration.org/le-beta/index.php/New_Page
Replace "New Page" above to the name that you want for the page.
Then, either select a category for this page (Figure 16):
or, just click on the "Create" link to create a page without any category (Figure 17)
Deleting an existing wiki page
Go to http://www.organicdatascience.org/index.php/Name_of_Page Replace "Name of Page" above to the name of the page to delete, as shown in Figure 18.
Then click on the "Delete" link, and delete the page. Figure 19 shows an example:
Searching existing wiki pages
Before creating any page, it is recommended to search if they exist. Searching a page can be done by entering the terms on the search bar located on the top right of any page (see Figure 20).
Any page containing the word introduced in the search bar will be returned.
Renaming wiki pages
Wiki pages may need to be renamed. For example, due to typos in the page name or community agreement. In order to rename an existing page without losing any of its contents, you should click on the "Move" button under the "More" menu on the top of the page. An example is shown in Figure 21.
By clicking on the Move button, the page showed in Figure Figure 22 will ask for the new page name, as well as a reason of the change.
After hitting the "Move page" button, your page will be renamed.
Uploading images and files
If you want to add an image or document to your a wiki page, you just have to click on the "upload files" button that can be seen on the left of any wiki page (see Figure 23).
After you are done selecting the document you want to upload, just hit the "Upload file" button at the bottom of the page. Now you may reference to this file using brackets (e.g., [ [ File:File.png ] ]). You can see the different options for showing files in this page: https://www.mediawiki.org/wiki/Help:Images
Best practices
This section will cover naming convntions for instances, publications or versions in a dataset. This is currently under discussion.
TBD
