Skip to contents

Changelog

Source: NEWS.md

gsm.bio v0.2.0 (Upcoming)

See it move: the annotated v0.2.0 demo has captures and try-it steps for everything below.

gsm.bio v0.2.0 draws the rest of bio.viz’s charts from R and adds output from R. Two new widgets, the cross-tabulation and the stratified survival chart, carry R’s tests in the page, and the biomarker screen adds hazard ratios. Every chart can now be drawn without a browser as well: a static figure, its statistics as a table and in RTF, and a whole list of the specifications bio.viz’s charts write, run in one call. Each output prints the same Analyze_*() answers its chart does.

What’s new

  • Cross-tabulation widget. Widget_CrossTab(): a two-way table of counts of two columns or cut biomarkers, with R’s chi-square and Fisher’s exact test stored in the page, and each cell’s participants a click away. obot.roadmap#359, #18, #31
  • Stratified survival widget. Widget_StratifiedSurvival(): Kaplan-Meier curves by a column or a cut biomarker on one endpoint of an outcomes table, with the number at risk, and R’s log-rank test, medians and hazard ratio stored in the page. The outcomes table is read as ADaM holds time to event, censored or event flag either way round. obot.roadmap#360, #35, #36
  • Hazard ratios in the biomarker screen. Given an outcomes table, Widget_BiomarkerScreen() offers a hazard ratio of high against low on an endpoint, each biomarker cut at its median, and every row opens its survival curves with R’s test stored too. The outcomes table is a new argument, dfOutcomes, after lSettings, so a call written for v0.1.0 works as it did. obot.roadmap#360, #35, #36
  • Static figures. Six Visualize_*() functions, one per chart, return a ggplot2 figure of the view its chart opens on, from the same settings, with the same Analyze_*() statistics printed under it. Titles, subtitles and footnotes take the chart’s placeholders, and the figure writes its own footnote last, with R’s method and counts. The survival figure draws R’s own survfit() curves with their bands. ggplot2 is suggested, not imported. The gallery shows each figure beside its widget. obot.roadmap#362, #37, #40
  • Statistics tables and RTF. Six Table_*() functions, one per chart, return the statistics of the view the chart opens on as a data frame, one row per statistic. Each row has its method, estimate and interval, counts, the p-value by the display rules (exploratory, adjustment named, no stars) and R’s reason where it was not computed. The numbers come from the same Analyze_*() calls the charts make. Write_RTF() writes a table, with its title and footnotes, to RTF through r2rtf, which is suggested, not imported. obot.roadmap#362, #38, #41
  • Batch runs of chart specifications. Run_Specifications() reads the specifications bio.viz’s charts write and draws each against a dataset, as a figure (PNG, PDF or SVG) and an RTF table, into a folder, with a manifest of what was written. One specification can run across every biomarker, one figure and one table each. A specification is data and nothing in it is evaluated; one that cannot be read is refused with bio.viz’s sentence, and the rest still run. The manifest counts the participants each view’s filters keep and says what the tables could not honour, as bio.viz’s notices do. obot.roadmap#362, #39, #42

Also in this release

  • A biomarker cut into groups. A cut variable, list(measure, visit, cut) or list(col, type = "number", cut), makes groups at the median, the tertiles, the quartiles or typed points, by the same rule as bio.viz: quantile() with its default, and cut() with a value on a point in the lower group. Widget_GroupComparison() takes one as its groups or its panels, and hands R the groups low to high. obot.roadmap#359, #18, #31
  • Titles and footnotes on the widgets. Every widget takes bio.viz’s title, subtitle and footnotes settings, with the chart’s placeholders. The chart’s own footnote names the R and gsm.bio versions that computed the results stored with the page, which the widget now hands it. obot.roadmap#362, #37, #40
  • A filter set to no value lets nobody through, as the chart opens it. In R, a filter of several values whose start is an empty list used to let everyone through. It now keeps no one, and each figure and table says no participant passes the filters. #39, #42
  • A column’s categories in the chart’s order. The cross-tabulation’s categories and the survival chart’s groups of a column are handed to R as the chart draws them: by name with numbers as numbers, so “2 mg” comes before “10 mg” and “a” before “B”. The chart finds its stored results for such columns again. A cut’s order is unchanged. #44, #45
  • An infinite odds ratio is kept. A stored result now writes R’s Inf, -Inf and NaN as text, which bio.viz reads back as the numbers. Before, the page had null, so Fisher’s odds ratio of a table with an empty cell disappeared. The cross-tabulation’s figure now prints each estimate with its interval, as the chart’s line does. The figure and the table name Fisher’s odds ratio by its rows and columns, for example “odds ratio (A / B, odds of x against y)”, and print an infinite one in words: “infinite, 95% confidence interval 14.86 to infinity”. #44, #45
  • Pages carry text as UTF-8 in any locale. A widget made in an R session whose locale is not UTF-8 (Rscript started with no LANG) wrote text that is not ASCII, such as a category “Ödem”, into its page as escapes. The chart showed “<96>dem”, and a view keyed by it said statistics are unavailable. Every widget now marks its tables’, settings’ and results’ text as UTF-8 before it computes or writes anything. #22, #34
  • The widgets carry bio.viz v0.2.0, copied from bio.viz dev at its v0.2.0 release preparation, with the specification schema the batch runner reads. safety.viz stays at v1.9.0. #44, #45

Tests and provenance

300 tests (34,586 expectations on R 4.3.3) pass from the source tree, where none may skip; R CMD check runs them too, skipping the ten that read the repository’s own files. Every statistic a widget stores, a figure prints or a table holds is held to the Analyze_*() function on rows the test works out from the study’s tables. Each figure is also held to a snapshot of the data and labels it draws, which are the same on every platform. The batch runner’s reader is held to bio.viz’s own reader, run in node on the same specifications: the format’s rules case by case, and every setting of every chart given each of 21 values (4,578 specifications). The rules R shares with the charts are held to frames, requests and filter states written by the vendored bundles: bio.viz dev at 35ccfd3, and through it safety.viz dev at 096cc26.

gsm.bio v0.1.0

See it move: the annotated v0.1.0 demo has captures and try-it steps for everything below.

gsm.bio is the R behind the bio.viz biomarker charts: seven statistics functions, each a thin wrapper around the stats or survival function that computes it (only the standardised difference is the package’s own), and four widgets that draw a bio.viz chart from R with those statistics stored in the page. A widget saved as one file opens anywhere, offline, and shows only R’s numbers; a view it holds no numbers for says so.

What’s new

Also in this release

  • One statistics file. The functions are defined once, in inst/statistics/statistics.R, which needs only stats and survival, so the browser and the desk run the same lines. #3, #7
  • Every result has one shape, with a reason in place of numbers and R’s own warnings, never an error. StatisticsResult(), #3, #7
  • Data a statistic does not allow gets a reason, not a number. Values that do not vary, ranks all tied, no event in any group, or a smooth on fewer than seven pairs answers with a reason, never “ok” with a number that means nothing. A hazard ratio whose Cox interval is not finite, as when one of two groups has no events, is reported as not estimable, and the log-rank test is kept. #24, #26
  • A result is the running R’s answer: R 4.3 and R 4.6 can word a warning, or compute a p-value, differently. #4, #8
  • The widgets need, and carry, safety.viz v1.9.0 and bio.viz v0.1.0. safety.viz v1.9.0 is the first with the kit bio.viz’s charts are built from; each widget carries the copy bio.viz takes from safety.viz dev at its v1.9.0 release preparation, labelled 1.9.0 and not as an earlier release, so a page that also holds a gsm.safety widget loads one safety.viz, the newer, as htmlwidgets keeps the highest version of a dependency. Both commits are recorded. Filters follow safety.viz’s rule: a start the data lacks opens on All, and all = FALSE opens on the first value. The reader’s browser may order accented letters and punctuation differently from R, so the widget names R’s first value to the chart as the filter’s start. #19, #20, #27, #28
  • Checks and a reference site. R CMD check on every pull request, the suite rerun from the source tree, and the reference site deployed from dev. #1, #5, #6

Tests and provenance

181 tests (28,853 expectations on R 4.3.3) pass from the source tree, where none may skip; R CMD check runs them too, skipping the nine that read the repository’s own files. The group, correlation, matrix, fitted-line and screen statistics the charts print are held to desktop R’s answers that bio.viz recorded on the same rows. Survival, contingency and the screen’s hazard ratio are held to survdiff(), coxph(), chisq.test() and fisher.test() called directly. Every widget’s stored results are held to the R functions, member by member. The rules R shares with the charts are held to frames, requests and filter states written by the vendored bundles: bio.viz dev at 29ac722, and through it safety.viz dev at a57dbb2.