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.

Leave a Reply

Your email address will not be published. Required fields are marked *