For R users: How to install scimapClient

scimapClient anonymously tracks which R packages you use, and sends this information to http://scisoft-net-map.isri.cmu.edu, where you can browse the aggregated results.

To install

Type this from your R command line:
install.packages("scimapClient", repos="http://scisoft-net-map.isri.cmu.edu/static/R")
After you install it, if you load the package (i.e. library(scimapClient) ) in the next few minutes, it will prompt you for permission to do two things: If you don't happen to load the package right away, or just want to wait and enable it later, you'll have to enable it manually: type library(scimapClient) to load it, then enableScimap() to trigger the prompt for permission.

Source

Examine the source code on Github: https://github.com/cbogart/scimapClient. You're free to fork it and modify it, but if you do so, please have it upload usage packets to a different site than ours (this is set in the "reghost" variable).

For R package authors: how to instrument your software

Simplest way: package-level information only

Add a dependency to scimapClient to your package, and the line: library(scimapClient) somewhere in your code, and work with us to make sure your package is available from the same repositories yours is available from. It is currently available on github.com and on r-forge.com. The users will not have to do anything special; when they install or use your package, the monitoring software will come with it, and ask for permission to enable itself. We recommend that you make sure your users know about it ahead of time so they know what's going on: mention it prominently in the package documentation, and let users know that they can disable tracking later by typing (just one time, at a command line), disableScimap().

Technical details for the curious

The scimapClient package captures the names and version numbers of every package you load during your R session, and their static dependencies. When you exit your R session, it bundles these into an JSON message and sends them by TCP to port 7778 of scisoft-net-map.isri.cmu.edu. Here is a sample packet:
{ "scimapInfoVersion" : 3,
  "startTime" : "Thu Sep 18 18:36:17 2014",
  "startEpoch" : "1411079777",
  "pkgT" : { "methods/3.1.1" : "utils",
             "datasets/3.1.1" : [ ],
             "utils/3.1.1" : [ ],
             "R/3.1.1" : "utils",
             "grDevices/3.1.1" : [ ],
             "base/3.1.1" : [ ],
             "stats/3.1.1" : [ ],
             "scimapClient/0.1.4" : [ "RJSONIO", "tools" ],
             "graphics/3.1.1" : "grDevices" 
  },
  "jobID" : "16222613839223790698650621411079777",
  "platform" : { "hardware" : "x86_64",
                 "version" : "13.4.0",
                 "system" : "Darwin" },
  "user" : "1622261383922379069865062",
  "weakDeps" : [ ],
  "userMetadata" : [ ],
  "dynDeps" : [ ],
  "weakPackDeps" : [ ],
  "dynPackDeps" : [ ] }
You can see a sample packet in your own installation by loading the scimapClient package and typing "previewPacket()" at the R prompt.

Meaning of the fields:

"startTime" and "startEpoch" are the time when your R session started

"pkgT" shows which packages were used, and what their static dependencies were.

"user" is a random string of digits generated when you install the package, so that we can distinguish distinct users.

"jobid" is the user number plus the start time of the session, so we can distinguish distinct sessions.

For future use:

"userMetadata" is a field you can fill (by calling addUserMetadata(list(...)) within your R session). Currently "write only", since the server stores this information but the web page does not display it.

"weakDeps", "dynDeps", "weakPackDeps", "dynPackDeps": If the author of an R chose to collect information about logical dependencies, (sequences of calls to functions of interest), these fields would show sequence and nesting relationships between instrumented functions and the packages they came from.