*! version 0.8.4 09nov2026 Eric Booth *! _sm_renderflow -- draw a paths journal (pnode/pflow/ppath rows) as a *! self-contained HTML page: one column per item, one block per common *! answer, ribbons between consecutive columns sized by the people who gave *! both answers, and a table of the most common full sequences underneath. *! *! Everything drawn is read back from the journal; nothing is recounted. *! The one derived quantity is geometry: block heights share a single *! people-to-pixels scale, so a block twice as tall is twice as many *! people, in every column. *! *! Escaping discipline is _sm_renderhtml's: journal text is *! neutralized to marker characters at import, carried through macros *! inertly, and mapped to XML entities at the moment of writing. program define _sm_renderflow, sclass version 16 syntax using/, SAVing(string) [TITLe(string) NAME(string) /// HIGHlight(string) EMBed replace] sreturn clear local hf `"`saving'"' if strlower(substr(`"`hf'"', -5, .)) != ".html" local hf `"`hf'.html"' capture confirm file `"`hf'"' if !_rc & "`replace'" == "" { di as err `"surveymap paths: `hf' exists; add replace to overwrite"' exit 602 } * ---- intake ---------------------------------------------------------- tempname J frame create `J' frame `J' { quietly import delimited using `"`using'"', delimiter(tab) /// varnames(1) stringcols(_all) encoding("utf-8") bindquote(nobind) clear capture confirm variable class local badc = _rc capture confirm variable gatevar if `badc' | _rc { display as error "`using' is not a surveymap journal (no " /// "class/gatevar column; see proto/JOURNAL_SCHEMA.md in the GitHub repository)" exit 459 } foreach v in seq class var position vallabel value gatevar n_asked /// n_answered n_nonresp n_sysmiss pct_answered rate status gate /// gated_by pooled type severity flags { capture confirm variable `v' if _rc quietly generate str1 `v' = "." quietly replace `v' = "." if `v' == "" } foreach v in class var vallabel value gatevar status gate gated_by /// pooled type severity flags { quietly replace `v' = subinstr(`v', "&", char(16), .) quietly replace `v' = subinstr(`v', "<", char(17), .) quietly replace `v' = subinstr(`v', ">", char(18), .) quietly replace `v' = subinstr(`v', char(96), char(6), .) quietly replace `v' = subinstr(`v', char(36), char(7), .) quietly replace `v' = subinstr(`v', char(34), char(19), .) } } frame `J': local NR = _N * ---- survey row: N, the settings line, the scope --------------------- local NN "." local sflags "" local K = 0 forvalues i = 1/`NR' { frame `J': local cls = class[`i'] if "`cls'" == "survey" { frame `J': local NN = n_asked[`i'] frame `J': local sflags = flags[`i'] } if "`cls'" != "item" continue frame `J': local p = real(position[`i']) if `p' >= . continue local K = max(`K', `p') frame `J': local v_`p' = var[`i'] frame `J': local lb_`p' = vallabel[`i'] } if `K' < 2 { frame drop `J' di as err "surveymap paths: `using' has no item rows to draw" di as err " write the journal with surveymap paths varlist, out(...)" exit 459 } local NSEQ "" if ustrregexm(`"`sflags'"', "([0-9]+) distinct full sequences") { local NSEQ = ustrregexs(1) } local NUNI "" if ustrregexm(`"`sflags'"', "([0-9]+) interviews on unique routes") { local NUNI = ustrregexs(1) } local scopetxt "" local p = strpos(`"`sflags'"', "; scope: ") if `p' { local scopetxt = strtrim(substr(`"`sflags'"', `p' + 9, .)) } * ---- blocks (pnode), ribbons (pflow), sequences (ppath) -------------- local KM = 0 forvalues i = 1/`NR' { frame `J': local cls = class[`i'] if "`cls'" == "pnode" { frame `J': local t = real(position[`i']) frame `J': local s = real(gate[`i']) if `t' >= . | `s' >= . continue local KM = max(`KM', `s') frame `J': local nk_`t'_`s' = real(n_asked[`i']) if `nk_`t'_`s'' >= . { frame drop `J' di as err "surveymap paths: a pnode row in `using' has no count" di as err " the journal is damaged; rewrite it with surveymap paths ..., nodraw" exit 459 } frame `J': local pk_`t'_`s' = pct_answered[`i'] frame `J': local dk_`t'_`s' = vallabel[`i'] frame `J': local vk_`t'_`s' = value[`i'] } if "`cls'" == "pflow" { frame `J': local t = real(position[`i']) frame `J': local a = real(gate[`i']) frame `J': local b = real(rate[`i']) if `t' >= . | `a' >= . | `b' >= . continue local FL_`t' "`FL_`t'' `a':`b'" frame `J': local fn_`t'_`a'_`b' = real(n_asked[`i']) frame `J': local fp_`t'_`a'_`b' = pct_answered[`i'] } if "`cls'" == "ppath" { frame `J': local r = real(gate[`i']) if `r' >= . continue if "`NPATH'" == "" local NPATH = 0 local NPATH = max(`NPATH', `r') frame `J': local sq_`r' = value[`i'] frame `J': local sn_`r' = n_asked[`i'] frame `J': local sp_`r' = pct_answered[`i'] } } if `KM' == 0 { frame drop `J' di as err "surveymap paths: `using' has no pnode rows" di as err " it is a scan journal; draw it with surveymap draw" exit 459 } frame drop `J' * top comes from the survey row's settings line, not from the occupied * slots: on complete data the no-answer slot is never journaled, and * inferring from occupancy would shift every colour and the guide text local topk = `KM' - 2 if ustrregexm(`"`sflags'"', "top=([0-9]+)") { local topk = real(ustrregexs(1)) local KM = `topk' + 2 } local N = real(`"`NN'"') if `N' >= . | `N' <= 0 { di as err "surveymap paths: `using' has no survey row with the scope count" di as err " the journal is damaged; rewrite it with surveymap paths ..., nodraw" exit 459 } * ---- what to highlight ---------------------------------------------- * Two forms. highlight(paths #) picks out the # most common complete * paths: their ribbons keep full colour while every other ribbon fades, * and their table rows print bold. highlight(var = value) picks out one * answer block: the ribbons into and out of it stay, the rest fade. local hlmode "" if `"`highlight'"' != "" { local hspec = strtrim(`"`highlight'"') gettoken hw hrest : hspec, parse(" =") local hwl = strlower(strtrim(`"`hw'"')) if inlist("`hwl'", "path", "paths") { local hrest = strtrim(`"`hrest'"') if `"`hrest'"' == "" local hrest "1" capture confirm integer number `hrest' if _rc | `hrest' < 1 | `hrest' > 10 { di as err "highlight(paths #): give a whole number from 1 to 10" di as err " highlight(paths 3) keeps the three most common complete paths" exit 198 } if "`NPATH'" == "" { di as err "highlight(paths): this journal has no path table to pick from" exit 459 } local hlmode "paths" local hln = min(`hrest', `NPATH') local hlpct = 0 forvalues r = 1/`hln' { if `"`sq_`r''"' == "" continue local hlpct = `hlpct' + real(strtrim(`"`sp_`r''"')) local rest `"`sq_`r''"' local t = 0 local prev . while `"`rest'"' != "" & `t' < `K' { local ++t local p = strpos(`"`rest'"', char(18)) if `p' { local tok = substr(`"`rest'"', 1, `p' - 1) local rest = substr(`"`rest'"', `p' + 1, .) } else { local tok `"`rest'"' local rest "" } local s = real(`"`tok'"') if `s' >= . continue local HB_`t'_`s' = 1 if `prev' < . local HF_`=`t'-1'_`prev'_`s' = 1 local prev = `s' } } local hlpct = string(`hlpct', "%9.1f") } else { local eq = strpos(`"`hspec'"', "=") if !`eq' { di as err `"highlight(): could not read "`hspec'""' di as err " highlight(paths 3) keeps the three most common complete paths" di as err " highlight(q2 = 1) keeps the ribbons through one answer block" exit 198 } local hv = strtrim(substr(`"`hspec'"', 1, `eq' - 1)) local hval = strtrim(substr(`"`hspec'"', `eq' + 1, .)) local t0 = 0 forvalues t = 1/`K' { if `"`v_`t''"' == `"`hv'"' local t0 = `t' } if !`t0' { di as err "highlight(): `hv' is not an item on this map" local its "" forvalues t = 1/`K' { local its "`its' `v_`t''" } di as err " the items are:`its'" exit 198 } local s0 = 0 forvalues s = 1/`KM' { if `"`vk_`t0'_`s''"' == "" continue if real(`"`vk_`t0'_`s''"') == real(`"`hval'"') & real(`"`hval'"') < . { local s0 = `s' } if `"`vk_`t0'_`s''"' == "~o" & inlist(strlower(`"`hval'"'), "other", "~o") local s0 = `s' if `"`vk_`t0'_`s''"' == "~m" & inlist(strlower(`"`hval'"'), "noanswer", "missing", "~m") local s0 = `s' } if !`s0' { di as err "highlight(): `hv' has no drawn block for `hval'" di as err " it is pooled or absent; raise top(), or name a drawn" di as err " answer value, or use other / noanswer for the grey blocks" exit 198 } local hlmode "block" local HB_`t0'_`s0' = 1 if `t0' < `K' { forvalues b = 1/`KM' { local HF_`t0'_`s0'_`b' = 1 } } if `t0' > 1 { forvalues a = 1/`KM' { local HF_`=`t0'-1'_`a'_`s0' = 1 } } } } * ---- geometry -------------------------------------------------------- * One vertical scale for every column: pixels per person. Block heights * get a floor so a sliver stays visible; the floor inflates a column by * a few pixels at most, and the ribbons anchor inside the drawn blocks, * so the braid still partitions each bar edge exactly. local PH = 520 local TOPM = 96 local BOTM = 30 local NW = 16 local GAPX = 186 local LM = 14 local RM = 200 local SGAP = 5 local pxper = (`PH' - (`KM' - 1) * `SGAP') / `N' local W = `LM' + `K' * `NW' + (`K' - 1) * `GAPX' + `RM' * block tops and heights; a slot with no row (n = 0) takes no space local Hmax = 0 forvalues t = 1/`K' { local y = `TOPM' forvalues s = 1/`KM' { if `"`nk_`t'_`s''"' == "" continue local h = max(3, round(`nk_`t'_`s'' * `pxper')) local gy_`t'_`s' = `y' local gh_`t'_`s' = `h' local y = `y' + `h' + `SGAP' } local Hmax = max(`Hmax', `y' - `SGAP') } local H = `Hmax' + `BOTM' * ---- file ------------------------------------------------------------ local stub `"`hf'"' local p = max(strrpos(`"`stub'"', "/"), strrpos(`"`stub'"', char(92))) if `p' local stub = substr(`"`stub'"', `p' + 1, .) if strlower(substr(`"`stub'"', -5, .)) == ".html" { local stub = substr(`"`stub'"', 1, strlen(`"`stub'"') - 5) } _srf_slug `"`stub'"' local PFX "`s(o)'" local jname `"`name'"' if `"`jname'"' == "" { local jname `"`using'"' local p = max(strrpos(`"`jname'"', "/"), strrpos(`"`jname'"', char(92))) if `p' local jname = substr(`"`jname'"', `p' + 1, .) } local ttl `"`title'"' if `"`ttl'"' == "" local ttl "How the answers flow, item by item" * option text and filenames arrive as literals, not marker-encoded * journal text, so they get their own XML escaping here _srf_lit `"`ttl'"' local ttl `"`s(o)'"' _srf_lit `"`jname'"' local jname `"`s(o)'"' tempname h quietly file open `h' using `"`hf'"', write text replace if "`embed'" == "" { file write `h' `""' _n file write `h' `""' _n file write `h' `"
"' _n file write `h' `""' _n _srf_map `"`ttl'"' file write `h' `"`Nfmt' respondents, each counted once in every column · journal: `jname'
"' _n if `"`scopetxt'"' != "" { _srf_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' `"A column is one item. A block is one answer, sized by how many gave it. A ribbon joins two answers on consecutive items, sized by how many gave both. Hover anything for exact counts.
"' _n if "`hlmode'" == "paths" { local hlw "the `hln' most common complete paths, together" if `hln' == 1 local hlw "the most common complete path," local hlnote "" if real(strtrim("`hlpct'")) < 5 { local hlnote " That is a small slice of the sample, so the fade mutes most of the braid; highlight(var = value) picks out one answer block instead." di as txt "note: the highlighted paths cover only " as res strtrim("`hlpct'") "%" as txt " of the sample; consider highlight(var = value)" } file write `h' `"highlighted: `hlw' `=strtrim("`hlpct'")'% of respondents; every other ribbon is faded, and the picked paths print bold in the table below.`hlnote'
"' _n } if "`hlmode'" == "block" { _srf_map `"`dk_`t0'_`s0''"' file write `h' `"highlighted: the ribbons into and out of `hv' = `s(o)'; every other ribbon is faded
"' _n } file write `h' `"The largest flows, each counting the people who gave one pair of answers on two neighboring items:
"' _n file write `h' `"| share | people | flow |
|---|---|---|
| `pc'% | `nf' | `va' `la' → `vb' `lb' |
The most common full paths, reading `order'.`fragtxt'
"' _n file write `h' `"| share | people | path |
|---|---|---|
| `pc'% | `nf' | `cells' |
Reading rule: counts are unweighted respondents in scope. A ribbon is the number of people who gave that pair of answers on two consecutive items. A table line is the number who took that complete path. no answer recorded includes people the routing never showed the item, which item data cannot separate from a decline. Drawn by surveymap from `jname'. The journal has a weighted count column when the scan was weighted.
"' _n file write `h' `"