ltrr-arizona-edu/burnr

🔥 Forest fire history analysis in R.

burnr

Basic tools to analyze forest fire history data (e.g. FHX) in R. This is designed for power users and projects with special needs.

Installation

You can install the released version of burnr from CRAN with:

install.packages("burnr")

And the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("ltrr-arizona-edu/burnr")

Example

This is a basic example which shows you how to solve a common problem:

library(burnr)

# This gives you a basic plot. There are more advanced options. For example, we can color our plot by sample species.

data(lgr2_meta)

plot(lgr2,
  color_group = lgr2_meta$SpeciesID,
  color_id = lgr2_meta$TreeID,
  plot_legend = TRUE
)

Support

Documentation is included in the code. If you’re new to burnr, our 2018 paper in Dendrochronologia is a nice survey of the package with many examples. We also have instructional vignettes on the project website, https://ltrr-arizona-edu.github.io/burnr/. And you can work through examples, with included data, in an R project hosted by @chguiterman on GitHub: https://github.com/chguiterman/burnr_demo. We’re working to enhance our instruction and add to these demos on the burnr website, so please send us requests for new tips and tricks, or create your own and share with us!

Citation

Please cite the original burnr paper if you use it in your research:

Malevich, Steven B., Christopher H. Guiterman, and Ellis Q. Margolis (2018) Burnr: Fire History Analysis and Graphics in R. Dendrochronologia 49: 9–15. DOI: 10.1016/j.dendro.2018.02.005.

Citations help us to identify user needs and justify additional time developing and maintaining burnr.

Development

Please file bugs in the bug tracker.

Want to contribute? Great! We’re following Hadley’s packaging workflow and style guide. Fork away.

If you’re not a developer, don’t worry! We also welcome help with documentation and tutorials.

burnr's Issues

Option or default move of y-axis (series) labels to the right side of the plot.

Can we add the option or default move of y-axis (series) labels to the right side of the plot. It would clean things up and make the plots easier to read.

White space is not removed from the edges of series names

As stated. White space is not removed from the edges of series names in read_fhx().

Add option to remove legend in plot function.

Can we add an argument to the FHX plot function to include or remove the legend when plotting.

Warning if duplicates are found when concat'ing fhx objects

It would be nice to print a warning giving the ID of any series when duplicates are found during concatenation.

Developer has been too lazy to write unit tests

Seriously, we need some basic unit testing.

Need a few basic vignettes using our example data.

Style clashes with S3 classes

We need refractoring and renaming of classes, functions and a few variables so that it doesn't class so harsh with our S3 class(es). I am thinking of moving from Google Styles Guide to Hadley Wickhams.

This will likely go down as I move things into package format.

Argument to FHX plot function to buffer rug from main plot.

Add argument to FHX plotting function to "separate" the composite (i.e., the rug plot) from the data in the chart. A horizontal line above the rug would be one way. Maybe just add white space.

read_fhx error when first year is a scar

This is partially a limitation in how FHX data is handled.

If the first year of a series is a scar (and I suspect, same goes for injury), read_fhx has an error.

Ellis Margolis found this bug on 2015-10-29.

In concatenate() (or combine()), try to have it handle multiple files to concatenate.

This is something we lost with when we moved this functionality from the '+' operator.

Users can no longer do a + b + c. It would be nice to be able to do combine(a, b, c).

rug.filter() needs more intuitive name

Users have been using rug.filter() for non-plotting purposes. It would be good to give it another name like make_composite() or composite()

Add "dot" or "bars" to legend in FHX plots.

As stated, can we add "dot" or "bars" to legend in FHX plots.

Need basic utility functions for fhx class

Easy functions so that users can add or delete a single series to an fhx object, for example.

"Fire scar" symbol is weak and not bold relative to other symbols.

The current fire scar symbol (124) is weak. We cannot embolden it even by changing lwd manually through the grid package. Maybe we need to rethink our symbols?

Complete essential work so this can be submitted to CRAN.

Color fire history plots by species?

Is there some way to bring in species data (associated with an ID in an fhx object) then use the species data to color the default fire history plot?

Change `concatenate()` to `combine()`

This would make it more compatible with dplR and shorten the function name.

`order.fhx` should be renamed to `sort.fhx`

The usual behavior of order functions in R does not really describe how this function behaves in burnr. sort.fhx would be a better fit.

User is allowed to plot rugs with facet

This leads to an error (See #21). We need to catch this when the function is called.

Need an example or basic recipe in wiki

Right now, the wiki only has a template recipe. I should add at least one recipe so people have an idea of how it works.

`+.fhx` may not be the appropriate name for this operation

Maybe bind, concatenate, or concat?

Documentation for all functions needs to be cited, fluffed, proof read.

Need data and not files to be packaged

Right now our example data is packaged as an external file. We need this FHX file and it's associated species file need to be loaded when the user runs data().

Also, we need one additional example dataset other than LGR2. Maybe PGM?

Need to register S3 extensions

We get the error:

Found the following apparent S3 methods exported but not registered:
  plot.fhx sort.fhx
See section ‘Registering S3 methods’ in the ‘Writing R Extensions’
manual.

Cannot read Tridas format XML files

We can't read tridas XML format.

I think we're going to wait for triforce to develop and then support the format from there.

This is a feature that may not make the first release.

Can we remove excess white-space in plots when using facet_wrap?

Small-sized facet subplots take up a huge amount of space when plotted with large-sized facet subplots.

I think we can get around this by using facet_grid(), with the space argument, instead of facet_wrap().

ggplots symbols are misordered if fhx instance doesn't have all of "Scar", "Injury", "Pith/Bark" types.

Need to package software

We actually need to package this software with unit tests and everything. Even if we don't put it into CRAN, It will be just like Christmas!

Bad rugs when using plotting facets.

Rugs and facets do not work well together (if at all). I imagine this has to do with how we hacked our way around spacing our rugs with single plots...

Anyways, we also have a problem with needing to define a independent rug for each facet subplot. i.e. facets do not share the same rug.

read_fhx() throws error when given file contains only single series

Removing y-axis labels ditches tick marks in ggplot.fhx

Title says it all.

Compressed FHX objects written to an FHX file do not read back into R with correct series.name.

In the develop branch:

d <- read.fhx("17P.fhx")
d.comp <- compress(d, "PET")
write.fhx(d.comp, "test.fhx")
d.comp2 <- read.fhx("test.fhx")

d.comp2 does not have the correct series name associated with the FHX series, instead we seem to get <NA>s.

Argument to FHX plot function to scale fire event symbols.

Simple enough: add an argument to FHX plot function to scale fire event symbols. Some folk have trouble seeing the marks.

Reading FHX files throws error when user loads reshape package

I'm not actually sure what is going on here.

We get error when:

library(reshape)
library(burnr)

d <- read_fhx('somefile.fhx')

Which gives us the error:

Error in eval(expr, envir, enclos) : object 'rec_type' not found

`resolve_duplicates()` should be `check_duplicates()`

The function resolve_duplicates() should be renamed because the function name does not describe what it actually does.

Levels for ring-type factor are inconsistent style

The levels for ring types include "." which means they look like S3 methods. This needs to be fixed.

Need time series plot showing change in fire scar type through time.

It would be nice to have a plot function that shows the change in fire scar type composition through time. Maybe look into ggplot2's geom_bar()?

Some of our functions should be proper generics.

ggplot.fhx is one example. It's intended to be a method but we need a generic function for the fhx class.

This includes:

• ggplot.fhx
• order.fhx

Add labels of actual years of events to the rug at the bottom of plots.

Can we include some way to annotate or put the actual year of events in the FHX plot's rug? Bonus points if we can do this without overlapping.

Update README to remove warning about breaking backwards compatibility.

I promise to only break backwards compatibility on Major releases.

I promise to only break backwards compatibility on Major releases.

I promise to only break backwards compatibility on Major releases.

I promise to only break backwards compatibility on Major releases.

I promise to only break backwards compatibility on Major releases.

(after version 1.0)

Differentiate FHX plot symbols for fire injuries and fire scars

As above, can we differentiate FHX plot symbols for fire injuries and fire scars?

Concat function for fhx is very very slow.

Concatenating ("+"ing) multiple FHX files is very slow. This is especially a problem when working with many large files. Vectorize it or maybe write it in C?

This might be a good excuse to revisit how we structure FHX data internally.

Functions are crude and need to be broken down

Some of our functions are very crude and need to be broken down.

creation of basic site and tree-level stats functions

`legend` argument in get_ggplot() should be renamed to avoid confusion with actual ggplot2 function

There is "too much ink" on end symbols (i.e. bark/pith)

The solid circle draws the eye. Can we use another symbol that doesn't use as much ink? Maybe an empty circle?

Compressed FHX objects do not plot properly.

Using the develop branch, do the following:

d <- read.fhx("17P.fhx")
d.comp <- compress(d, "PET")
plot(d.comp)

The plot seems to show consecutive overlapping fire events.

sort.fhx() needs a default behavior.

At the moment concatenate()'s use of sort.fhx() creates an error because no decreasing argument is passed in concatenate().

Props to Ellis for finding this.

Make injuries optional in composite.

Some people may not want injuries to be considered when calculating fire event years in composite. Make this optional with a function argument.

User option to adjust horizontal axis (time) scale (e.g., 1400 - 2010).

Add a user option to adjust horizontal axis (time) scale (e.g., 1400 - 2010) in the FHX plotting function.