stiles.utils {INLA} | R Documentation

## sTiles utils: streaming spy plots and graph<->mtx I/O

### Description

Streaming sparsity-pattern plots and conversions between INLA graph files and MatrixMarket `.mtx` files. The spy plots stream the input file (never loading the full matrix), bin entries into a `⁠GRID x GRID⁠` grid, and render a log-density image. This makes them usable on matrices that would otherwise exhaust memory if read into a `Matrix`.

INLA graph files are autodetected as 0-based or 1-based by inspecting the first data row; override with `base = 0L` or `base = 1L`. MatrixMarket files use the standard 1-based coordinate convention.

`inla.stiles.graph2mtx` writes a symmetric MatrixMarket file. By default the diagonal is set to the node degree (matches the typical precision-matrix convention where `Q[i,i]` equals the sum of weights of incident edges, giving a diagonally-dominant Q with unit off-diagonals). Use `diagonal = "one"` for unit diagonals, or `diagonal = "none"` to omit the diagonal entirely.

### Usage

    inla.stiles.spy.mtx(
      file,
      out = NULL,
      GRID = 1000L,
      text = FALSE,
      colorbar = FALSE,
      palette = "grey",
      CHUNK = 2000000L
    )

    inla.stiles.spy.graph(
      file,
      out = NULL,
      GRID = 1000L,
      text = FALSE,
      colorbar = FALSE,
      palette = "grey",
      CHUNK = 100000L,
      base = NULL
    )

    inla.stiles.graph2mtx(
      graph_file,
      mtx_file,
      diagonal = c("degree", "one", "none"),
      base = NULL
    )

    inla.stiles.mtx2graph(mtx_file, graph_file, base = 0L, CHUNK = 2000000L)

### Arguments

`file` | For `inla.stiles.spy.mtx`: path to a `.mtx` file. For `inla.stiles.spy.graph`: path to an INLA graph file.
`out` | Output PNG path. Defaults to the input path with extension replaced by `.png`.
`GRID` | Bin grid resolution (default 1000).
`text` | If `TRUE`, draw title and axis labels (default `FALSE`).
`colorbar` | If `TRUE`, draw a colorbar to the right (default `FALSE`).
`palette` | Colour palette: `"grey"` (default), `"gray"`, `"binary"`, `"viridis"`, or any name accepted by `hcl.colors()`.
`CHUNK` | Lines read per streaming chunk. Tune for very large files.
`base` | Index base for INLA graph files. `NULL` (default) auto-detects by peeking at the first data row.
`graph_file` | Path to an INLA graph file (ASCII).
`mtx_file` | Path to a MatrixMarket `.mtx` file.
`diagonal` | Diagonal value for `inla.stiles.graph2mtx`: `"degree"` (default), `"one"`, or `"none"`.

### Value

The output file path (invisibly).

### Author(s)

Esmail Abdul Fattah esmail.abdulfattah@kaust.edu.sa

### See Also

`inla.spy()`, `inla.read.graph()`, `inla.write.graph()`

### Examples

    ## Not run:
    ## spy a large MTX file (streamed, never fully loaded)
    inla.stiles.spy.mtx("Q.mtx", "Q.png")

    ## spy an INLA graph file directly
    inla.stiles.spy.graph("inla_graph_animal1", "animal.png")

    ## convert between formats (round-trips bit-identical up to neighbour order)
    inla.stiles.graph2mtx("inla_graph_animal1", "animal.mtx")
    inla.stiles.mtx2graph("animal.mtx",         "animal.graph")

    ## End(Not run)

[Package INLA version 26.08.22 Index]