*! version 0.8.4 09nov2026 Eric Booth *! _sm_renderhtml -- render a surveymap journal (TSV, 20 columns) as HTML *! with one inline SVG flow map. *! *! syntax: _sm_renderhtml using journal.tsv, saving(x.html) *! [name(string) embed noheader replace accent(hex)] *! *! Layout is horizontal, left to right: items are columns in position order. *! An ungated stretch is one row of item boxes on the spine. At a gate the *! flow fans out into one lane per cat row of the (already pruned) journal -- *! kept categories + other + noanswer -- each lane crossing the gate's *! segment cell by cell, and the lanes merge at a join point before the next *! stretch. A cell the lane was routed around draws as a dashed grey ghost *! box. Width grows with items; the page scrolls sideways (.sm-wrap is *! overflow-x auto), and lane rows stack vertically, so total height follows *! the widest gate. *! *! Two output shapes: *! page (default) a self-contained document; the map runs full height *! embed (option) a FRAGMENT for pasting into a host report: one scoped *! "' _n file write `H' `""' _n file write `H' `""' _n file write `H' `"

surveymap · `jname'

"' _n } else { file write `H' `""' _n file write `H' `""' _n } file write `H' `"
"' _n if "`noheader'" == "" { _srh_n `"`NN'"' local nnf `"`s(o)'"' if "`nnf'" == "" local nnf "?" local gw = cond(`G' == 1, "gate", "gates") local iw = cond(`K' == 1, "item", "items") local wnote = cond(`haswt', /// " · counts unweighted, percentages weighted", "") file write `H' `"
survey: `jname' · `nnf' respondents · `K' `iw' · `G' `gw'`wnote'
"' _n if `"`scopetxt'"' != "" { _srh_map `"`scopetxt'"' file write `H' `"
scope: only respondents where `s(o)' · every count and share on this page describes that group
"' _n } file write `H' `"
!! = warning (never colour alone) · !? = the declared routing and the data disagree · dashed box = skipped, routed around by the gate · lanes partition the sample · hover a node for detail
"' _n * ---- how to read this map, generated with this survey's own names -- local rdir "left to right" local rd1 "leftmost" if `vert' { local rdir "top to bottom" local rd1 "top" } _srh_n `"`na_1'"' local rn1 `"`s(o)'"' local gname "" forvalues p = 1/`K' { if "`gname'" == "" & "`g_`p''" == "1" local gname `"`v_`p''"' } file write `H' `"
How to read this map, step by step
    "' _n file write `H' `"
  1. Each solid box is one survey item, in questionnaire order, `rdir'. Start at the `rd1' box, `v_1': `rn1' respondents were in scope there, and the count line inside each box says how many answered it and what share of the scope that is.
  2. "' _n if `HASRESP' { file write `H' `"
  3. The shaded rows inside a box are that item's most common answers. Each row's bar length is its share of the people the item was put to, so the answer rows, the other answers row and the no answer row account for everyone who saw the question.
  4. "' _n } file write `H' `"
  5. Follow the arrow out of a box to the next item the survey asked.
  6. "' _n if "`gname'" != "" { file write `H' `"
  7. Where a heading says split by `gname', the sample fans into lanes, one per answer to `gname', each headed by the answer and the number of people in that lane. Inside a lane, a solid box is an item that lane was asked and a dashed grey box is an item the skip logic routed that lane around.
  8. "' _n file write `H' `"
  9. The lanes rejoin the spine at a small dot, and the single path continues. Lane counts add back to the sample: nobody is lost and nobody is counted twice.
  10. "' _n } else { file write `H' `"
  11. This survey has no branching drawn, so there is a single path. A dashed grey box, if one appears, is an item the skip logic routed respondents around.
  12. "' _n } file write `H' `"
  13. !! flags an item that many people declined to answer; !? flags an item where the declared skip logic and the data disagree. Hover any box for its full record, and the table at the bottom of the page repeats every number as text.
  14. "' _n file write `H' `"
"' _n } file write `H' `"
"' _n if "`embed'" == "" { file write `H' `""' _n } else { * embed: viewBox only, no width/height; natural width comes from a * scoped CSS rule inside .sm-wrap file write `H' `""' _n } local dirw = cond(`vert', "down the page", "left to right") file write `H' `"surveymap flow map for `jname'"' _n file write `H' `"Items run `dirw' in questionnaire order. A gate fans the sample into lanes that rejoin the spine at the end of its segment. The same numbers are in the table below the figure."' _n file write `H' `""' _n file write `H' `""' _n file write `H' `""' _n * copy the body (data was neutralized, so no backticks, dollars or quotes) tempname R file open `R' using "`bodyf'", read text file read `R' bline while r(eof) == 0 { file write `H' `"`macval(bline)'"' _n file read `R' bline } file close `R' file write `H' `""' _n file write `H' `"
"' _n * ---- the same numbers, as text ------------------------------------ * A screen reader cannot follow a spine, and neither can a reader who * prints this badly or has the images turned off. The map is drawn from * a table, so the fallback is that table rather than a sentence about it. file write `H' `"
"' _n file write `H' `"The same map as a table"' _n file write `H' `""' _n file write `H' `""' _n file write `H' `""' _n file write `H' `""' _n forvalues p = 1/`K' { _srh_n `"`nn_`p''"' local tnn `"`s(o)'"' _srh_n `"`nr_`p''"' local tnr `"`s(o)'"' if "`tnr'" == "" local tnr "0" _srh_n `"`ns_`p''"' local tns `"`s(o)'"' if "`tns'" == "" local tns "0" local tgb `"`gb_`p''"' if `"`tgb'"' == "." | `"`tgb'"' == "" local tgb "—" local trow "sm-tr" if "`g_`p''" == "1" local trow "sm-tr sm-trg" file write `H' `""' _n } file write `H' `"
Every item in questionnaire order. Answered, declined and not shown add to the `nnf' respondents in scope at every row.
#itemanswereddeclinednot shownrouted by
`p'`v_`p''`tnn' (`pa_`p''%)`tnr'`tns'`tgb'
"' _n file write `H' `"
"' _n * provenance footer local flav = cond(c(MP) == 1, "MP", cond(c(SE) == 1, "SE", c(flavor))) file write `H' `"
surveymap · journal `jname' · generated `c(current_date)' `c(current_time)' · Stata `c(stata_version)' `flav'
"' _n file write `H' `"
"' _n if "`embed'" == "" { file write `H' `""' _n file write `H' `""' _n } file close `H' frame drop `J' capture macro drop SRH_ACC SRH_PFX local tag = cond("`embed'" != "", ", embed fragment", "") display as text "_sm_renderhtml: wrote " as result "`out'" /// as text " (`K' items, `G' gates`tag')" end * ============================================================ stylesheet * Every rule is scoped under the per-diagram class and every selector is a * class selector. No element selectors: those would restyle the host page * an embed fragment is pasted into. program define _srh_css args H pfx accent svgw embed local P ".`pfx'" local MONO "SF Mono, Menlo, Consolas, DejaVu Sans Mono, monospace" local SANS "-apple-system, Segoe UI, Helvetica, Arial, sans-serif" file write `H' `"`P' { margin: 1rem 0; }"' _n * The fragment gets a bounded, resizable viewport, because it sits inside * someone else's page. A standalone page is the page: no max-height cap, * the browser scrolls it. The print query lifts the cap either way. if "`embed'" != "" { file write `H' `"`P' .sm-wrap { max-height: 32rem; overflow: auto; resize: vertical; border: 1px solid #e4e4e4; border-radius: 4px; padding: 6px; background: #fff; }"' _n } else { file write `H' `"`P' .sm-wrap { overflow-x: auto; border: 1px solid #e4e4e4; border-radius: 4px; padding: 6px; background: #fff; }"' _n } * width grows with items: keep native width, scroll sideways file write `H' `"`P' .sm-svg { width: `svgw'px; max-width: none; height: auto; display: block; }"' _n file write `H' `"`P' .sm-cap { font-family: `SANS'; font-size: 12px; color: #666; margin: 0 0 3px 0; }"' _n file write `H' `"`P' .sm-leg { font-family: `SANS'; font-size: 11px; color: #888; margin: 0 0 8px 0; }"' _n file write `H' `"`P' .sm-legk { color: `accent'; font-weight: 700; }"' _n file write `H' `"`P' .sm-foot { font-family: `SANS'; font-size: 10px; color: #999; margin: 10px 0 0 0; line-height: 1.5; }"' _n file write `H' `"`P' .sm-alt { font-family: `SANS'; font-size: 12px; color: #333; margin: 12px 0 0 0; }"' _n file write `H' `"`P' .sm-alts { cursor: pointer; color: #555; padding: 2px 0; }"' _n file write `H' `"`P' .sm-read { font-family: `SANS'; font-size: 12.5px; color: #333; margin: 6px 0 2px 0; }"' _n file write `H' `"`P' .sm-rdl { margin: 6px 0 4px 18px; padding: 0; max-width: 760px; }"' _n file write `H' `"`P' .sm-rdl li { margin: 0 0 6px 0; line-height: 1.45; }"' _n file write `H' `"`P' .sm-tbl { border-collapse: collapse; margin: 8px 0 0 0; font-size: 12px; }"' _n file write `H' `"`P' .sm-tcap { text-align: left; color: #666; padding: 0 0 6px 0; font-size: 11px; }"' _n file write `H' `"`P' .sm-tbl th, `P' .sm-tbl td { border: 1px solid #ddd; padding: 3px 8px; text-align: right; font-variant-numeric: tabular-nums; }"' _n file write `H' `"`P' .sm-tbl thead th { background: #f4f4f4; text-align: right; }"' _n file write `H' `"`P' .sm-tbl th[scope="row"] { text-align: left; font-weight: 600; }"' _n file write `H' `"`P' .sm-trg th[scope="row"] { color: #2f5573; }"' _n file write `H' `"`P' .sm-node { cursor: help; }"' _n * svg text roles file write `H' `"`P' .sm-t { font-family: `MONO'; }"' _n file write `H' `"`P' .sm-bh { font-size: 12px; font-weight: 700; fill: #111; }"' _n file write `H' `"`P' .sm-bl { font-size: 11px; fill: #333; }"' _n file write `H' `"`P' .sm-bn { font-size: 11px; fill: #666; }"' _n file write `H' `"`P' .sm-bf { font-size: 11px; font-weight: 700; fill: `accent'; }"' _n file write `H' `"`P' .sm-rt { font-size: 10.5px; fill: #222; }"' _n file write `H' `"`P' .sm-rt2 { font-size: 10.5px; fill: #777; }"' _n file write `H' `"`P' .sm-gt { font-size: 11px; fill: #8a8a8a; }"' _n file write `H' `"`P' .sm-ll { font-size: 11px; fill: #333; }"' _n file write `H' `"`P' .sm-lh { font-size: 11px; font-weight: 700; fill: #222222; }"' _n * svg shape roles file write `H' `"`P' .sm-bx { fill: #f7f7f7; stroke: #333; stroke-width: 1.1; }"' _n file write `H' `"`P' .sm-cx { fill: #fcfcfc; stroke: #666; stroke-width: 1; }"' _n file write `H' `"`P' .sm-gx { fill: #fff; stroke: #999; stroke-width: 1; stroke-dasharray: 5 3; }"' _n file write `H' `"`P' .sm-sp { stroke: #444; stroke-width: 1.2; fill: none; }"' _n file write `H' `"`P' .sm-jp { fill: #444; }"' _n file write `H' `"@media print { `P' .sm-wrap { max-height: none; overflow: visible; resize: none; border: 0; padding: 0; } }"' _n end * ============================================================ svg writers * Shapes carry presentation attributes as well as classes, so a fragment * whose stylesheet is stripped still renders as legible boxes. program define _srh_rect args B x y w h cls local fill "#f7f7f7" local strk "#333" local sw "1.1" local dash "" if "`cls'" == "cx" { local fill "#fcfcfc" local strk "#666" local sw "1" } if "`cls'" == "gx" { local fill "#ffffff" local strk "#999" local sw "1" local dash `" stroke-dasharray="5 3""' } if "`cls'" == "rb" { local fill "#dbe3ec" local strk "none" local sw "0" } if "`cls'" == "ro" { local fill "#ececec" local strk "none" local sw "0" } file write `B' `""' _n end * connector; every arrowhead uses the accent marker (the one place besides * "!!" the accent colour appears) program define _srh_line args B x1 y1 x2 y2 file write `B' `""' _n end * write an svg ; maps marker chars to XML entities and mirrors the CSS * into presentation attributes program define _srh_wtext gettoken h 0 : 0 gettoken x 0 : 0 gettoken y 0 : 0 gettoken cls 0 : 0 if "`cls'" == "" local cls "bl" * the text arrives as ONE compound-quoted token; gettoken binds and * strips the quotes (args would keep them, and they would draw) gettoken txt : 0 _srh_map `"`txt'"' local t = trim(`"`s(o)'"') local size 11 local wt "normal" local fill "#333" if "`cls'" == "bh" { local size 12 local wt "bold" local fill "#111" } if "`cls'" == "bn" local fill "#666" if "`cls'" == "bf" { local wt "bold" local fill "$SRH_ACC" } if "`cls'" == "gt" local fill "#8a8a8a" if "`cls'" == "rt" { local size 10.5 local fill "#222" } if "`cls'" == "rt2" { local size 10.5 local fill "#777" } file write `h' `"`t'"' _n end * one tooltip line (a real newline: browsers honour it inside svg ) program define _srh_wtip gettoken h 0 : 0 _srh_map `"`0'"' local t = trim(`"`s(o)'"') file write `h' `"`t'"' _n end * map internal marker chars to XML entities -> s(o) program define _srh_map, sclass args t local t = subinstr(`"`t'"', char(16), "&", .) local t = subinstr(`"`t'"', char(17), "<", .) local t = subinstr(`"`t'"', char(18), ">", .) local t = subinstr(`"`t'"', char(19), """, .) local t = subinstr(`"`t'"', char(6), "`", .) local t = subinstr(`"`t'"', char(7), "$", .) local t = subinstr(`"`t'"', char(1), "…", .) local t = subinstr(`"`t'"', char(3), "·", .) sreturn local o `"`t'"' end * comma-format a count string ("." or "" -> empty) -> s(o) program define _srh_n, sclass args s if `"`s'"' == "." | `"`s'"' == "" sreturn local o "" else sreturn local o = trim(string(real(`"`s'"'), "%20.0fc")) end * middle-ellipsis to maxlen -> s(o); only when the label genuinely overflows program define _srh_mell, sclass args maxlen t * character counts, not bytes: a byte-based cut can split a curly quote * or an accented letter in half and leave an invalid byte on the page if ustrlen(`"`t'"') <= `maxlen' { sreturn local o `"`t'"' exit } local h1 = floor((`maxlen'-1)/2) local h2 = `maxlen' - 1 - `h1' local L = ustrlen(`"`t'"') sreturn local o = usubstr(`"`t'"', 1, `h1') + char(1) + /// usubstr(`"`t'"', `L' - `h2' + 1, .) end * word-wrap to at most maxlines lines -> s(n), s(l1..); overflow past the * last line merges in with a middle-ellipsis program define _srh_wrapn, sclass args maxlen maxlines t local rest = trim(`"`t'"') local n 0 while `"`rest'"' != "" & `n' < `maxlines' { if ustrlen(`"`rest'"') <= `maxlen' { local ++n local l`n' `"`rest'"' local rest "" } else { local head = usubstr(`"`rest'"', 1, `maxlen') local p = ustrrpos(`"`head'"', " ") if `p' < 8 local p = `maxlen' local ++n local l`n' = trim(usubstr(`"`rest'"', 1, `p')) local rest = trim(usubstr(`"`rest'"', `p'+1, .)) } } if `"`rest'"' != "" & `n' > 0 { local merged `"`l`n'' `rest'"' _srh_mell `maxlen' `"`merged'"' local l`n' `"`s(o)'"' } sreturn clear sreturn local n = `n' forvalues k = 1/`n' { sreturn local l`k' `"`l`k''"' } end * sanitize an id/class prefix -> s(o) program define _srh_slug, sclass args t local out "" local L = strlen(`"`t'"') if `L' > 40 local L 40 forvalues i = 1/`L' { local ch = substr(`"`t'"', `i', 1) if !ustrregexm("`ch'", "^[A-Za-z0-9-]$") local ch "-" local out "`out'`ch'" } while substr("`out'", -1, 1) == "-" { local out = substr("`out'", 1, strlen("`out'")-1) } if substr("`out'", 1, 3) != "sm-" local out "sm-`out'" if "`out'" == "sm-" local out "sm-1" sreturn clear sreturn local o "`out'" end