Skip to content

gsm.bio v0.2.0

Choose a tag to compare

@obotclaw obotclaw released this 05 Oct 03:04
c75934f

gsm.bio v0.2.0

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 has one row per participant and endpoint, with the time to the event and a flag. The flag can say the time was censored (1 = censored, as ADaM's CNSR) or that the event happened (1 = event). 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, the last one, so every v0.1.0 call, by position or by name, works as it did. obot.roadmap#360, #35, #36, #48
  • 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. The cross-tabulation runs a cut's groups low to high too. The survival chart hands them to R high to low, so its hazard ratio is the higher group's over the lower's. 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. For a two-by-two table with an empty cell they print, as the chart does: "odds ratio (A / B, odds of x against y): 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, with the specification schema the batch runner reads. They are copied from bio.viz dev at 35ccfd3, byte for byte the same as bio.viz's v0.2.0 tag (4440a43), and the copy's records name both. safety.viz stays at v1.9.0. #44, #45, #48

Tests and provenance

305 tests (34,632 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.