In romunov/wolfexplorer: Explorer designed to visualize complex multi-year multi-specimen data. Case study of Slovenian wolves.
Explorer designed to visualize complex multi-year multi-specimen data. Attached data is a subset of data from wolf monitoring of wolves in Slovenia in season 2016/2017 (summary in English).
Limitations
This viewer will require you shape your data to a somewhat specific, yet general enough, format. It can display only certain coordinate systems. Luckily WGS 84 (EPSG: 4326) is one of them. Data in the application is not persistent, but this limitation is something we're thinking of relaxing in the future.
WARNING: Date slider and some other features may not be working perfectly in some browsers (looking at you, Chrome). If you experience problems, please do drop us a line and switch browsers. Testing has been done on Firefox.
Community guidelines
1) Contributing to the software
Anyone interested is welcome to contribute to the software. There are a few ways to do it.
Firstly, if there is a feature that you would like us to add, you can open a new issue with an enhancement tag.
Secondly, you can fork the repository, do your magic and offer your upgraded code through a pull request. When writing code please follow R Style Guide.
2) Reporting issues or problems with the software
Github makes it easy to report issues with the software. Simply navigate to the issues tab and check if there is an issue similar to one you are experiencing already reported. If so, you are more than welcome to add your experience in a form of a comment to that issue thread. Otherwise, do not hesitate to report a new issue, that has not been previously reported.
3) Seeking support
Feel free to contact us through email. We are also both on twitter as romunov and zkuralt.
How to run this application
The easy way
Assuming you have all the packages installed*, starting with shiny, you can run this piece of code and you're off.
shiny::runGitHub(repo = "wolfexplorer", username = "romunov")
* you can install packages listed in the app.R using something along the lines of
x <- readLines("app.R")
libs <- x[grepl("^library\\(.*\\)$", x)]
libs <- gsub("^library\\((.*)\\)$", "\\1", libs)
cat(sprintf("install.packages(c(%s))", paste('"', libs, '"', collapse = ", ", sep = "")))
The manual way
First you need to clone the repository using git
git clone https://github.com/romunov/wolfexplorer
If you are using RStudio, open the project file, open app.R and press Run App button in the upper right corner of the script window.
If you are not using RStudio, just set working directory the project folder and run runApp().
If all goes well, you should see the application, displayed either in RStudio viewer pane or in your default broweser (preferably).
How to format data
To start, you should load the data using Data > Samples data menu for raw data and parentage information to Data > Parentage data.
Samples data
Samples data should come in the following raw text format:
$ x : num 430263 430260 475503 428961 419071 ...
$ y : num 63602 63609 59611 75076 44413 ...
$ date : chr "2012-05-30" "2012-05-30" "2011-08-27" "2011-06-23" ...
$ sample_type : chr "Direct Saliva" "Direct Saliva" "Direct Saliva" "Direct Saliva" ...
$ animal : chr "649" "650" "651" "652" ...
$ sex : chr "M" "M" "M" "F" ...
$ sample_name : chr "AH.02UE" "AH.02UH" "AH.0388" "AH.038A" ...
$ reference_sample: chr "AH.02UE" "AH.02UH" "AH.0388" "AH.038A" ...
Notice the name of columns. In this example the coordinates for x and y are "Gauss Krüger" (EPSG: 3912). You should supply WGS 84 (EPSG: 4326) coordinates for longitude and latitude, respectively, as they will be used without converting. See GKtoWGS.R for implementation of conversion. This would also be the place to perhaps add your "parser" to accomodate your coordinate format.
date should come in the %Y-%m-%d form. sample_type right now is hard coded but this restriction will probably be relaxed in the near future. The rest should be pretty self explanatory. Animal is the designation for a group (or a singleton) of genotypes, sex and sample_name appear in the popup to aid in exploring of data.
Parentage data (optional)
Data for parentage, derived from your favorite software, should be transformed to the following format:
$ offspring: chr "M1UA7" "M1YFC" "M2122" "M226C" ...
$ mother : chr "EE.156X" "AL.068T" "AU.0AEF" "M20PK" ...
$ father : chr "AX.0E1C" "AY.0F1M" "AH.03MT" "*1" ...
$ cluster : chr "1" "2" "2" "2" ...
Column offspring is reference_sample (from samples data) of a putative child, mother and father its parents and cluster should be "family" id. This step is optional but note that some functionality will not be available (see below).
Navigating the application
As mentioned above, you should read in the (genetic) samples data through the Data > Samples data menu. Imported data should appear in a table as seen in the picture below. Feel free to browse your data using autofilter input fields.
If you now head to Explore data menu, you should see the initial map with all samples plotted in grey. These markers are clickable. Go ahead, try it.
Upper right corner of the map should house a transparent box which now has a slider and an input field. Use the slider to filter out samples between specific dates. Note that this does not work for grey samples, but only on which animals you can select in the input field (and thus their displaying on the map).
If you also load parentage data (optional), you will be able to display selected animals' offspring as well.
Head back to the Explore data menu. Notice that another input field has appeared. In the below example you can see offspring of animal M2122. These should be colored orange if added to the selection.
It is also possible to plot pedigree tree. Once you've selected parentage data and selected a cluster ("family"), check Plot pedigree checkmark.
You can draw MCP (maximum convex polygon) for selected animals by checking the Show MCP checkmark. If there's only one sample, a circlular polygon is drawn around that point. For two points, a buffer of 1 km is drawn around the straight line connecting the two points. These two cases are not true MCPs but is a compromise between accuracy of MCP and visual display of limited number of points. For three points or more, a MCP as one would expect is created.
Sliders in the sidebar should aid in visualizing overlapping points/lines.
See menu Summary for information on the dataset. If you filter samples by date, summary will be calculated on that subset.
Legend colors can be manipulated through the Settings menu. Click on the input tab of the color and pick a color, any color.
romunov/wolfexplorer documentation built on June 16, 2019, 5:13 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Explorer designed to visualize complex multi-year multi-specimen data. Attached data is a subset of data from wolf monitoring of wolves in Slovenia in season 2016/2017 (summary in English).
Limitations
This viewer will require you shape your data to a somewhat specific, yet general enough, format. It can display only certain coordinate systems. Luckily WGS 84 (EPSG: 4326) is one of them. Data in the application is not persistent, but this limitation is something we're thinking of relaxing in the future.
WARNING: Date slider and some other features may not be working perfectly in some browsers (looking at you, Chrome). If you experience problems, please do drop us a line and switch browsers. Testing has been done on Firefox.
Community guidelines
1) Contributing to the software
Anyone interested is welcome to contribute to the software. There are a few ways to do it.
Firstly, if there is a feature that you would like us to add, you can open a new issue with an enhancement tag.
Secondly, you can fork the repository, do your magic and offer your upgraded code through a pull request. When writing code please follow R Style Guide.
2) Reporting issues or problems with the software
Github makes it easy to report issues with the software. Simply navigate to the issues tab and check if there is an issue similar to one you are experiencing already reported. If so, you are more than welcome to add your experience in a form of a comment to that issue thread. Otherwise, do not hesitate to report a new issue, that has not been previously reported.
3) Seeking support
Feel free to contact us through email. We are also both on twitter as romunov and zkuralt.
How to run this application
The easy way
Assuming you have all the packages installed*, starting with shiny, you can run this piece of code and you're off.
shiny::runGitHub(repo = "wolfexplorer", username = "romunov")
* you can install packages listed in the app.R using something along the lines of
x <- readLines("app.R") libs <- x[grepl("^library\\(.*\\)$", x)] libs <- gsub("^library\\((.*)\\)$", "\\1", libs) cat(sprintf("install.packages(c(%s))", paste('"', libs, '"', collapse = ", ", sep = "")))
The manual way
First you need to clone the repository using git
git clone https://github.com/romunov/wolfexplorer
If you are using RStudio, open the project file, open app.R and press Run App button in the upper right corner of the script window.
If you are not using RStudio, just set working directory the project folder and run runApp().
If all goes well, you should see the application, displayed either in RStudio viewer pane or in your default broweser (preferably).
How to format data
To start, you should load the data using Data > Samples data menu for raw data and parentage information to Data > Parentage data.
Samples data
Samples data should come in the following raw text format:
$ x : num 430263 430260 475503 428961 419071 ... $ y : num 63602 63609 59611 75076 44413 ... $ date : chr "2012-05-30" "2012-05-30" "2011-08-27" "2011-06-23" ... $ sample_type : chr "Direct Saliva" "Direct Saliva" "Direct Saliva" "Direct Saliva" ... $ animal : chr "649" "650" "651" "652" ... $ sex : chr "M" "M" "M" "F" ... $ sample_name : chr "AH.02UE" "AH.02UH" "AH.0388" "AH.038A" ... $ reference_sample: chr "AH.02UE" "AH.02UH" "AH.0388" "AH.038A" ...
Notice the name of columns. In this example the coordinates for x and y are "Gauss Krüger" (EPSG: 3912). You should supply WGS 84 (EPSG: 4326) coordinates for longitude and latitude, respectively, as they will be used without converting. See GKtoWGS.R for implementation of conversion. This would also be the place to perhaps add your "parser" to accomodate your coordinate format.
date should come in the %Y-%m-%d form. sample_type right now is hard coded but this restriction will probably be relaxed in the near future. The rest should be pretty self explanatory. Animal is the designation for a group (or a singleton) of genotypes, sex and sample_name appear in the popup to aid in exploring of data.
Parentage data (optional)
Data for parentage, derived from your favorite software, should be transformed to the following format:
$ offspring: chr "M1UA7" "M1YFC" "M2122" "M226C" ... $ mother : chr "EE.156X" "AL.068T" "AU.0AEF" "M20PK" ... $ father : chr "AX.0E1C" "AY.0F1M" "AH.03MT" "*1" ... $ cluster : chr "1" "2" "2" "2" ...
Column offspring is reference_sample (from samples data) of a putative child, mother and father its parents and cluster should be "family" id. This step is optional but note that some functionality will not be available (see below).
Navigating the application
As mentioned above, you should read in the (genetic) samples data through the Data > Samples data menu. Imported data should appear in a table as seen in the picture below. Feel free to browse your data using autofilter input fields.
If you now head to Explore data menu, you should see the initial map with all samples plotted in grey. These markers are clickable. Go ahead, try it.
Upper right corner of the map should house a transparent box which now has a slider and an input field. Use the slider to filter out samples between specific dates. Note that this does not work for grey samples, but only on which animals you can select in the input field (and thus their displaying on the map).
If you also load parentage data (optional), you will be able to display selected animals' offspring as well.
Head back to the Explore data menu. Notice that another input field has appeared. In the below example you can see offspring of animal M2122. These should be colored orange if added to the selection.
It is also possible to plot pedigree tree. Once you've selected parentage data and selected a cluster ("family"), check Plot pedigree checkmark.
You can draw MCP (maximum convex polygon) for selected animals by checking the Show MCP checkmark. If there's only one sample, a circlular polygon is drawn around that point. For two points, a buffer of 1 km is drawn around the straight line connecting the two points. These two cases are not true MCPs but is a compromise between accuracy of MCP and visual display of limited number of points. For three points or more, a MCP as one would expect is created.
Sliders in the sidebar should aid in visualizing overlapping points/lines.
See menu Summary for information on the dataset. If you filter samples by date, summary will be calculated on that subset.
Legend colors can be manipulated through the Settings menu. Click on the input tab of the color and pick a color, any color.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.