photobiology 0.7.1 (and 0.7.0)

This release adds lots of new functionality: classes and corresponding methods for collections of spectral objects are now implemented and tested. Not all methods, and no operators are yet implemented for the new classes.  The new classes for collections of multiple spectra are named after the single spectrum ones, but replacing the _spct ending by _mspct. For example collections of source_spct can be stored in objects of class source_mspct. There are too many new features to list them here, but they are documented in the NEWS file and in the User Guide.

The idea for these new classes for collections of spectra came from a question from Susan Holmes after my talk at the UseR!2015 conference in Aalborg. She asked whether my packages could handle hyperspectral image data. I answered that they could not, but that this feature could be easily implemented. This looked like an interesting challenge so I worked on it during the past two weeks. As with the rest of the package, I used for the new functionality a design that avoids as much as possible making assumptions about the data and allows easily extensibility. I hope these additions make the package useful to those working with time series of spectra and/or spectral image data.

This release also includes a few bug fixes and additions to the old methods and classes for individual spectra.

The ratio functions ratio, q_ratio, e_ratio, qe_ratioand eq_ratio where changed into methods of the spectral classes, and wb.trim was added as a formal parameter to them.

Formal parameter pc.out was removed from all methods and functions that had it as it is easy enough to multiply the returned value by 100 to obtain results expressed as percentages.

Attribute "spct.version" was added to objects of all spectral classes, and the new function getSpctVersion() can be used to retrieve its value. Similarly, objects of the new classes for collections of spectra have an attribute "mspct.version" and a function getMspctVersion() can be used to retrieve its value.

New function normalized_diff_ind() usable for calculation of indexes similar to NDVI (normalized difference vegetaion index) for reflectance and any other spectral summary quantity and two waveband objects was added. This addition was inspired by a poster at the UseR!2015 conference in Aalborg describing package hsdar (available through CRAN) that provides functions for analysis of hyperspectral images. In contrast to our package, in hsdar the index definitions are hard-coded into the package functions. On the other hand, hsdar has a lot of functionality specific to the analysis of hyperspectral data that is missing from our own packages.

Method upgrade() was changed into upgrade_spct() function to avoid name conflicts, and updated to add the attribute 'spct.version' attribute when missing. This function is a stop gap solution as the objects’ meta data stored in attributes has slightly changed from that used in earlier versions of the package. The lack of these data can affect printing of returned values for summaries as well as automatic annotations in plots.

The User Guide was expanded to reflect most of these changes and chapters and sections reorganized into a more logic structure.

BACKWARDS COMPATIBILITY: These changes are not 100% backwards compatible, but should be of little consequence to most users, as the changes affect functions and methods that are mostly used internally by the package itself.

NOTE: Sources, and Windows binaries for R 3.1.x and R 3.2.x, are now available in the repository.

Major update

All packages in the suite have been updated.
This update includes several changes which are not backwards compatible:

  1. S3 classes and methods, and several other functions have been renamed. Dots have been replaced by underscores.
  2. Rescale() has been renamed to fscale().
  3. All dummy packages which have been maintained for backwards compatibility have been removed: photobiologyCry, photobiologyPhy, photobiologyUV, and photobiologyVIS are no longer available and photobiologyPlants and photobiologyWavebands should be used instead.
  4. The code has been fixed so eliminate most warnings during checking.
  5. A new vignette Upgrade Guide has been added to package photobiology.

Being such a major update all version numbers have been increased in the second digit. Current versions are:
photobiology 0.6.1, and version 0.3.0 for all the remaining packages.

Package photobiologyInOut also was modified in several respects, but still cannot be considered stable. The other packages, will not suffer major changes for the first public release of the suite.

NOTE: Please, do upgrade only at a time when you have enough time to upgrade old scripts and old data objects, and solve possible problems!

NOTE: Sources, and Windows binaries for R 3.1.x, and R 3.2.x are now available in the repository.

At the moment the repository at https://www.r4photobiology.info/R is responding very slowly, the mirror at http://www.mv.helsinki.fi/aphalo/R is faster.


photobiology 0.5.13

New function smooth_spct() for spectra added. Based on the smoothing code in package MayaCalc and optionally behaving as a wrapper to other smoothers available in R. Implemented for source.spct, filter.spct, reflector.spct and response.spct objects. Its interface may change. Now package caTools is neded.

Operations between .spct objects and numeric vectors, possibly of length one, now preserve other variables (e.g. ID factors) contained in the spectral objects.

Fixed bug in reflectance() function.

Backwards compatible.

photobiology 0.5.12

Bad input error reporting improved for off-range Tfr and Rfr values in check(). Warning given by T2A() when Tfr = 0 result in A = Inf. Added na.rm = TRUE when min() and max() are called on spectral data within the package code.

The formal arguments added to function rbindspct() in version 0.5.7 have been changed to more closely follow the development version 1.9.5 of package data.table. This will break user code that uses the previous syntax as added a few weeks ago to this package.

Fixed bug in handling of 'quantity' arguments "contribution.pc" and "relative.pc" in function absorbance() which was affecting plot annotations.

Mostly backwards compatible, but new checks for validity of data be triggered by code and data that earlier silently accepted bad and dubious quality data.

photobiologyWavebands 0.2.6

Added luminous efficiency functions for human vision, and the constants used in the definition of Lumen.

Setlow’s BSWF is now stored as a response.spct object using the same variable names as in the rest of the suite. The Setlow data from TUV has already been converted to energy units, but this was not noticed when this data was added to the package. This bug is now corrected.

Updated User Guide with some examples of the calculation of luminous flux in lux from spectral irradiance data.

Added plots of the luminous efficiency curves to the Data Plots vignette.

Backwards compatible.

NOTE: Sources, and Windows binaries for R 3.1.x, are now available in the repository.

A summary of new functionality and other changes

1) More consistent naming of function parameters. Spectral object parameters are always called spct. Waveband and lists of wavebands parameters are called w.band. Parameters that take arguments that have a range function available are now more consistently named range. However, many generic functions, and specializations of generic functions, which because of being generic already have, or could have in the future specializations to other objects, use the name x for object of their own class. In addition, parameter unit, using only in some functions has been renamed to unit.out so that naming is now consistent. In the case of wavebands, at least for this version, the old names are also accepted but the use of the old names is deprecated, as they will be removed before the wider release of the packages.

2) In this version, everywhere were a list of wavebands is expected as input, a single waveband object by itself will also work without errors.

3) All summary functions of the irrad, response, transmittance, absorbance and reflectance now work consistently. Some of these functions are new to this version. They all consistently also accept lists of wavebands, and in cases when BSWFs shouldn’t be applied, only the range of wavelengths is used with a warning. All functions now handle more elegantly wavebands that extend outside the spectral data wavelength range, and by default NO LONGER return values unless there is spectral data available for the whole extent of the waveband. A new optional argument wb.trim can be used to change this behaviour, by trimming the portion of the waveband that falls outside the data, and labelling the resulting waveband so that the trimming is visible in the output. The functions have also acquired new parameters, but the defaults preserve earlier behaviour. A parameter common to all these functions is quantity which at the moment can take one of six possible values: "average", "total", "contribution", "contribution.pc", "relative", and "relative.pc". Contribution returns the waveband totals divided by the total for whole spectrum, while relative returns the total for each waveband divided by the sum of the waveband totals. When .pc is added percentages are returned, instead of fractions for these last to types of values. Total is just the integrated value over wavelengths for each waveband, while average, are these same values, each one, divided by the wavelength spread of the corresponding waveband (in the same units as the original spectrum).

4) A new function was added, called trim_waveband, which does the work of filtering out by default, all those wavebands in a list of wavebands which do not completely fall within the range of the spectral data. However, the optional argument trim can be used to change this behaviour so that those wavebands which are partly within the spectral data range and partly outside it, are replaced by new wavebands from which the portion outside the data range has been removed or trimmed. This function is used by the package code itself, but may be also useful to users.

5) The operators’ code was fully rewritten to remove repeated code, and to improve functionality. The earlier requirement of starting an expression with spectral object is removed. Now spectrum objects can appear almost any position in statements. The allowed combinations of spectra of different types that can be mixed is now somehow more restricted, and the code tries better guess what makes sense from the point of view of light physics and what not.

6) Although very handy, operators have the problem that they cannot take additional arguments. As earlier defined operators would result always in calculations done using and values returned in energy-based units for light sources or transmittance for filters. This remains the default behaviour, but it is possible through global R options to alter the defaults. These options also affect the default for function irrad which earlier required the unit.out argument to be supplied. (The options only change the defaults, and the new default can be over-ridden as usual with optional arguments in the functions.

7) The earlier behaviour, of printing by default spectral objects returned by functions is restored, as this is the natural and expected R behaviour, but how to obtain a more brief output is now documented. This behaviour was changed in the previous version and caused confusion.

8) Most of the changes described above also apply to the plot functions. New plot function specializations were added, so that now all types of spectral objects can be plotted consistently. All the functions support the functionality described in 3) with respect to choosing the values displayed in the waveband labels, and with respect to trimming of wavebands. All the possible quantity values and time unit attributes are used to decide the correct labels and units automatically. (This of course requires that the expected units are used when creating spectral objects.) The options described in 6) also affect the default behaviour of the plot functions.

9) In process of this overhaul, I found some bugs present already in earlier versions, which are now hopefully fixed.

10) A few less important additions are described in the NEWS files of the last version, plus the NEWS files of intermediate versions that were never released.