Package 'retroglyph'

Description

Create a 'retroglyph' agent object.

Usage

retro_agent(chat, state = new.env(parent = emptyenv()))

Arguments

Value

A 'retro_agent' 'R6' object.

Examples

if (nzchar(Sys.getenv("ANTHROPIC_API_KEY"))) {
    chat <- ellmer::chat_anthropic()
    agent <- retro_agent(chat)
    agent$chat$chat("ping")
  }

Description

R6 class for a 'retroglyph' agent with an 'ellmer' chat and associated state.

Public fields

Methods

Public methods

• retro_agent$new()

• retro_agent$register()

• retro_agent$reconstruct()

• retro_agent$legend()

• retro_agent$risk_table()

• retro_agent$events_table()

• retro_agent$data()

• retro_agent$hazard_ratios()

• retro_agent$quantiles()

• retro_agent$probabilities()

• retro_agent$counts()

• retro_agent$compare()

• retro_agent$export()

• retro_agent$clone()

retro_agent$new()

Create a new 'retro_agent' object.

Usage

retro_agent$new(chat, state)

Arguments

retro_agent$register()

Register a source image for reconstruction: normalize it to an opaque PNG, store it in 'state$image_source', and optionally clear the chat's turn history. This is the half of reconstruction that needs no model call, so a Shiny app can call it as soon as the user uploads a file - before the chat loop (driven by ‘shinychat'’s or ‘ellmer'’s own round trip to the model, triggered separately by the user typing into the chat) ever starts. [retro_agent_class] $reconstruct() calls this method itself, so most callers never need to call it directly. Resets 'state$image_quantized' and 'state$data_label' to 'NULL' so the four-tool workflow (quantize → label → distill → data) starts fresh.

Usage

retro_agent$register(file, clear = TRUE)

Arguments

Returns

'NULL', invisibly.

retro_agent$reconstruct()

Run the full reconstruction workflow on a source image: register the file (see [retro_agent_class]$register()), then chat with the model to view the image, label the numbers, distill the image down to its curves, and read the data off them.

Usage

retro_agent$reconstruct(file, prompt = "", clear = TRUE, timeout = 600)

Arguments

Returns

'NULL', invisibly.

retro_agent$legend()

Access the color/series legend produced by the distill tool.

Usage

retro_agent$legend(friendly = TRUE)

Arguments

Returns

A tibble with columns 'series', 'color', and 'reference' (from 'state$data_legend'), or 'NULL' if the distill tool has not run yet.

retro_agent$risk_table()

Access the risk table read by the data tool, in one of three layouts.

Usage

retro_agent$risk_table(mode = "transposed")

Arguments

Returns

A tibble in the layout named by 'mode' (see [retro_table_wide()] and [retro_table_transpose()] for the '"wide"' and '"transposed"' shapes), or 'NULL' if the data tool has not run yet.

retro_agent$events_table()

Access the per-arm total events counts read by the data tool. Optional throughout: unlike the risk table, total events is not required, and coverage may be partial, so a 'NULL' return does not mean the data tool failed to run. Worth reviewing when it is present - the model reads the number off the source image (or takes it from your own prompt), and it changes the reconstruction by sharpening the estimated censoring in each arm's final interval.

Usage

retro_agent$events_table()

Returns

A tibble with columns 'series' and 'events', at most one row per series (from 'state$data_events', the return value of [retro_data_events()]), or 'NULL' if the data tool has not run yet or no arm reported a total.

retro_agent$data()

Access the reconstructed survival data. This is an interpreted survival reconstruction: individual patient time-to-event and censoring status, inferred from the digitized, scaled curve data produced internally by the data tool together with the risk table counts via the Guyot et al. (2012) algorithm (see [retro_data_survival()]).

Usage

retro_agent$data()

Returns

A tibble with columns 'series', 'time', and 'status' (from 'state$data_survival', the return value of [retro_data_survival()]), or 'NULL' if the data tool has not run yet.

retro_agent$hazard_ratios()

Fit a proportional hazards model to the reconstructed individual patient survival data ([retro_agent_class]$data()) and report the hazard ratio of every other series relative to a chosen reference series (see [retro_survival_hazard_ratios()]).

Usage

retro_agent$hazard_ratios(
  reference = {
     leg <- self$legend(friendly = FALSE)
     leg$series[leg$reference]

    },
  confidence = 0.95
)

Arguments

Returns

A tibble with columns 'series', 'estimate', 'lower', 'upper', and 'p_value' (see [retro_survival_hazard_ratios()]), one row per series other than 'reference'.

retro_agent$quantiles()

Compute Kaplan-Meier survival quantiles (e.g. median survival) for each series in the reconstructed individual patient survival data ([retro_agent_class]$data()), at the probabilities requested. The digitized, scaled curve data produced internally by the data tool is deliberately never used for this, even as a fallback: it makes no statistical claims, and reconstruction does not record whether its y-axis was survival or cumulative incidence, so a quantile read off it would not be statistically defensible.

Usage

retro_agent$quantiles(
  probabilities = c(0.25, 0.5, 0.75),
  type = c("survival", "incidence"),
  confidence = 0.95
)

Arguments

Returns

A tibble with columns 'series', 'survival', 'incidence' ('1 - survival'), 'time', 'time_lower', and 'time_upper', one row per series/probability combination, sorted chronologically (increasing 'time', i.e. decreasing 'survival') within each series. 'time' (and 'time_lower'/'time_upper') is 'NA' for any probability the reconstructed survival curve never reaches.

retro_agent$probabilities()

Compute Kaplan-Meier survival probabilities (e.g. 12-month survival) for each series in the reconstructed individual patient survival data ([retro_agent_class]$data()), at the times requested. This is the inverse of [retro_agent_class]$quantiles(): instead of asking "at what time is a target survival probability reached", it asks "what is the survival probability at a target time". The digitized, scaled curve data produced internally by the data tool is deliberately never used for this, even as a fallback: it makes no statistical claims, and reconstruction does not record whether its y-axis was survival or cumulative incidence, so a probability read off it would not be statistically defensible.

Usage

retro_agent$probabilities(quantiles, confidence = 0.95)

Arguments

Returns

A tibble with columns 'series', 'time', 'survival', 'survival_lower', 'survival_upper', 'incidence' ('1 - survival'), 'incidence_lower' ('1 - survival_lower'), and 'incidence_upper' ('1 - survival_upper'), one row per series/time combination, sorted chronologically (increasing 'time') within each series.

retro_agent$counts()

Count the number of patients and events per series in the reconstructed individual patient survival data ([retro_agent_class]$data()). One row per legend row, in legend order, plus a final total row summing across all series (see [retro_survival_counts()]).

Usage

retro_agent$counts()

Returns

A tibble with columns 'series', 'patients', and 'events' (see [retro_survival_counts()]), one row per legend row in legend order, plus a final '"total"' row.

retro_agent$compare()

Visually compare the source image against a freshly generated impression, with axes drawn back in and one series brought to the front. Two sources are available for the impression (see the 'data' argument): the reconstructed survival data ('state$data_survival') refit to a Kaplan-Meier curve per series, which validates the thing the package actually exists to produce rather than the raw digitized pixels; or the raw digitized trace ('state$data_scaled') before reconstruction, which isolates whether a disagreement traces back to retroglyph's own digitization or to ‘IPDfromKM'’s reconstruction. Each series is drawn out to its own last reconstructed observation, so arms with shorter follow-up end earlier in the impression than arms with longer follow-up, exactly as they do in the source figure. Assumes 'reconstruct()' has already completed successfully.

Usage

retro_agent$compare(front = 1L, data = "survival")

Arguments

Returns

An HTML widget (from 'diffviewer::visual_diff()') comparing 'state$image_source' (old, ground truth) to the generated impression (new).

retro_agent$export()

Save the reconstruction to disk under the 'output' directory (created if it doesn't already exist), split into two subdirectories: * 'compare/': one self-contained HTML comparison widget per legend row, each bringing that row's series to the front (see [retro_agent_class]$compare()). Files are named '<series>_<color-name>.html', where '<color-name>' is the nearest built-in R color name (from 'grDevices::colors()') to the series' hex color. * 'data/': 'risk_table.csv' (see [retro_agent_class]$risk_table()), 'events_table.csv' (see [retro_agent_class]$events_table()), 'data.csv' (see [retro_agent_class]$data()), 'counts.csv' (see [retro_agent_class]$counts()), 'quantiles.csv' (see [retro_agent_class]$quantiles()), 'probabilities.csv' (see [retro_agent_class]$probabilities()), and 'hazard_ratios.csv' (see [retro_agent_class]$hazard_ratios()) whenever those are non-'NULL'. 'events_table.csv' is absent whenever no arm reported a total events count, which is common and not an error. 'probabilities.csv' is absent unless 'quantiles' (below) is supplied. Assumes 'reconstruct()' has already completed successfully.

Usage

retro_agent$export(
  output,
  data = "survival",
  probabilities = c(0.25, 0.5, 0.75),
  type = c("survival", "incidence"),
  quantiles = NULL,
  confidence = 0.95
)

Arguments

Returns

'NULL', invisibly.

retro_agent$clone()

The objects of this class are cloneable with this method.

Usage

retro_agent$clone(deep = FALSE)

Arguments

Description

Create and return a Shiny app that wraps a [retro_agent()] in a browser-based UI for uploading Kaplan-Meier images, chatting with the model, and reviewing the reconstructed image, risk table, hazard ratios, and survival quantiles/probabilities.

Usage

retro_app(
  chat,
  theme = bslib::bs_theme(version = 5, preset = "flatly", primary = "#2C3E50"),
  authentication_ui = NULL,
  authentication_server = NULL,
  onStart = NULL,
  options = list()
)

Arguments

Details

'chat' is cloned once per Shiny session (via 'chat$clone(deep = TRUE)'), so the same 'chat' object can be reused across multiple concurrent app sessions without one session's conversation or registered tools leaking into another's.

Value

A Shiny app object from 'shiny::shinyApp()'.

Examples

if (identical(Sys.getenv("RETROGLYPH_EXAMPLES"), "true")) {
    retro_app(retro_chat_replay_simulation())
 }

Description

Create an 'ellmer' chat object that does not authenticate or connect to any real provider. Useful for testing and development without network access.

Usage

retro_chat_mock()

Details

The returned chat supports registering tools, setting system prompts, and all other local operations. It will error only if you attempt to send a message to the model.

Value

An 'ellmer' chat object.

See Also

Other chats: retro_chat_replay_simulation()

Examples

chat <- retro_chat_mock()
  chat$get_system_prompt()

Description

Create an 'ellmer' chat object that replays a fixed, real tool-call transcript instead of talking to a model. Useful for exercising [retro_agent()]/[retro_app()] end to end, deterministically and without a network call.

Usage

retro_chat_replay_simulation()

Details

The returned chat is only good for one image: the 'inst/simulation.png' example shipped with the package. Its 'chat()'/'stream_async()' methods replay the exact tool-call sequence a live model once took to reconstruct that specific image - quantize, label, distill, then data, each called with the arguments that model read off 'inst/simulation.png' - then return a canned summary of the result. 'chat()' returns that summary directly, and 'stream_async()' returns a promise of it, so [retro_app()] streams the replay the same way it streams a real model's response. Because the replayed calls run the real tools [retro_agent()] registers (not canned tool results), the state ends up populated exactly as it would from a real reconstruction of 'inst/simulation.png', but any other image will not track this chat's hard-coded axis calibration and risk table, so results are only sensible for 'inst/simulation.png'.

Value

An 'ellmer' chat object.

See Also

Other chats: retro_chat_mock()

Examples

if (identical(Sys.getenv("RETROGLYPH_EXAMPLES"), "true")) {
    chat <- retro_chat_replay_simulation()
    agent <- retro_agent(chat)
    agent$register(system.file("simulation.png", package = "retroglyph"))
    agent$chat$chat("Reconstruct the data from the registered plot.")
    agent$data()
    if (interactive()) {
      agent$compare()
    }
    # Run the Shiny app against the replay chat instead of a real model:
    shiny::runApp(retro_chat_replay_simulation())
  }