Pretty Good Bird Workbench Documentation

Tab: Prairie Haven Overview

The Prairie Haven Overview tab summarizes BirdNET-Analyzer results in a tabular view – like pivot table functionality in Excel spreadsheets. Rather than presenting observation-based data, the tables on this page transform the data into species-level summaries. Users are able to select how they want the data to be summarized, and can also provide additional filters for further subsetting the data. Click on pictures to embiggen.

User Inputs

User inputs are found on the sidebar for this tab.

Input Name	Input Choices	Description
Model-Match Scale ‘Model Proximity’ or ‘Model Adherence’	Numerical value or range of values between 0 and 1.	This input allows you to filter that output on this tab based on BirdNET-Analyzer’s ‘Confidence’ attribute. We have renamed this input to ‘BirdNET Model-Match Scale’ because BirdNET’s confidence isn’t actually a probability and is not related to confidence intervals. Read more about that here.
Species Lookup	Categorical selection based on species present in the dataset. Multiple selection is allowed.	With this tool, you can filter the output on this tab to specific species that you have defined.
Pivot Table Selection	Your choice of 4 pivot views: 1.        Species by Month 2.        Species by Location 3.        Species by Year 4.        Species by Week	This selection determines how the data is summarized in your output table. Each row is a species, and columns show months, locations, years, or weeks.
Pivot Table Filters	Dynamic filtering tools, determined based on your Pivot Table Selection value.	The Pivot Table Filters change based on your Pivot Table Selection. These inputs allow for further filtering of the table output, including filtering by year, location, month, and week.

 

Output Explanation

Example Pivot Table Output

The starting point for this output is the FST file which is defined in the code as `all_data`. This dataset is cleaned / formatted BirdNET-Analyzer results for all years of data and all confidence levels. Each observation in the FST file is a single bird vocalization, with attributes including the specie’s name and code, confidence level, location, date, time, and file name. The purpose of the Prairie Haven Overview Page is to transform this information into a new view. Here are the steps taken in the code to do this transformation.

1. `all_data` is filtered based on BirdNET Model-Match Scale and saved as the value `filtered_data`
2. A `create_pivot_input` function is called based on the user input for Pivot Table Selection.
   1. If ‘Species by Month’ is selected, `create_pivot_month` is called.
   2. If ‘Species by Location’ is selected, `create_pivot_location` is called.
   3. If ‘Species by Year’ is selected, `create_pivot_year` is called.
   4. If ‘Species by Week’ is selected, `create_pivot_week` is called.

The table below outlines how each function behaves:

Function Name	Pivot Table Filters	Function Behavior
`create_pivot_month`	Year, Location	` filtered _data` is filtered based on user-entered values for Species Lookup, Year, and Location. ` filtered _data` is grouped by species, with columns for each month, and the count of observations for each species is computed.
`create_pivot_location`	Year, Month, Week	` filtered _data` is filtered based on user-entered values for Species Lookup, Year, Month, and Week. ` filtered _data` is grouped by species, with columns for each location, and the count of observations for each species is computed.
`create_pivot_year`	Location, Month, Week	` filtered _data` is filtered based on user-entered values for Species Lookup, Location, Month, and Week. ` filtered _data` is grouped by species, with columns for each year, and the count of observations for each species is computed.
`create_pivot_week`	Year, Location, Week, Time	` filtered _data` is filtered based on user-entered values for  Species Lookup, Year, Location, Week and Time. ` filtered _data` is grouped by species, with columns for each week, and the count of observations for each species is computed.

 

3. The output data table is formatted.
   1. A row is added to the top of the table for total counts by column values.
   2. A column is added to the left of the table for total counts by species.

Interacting with the Output

Generating Tables:

First, to see the output print to screen, a user needs to select the Generate Table button found in the sidebar:

After generating a table, the Generate Table button is disabled until the user either selects a new Pivot Table view or adjusts any of the parameters in the sidebar. When this happens, the Generate Table will be enabled again and a new output can be rendered.

Copying the table or downloading a CSV:

There are two buttons found at the bottom of the table output, allowing a user to copy the table to clipboard, or download the table as a CSV. These options copy the table exactly as it is seen in the display.

Sorting data in the table:

Data in the table output can be sorted by the columns. This is done by selecting the columns header you want to sort by with the mouse:

If you want to sort by multiple columns, hold the shift key as you select your column header choices:

Selecting a species to view:

Double clicking on a row of the table will automatically take the user to the Species-Specific Location Drilldown. The data on this page will reflect the species that was selected.

Double click ‘American Robin’

Redirected to the Species-Specific Location Drilldown for American Robin.

 

Tab: Species-Specific Location Drilldown

The Species-Specific Location Drilldown tab provides a species-specific and location-specific visual overview for individual bird species. It displays species-specific observations as an interactive histogram, allowing the user to view the distribution of observations over the year and across different habitat types. Users can make selections from the histogram to output a table view of specific observations. From this view, users can also launch a separate application for manually reviewing observations.

User Inputs

User inputs are found on the sidebar for this tab.

Input Name	Input Choices	Description
Model-Match Scale ‘Model Proximity’ or ‘Model Adherence’	Numerical value or range of values between 0 and 1.	This input allows you to filter that output on this tab based on BirdNET-Analyzer’s ‘Confidence’ attribute. We have renamed this input to ‘BirdNET Model-Match Scale’’ because BirdNET’s confidence isn’t actually a probability and is not related to confidence intervals. Read more about that here.
Species Lookup	Categorical selection based on species present in the dataset. Single selection only.	Note: The Species Lookup tool on this page behave differently than the Species Lookup tool in Prairie Haven Overview. On this tab, only one species can be selected. This controls what species is displayed on the page.
Plot Settings	Time interval choices: ·      Week ·      Month	This input controls how the histogram bins are defined. If a user selects week, data is grouped and displayed at a weekly interval. If a user selects month, data is grouped and displayed at a monthly interval. Weeks are defined as beginning on Sundays. Week 1 begins on the first Sunday of the year.
Cornell Ornithology Links	Button choices for launching a new window.	‘All About Birds’ launches the Cornelll Ornithology All About Birds web page for the current species displayed. ‘Macaulay Library’ launches the Cornell Ornithology Macaulay Library web page for the current displayed species.

 

Output Explanation

Histogram Output

Example histogram output for Species-Specific Location Drilldown

The starting point for this output is the data stored in `filtered_data`, which is the same data from Prairie Haven overview. It comes from our original FST file, but it is filtered based on the values in ‘Model Match’. The following steps describe how the histogram output is produced in the code:

1. First, a for loop is used to sequence through each unique Location value in the dataset. For each location, `filtered_data` is filtered by the select Species and the current selected Location in the for loop. This filtered data is saved as the variable `species_data`. If there are no observations available for the species at this location, an informational message will display in the app.
2. The `species_data` is grouped by year and saved as `complete_data`.
3. Two new variables are saved, corresponding to the two options for viewing histogram (by Month and by Week). `count_data_week` divides each year of data into weekly bins, and calculates the number of observations in that bin. `count_data_month` divides each month of data into monthly bins, and calculates the number of observations in that bin.
4. The output graph is produced using ggplot’s `geom_bar` function. This is saved as the variable `p`.
5. `p` is converted into a plotly object which allows it to be interacted with by a user.
6. Only the three most recent years of data are displayed in the histogram output by default, which is defined by the variable `recent_years`.
7. Steps 2 – 6 are repeated for each unique Location value.

Data Table Output

Example data table output for Species-Specific Location Drilldown

The data table output appears when a user selects one or more of the bins in the histogram output. The steps below outline how the data table is calculated and displayed:

1. Each histogram bin in the plot has a ‘key’ that stores either `Year.Loc` for weekly intervals (i.e. 25,2023,Prairie) or `Month.Year.Loc` for monthly intervals (i.e. 6,2023,Wetland). When histogram bin(s) are selected in the plot, we updated a variable called `selected_data`with the ‘key’.
2. Some generic filters then get applied to our filtered_data First we create a variable `species_data` which is filtered by the selected species and then formatted with new columns that contain the grouping variables (Week.Year.Loc and Month.Year.Loc).
3. The code filters the dataset further by filtering based on the weekly or monthly key (depending on your time interval selection). It saves this output as `out_df`.
4. Each row in the `out_df` gets a dynamically created ‘Open Observation button’ which redirects the user to a new application.
5. The data tables is then rendered, displaying a subset of the original columns.

Interacting with the Output

Hovering over bins to view plot details

Hovering over individual bins allows you to see details including Week #, Date range, and count of observations.

Selecting years in the legend

Toggle specific years in the legend on or off to display them in the plot.

Select bins in the histogram plot to display data table

One bin can be selected by a single click, or you can select multiple bins by holding down the shift key as you click. This will dynamically generate and display an associated data table for the selected bins.

Click the ‘Open Observation’ button from the data table to launch the application ‘Tiny Shiny’ to manually review the selected observation.

Species-Specific Overview

The Species-Specific Overview displays frequency polygon (line) plots that show seasonal patterns for a selected species across six habitat locations simultaneously. This tab is designed for exploratory analysis and pattern recognition across habitats for specific species.

User Inputs

User inputs are found on the sidebar for this tab.

Input Name	Input Choices	Description
Model-Match Scale ‘Model Proximity’ or ‘Model Adherence’	Numerical value or range of values between 0 and 1.	This input allows you to filter that output on this tab based on BirdNET-Analyzer’s ‘Confidence’ attribute. We have renamed this input to ‘BirdNET Model-Match Scale’’ because BirdNET’s confidence isn’t actually a probability and is not related to confidence intervals. Read more about that here.
Species Lookup	Categorical selection based on species present in the dataset. Single selection only.	Note: The Species Lookup tool on this page behave differently than the Species Lookup tool in Prairie Haven Overview. On this tab, only one species can be selected. This controls what species is displayed on the page.

 

Output Explanation

1. First, a for loop is used to sequence through each unique Location value in the `location_list` (House, Glen, Prairie, Wetland, Savanna, Forest). For each location, `filtered_data()` is filtered by the selected Species and the current Location in the for loop. This filtered data is saved as the variable `species_data`. If there are no observations available for the species at this location, an informational message will display in the app.
2. The `species_data` has time-based grouping variables added to it (Date, Year, Month, Week.Year, Month.Year.Loc, Week.Year.Loc) using the `mutate()` function, but unlike the previous section, no data completion or gap-filling is performed.
3. The output graph is produced using ggplot’s `geom_freqpoly` function with a binwidth of 1, creating smooth line plots rather than bars. The plot uses `aes(color = as.factor(Year), linewidth = as.factor(Year))` to differentiate years by both color and line thickness. This is saved as the variable p.
4. Color palettes and line thickness values are pre-defined using the viridis “plasma” color scheme (cols) and a sequence of line sizes ranging from 0.3 to 1.2 (line_size), with both mapped to the available years in the data.
5. p is converted into a plotly object using ggplotly() with dynamicTicks = TRUE for better axis scaling.
6. Steps 1-6 are repeated for each unique Location value, resulting in six separate line plots displayed simultaneously in a 2×3 grid layout rather than in separate tabs.

File Analysis

The File Analysis page provides a table-based interface for exploring and analyzing audio recording files. It aggregates observations by audio file and calculates metrics like number of observations per file, species diversity, and confidence scores. It generates a file quality Score for each file based on multiple factors and provides audio playback functionality. Users can explore files through this interactive data table and navigate toe detailed file analysis by interacting with the data table.

User Inputs

Input Name	Input Choices	Description
Model-Match Scale ‘Model Proximity’ or ‘Model Adherence’	Numerical value or range of values between 0 and 1.	This input allows you to filter that output on this tab based on BirdNET-Analyzer’s ‘Confidence’ attribute. We have renamed this input to ‘BirdNET Model-Match Scale’’ because BirdNET’s confidence isn’t actually a probability and is not related to confidence intervals. Read more about that here.
Species to Exclude	Multiple selection of species to exclude for generating the output table.	Observations for the selected species will not be included in the output data table. In other words, if an audio file only contains observations of the selected species, that audio file will not be included in the data table output.
Filter Files by Species	Multiple selection of species to use for filtering the output table.	Only files which contain at least one observation for the selected species will be included in the output. The selections in this input utilize “OR” logic.

 

Output Explanation

1. Two reactive inputs are created called `debounced_species_exclude` and `debounced_species_file_filter` for filtering files by specific species.
2. The `cached_filtered_data` reactive value is updated whenever the filtered data or species exclusion criteria change. It removes excluded species from `filtered_data` and if species file filtering is applied, it identifies audio files containing those species and retains only observations from those files, effectively filtering the entire dataset by file-level species presence.
3. Data processing begins in the `create_pivot_files` function, which groups observations by audio file (`Begin.Path`) along with location, date, and weather data. For each unique file, it calculates summary metrics including number of observations, number of unique species, mean confidence scores, and determines time of day categories (Morning/Afternoon/Night).
4. Percentile based scoring is implemented that calculates percentile ranks for three metrics: number of observations, wind speed (inverted so lower wind scores higher), and mean confidence. These are averaged into a single `Score` value, wi5th missing wind speed handled by averaging the other two metrics plus 0.5. The score is then mapped to a color gradient from white (lowest) to dark blue (highest).
5. Interactive audio buttons are generate for each file using the `find_audio_file_full` function, which locates the actual audio file path and creates a button that will stream the first 15 seconds of the audio file when clicked.
6. The data table is rendered with customization including CSV and copy export buttons, fixed headers, scrolling, and conditional formatting that colors the Score column.
7. Double-clicking a table row triggers navigation to a detailed file analysis view by updating the `file_click` reactive value with the selected file path.

Interacting with the Output

File Drilldown

The File Drilldown page provides a detailed analysis of individual audio recording files. When a specific file is selected, it displays comprehensive information including all bird observations detected within the file, weather conditions during and around the recording time, and temporal patterns of detections. This tab combines tabular data presentation with weather visualization plots, showing wind speed and temperature trends with the audio file recording period highlighted. This section serves as the detailed follow-up to the File Analysis page, allowing users to examine the specific contents and environment context of individual audio recordings.

User Inputs

User inputs are found on the sidebar for this tab.

Input Name	Input Choices	Description
Model-Match Scale ‘Model Proximity’ or ‘Model Adherence’	Numerical value or range of values between 0 and 1.	This input allows you to filter that output on this tab based on BirdNET-Analyzer’s ‘Confidence’ attribute. We have renamed this input to ‘BirdNET Happiness Scale’ because BirdNET’s confidence isn’t actually a probability and is not related to confidence intervals. Read more about that here.
File Lookup	Categorical selection based on files present in the dataset. Single selection only.	This controls what file information is displayed on the page.
Plot Settings	Weather Time Range with two choices: 1.        24 Hour Context 2.        1 Hour Context	This input controls how the weather plots are displayed. If 24 hour context is selected, the plots will display the 12 hours before and after the audio file. If 1 hour context is selected, plots will display only the hour that audio was recorded.

 

Output Explanation

Weather Plots

1. `file_wind_plot` and `file_temp_plot` create weather visualizations by querying a SQLite weather database. The time range for plotting is determined by user input `input$weather_context`: either a 24-hour window (12 hours before and after the recording) or just the 1-hour recording period.
2. Database queries are executed using `dbConnect` and `dbGetQuery` to retrieve wind speed and temperature data from separate tables, filtering by Unix timestamp ranges converted from the audio file’s datetime. The data converts Unix timestamps back to POSIXct for ggplot compatibility.
3. Weather plots us ggplot with geom_line to show temporal trends and include a highlighted rectangular regions `geom_rect` that marks the exact 1-hour audio file recording period with a blue overlay.

File Scatterplot

1. The scatterplot visualization is created using ggplot showing the temporal distribution of bird detections within the selected audio file. Points are positioned by detection time (calculated as `Date.Time + Begin.Time..s.` offset) on the x-axis and confidence level on the y-axis.
2. Points are colored by species (`Common.Name`) to visually distinguish different bird species detected within the same audio file, allowing users to see species diversity and detection patterns over time.
3. The ggplot object is converted to an interactive Plotly object using ggplotly for enhanced interaction.

File Details Table

1. The detailed data table displays all observations from the selected file using the `file_details_data` reactive value.
2. The table is formatted to include top filtering for searching within the file’s observations, fixed headers for navigation, and vertical and horizontal scrolling to accommodate the data.