Help > Tutorial - Building a basic eBird pipe

Introduction

This tutorial will take you through the steps of building a pipe that creates a simple visualization of eBird data.  You will end up with a pipe similar to the one called “example – AKN eBird dataset” pictured below. This tutorial is also available as a PDF.

Part 1. Getting Started

These steps will get you logged into the Science Pipes web site, and into the pipe editor.

1) Go to http://sciencepipes.org and sign in. If you don’t have an account, you will need to create an account first. (NOTE: if you are an eBird user, you can use the same user name and password for Science Pipes.)

2) Go to the My Pipes page. This page shows the pipes that you own, but will be empty if you are a new Science Pipes user.

3) Click on the Create new pipe link to bring up the Create Pipe page:

 

4) Give your pipe a name by typing the name into the first field on the page. You could name it something like “my first eBird pipe”.

5) Use the “Description” to give a text explanation of what you intend the pipe to do.  For this pipe something like the following would be appropriate:

This pipe shows a simple visualization of eBird data. It was created by following the “Building a Basic eBird Pipe” tutorial.

 

6) For “Type of pipe” choose “eBird AKN”. This indicates which set of components you would like to use to build your pipe.

7) Clicking on “Create” will create a blank pipe with the name you gave and open the pipe editor.

Part 2. The Pipe Editor – Components

The section will take you through dragging components onto the pipe editor workspace. The next section will focus on connecting the components together.

 

1) Click on the “AKN eBird Data” component from the component library and drag it onto the workspace:

2)   Click on the “AKN Histogram Calculator” and drag it onto the workspace. Place this component to the right of the “AKN eBird Data” component:

3) Click on the “Data Viewer” and drag it onto the workspace. You may need to use the scroll bar at the right of the component library to scroll the components to find the “Line Chart” under the “Output” group. Place this component underneath the “AKN Histogram Calculator”:

4) Click on the “Line Chart” and drag it onto the workspace.  Place this component to the right of the “AKN Histogram Calculator”:

5) These components should be arranged on your workspace as indicated below:

Part 3. The Pipe Editor – Connections

This section will walk you through creating the connections that will make your pipe work. We will create four connections in this example. Connections are made between ports, which are represented with this icon: 

1) Get eBird observations to the histogram calculator. We want to connect the “out” port on the “AKN eBird Data” component to the “in” port on the “AKN Histogram Calculator”. You can think of the species occurrence records in the eBird dataset being sent through the “out” port into the “in” port of the histogram calculator. Use your mouse to click on the port labeled “out” in the “AKN eBird Data” component and, while holding your mouse button down, drag it over to the port labeled “in” on the “AKN Histogram Calculator”. When the port on the “AKN Histogram Calculator” is highlighted with a green square, release your mouse button and the two ports will be connected with a solid line.

 

2) Get calculation results to the line chart. For the purposes of this example, let’s visualize the total number of observations in the eBird dataset (for the species we will later choose) in relation to the Julian date of the observation. To do that, we want to connect the “total number of observations” port in the “AKN Histogram Calculator” to the “dataPort” in the “Line Chart”. You should end up with a connection as shown below.

3) Show the species of interest in the line chart. The “AKN eBird Data” component allows you to choose a species of interest, and it provides the name of that species as output through the “species selected” port. If we connect that port to the “auxiliary title” port in the “Line Chart”, our chart will automatically include the name of the species we have chosen. Make that connection now, as shown below:

4) Show a description of the dataset. The “AKN eBird Data” component also gives more details about the data it is using. You can access that description using the “data description” port, and expose it as a pipe result using the “Data Viewer”, which is a component that simply shows whatever text is sent to it. Connect the “data description” port of the “AKN eBird Data” component to the “input” port of the “Data Viewer” as shown below:

5) Now all the required connections for this pipe are made. It would be a good time to save your pipe by clicking on the “Save Pipe” button.

6) The next section in this tutorial will walk you through customizing some of the settings in your pipe. However it you are just dying to see your pipe run, you could close it (using the “Close…” button) and run it (skip to Part 5).

Part 4. Pipe Settings

This section will take you through configuring your pipe to run.

1) Pick the species in which you are interested. Use the pull down menu in the “AKN eBird Data” component to select the species you want to look at first. This will be the default species whenever the pipe is run, but there are also ways to allow the person running the pipe to choose a different species. There are a lot of species from which to choose, and we know that the pull down isn’t an ideal way to choose a species.

 

2) Decrease the number of categories used in the histogram. By default, the “AKN Histogram Calculator” groups species occurrence data by 7 day intervals (“Groups Size”). A larger interval will decrease the number of categories and will make a more pleasing visualization. Try changing the “Group Size” to 14  instead of 7.

3) Customize the chart. There are a lot of settings that can be tweaked in the charts and graphs, including the  “Line Chart”. We’ll look at them one at a time.

a) Title. We have left the “title” port unconnected, so that means we should probably enter one manually. Enter “eBird Data”.

b) Auxiliary Title. The “auxiliary title” port in our pipe is already connected, so we don’t need to provide an auxiliary title.

c) Height. This is the number of pixels for the chart. 400 is the default and that should be fine for most purposes.

d) Width. The default of 400 pixels for the width of the chart is a little small for our purposes. Enter 800 instead.

e) Category Axis Label.  This is the label along the bottom of the chart. Enter “Julian Date”.

f) Value Axis Label. The value we are charting is the number of observations. Enter “Number of Observations”.

4) Save and Close. Click on the “Save Pipe” button to save the changes you have made to your pipe. Then click on the “Close…” button to exit the pipe editor  interface.

Part 5. Running Your Pipe

In this section you will run your new pipe.

1) When you close the pipe editor, you will see the details of your pipe, shown below:

2) Click on the “Run” link to run your pipe and see what it does. You will see the “Run Pipe” page:

3) We will see later how to change the settings on your pipe so that you can pick the species when you run it. For now, just click on the “Run” button.

4) It may take a few seconds to run, but you should eventually see a page with your pipe results. It will tell you that this is the “Latest Finished Result” and give you the status of your pipe run. In the case below, it shows that the pipe is finished running and that it took 512 milliseconds to run.

5) If you keep scrolling down on that page you will see that there are two results: one from the “Data Viewer” and one from the “Line Chart”.

a) Remember that the “Data Viewer” is connected to the description of the eBird dataset. Although it is not formatted very nicely, it is readable saying:

This dataset was downloaded from the Avian Knowledge Network (http://www.avianknowledge.net/content/download/packages/observation_data/project/ebird_all/) on Jan. 18, 2010. It contains an extract of all eBird data in the AKN system as of Jan. 15, 2010. Invalid records have been excised from this dataset. The format of the data is BMDE v1.38 (http://www.avianknowledge.net/content/contribute/the-bird-monitoring-data-exchange).

b) The “Line Chart” output shows the chart that we configured. Notice that our axis label (“Julian Date” and “Number of Observations”) and the primary title reflect the settings that we customized. Likewise, the auxiliary title (i.e., the second line of the chart title) shows the name of the species we selected.

Part 6. Making Your Pipe More Interesting

When you were creating this pipe, you chose a species of interest to visualize. To make this pipe more interesting, we can configure it to ask for that species before it is run. This will let you and others choose a different species each time it is run. This section shows how to do that.

1) Make sure you are viewing your pipe (or results from your pipe) so that the “Tools for this pipe” section is shown on the right side of the page.

2) Click on “Modify parameters” to open the page that lets you configure pipe settings outside of the editor. You will see the page below:

 

3) Click on the link next to “AKN eBird Data” that says “[1 parameter…]”. It will expand into some unwieldy details.

4) Click on the check box underneath the “EXPOSED?” column. That tells the system that you want to expose this setting whenever the pipe is run.

 

5) You can also take this opportunity to change the default species to use when the pipe is run by picking a different species from the pull down menu.

6) Now click on the “Save” button.

7) Click on the “Run” link under “Tools for this pipe”.

8) Now, you have the option to pick a different species when you run the pipe, as shown below:

References

• further information about eBird components
• more example pipes using eBird data
• Get this tutorial as a PDF.