Setting up Pumilio and Usage of the pumilioR Package

Introduction

The pumilioR package has functions to get data and sound files from the web-based sound archive system Pumilio (http://ljvillanueva.github.io/pumilio). This introduction will provide a brief overview of setting up Pumilio and examples of how to query the system and extract both data and soundfiles.

pumilioR requires R version 2.14, or newer, and depends on the packages XML and RCurl.

The source of the package is kept at Github: https://github.com/ljvillanueva/pumilioR

The website of the package is http://ljvillanueva.github.io/pumilioR/

Pumilio Setup

To allow the use of the package, log in as an administrator to the Pumilio system. Click the Admin menu link (on the top right edge of the page). On the main settings page of the Admin menu, under “System behavior”, there is an option:

Set it to Yes. Now pumilioR, and other programs, can read data from the archive using XML.

To limit the access to valid users registered in the Pumilio system, set the option:

to Users. To allow anyone to query the system set it to Any.

Check access

Before querying the system, first check that it is properly configured and that you can access it, for example:

# Load the package
library(pumilioR)

# Check that the system can use pumilioR, returns TRUE if it is allowed and
# the version supports it
access <- checkVersion(pumilio_URL = "http://pumilio.coquipr.com/pumilio/")
  Pumilio is running version 2.7.0
    and the XML access is set to: TRUE
access
[1] "TRUE"

Querying the system

To query the system, use the functions getCollections() or getSites() to get a data frame with the collections and the sites, respectively, in the system. Then, you can get the sounds for that collection or site using the function getSounds(). For example:

# Get all collections
cols <- getCollections(pumilio_URL = "http://pumilio.coquipr.com/pumilio/")
 
   Found 15 results
# Show the first row
cols[1, ]
   ColID CollectionName Author            FilesSource
 1   101           01-A    LJV Automated Audio Logger
   CollectionFullCitation  URL
 1                   NULL NULL
                                                                    Notes
 1 LJV A  Deployed on 20-oct-03 14:23  LEF. Next to the road, 191, km 9.3
# Get all sites
sites <- getSites(pumilio_URL = "http://pumilio.coquipr.com/pumilio/")
  
   Found 14 results
# Show the first row
sites[1, ]
 1    102 LEF - Road 191, km 9.3  18.3119  -65.7736      NULL  NULL
# Get all the sounds in the site with the SiteID = 102
sounds <- getSounds(pumilio_URL = "http://pumilio.coquipr.com/pumilio/", SiteID = 102, 
type = "site")
  
   Found 50 results
# Show the first row
sounds[1, ]
   SoundID ColID SiteID              OriginalFilename
 1     234   101    102 LINE_2003-10-30_23_30_37.flac
                  SoundName day month year hour minutes seconds
 1 LINE_2003-10-30_23_30_37  30    10 2003   23      30      37
   SamplingRate BitRate Channels Duration SoundFormat SensorID Notes
 1        48000      16        1    59.36        flac      101  NULL
             timestamp FileSize
 1 2010-11-10 10:05:58  2610263
                                                                                FilePath
 1 http://pumilio.coquipr.com/pumilio/sounds/sounds/101/50/LINE_2003-10-30_23_30_37.flac
   AudioPreviewFormat AudioPreviewFilename
 1                mp3  234.autopreview.mp3
                                                                 AudioPreviewFilePath
 1 http://pumilio.coquipr.com/pumilio/sounds/previewsounds/101/50/234.autopreview.mp3

Download files

Once a result is obtained from the system, the audio file can be downloaded using the function getFile(). This function needs the result of either getCollections() or getSites() and the SoundID of the desired file.

# First, get a list of results
results <- getSounds(pumilio_URL = "http://pumilio.coquipr.com/pumilio/", SiteID = 111, 
type = "site")
   Found 155 results
results[1, ]
   SoundID ColID SiteID              OriginalFilename
 1    4078   122    111 LINE_2004-03-20_02_01_11.flac
                  SoundName day month year hour minutes seconds
 1 LINE_2004-03-20_02_01_11  20     3 2004   02      01      11
   SamplingRate BitRate Channels Duration SoundFormat SensorID Notes
 1        48000      16        2  59.4027        flac      101  NULL
             timestamp FileSize
 1 2010-12-09 11:12:49  2943180
                                                                                FilePath
 1 http://pumilio.coquipr.com/pumilio/sounds/sounds/122/29/LINE_2004-03-20_02_01_11.flac
   AudioPreviewFormat                     AudioPreviewFilename
 1                mp3 LINE_2004-03-20_02_01_11.autopreview.mp3
                                                                                      AudioPreviewFilePath
 1 http://pumilio.coquipr.com/pumilio/sounds/previewsounds/122/29/LINE_2004-03-20_02_01_11.autopreview.mp3

Then, get the file from the first row, identified with the SoundID 4078. The audio file is saved in the working directory.

getFile(results, SoundID = 4078)

Apache Basic Authentication

Basic authentication can be used on the Apache webserver as a way to limit access to the data by requiring a username and password. This is outside the scope of this vignette. Since version 1.2 of pumilioR these sites can be accessed providing the username and password, separated with a colon, to the argument credentials in each function.

sites <- getSites(pumilio_URL = "http://pumilio.coquipr.com/pumilio2/", credentials = "pumilio:pumilio")
  
   Found 14 results
sites[1, ]
   SiteID               SiteName latitude longitude elevation notes
 1    102 LEF - Road 191, km 9.3  18.3119  -65.7736      NULL  NULL

Pumilio User Authentication

Since version 1.2 of pumilioR and version 2.7.0 of Pumilio, the system can be accessed providing a valid username and password, separated with a colon, already registered in the system to the argument pumiliologin in each function.

sites <- getSites(pumilio_URL = "http://pumilio.coquipr.com/pumilio3/", pumiliologin = "pumilio:pumilio")
  
   Found 14 results
sites[1, ]
   SiteID               SiteName latitude longitude elevation notes
 1    102 LEF - Road 191, km 9.3  18.3119  -65.7736      NULL  NULL

Package website

Please visit the package website for more information and updates: http://ljvillanueva.github.io/pumilioR/

For suggestions or to report bugs or problems: http://github.com/ljvillanueva/pumilioR/issues

The package page in CRAN is http://cran.r-project.org/web/packages/pumilioR/


Vignette “Setting up Pumilio and Usage of the pumilioR Package” by LJ Villanueva-Rivera

Version 1.0 (1 February 2014)