This page contains the release notes for the latest updates to
respR.
Ever been reading a paper and wanted to compare metabolic rates to
your own results but they were in a different unit? New in this release
is convert_MR(), a function for converting between
different units of oxygen uptake or production rate. These can be
absolute, mass-specific, or area-specific rates. See
help("convert_MR") for examples. It also works on
convert_rate or convert_rate.ft objects so you
can change the output units of a respR analysis without
having to re-run the whole thing.
To help with this new functionality, this version has undergone a
major update around unit handling. In case you didn’t know,
respR accepts different variations in unit formatting. E.g.
"mg per h", "mg H", "mg hr-1",
etc. are all recognised as mgO2/h. There’s been a
substantial internal update to unit recognition to use regex
instead of a brute force approach. This system is more robust and
accepts even more variations in style; units can be formed from
abbreviated versions or words (e.g. mg or
milligram), separated by a space, forward slash, dot, or
underscore, are case-insensitive, and accept other variations (e.g
km2, km -2, km^2,
kmsq, etc). In addition a few new units of dissolved oxygen
(DO) and metabolic rate are now accepted. See below.
A couple of minor but handy changes: salinity, temperature, and
atmospheric pressure are now saved to summary tables in
convert_rate() and convert_rate.ft() outputs
to help with keeping track of results from different experiments; and in
inspect(), inspect.ft(), and
oxy_crit() you can now specify columns by name as
well as column number.
Lastly, a major change is that import_file() has been
deprecated. It is still fully functional, but will not be updated and
will be removed in the next major release version
(i.e. v3.0, although this is not planned for any time
soon). This was only ever intended to be a convenience function for
those completely new to R, and was always experimental as
there is no way we could test against every variation of oxygen sensor
system output files. However, we found some users were overly reliant on
it and on encountering a problem with a file asking us to update the
function rather than try to import it themselves. To our knowledge,
every oxygen sensor system exports data in formats
(e.g. .csv, .txt, .xlsx) which
can be easily imported into R using generic functions such
as read.csv. This is a basic skill anyone using
R should be comfortable with, and also allows for much more
control and the ability to troubleshoot issues.
==================================== New =======================================
convert_MR()- A new function for converting
metabolic rates between different units of oxygen uptake or production.
See examples in help("convert_MR") and here.convert_rate(), convert_rate.ft() -
Salinity (S), temperature (t), and pressure
(P) inputs are now saved as columns in the final
$summary table. These can be entered even if they are not
required for conversions to the output rate unit, which may help with
keeping track of results across different experiments.inspect(), inspect.ft(),
oxy_crit() - Column names can now be used to specify
columns, not just column number. See example here.convert_DO or in
convert_rate as the oxy.unit of the original
data: ul/l, ul/kg, mm3/kg
(equivalent to ul/kg), cm3/kg (equivalent to
ml/kg), ppm (i.e. parts per million,
equivalent to mg/kg). In addition, "cc"
(abbreviation for cubic centimetres, as sometimes used in older
publications) is recognised as cm3 (e.g. cc/L
as DO, cc/h as a metabolic rate).convert_rate or convert_rate.ft as part of the
output unit, or in convert_MR to convert between units of
oxygen uptake: mm3, cm3, ul.
e.g. ul/h or cm3/day/kg, etc.R version 4.3.0
=================================== Changes ====================================
import_file() has been deprecated. It is still
fully functional but will not be updated and will be removed in a future
version. See above.convert_rate if you specify
"MG per h" or "mg h-1" as the output unit this
will appear as "mgO2/hr" in the output object;
"ml min-1 kg-1" becomes "mLO2/min/kg", etc.
This means you can be sure the unit is being recognised correctly even
if your input is formed differently.unit_args() updated for new units.This update focuses on extending to the flowthrough respirometry
workflow the functionality introduced in v2.1 for exploring
and selecting final rates. The online vignette
has been updated with some examples.
==================================== New =======================================
convert_rate.ft - Objects containing multiple
rates can now be plotted in three different ways to help explore the
results and decide how to summarise them. This pairs particularly well
with select_rate.ft for exploring and selecting a final
reportable rate.select_rate.ft - New function for selecting from
amongst multiple rates in convert_rate.ft objects in
flowthrough respirometry analyses. It is actually a simple wrapper for
the select_rate function, so you can use either.select_rate - has the additional methods
rep_omit, rank_omit, and
manual_omit for omitting rates.select_rate - has the additional methods
intercept and slope for selecting based on the
respective summary table columns. This is mostly useful for selecting
from flowthrough rate results where these parameters can indicate the
stability of the delta oxygen region rates are derived from (in other
analyses slope is essentially equivalent to the rate).=================================== Changes ====================================
convert_rate.ft - Output objects have been
restructured and new elements (e.g. $dataframe) brought
forward from the input objects to enable plotting.convert_rate - The y-axis range in the lower
panel of type = "rate" plots now adapts to the range of
rate values plotted if pos has been used. You can use this
to get a better idea of range of rates in a particular region.rate_b1 column (the slope
in the linear regression model used to calculate the rate) has been
renamed to slope_b1.==================================== Fixes =====================================
convert_rate.ft - Now correctly converts rates to
output units using nanomoles (nmol) and picomoles
(pmol) (e.g. pmol/min,
nmol/hr/ug, etc.).This is a huge update that finally introduces what many users have
been asking for - full support for analysing intermittent-flow
respirometry data. This was always possible but required use of more
advanced R methods. Now - no more for
loops!
This version introduces two new functions for easily extracting rates
from every replicate in intermittent-flow data,
calc_rate.int and auto_rate.int.
There is also a major focus on exploring and filtering results to
help with outputting a final reportable rate for an experiment. There is
a large update to convert_rate which adds new visualisation
options, and the new function select_rate which is ideal
for exploring and filtering the results of analyses using almost any
criteria you can think of and outputting a final rate. It works with
both intermittent-flow results and the outputs of other analyses. See
the updated vignettes here
and here
for examples.
================================ Highlights ====================================
calc_rate.int - A new function designed for
intermittent-flow respirometry data. It allows you to manually extract
rates from the same row or time range in every replicate.
auto_rate.int - A new function designed for
intermittent-flow respirometry data. It allows you to automatically
extract the most linear, lowest, and highest rates from every
replicate.
convert_rate objects containing multiple rates can
now be plotted in three different ways to help explore the results and
decide how to summarise them. This pairs particularly well with
select_rate for exploring and selecting a final reportable
rate.
select_rate - This function replaces
subset_rate which was introduced in v2.0, and has been
revised to be much more useful. It was original intended to
explore and subset auto_rate results, but we realised it
was just as useful for exploring, summarising and subsetting other
outputs. Therefore, as of this version it now works on
convert_rate objects, and is intended as the final step in
analysis for selecting a final rate. It can summarise and select rates
based on all sorts of different criteria, for example r-squared ranges,
regions of the data, duration, highest and lowest rates by number or
percentile, and much more. As well as summarising auto_rate
results, it pairs particularly well with the new
calc_rate.int and auto_rate.int functions. For
example, you can now use calc_rate.int to extract a rate
from multiple replicates, then use select_rate to extract,
for instance, the lowest 10th percentile of rates, and pipe the result
to mean() to obtain a final rate. All in only a few lines
of code.
==================================== New =======================================
calc_rate.int - New function for manually
extracting rates from every replicate in intermittent-flow respirometry
data.auto_rate.int - New function for automatically
extracting rates from every replicate in intermittent-flow respirometry
data.convert_rate - Objects containing multiple rates
can now be plotted in three different ways to help explore the
results.select_rate - A general function that works on
convert_rate objects to summarise and filter rates to
arrive at a final rate.nmol) and picomoles (pmol)
can now be used as the oxygen amount in output rates in
convert_rate (e.g. pmol/min,
nmol/hr/ug, etc.). Useful for micro-respirometry. They can
also be used as dissolved oxygen units in convert_DO
(e.g. pmol/L, nmol/kg, etc.).import_file - Support for Pyro Workbench files.
This is experimental as we have only one sample file to test it with.
Please contact
us if you have any issues with these files or can send us sample
files for testing.R version 4.2.0
=================================== Changes ====================================
subset_rate has been renamed to
select_rate and now only works on convert_rate
objects. It no longer plots, but the plotting functionality has been
added to convert_rate and expanded. Since outputs retain
the convert_rate class they can still be plotted. To plot
after a subsetting operation use pipes or call plot on the
resulting object.$rep as the first column. This contains the replicate
number that the rate came from when using calc_rate.int and
auto_rate.int on intermittent-flow data. For other cases it
is filled with NA.adjust_rate and convert_rate now
have the additional element $dataframe in the output. This
is the raw data carried forward from whatever object was initially
entered. It was always present in the $inputs, but is now
also placed at the top level for convenience. If numeric values were
entered it will be present as NULL.auto_rate - For the linear method,
the kernel density analysis results are now not printed to the
console when using summary(). Only the summary table will
be printed, making for a cleaner print out. This can be changed back to
the old behaviour by passing print.kds = TRUE in
summary.plot_ar function for plotting
auto_rate results has been removed, but the plotting
functionality has been added to convert_rate as the
type = "overlap" option. Therefore you will need to convert
auto_rate results before plotting them. (If you really need
to you can actually still plot auto_rate objects by calling
the internal function overlap.p using three colons,
i.e. respR:::overlap.p(object))convert_rate, convert_rate.ft -
The behaviour introduced in v2.0.1 where
summary() would print only a condensed version of the
summary table has been reversed. This is because it made it difficult to
view the results of selection operations in select_rate on
columns not printed to the console. The full table is now printed, even
though it is quite large. You can still use export = TRUE
to export the table as a data frame for easier viewing.subset_data - No longer prints a subset summary
to the console (i.e. quiet = TRUE is the default).select_rate - The "time_omit" and
"row_omit" methods have a progress bar when n
is a vector of three or more values. This is because these methods are
extremely computationally intensive when this is the case and may take
some time. If possible you should always use a time or row range of
lower and upper values instead (e.g. n = c(10, 20) instead
of 10:20).by = "proportion" method has been removed
from calc_rate and subset_data.==================================== Fixes =====================================
subset_data now works correctly when there are
NA in the data. Note however you should always
inspect() your data and remove or replace NAs
to avoid obscure errors or unintended behaviour.adjust_rate - Fix for incorrect messages when a
non-numeric object is entered as the by input.auto_rate - Fix for error message when using
pos in summary.auto_rate, calc_rate - Warns if the
input contains only one row of data.import_file - Fix for incorrect file extension
when export is used.print.auto_rate etc.) should no longer appear in the
function index.Only a month after 2.0.0, this is a quick update that fixes a few
bugs, adds a couple of enhancements, and has quite a large revision to
the newest function subset_rate.
==================================== New =======================================
calc_rate function can now be used to
calculate background rates for use in adjust_rate as the
by adjustment input. In other words, the by
input is no longer limited to using only calc_rate.bg
objects (or numerics). While using a combination of
subset_data and calc_rate.bg is the
recommended way of determining background rates, there are circumstances
when getting a rate via calc_rate might be easier (of
course, these rates could always previously have been entered manually
as a numeric value). See here
for further information about this.convert_rate and convert_rate.ft
summary table elements in the output now contain all rate regression
parameters, data locations, adjustments (if applied), units, and more.
This makes it much easier to save and keep track of all
relevant data regarding rate results. They can be saved by extracting
$summary directly from the output, or using
summary(object, export = TRUE). Note,
summary() only prints a condensed version to the console as
the full table is too large to print.=============================== subset_rate() ==================================
subset_rate can now reorder
auto_rate results in various ways. This can be useful in
several situations. See help docs and vignette on website for more
information and examples."rank" method for subsetting based
on the $rank column of the summary table. The rank always
refers to the original rate ranking or ordering as determined in the
original auto_rate call, which is retained unchanged
regardless of how the results are subsequently subset or reordered."oxygen" method for subsetting
based on oxygen values in the raw data. This can be used to constrain
results to particular oxygen ranges. Conversely, to exclude
particular oxygen values or ranges you can use the
oxygen_omit method. See help("subset_rate")
for specific details."row_omit" and "time_omit"
methods, the n input can now be a numeric vector of any
length. Regressions (i.e. rates) fit across any time or row value in
n will be omitted. A continuous range of rows or time can
still be entered by using regular R syntax for creating vectors such as
n = 10:20 or seq().rate, rsq,
row, time, and density methods
the n input of two values can now be entered in any
order.plot input default has been changed to
FALSE, and the internal plotting for this function has been
revised to be much quicker and show more plots (up to a max of 20 from
9). See help file for more info but briefly, this plotting functionality
is intended to provide a quick view of how many rates remain after
subsetting and where they occur in the data. In many cases it does not
need to be run in every subset_rate call.subset_rate and auto_rate now
behave better with objects which contain zero results, and allow piping
operations to continue even if an empty object is encountered somewhere
in the pipe. This can occur if subsetting criteria excludes every rate.
These auto_rate_subset objects with no results now work
with print, summary, and mean
giving a message that they contain no rates but still printing to the
console. subset_rate will now not stop if an empty
object is input as x or piped from a previous
subset_rate operation. Trying to plot these empty objects
in plot or plot_ar and also will not stop any
pipes, and will result in a console message but no plot.=============================== General Changes ================================
auto_rate output objects have been rearranged
slightly to be more consistent.method = "mean" has not been user-specified,
adjust_rate now issues a message if multiple rates have
been entered in by confirming the mean value will be used
for adjustments.assertthat, ggplot2, cowplot,
broom, and gridExtra are no longer
dependencies.==================================== Fixes =====================================
adjust_rate - Fix for warnings when using
auto_rate objects which have been passed through
subset_rate with paired or dynamic adjustment methods.plot_ar - Fix for incorrect subset number
appearing in plot titles.plot_ar - Fix for the pos and
highlight inputs sometimes failing to produce expected
behaviour.===============================================================================
It’s been a long time - over two and a half years (!) since the last
update. We are happy to see respR being used by the
respirometry community in that time. Amazingly we have picked up over 30
citations, so we are very grateful and happy that so many scientists are
finding the package of use.
We are glad to announce that respR has reached version
2.0 and is finally available on
CRAN.
v2.0 has been a massive and thorough update where almost every corner of the package has been revised, rewritten, streamlined and tested. In addition, we have added a lot of new functionality which you can read about below.
We have also updated and added even more vignettes, function guides and more on our brand new website detailing all the old and new functionality.
Unfortunately, a major version update inevitably comes with some code breaking changes, and this one is no exception. We thought long and hard about introducing changes that might break code written for v1.1, but made the decision to fix as many as possible of the inconsistencies, bugs, and poor design decisions we made while we had the chance with this major version update. The upside of this is that the package will be much easier to update in the future without breaking existing code.
We have created a page on the new website to detail how v2.0 code has changed and how you may go about revising your earlier code to update it. The good news is most of these changes will be very easy to make. If you have submitted code or are in the process of submitting it as part of a publication, we want this code to remain reproducible long into the future. See here for how you can link to resources that will allow anyone to run v1.1 code and keep these analyses reproducible.
We are happy to say the package has never been more stable and even easier to use, and it is now on a great base upon which to build future functionality. Here are the major changes in this version:
================================== HIGHLIGHTS ==================================
respR is now available on CRAN.
It can be installed just like any other package via the RStudio package
manager tab or by running install.packages("respR"). If you
want to be on the bleeding edge, for example test out the latest dev
version, you can use install.github() and the
ref input to select a different branch.subset_rate function. This allows
auto_rate results to be explored and filtered according to
various criteria.plot_ar function. This plots
auto_rate objects in a way that visualises how results are
distributed within the dataset. Pairs very nicely with
subset_rate above.adjust_rate contains several new methods of
adjusting for background respiration, including the ability to perform
adjustments from paired or concurrent blank chambers, and to perform
dynamic adjustments for background rates which change over the course of
an experiment.inspect and inspect.ft performs
additional data checks: that columns contain numeric data and a check
for infinite valuesarea input in convert_rate (accepts
"mm2", "cm2", "m2",
"km2"). You can also use day as the time
metric in output rates (e.g. "mgO2/day/m2")auto_rate "rolling" method. Performs
fixed-width rolling regressions across the entire dataset with no
ordering of results. This pairs nicely with the new
subset_rate function to allows users full control of
selection criteria (albeit with fixed width regressions)auto_rate "highest" and
"lowest" methods for absolute minimum and maximum of rates
regardless of signconvert_DO and convert_rate including percent
oxygen saturation, moles of oxygen, and more.convert_val function. A simple conversion function
to help with inputting experimental parameters in the correct
units.citation("respR") returns the citation to the
respR journal publication, including a BibTeX entry for
LaTeX users or other applications which accept this.R 4.1
and the new native pipes (|>)R
=============================== General Changes ================================
print(),
summary(), plot()) revised to produce cleaner,
consistent outputs.$rank column to all $summary
tables as first column to helps with consistent S3 summary outputs and
generally keeping track of summary rows$dataframe for consistency (was previously
$df, $data, $dataframe,
etc.)df to x where appropriate
(auto_rate, inspect, inspect.ft,
subsample). This was inconsistent and often confusing, in
that df often did not have to be a data frame, but could be
a different class of object.inspect_data and
pcrit have been removed$call element$inputs elementpar() restoration behaviour.======================== Function specific changes =============================
================================== inspect() ===================================
NEW: Checks that each column contains numeric data. This is the most important check, and if any column fails, the function skips the remaining checks for that column and returns a NULL result
NEW: Checks for infinite values (Inf/-Inf) in all
inspected columns
NEW: If uneven time intervals are detected, it now prints the minimum and maximum intervals found in the time data which can help indicate if there is a large gap in the data
NEW: Added a width input to adjust rolling rate plot
(default is 0.1)
NEW: An additional data type (for example temperature, salinity,
etc.) can be plotted alongside the oxygen timeseries by using the
add.data input. This should be a column number from the
same input data frame and share the same time data. Data
checks are not performed on this column (unless all columns are
specifically inspected), it is simply a plotting aid to understand where
the parameter may affect rates in different regions of the data. There
is similar functionality in inspect.ft.
NEW: Can pass rate.rev = FALSE to plot rates
not numerically reversed (for oxygen production
respirometry)
NEW: Can pass legend = FALSE to suppress
legends
NEW: summary() now works on output (although it’s
simply a wrapper for print())
CHANGE: Multiple rate plot improved. Now all plot on same axis range, better colours and spacing.
CHANGE: Prints NA locations for all oxygen columns
they are found in (previously only printed for first column)
CHANGE: If multiple columns are inspected, message that columns 1 and 2 are used by default by subsequent functions, although all are inspected.
CHANGE: Stops if oxygen or time columns
are not present in the input, or conflict with each other
CHANGE: Prints on assigning
CHANGE: Output has additional elements $call,
$inputs and $add.data
CHANGE: Output $list and $list_raw
renamed $locs and $locs_raw
FIX: Rolling rate plot failed with even a single NA
in time or oxygen data.
FIX: Fix for points sometimes being plotted twice slightly offset in large datasets.
FIX: Any time error locations are now printed when
multiple oxygen columns are inspected
================================ calc_rate() ===================================
NEW: Plot updated with title showing the rank of the current plot. It also now plots oxygen and rate against both time and row index
NEW: Now calculates from start of the data if
from = NULL, and to the end of the data if
to = NULL
NEW: S3 Generics: plot() has the additional inputs
panel to plot selected panels individually, and
legend to suppress the legend and other labels.
CHANGE: Detects and warns about multi-column inputs
CHANGE: Output elements have been renamed
CHANGE: Most $summary columns have been renamed and
reordered to be consistent with other functions
CHANGE: Plots full 4 panel plot by default
FIX: by = "proportion" and
by = "oxygen" now work correctly with oxygen
production data. Previously these methods didn’t work with
rising oxygen as the code for finding the
from-to values assumed it was decreasing. Now
it identifies all data within the range of
from-to. Essentially this makes
from-to interchangeable. Note this change
means with some data it may give slightly different results than v1.1
because of the way the from-to region is
identified internally. With most data any difference in rates should be
very minor.
FIX: Fix for failure to plot with very small datasets (2-5 values)
FIX: Fix for failing to work when there were NA in
the time data
================================ auto_rate() ===================================
NEW - "rolling" method. Performs simple rolling
regression of specified width, with no ordering of results.
This pairs nicely with the new subset_rate function to
allows users full control of selection criteria (albeit with fixed width
regressions)
NEW "highest" and "lowest" methods for
absolute minimum and maximum rate values regardless of sign.
These can only be used when rates all have the same sign.
NEW "maximum" and "minimum" methods.
These work the opposite way to "min" and
"max" from v1.1. These are strictly numerical, and order by
value taking account of the sign.
NEW: Added the Kernel Density metric $density to the
$summary table for the "linear" method. This
allows you to see how the results are ranked in regards to KDE (also
present for other methods, but as an NA column).
NEW: Added $oxy and $endoxy to the
$summary table, so you can easily see roughly how much of
an oxygen change each regression is using to calculate a rate. This
matches the summary table in calc_rate and
calc_rate.ft
NEW: Plot updated with title showing the rank of the current plot. It also now plots oxygen and rate against both time and row index.
NEW: Can pass rate.rev = FALSE to plot rates
not numerically reversed (for oxygen production
respirometry)
NEW: S3 Generics: plot() has the additional inputs
panel to plot selected panels individually, and
legend to suppress the legend and other labels.
CHANGE: The "min"and "max" methods have
been deprecated. They still work and produce the same results as in
v1.1, but have a prominent warning. These will be removed entirely in a
later version of respR.
CHANGE: Under the "linear" method, occasionally
linear regions which were identical but had different density scores
were identified. The lower ranked duplicate results are now
removed.
CHANGE: The width input behaviour has changed
slightly. Previously if it was a value between 0 and 1 it represented a
proportional width of the whole dataset regardless of the
by input. This now applies only to by = "row".
If by = "time" any value between 0 and 1 now represents (as
with values above 1) a time window in the units of the time
data.
CHANGE: Reordered inputs to put method
second
CHANGE: Summary table reordered to be consistent with other functions
CHANGE: Tidied and reordered summary S3 printout. Summary table
comes first, density result printed more compactly for
"linear" method
CHANGE: The rolling regression plot (panel 3) is now plotted on the same x-axes of time and row as the full timeseries plot, and has better spacing.
CHANGE: Prints all results of "interval" method
regardless of pos or width inputs
FIX: plot() now works correctly on
auto_rate objects
FIX: Fix for stopping with an obscure message when input datasets are small
FIX: Removed unused method "default"
FIX: Fix for plots failing when the result contained an
NA
FIX: method = "max" was missing
$total_regs element from metadata
FIX: Fixed an issue whereby under by = "time" and
method = "linear" a non-proportional width
(i.e. greater than 1) would get incorrectly passed as a row width rather
than a time width. This was only an issue in data where time and row
spacing were mismatched, for instance where time was in minutes or
hours, or in seconds but not at one second intervals. This would not
have affected returned rate values, but instead led to poor
ranking of the returned rates.
FIX: Fixed an issue where the function would fail when assembling final output
FIX: Fixed an issue where rates would not be returned over regions which contained NA values. The function is now generally much more robust to missing values (though input data should wherever possible not contain NA values).
=============================== adjust_rate() ==================================
NEW: Completely rewritten to allow several new methods, including
dynamic background correction. It has the same original inputs
(x, by) plus five additional ones. The
method defaults to "mean" so previous code
will output the same results as it did in v1.1, but there is a great
deal of new functionality.
CHANGE: In the output, $corrected changed to
$rate.adjusted, and $input.rate changed to
$rate.input
FIX: The adjustment column was missing from
$summary table
FIX: summary() now works correctly on
objects
FIX: print() prints adjustment correctly if
pos > 1
=============================== convert_rate() =================================
NEW: Can now convert to surface area-specific rates via the
area input (accepts "mm2", "cm2",
"m2", "km2")
NEW: Can now import data and output rates using
"day" as the time unit
e.g. "mgO2/day/m2"
NEW: Can now output oxygen used in moles
e.g. "molO2/day/kg"
NEW: Can now accept input oxygen concentration units in moles
e.g. "mol/L", "mol/kg" and percent oxygen
saturation ("%Oxy"). Because of this % air saturation is
now "%Air" and the previous "%" operator for
this has been deprecated.
CHANGE: The o2.unit input has been renamed to
oxy.unit
CHANGE: oxy.unit = NULL and
time.unit = NULL now stop the function instead of applying
a default unit
CHANGE: Now applies a default output.unit for mass-
and area specific rates as well as absolute rates
CHANGE: The output.unit oxygen amount component now
has “O2” appended to ensure it is not confused with the mass-specific
component. For example, "mgO2/h/mg",
"umolO2/day/kg". These variations are also accepted as
inputs.
CHANGE: output elements have been renamed
(e.g. $output to $rate.output,
$absolute to $rate.absolute etc.).
FIX: summary() prints summary table as columns
correctly
================================== oxy_crit() ==================================
NEW: This replaces the calc_pcrit function from
v1.1
NEW: method input. This selects the method to use to
determine the critical oxygen value. At present either
"bsr" for Broken-Stick or "segmented" for the
Segmented method. Previously both were performed.
NEW: thin input. Defaults to 5000. This applies only
to the Broken-Stick regression analysis. If the dataset is longer than
this, this determines the number of rows it is uniformly subsampled to
before running the analysis. The BSR method is quite computationally
intensive, so this speeds it up. In testing, values above this have
little effect on the result, but this may vary with different data. To
prevent any subsampling and use the entire dataset enter this as
NULL.
NEW: S3 Generics: plot() has the additional inputs
legend, quiet, rate.rev and
panel.
NEW: S3 Generics: summary() allows results to be
exported via export = TRUE.
CHANGE: parallel = FALSE is now the default. Use
parallel = TRUE to use parallel processing if your datasets
are particularly large and the function is taking too long to
process.
CHANGE: Uptake rates are now plotted as negative in the rolling
rate plot on a reversed y-axis. Plots look the same, but y-axis values
are now negative. There is a rate.rev input to control
this, for instance if you are using the function with existing positive
rate values.
CHANGE: An increase to the internal thin value (see
above) from 1000 to 5000 may mean results will differ slightly from the
previous version, but should be more accurate.
CHANGE: Output has been completely restructured and elements renamed. Previous code used to extract results will likely now not work.
FIX: Fixed issue which caused a failure if the package wasn’t
loaded but function was called, i.e. using
respR::oxy_crit()
FIX: Fix for plot failure when results were very close together.
================================ import_file() =================================
NEW: Imports European style formatted numeric data which uses commas instead of points for decimals.
NEW: Support for Presens Datamanager files
CHANGE: Importing now generally does not remove any columns (e.g. empty or NA columns). Column naming is now much improved (e.g. unique names, data type linked to channel IDs, etc.).
FIX: Fix for PreSens Oxyvew csv and txt files not being imported as numeric. Now separate parsing for each.
FIX: Fix for MiniDot files not being imported as numeric.
FIX: Fix for Pyro/Firesting numeric columns being imported as character when Firesting software replaces missing data with “—”
================================ format_time() =================================
CHANGE: Numeric time column name changed from
elapsed to time.num
FIX: Fix for not appending new numeric time column onto a
data.table
FIX: Fix for data frame columns being renamed on return
FIX: Fix for not working with multiple date-time columns if one of them wasn’t column 1
FIX: Fix for failing to format date-times which were already in POSIX/POSIX.ct format
================================ convert_val() =================================
convert_DO and convert_rate.
See Examples.=============================== calc_rate.bg() =================================
NEW: The oxygen timeseries is now plotted against both time and row index
NEW: Plots have legend input to suppress equation
text boxes
CHANGE: In the output $bgrate changed to
$rate.bg, and $mean changed to
$rate.bg.mean
CHANGE: Stops if oxygen or time columns
not present in the input, or conflict with each other
CHANGE: Removed “input detected” message at start
================================ convert_DO() ==================================
NEW: Added support for % oxygen saturation ("%O2")
units. % air saturation is now "%Air" and the previous
"%" operator for this has been deprecated
NEW: Added support for oxygen concentration units of
mol/L and mol/kg
NEW: Added support for oxygen concentration units of
cm3/L. This is a scarce unit, only used in older
publications and is equivalent to ml/L.
NEW: Added simplify input. The default is
simplify = TRUE and means the converted values are output
as a numeric vector, rather than within a list object. If
FALSE the output is a list object of class
convert_DO which works with print(),
summary(), and mean()
CHANGE: Removed ability to accept objects of class
calc_rate, auto_rate or
adjust_rate. This didn’t make any sense in this function as
rates are not a DO measure!
CHANGE: Added warning for P atmospheric pressure
values being outside a realistic range.
FIX: Fix for error with non-numeric x
inputs
================================ unit_args() ===================================
================================= subsample() ==================================
length.out input which uniformly subsamples
to an exact number of rows (data frames) or length (vectors)=============================== subset_data() ==================================
NEW: Support for inspect.ft objects
NEW: Added quiet input to allow console output to be
suppressed
NEW: Now subsets from start of the data if
from = NULL, and to the end of the data if
to = NULL
CHANGE: Updated help documentation, particularly to specify that
by = "oxygen" or by = "proportion" applies to
first column only in multi-column dataframes
CHANGE: Warns if output subset is empty
FIX: Fix for failure with inspect() objects
FIX: by = "proportion" and
by = "oxygen" now work correctly with oxygen production
data. Note this now generally results in longer subsets than v1.1 code
because of a change in identifying where to is within the
data.
============================== flowthrough data ================================
NEW: inspect.ft
NEW: calc_rate.ft
NEW: adjust_rate.ft
NEW: convert_rate.ft
This is a completely new workflow specific to flowthough respirometry data. See help documentation and vignettes for full details.
==================================== data ======================================
data.table
flowthrough.rd amended to make delta column
(i.e. unitless rates) negative values to be consistent with how uptake
rates are always negative in the packageflowthrough.rd column names changed to
time, oxy.out, oxy.in and
oxy.delta
zeb_intermittent.rd column names changed to
Time and Oxygen
sardine.rd has had a Temperature
column added (to demonstrate the new inspect()
functionality to plot an additional data type)NEW: New example datasets
algae.rd: oxygen production dataflowthrough_mult.rd: multiple column flowthrough
dataflowthrough_sim.rd: flowthrough data with increasing
background recordingbackground_con.rd: constant level background, for
testing new background correction functionalitybackground_lin.rd: linear increasing background, for
testing new background correction functionalitybackground_exp.rd: exponential increasing background,
for testing new background correction functionality================================= S3 Methods ===================================
mean.adjust_rate
mean.adjust_rate.ft
mean.auto_rate
mean.calc_rate
mean.calc_rate.bg
mean.calc_rate.ft
mean.convert_rate
mean.convert_rate.ft
NEW: These are new generic S3 functions for calculating mean
rates, and work on the relevant function output rate. None alter the
output object, but have an export input so the mean values
can be exported as a numeric value if export = TRUE. They
also have a pos input (where relevant) to select a range of
rates to average. Most useful is mean.convert_rate which
can be used to output a final mean rate at the end of an
analysis.
mean.convert_DO
NEW: This works as the above but averages converted oxygen values
from convert_DO. The output must have been saved as a
convert_DO object for this to work by using
simplify = FALSE (otherwise convert_DO by
default outputs a numeric vector upon which mean() works
anyway and gives the same result).
NEW: All plot() S3 have a quiet input
to suppress console output
NEW: All summary() S3 (where appropriate) have
export = TRUE for export of summary table or value
NEW: All S3 (where appropriate) have pos input to
select positions or ranks of results to plot, print or average, and stop
with an error if pos is too high
NEW: Plotting functions accept the generic par()
inputs oma, mai, tck,
mgp, las, and pch via
... to allow default parameters to be changed. Particularly
useful are las = 1 to make axis labels horizontal and
adjusting the second (left side) of the four mai (inner
margins) input to make y-axis labels more readable.
CHANGE: Consistently named inputs (for summary() the
first input should be object, but in all others it is
x)
CHANGE: All console output prints more consistently with nicer spacing, especially in pipes
FIX: In auto_rate S3 methods stop with a message if
no rates found in object (this can happen with over-enthusiastic
subsetting in the new subset_rate function)
FIX: All revised to work correctly with |> or
%>% pipes
This is the final release of v1 of respR.
There is only one change, the addition of function called
installation_help. This function simply opens its own help
file. It contains resources which may be helpful in running v1 code in
the future, such as a list of dependencies and the latest versions known
to work with v1.1.1, and how to install them. This is intended for users
who have recently submitted v1.1 code as part of a publication, and
investigators who may wish to reproduce their analyses in the
future.
The reason this may be necessary is because version 2.0 of
respR will be released shortly and contains several
code-breaking changes which means code written using v1.x will fail to
run or return the same results. Using the information in this file an
investigator should be able to install respR v1.1.1 and its
dependencies and reproduce these analyses.
Lots of updates! First, we have a new function,
calc_pcrit(), which we will use to include new methods in
the future. We’ve also made some improvements to
import_file() with increased support to more files from
Vernier, PRESENS and Loligo systems.
Vignettes have been migrated into a new repository on GitHub, and are now updated separately. This gives us several advantages – the documentation can be updated without needing to compile a new package, and the size of the package is significantly reduced. Users can also contribute to the documentation more easily now that it is not tied to the package.
respR by
running citation("respR").respR will print a startup message
containing links to our published manuscript and vignettes.inspect() can now plot data with multiple columns
when more than 2 columns are detected. For some people, this may provide
a great overview of the data.calc_pcrit() is a new function
that will be developed in parallel to the current pcrit()
function. In the future we intend to use calc_pcrit() to
incorporate new methods.import_file() supports even more files! Added more
parsers for Vernier, PRESENS and Loligo systems.format_time() can now calculate time elapsed even
if date information is not provided (e.g. “HMS”-only data).by input in auto_rate(),
calc_rate(), calc_rate.bg() and
subset_data() is now more forgiving with string input
values (e.g. "oxygen", "Oxygen",
"o2", "O2", etc. are recognised). To achieve
this we created a string matching function, by.val() which
uses brute force matching to recognise different ways of writing the
same text.convert_DO():
"P" (pressure) was ignored even when
a value was already specified, resulting in the default used. The
function will now respect the "P" value provided.inspect():
convert_rate():
"mass" input is provided but
"output.unit" is not a mass-specific unit.calc_rate.bg.output.unit in the code.calc_rate.ft():
"time" input has been removed
as it was not used.inspect.pcrit():
inspect and
inspect_data. Please note that the
inspect_data() function is deprecated and will be removed
in the near future.This is a quick fix for images not showing in the online vignettes.
This version is aimed at improving the functionality and usability of
our conversion functions. We have decided to remove the default values
for temperature and salinity inputs in convert_DO() and
convert_rate() (i.e. switched t and
S numerics to NULL). This was no easy
decision, but we noticed that some users were running the functions by
default without considering (or even knowing the existence of) these two
important input variables. With this change, existing
workflows using calc_DO() and calc_rate()are
likely to break. Do note that this is a very rare modification
– we know that changing core functionality that breaks prior code is not
something to be taken lightly. Please update these two functions
respectively.
convert_DO() and convert_rate()
now require the user to explicitly provide t (temperature)
and S (salinity) values.convert_DO() and convert_rate()
will warn the user when the default P value is used for O2
units that are strongly influenced by atmospheric pressure.unit_args() has been updated to indicate which
O2 units need inputs of t, S and
P.inspect() has a better-looking plot for rolling
regressions.This version updates the new functions from 1.0.0 and tries to improve piping workflows.
import_data() was not importing firesting files
properly.subset_data() - objects produced by this
function can now be immediately passed on to other functions.
subset_data() is a lesser known function but it’s very
useful, e.g. for truncating intermittent data before analyses. It’s been
updated work well with other functions, and can also be piped.import_data() - works with a lot more files.
Now supports: Firesting Logger | Pyro Oxygen Logger (also Firesting) |
PRESENS OXY10 | PRESENS (generic) | MiniDOT | Loligo Witrox Logger |
Loligo AutoResp (software output). Get more files to us, people!auto_rate().The big update! Maybe it’s time to submit to CRAN?
dplyr and magrittr
are now imported into respR.import_file(): automatically import and format raw
files from common devices. This function is not complete but needs to be
put out there for user feedback. It’s stable, just doesn’t support all
available machines yet. We expect this function to be improved
dramatically once users send in feedback and sample files.dplyr pipes now work after print()
and summary() commands. Will add support for
plot() depending on feedback.adjust_rate(): minor print issue (new line
required) that was messing with the console output.adjust_rate() documentation has been
updated.calc_rate.bg() did not subset data properly in
certain usage scenarios (see #49)We are getting close to a 0.1 release, which will be ready for CRAN.
format_time(), which fixes some
errors with zeroing in some numeric data.format_time(). This function is
a wrapper for lubridate functions and is used specifically
to convert date-time to numeric time.inspect() that contains
much cleaner code. The old function inspect_data() was
tough to fix. It will be deprecated in a future update, but will still
be supported for at least 18 months after we announce the deprecation.
For now, users need not worry about using either function.calc_rate(), calc_rate.bg(),
calc_rate.ft(), and auto_rate() are updated to
work with inspect(). (TODO: calc_rate.ft()
still needs to be fixed.)auto_rate() is now available.auto_rate()’s
linear detection method is now available.sim_data(): simulate data for benchmark
analyses.test_lin(): perform benchmark analyses specific
for auto_rate()’s linear detection
(i.e. methods = "linear").auto_rate() fixed (it
was messing with print() commands).convert_rate() fails when output contains
“mmol”. Fixed.pcrit() example on
website.subset_data() now contains examples.inspect_data() plot output was plotting only
columns 1 and 2 by default, even when other columns are selected in
inputs.convert_rate() was not accepting objects of class
calc_rate.ft.