* Program to generate forestplots -- used by ipdmetan etc. but can also be run by itself
* April 2013
*   Forked from main ipdmetan code
* September 2013
*   Following UK Stata Users Meeting, reworked the plotid() option as recommended by Vince Wiggins

* version 1.0  David Fisher  31jan2014

* version 1.01  David Fisher  07feb2014
* Reason: fixed bug - random-effects note being overlaid on x-axis labels

* version 1.02  David Fisher  20feb2014
* Reason: allow user to affect null line options

* version 1.03  David Fisher  23jul2014
* Reason: implented a couple of suggestions from Phil Jones
* Weighting is now consistent across plotid groups
* Tidying up some code that unnecessarily restricted where user-defined lcols/rcols could be plotted
* Minor bug fixes and code simplification
* New (improved?) textsize and aspect ratio algorithm

* version 1.04  David Fisher 29jun2015
// Reason: Major update to coincide with publication of Stata Journal article

* Aug 2014: fixed issue with _labels
* updated SpreadTitle to accept null strings
* added 'noBOX' option

* Oct 2014: added "newwt" option to "dataid" to reset weights

* Jan 2015: re-written leftWD/rightWD sections to use variable formats and manually-calculated indents
* rather than using char(160), since this isn't necessarily mapped to "non-breaking space" on all machines

* May 2015: Fixed issue with "clipping" long column headings
* May 2015: Option to save parameters (aspect ratio, text size, positioning of text columns relative to x-axis tickmarks)
* in a matrix, to be used by a subsequent -forestplot- call to maintain consistency

* October 2015: Minor fixes to agree with new ipdmetan/admetan versions

* July 2016: added rfdist

* 30th Sep 2016: added "range(min max)" option so that range = min(_LCI) to max(_UCI)

* Coding of _USE:
* _USE == 0  subgroup labels (headings)
* _USE == 1  successfully estimated trial-level effects
* _USE == 2  unsuccessfully estimated trial-level effects ("Insufficient data")
* _USE == 3  subgroup effects
* _USE == 4  between-subgroup heterogeneity info and/or `hetinfo' placed on new line 
* _USE == 5  overall effect
* _USE == 6  blank lines (text/data in such rows will be ignored in the plot)
* _USE == 7  prediction interval data
* _USE == 9  titles (internal only)

* version 2.0  David Fisher  11may2017
// Not updated nearly as much as -admetan-, -ipdmetan- and -ipdover-
// but up-versioned to match

* version 2.1  David Fisher  14sep2017
// various bug fixes
// improvements to range() and cirange()
// improvements to rfopts

// - N.B. cannot override "interaction" option with pointopts(msymbol(square)) -- is this a bug or a feature?
// for next version:  include addplot() option ?

* version 3.0  David Fisher  08nov2018

* version 3.1  David Fisher  03dec2018
// only implement lalign() if c(stata_version)>=15
// corrected order of `graphopts' and `fpuseopts' so that -useopts- works as intended
// -forestplot- now consistently honours blank varlabels in lcols/rcols (whether string or numeric)

* version 3.2  David Fisher  28jan2019
// corrected error which caused first help-file example to fail
// some text in help file is updated
// improved counting of rows in titles containing compound quotes

* version 4.00  David Fisher  25nov2020
// changes to `xlabopts'
// changes to `influence' plot (including "hide" option)
// changes to fp() option
// -double- option added back in; "height" etc. now calculated using values of `id' rather than by counting observations
// minor change to ProcessColumns to ensure "95% CI" (in _EFFECT varlabel) is not broken across lines
// upversioned to match with -metan-

* version 4.01  David Fisher  12feb2021
// minor change to behaviour of -extraline()- and -lcolscheck-
// fixed bug in -favours()- which sometimes caused quotes to appear in plot
// improvements to code so that earlier versions of Stata do not truncate plot macros
//  (thanks to Daniel Klein for assistance with testing of earlier versions)

* version 4.02  David Fisher  23feb2021
// No changes to -forestplot- code; upversioned to match with -metan-

* version 4.03  David Fisher  28apr2021
// fixed automated choice of x-axis with proportions with denominator(#)
// now catches extreme cases where `DXmin' or `DXmax' are missing
// only implement lalign() if 15.1+ , following user reports that fails with 15.0
// corrected bug which failed to show diamonds correctly if off-scale

* version 4.04  David Fisher  16aug2021
// added prefix() option

* version 4.05  David Fisher  29nov2021
// fixed bug preventing plotid() and dataid() being specified together
// added ability to modify "border line" between the data and the column headings
// new option "nooverlay" in two new places:
//  - for drawing weighted boxes on top of conf. ints. (instead of default = overlaying CIs on top of boxes)
//  - for drawing data (boxes, CIs etc.) on top of null and/or overall line(s)

* version 4.06  David Fisher  12oct2022
// new option "sepline" for drawing prediction interval lines separately (below) confidence interval lines instead of straddling them

* version 4.07  David Fisher  15sep2023
// no changes; upversioned to v4.07 alongside metan.ado

*! version 4.08  David Fisher  17jun2024
// Q heterogeneity p-value now shows in forestplot as "< 0.001" rather than "= 0.000"
// right-alignment of columns in -forestplot- now done via mlabpos() rather than explicit indentation
// works with metan v4.07+ : new value _USE==7 defining prediction intervals
// fixed bug whereby matname `usedims' might be misinterpreted by Stata as a varname, leading to error
// fixed bug whereby untransformed proportions led to forestplot expecting _Prop_ES etc. rather than _ES, leading to error
// improvements to ocilineopts() and rfcilineopts()
// text printed to screen no longer includes "use() labels() wgt() by()" if these options are empty
// `colsonly' option moved out of beta and fully documented


program define forestplot, sortpreserve rclass

	version 11.0		// needs v11 for SMCL in graphs

	// June 2018 [updated Oct 2018]: check for "useopts", which recreates previous -metan- (or ipdmetan/ipdover) call
	syntax [varlist(numeric max=5 default=none)] [if] [in] [, USEOPTs * ]
	local graphopts `"`options'"'

	local usevlist `varlist'
	local useifin  `if' `in'

	if `"`useopts'"'!=`""' {
		local orig_gropts : copy local graphopts
	
		local fpusevlist : char _dta[FPUseVarlist]
		local fpuseifin : char _dta[FPUseIfIn]
		local fpuseopts : char _dta[FPUseOpts]

		if `"`fpusevlist'`fpuseifin'`fpuseopts'"'==`""' {
			nois disp as err `"No stored {bf:forestplot} options found"'
			exit 198
		}
	
		// varlist and if/in:  if supplied directly, overwrite characteristics
		if `"`usevlist'"'==`""' local usevlist `fpusevlist'
		if `"`useifin'"'==`""'  local useifin  `fpuseifin'

		local fpcmdline = trim(itrim(`"forestplot `usevlist' `if' `in', `fpuseopts' `graphopts'"'))
		nois disp as text `"Full command line as defined by {bf:useopts} is as follows:"'
		nois disp as res `"  `fpcmdline'"'
		nois disp as text `"(Note: any or all of this information may be over-ridden by other options;"'
		nois disp as text `" in general only the rightmost of any repeated options will be honoured, but see {help repeated_options})"'
	}

	// Nov 2018: note that -syntax- is *leftmost*, not rightmost; so `graphopts' must come first to overrule `fpuseopts'
	local 0 `"`usevlist' `useifin', `graphopts' `fpuseopts'"'
	
	// June 2018: main parse
	syntax [varlist(numeric max=5 default=none)] [if] [in] [, WGT(varname numeric) USE(varname numeric) PREfix(name local) ///
		///
		/// /* General user-specified -forestplot- options */
		BY(varname) EFORM EFFect(string asis) LABels(varname string) DP(integer 2) KEEPAll USESTRICT /*(undocumented)*/ ///
		INTERaction LCols(namelist) RCols(namelist) LEFTJustify COLSONLY RFDIST(varlist numeric min=2 max=2) RFLevel(passthru) ///
		NULLOFF noNAmes noNULL NULL2(string) noKEEPVars noOVerall noSUbgroup noSTATs noWT noHET LEVEL(passthru) ILevel(passthru) OLevel(passthru) ///
		XTItle(passthru) /*FAVours(passthru)*/ /// /* N.B. -xtitle- is parsed here so that a blank title can be inserted if necessary */
		CUmulative INFluence /*PRoportion*/ DENOMinator(passthru) /// /* undocumented; passed through from -metan-; needed in order to implement "hide" option... */
		/// /* ...and to control default null line/x-axis (e.g. for proportion/influence)
		/// /* Sub-plot identifier for applying different appearance options, and dataset identifier to separate plots */
		PLOTID(string) DATAID(string) ///
		///
		TEXTSize(passthru) /// /* legacy -metan9- option, implemented here as a post-hoc option; use at own risk */
		/// /* "fine-tuning" options */
		SAVEDIms(name) USEDIms(name) ASText(real -9) noADJust ///
		noPREFIXWARN ///	/*(undocumented; suppress "using default varlist" message if passing directly from -metan- using prefix()*/
		KEEPXLabs * ]		/*(undocumented; colsonly option)*/

	local graphopts `"`options'"'			// "graph region" options (also includes plotopts for now)		
	marksample touse, novarlist				// do this immediately, so that -syntax- can be used again
	
	
	** N.B. Parts of this early setup may repeat work already done by calling program (e.g. -metan- )
	//  but hopefully the extra overhead is negligible

	// Set up variable names
	if `"`varlist'"'!=`""' {
		tokenize `varlist'
		if `"`4'"'!=`""' {
			nois disp as err `"Syntax has changed as of ipdmetan v2.0 09may2017"'
			nois disp as err `"{bf:_WT} and {bf:_USE} should now be specified using options {bf:wgt()} and {bf:use()}"'
			exit 198
		}
		if `"`2'"'==`""' | `"`3'"'==`""' {
			nois disp as err `"{it:varlist} detected but with too few members; syntax is {it:es lci uci}"'
			exit 198
		}		
	}
	else {		// if not specified, assume "standard" varnames
		if `"`denominator'"'==`""' {
			local varlist `prefix'_ES `prefix'_LCI `prefix'_UCI
			if `"`prefixwarn'"'==`""' nois disp as text `"Note: no {it:varlist} specified; using default {it:varlist}"' as res `" {bf:`varlist'}"'
		}
		else {
			local varlist `prefix'_Prop_ES `prefix'_Prop_LCI `prefix'_Prop_UCI		// August 2023
			if `"`prefixwarn'"'==`""' {
				nois disp as text `"Note: no {it:varlist} specified; using default {it:varlist}"' as res `" {bf:`varlist'}"'
				nois disp as text `" due to option {bf:denominator(}{it:#}{bf:)} being specified"'
			}
			foreach x in Prop_ES Prop_LCI Prop_UCI {
				cap confirm var `prefix'_`x'
				if _rc {
					if `"`prefixwarn'"'==`""' {
						nois disp as text `"Note: expected to find variable "' as res `"{bf:`prefix'_`x'}"' as text `", but failed;"'
						nois disp as text `"assuming proportions pooled on untransformed scale using variables "' as res `"{bf:`prefix'_ES}, {bf:`prefix'_LCI}, {bf:`prefix'_UCI}"'
					}
					local varlist `prefix'_ES `prefix'_LCI `prefix'_UCI				// March 2024
					continue, break
				}
			}
		}
		tokenize `varlist'
	}
	args _ES _LCI _UCI
	foreach x in _ES _LCI _UCI {
		confirm numeric var ``x''
	}

	// Set up data sample to use
	local _USE `use'
	if `"`use'"'==`""' {
		cap confirm numeric var `prefix'_USE
		if !_rc {
			if `"`prefixwarn'"'==`""' {
				nois disp as text `"Note: option {bf:use(}{it:varname}{bf:)} not specified; using default {it:varname}"' as res `" {bf:`prefix'_USE}"'
			}
			local _USE `prefix'_USE
		}
		else {
			if _rc!=7 {			// if _USE does not exist
				tempvar _USE
				qui gen byte `_USE' = cond(missing(`_ES', `_LCI', `_UCI'), 2, 1)
				nois disp as text `"Note: default variable"' as res `" {bf:`prefix'_USE} "' as text `"not found; all included observations will be assumed to contain study estimates"'
			}
			else {
				nois disp as err `"Default variable {bf:`prefix'_USE} exists but is not numeric"'
				exit 198
			}
		}
	}
	confirm numeric variable `_USE'
	markout `touse' `_USE'		// observations for which _USE is missing

	qui replace `touse' = 0 if inlist(`_USE', 3, 4) & `"`subgroup'"'!=`""'
	qui replace `touse' = 0 if `_USE' == 4 & `"`het'"'!=`""'
	qui replace `touse' = 0 if `_USE' == 5 & `"`overall'"'!=`""'	
	// qui replace `touse' = 0 if inlist(`_USE', 3, 5) & missing(`_ES') & `"`stats'"'!=`""' & `"`rfdist'"'!=`""'
	qui replace `touse' = 0 if `_USE' == 7 & `"`stats'"'!=`""' & `"`rfdist'"'!=`""'
	
	if `"`keepall'"'==`""' qui replace `touse' = 0 if `_USE'==2		// "keepall" option (see -metan-)
	qui count if `touse'
	if !r(N) {
		nois disp as err "no observations"
		exit 2000
	}
	// return scalar obs = r(N)
	// Jan 2020: do this later, after BuildPlotCmds, in case of "hidden" pooled observations

	// Check that UCI is greater than LCI
	cap assert `_UCI' > `_LCI' if `touse' & !missing(`_UCI') & !(float(`_LCI')==float(`_ES') & float(`_ES')==float(`_UCI'))
	if _rc {
		nois disp as err "Error in confidence interval data; please check the following observations:"
		nois list `_USE' `_LCI' `_UCI' if `touse' & !missing(`_UCI') & !(`_UCI' > `_LCI') & !(float(`_LCI')==float(`_ES') & float(`_ES')==float(`_UCI'))
		exit 198
	}		

	// Weighting variable
	local _WT `wgt'
	if `"`wgt'"'==`""' {
		cap confirm numeric var `prefix'_WT
		if !_rc {
			if `"`prefixwarn'"'==`""' {
				nois disp as text `"Note: option {bf:wgt(}{it:varname}{bf:)} not specified; using default {it:varname}"' as res `" {bf:`prefix'_WT}"'
			}
			local _WT `prefix'_WT
		}
		else {
			if _rc!=7 {			// if _WT does not exist
				tempvar _WT
				qui gen byte `_WT' = 1 if `touse' & inlist(`_USE', 1, 3, 5)		// generate as constant if doesn't exist
				nois disp as text `"Note: default variable"' as res `" {bf:`prefix'_WT} "' as text `"not found; all observations will have equal weights"'
				local wt nowt						// don't display as text column
			}
			else {
				nois disp as err `"Default variable {bf:`prefix'_WT} exists but is not numeric"'
				exit 198
			}
		}
	}
	confirm numeric variable `_WT'

	// Check existence of `labels' (string) and `by' (should really be numeric but doesn't actually matter)
	foreach x in labels by {
		local X = upper("`x'")
		if `"``x''"'!=`""' local _`X' ``x''
		else {
			cap confirm var `prefix'_`X'
			if !_rc {
				local _`X' `prefix'_`X'		// use default varnames if they exist and option not explicitly given
				if "`x'"=="labels" {		// don't print message r.e. `by' as it is only used in a minor way by -forestplot-
					if `"`prefixwarn'"'==`""' {
						nois disp as text `"Note: option {bf:labels(}{it:varname}{bf:)} not specified; using default {it:varname}"' as res `" {bf:`prefix'_LABELS}"'
					}
				}
			}
			
			// Jan 2019
			else if "`x'"=="labels" {
				nois disp as text `"Note: option {bf:labels(}{it:varname}{bf:)} not specified and default {it:varname} {bf:`prefix'_LABELS} not found; observations will be unlabelled"'
				local names nonames
			}
		}
	}
	if `"`_LABELS'"'!=`""' {
		confirm string var `_LABELS'
	}
	if `"`_BY'"'!=`""' {
		confirm var `_BY'
	}

	// Check validity of `_USE' (already sorted out existence)
	//  if `usestrict'; otherwise responsibility is with user
	if `"`usestrict'"'!=`""' {
		tempvar flag
		qui gen byte `flag' =      `touse' & `_USE'==1 &  missing(`_ES', `_LCI', `_UCI', `_WT')
		qui replace  `flag' = 1 if `touse' & `_USE'==2 & !missing(`_ES', `_LCI', `_UCI')
		if `"`names'"'==`""' {		// Jan 2019
			qui replace  `flag' = 1 if `touse' & `_USE'==6 & !missing(`_LABELS')
		}
		qui replace  `flag' = 1 if `touse' & inlist(`_USE', 2, 6) & !missing(`_WT') & `"`wt'"'==`""'
		qui replace  `flag' = 1 if `touse' & `_USE' > 6 & !missing(`_USE')
		qui count if `flag'
		if r(N) {
			nois disp as err `"The following observations are inconsistent with {bf:_USE}:"'
			nois list `_USE' `_LABELS' `_ES' `_LCI' `_UCI' `_WT' if `flag'
			exit 198
		}
		qui drop `flag'
	}
	
	
	// Sort out `dataid' and `plotid'
	tempvar obs touse2
	qui gen long `obs' = _n

	// local nd=1
	local 0 `dataid'
	syntax [varname(default=none)] [, NEWwt]
	if `"`varlist'"'!=`""' {
		cap tab `varlist' if `touse', m
		if _rc {
			nois disp as err `"error in option {bf:dataid()}"'
			qui tab `varlist' if `touse', m
		}

		if `"`newwt'"'==`""' local dataid `varlist'
		else {
			qui gen byte `touse2' = `touse' * inlist(`_USE', 1, 2, 3, 5, 7)
			
			local dataid
			tempvar dtobs dataid					// create ordinal version of dataid
			qui bysort `touse2' `varlist' (`obs') : gen long `dtobs' = `obs'[1] if `touse2'
			qui bysort `touse2' `dtobs' : gen long `dataid' = (_n==1) if `touse2'
			qui replace `dataid' = sum(`dataid') if `touse2'
			label variable `dataid' "dataid"
		}
	}
	
	if `"`plotid'"'==`""' {
		tempvar plotid
		qui gen byte `plotid' = 1 if `touse'	// create plotid as constant if not specified; this makes BuildPlotCmds much easier
	}
	else {
		disp _n _c								// spacing, in case following on from ipdmetan (etc.)
		cap confirm var `prefix'_OVER
		local _OVER = cond(_rc, `""', `"`prefix'_OVER"')
		
		local 0 `plotid'
		syntax name(name=plname id="plotid") [, List noGRaph]
		local plotid		// clear macro; will want to define a tempvar named plotid

		if "`plname'"!="_n" {
			confirm var `plname'
			cap tab `plname' if `touse', m
			if _rc {
				nois disp as err `"error in option {bf:plotid()}"'
				qui tab `plname' if `touse', m
			}
			if `"`_OVER'"'==`""' {
				qui count if `touse' & inlist(`_USE', 1, 2) & missing(`plname')
				if r(N) {
					nois disp as err `"Warning: variable {bf:`plname'} (in option {bf:plotid()}) contains missing values"'
					nois disp as err `"{bf:plotid()} groups and/or allocated numeric codes may not be as expected"'
					if "`list'"=="" nois disp as err `"This may be checked using the {bf:list} suboption to {bf:plotid()}"'
				}
			}
		}
		
		* Create ordinal version of plotid...
		// tempvar touse2
		cap confirm variable `touse2'
		if _rc {
			qui gen byte `touse2' = `touse' * inlist(`_USE', 1, 2, 3, 5, 7)
		}
		// local plvar `plname'

		// ...extra tweaking if passed through from (ad)metan/ipdmetan/ipdover (i.e. _STUDY, and possibly _OVER, exists)
		if inlist("`plname'", "_STUDY", "_n", "_LEVEL", "_OVER") {
			cap confirm var `prefix'_STUDY
			local _STUDY = cond(_rc, `"`prefix'_LEVEL"', `"`prefix'_STUDY"')
			tempvar smiss
			qui gen byte `smiss' = missing(`_STUDY')
			
			if inlist("`plname'", "_STUDY", "_n") {
				tempvar plvar
				qui bysort `touse2' `smiss' (`_OVER' `_STUDY') : gen long `plvar' = _n if `touse2' & !`smiss'
			}
			else if "`plname'"=="_LEVEL" {
				tempvar plvar
				qui bysort `touse2' `smiss' `_BY' (`_OVER' `_STUDY') : gen long `plvar' = _n if `touse2' & !`smiss'
			}
			else local plvar `prefix'_OVER
		}
		else local plvar `plname'
		
		tempvar plobs plotid
		qui bysort `touse2' `smiss' `plvar' (`obs') : gen long `plobs' = `obs'[1] if `touse2'
		qui bysort `touse2' `smiss' `plobs' : gen long `plotid' = (_n==1) if `touse2'
		qui replace `plotid' = sum(`plotid') if `touse2'
		local np = `plotid'[_N]					// number of `plotid' levels (N.B. `plotid' is guaranteed to be ordinal)
		label variable `plotid' "plotid"
		
		* Optionally list observations contained within each plotid group
		if "`list'" != "" {
			sort `obs'
			nois disp as text _n "plotid: observations marked by " as res "`plname'" as text ":"
			forvalues p=1/`np' {
				nois disp as text _n "-> plotid = " as res `p' as text ":"
				nois list `dataid' `_USE' `_BY' `_OVER' `_LABELS' if `touse2' & `plotid'==`p', table noobs sep(0)
			}
			if `"`graph'"'!=`""' exit
		}
		qui drop `touse2' `plobs' `smiss'
	}
	// qui drop `obs'	// don't drop yet; use again later
	
	// Parse eform option and finalise "effect" text
	cap nois CheckOpts, soptions opts(`eform' `graphopts')
	if _rc {
		if _rc==1 nois disp as err "User break"
		else nois disp as err `"Error in {bf:forestplot.CheckOpts}"'
		c_local err noerr		// tell calling subroutine not to also report an error
		exit _rc
	}
	local eform `"`s(eform)'"'			// either "eform" or nothing
	local graphopts `"`s(options)'"'

	if `"`effect'"'==`""' {
		// amended Feb 2018 due to local x = "" issue with version <13
		// local effect = cond(`"`r(effect)'"'=="", "Effect", `"`r(effect)'"')
		local effect `"`s(effect)'"'
		if `"`effect'"'==`""'      local effect "Effect"
		if `"`interaction'"'!=`""' local effect `"Interact. `effect'"'
	}

	// May 2020: significance levels
	// If a -metan- results set is used, specifying level() is unnecessary
	//  as the relevant values will be taken from variable characteristics
	// But levels can be specified manually if necessary.
	if `"`level'"'!=`""' {
		if `"`ilevel'"'!=`""' {
			nois disp as err "Cannot specify both {bf:level()} and {bf:ilevel()}"
			exit 184
		}
		if `"`olevel'"'!=`""' {
			nois disp as err "Cannot specify both {bf:level()} and {bf:olevel()}"
			exit 184			
		}
		local ilevel : copy local level
		local olevel : copy local level
		local level
	}	
	local 0 `", `olevel'"'
	syntax [, OLevel(cilevel) ]
	
	* Default placing of labels, effect sizes and weights:
	// unless noSTATS and/or noWT, effect sizes and weights are first two elements of `rcols'
	if `"`eform'"'!=`""' local xexp exp
	if `"`stats'"'==`""' {
	
		// determine format
		summ `_UCI' if `touse', meanonly
		local fmtx = max(1, ceil(log10(abs(`xexp'(r(max)))))) + 1 + `dp'
	
		if `"`keepvars'"'!=`""' tempvar _EFFECT
		else {
			cap drop `prefix'_EFFECT
			local _EFFECT `prefix'_EFFECT
		}
		qui gen str `_EFFECT' = string(`xexp'(`_ES'), `"%`fmtx'.`dp'f"') if !missing(`_ES')
		qui replace `_EFFECT' = `_EFFECT' + " " if !missing(`_EFFECT')
		qui replace `_EFFECT' = `_EFFECT' + "(" + string(`xexp'(`_LCI'), `"%`fmtx'.`dp'f"') + ", " + string(`xexp'(`_UCI'), `"%`fmtx'.`dp'f"') + ")"
		qui replace `_EFFECT' = `""' if !(`touse' & inlist(`_USE', 1, 3, 5, 7))
		qui replace `_EFFECT' = "(Insufficient data)" if `touse' & `_USE'==2
		
		// March 2020:  extra lines to handle "empty" subgroups, and single-study subgroups with `influence'
		qui replace `_EFFECT' = "(Insufficient data)" if `touse' & inlist(`_USE', 3, 5) & missing(`_LCI')
		qui replace `_EFFECT' = "(Insufficient data)" if `touse' & `_USE'==1 & missing(`_LCI') & `"`influence'"'!=`""'

		local f = abs(fmtwidth("`: format `_EFFECT''"))
		format `_EFFECT' %-`f's		// left-justify
		
		// variable label
		if `"`effect'"' == `""' {
			local effect = cond("`interaction'"!="", "Interaction effect", "Effect")
		}
		if `"`ilevel'"'==`""' {
			local lciLevel : char `_LCI'[Level]
			local uciLevel : char `_UCI'[Level]
			if `"`lciLevel'"'!=`""' & `"`uciLevel'"'!=`""' & `"`lciLevel'"'!=`"`uciLevel'"' {
				nois disp as err "Conflicting confidence limit coverages"
				exit 198
			}
			local ilevel `lciLevel'
			if `"`ilevel'"'==`""' local ilevel `uciLevel'
		}
		if `"`ilevel'"'==`""' {		// if `ilevel' manually specified, use it in preference to the value stored in the variable characteristics
			local 0 `", `ilevel'"'
			syntax [, ILevel(cilevel) ]
		}
		label variable `_EFFECT' `"`effect' (`ilevel'% CI)"'
	}
	if `"`names'"'==`""' local lcols `_LABELS' `lcols'		// unless noNAMES specified, add `_LABELS' to `lcols'
	if "`wt'" == "" local rcols `_WT' `rcols'				// unless noWT specified, add `_WT' to `rcols'
	local rcols `_EFFECT' `rcols'							// unless noSTATS specified, add `_EFFECT' to `rcols'			

	// finalise lcols and rcols
	foreach x of local lcols {
		cap confirm var `x' 
		if _rc {
			nois disp as err `"variable {bf:`x'} not found in option {bf:lcols()}"'
			exit _rc
		}
	}
	foreach x of local rcols {
		cap confirm var `x' 
		if _rc {
			nois disp as err `"variable {bf:`x'} not found in option {bf:rcols()}"'
			exit _rc
		}
	}
	local lcolsN : word count `lcols'
	local rcolsN : word count `rcols'

	// [Revised May 2024 for v4.08]
	// `colsonly' option expects exactly one of `lcolsN' or `rcolsN' to be nonzero
	if `"`colsonly'"'!=`""' {
		if !`lcolsN' & !`rcolsN' {
			disp as err `"Option {bf:colsonly} supplied with no columns of data; nothing to plot"'
			exit 2000
		}
		else if `lcolsN' & `rcolsN' {
			disp as err `"Option {bf:colsonly} requires either left-side or right-side data columns, but not both"'
			exit 198
		}
	}
	// Check that `keepxlabs' implies `colsonly';  so that later we may use `keepxlabs' in place of `colsonly' where appropriate
	else if `"`keepxlabs'"'!=`""' {
		disp as err `"Option {bf:keepxlabs} cannot be specified without {bf:colsonly}"'
		exit 198
	}
	
	
	** GET MIN AND MAX DISPLAY
	// [comments from _dispgby subroutine of metan.ado follow]
	// SORT OUT TICKS- CODE PINCHED FROM MIKE AND FIDDLED. TURNS OUT I'VE BEEN USING SIMILAR NAMES...
	// AS SUGGESTED BY JS JUST ACCEPT ANYTHING AS TICKS AND RESPONSIBILITY IS TO USER!
	
	// N.B. `DXmin', `DXmax' are the left and right co-ords of the graph part
	// These are NOT NECESSARILY the same as the limits of xlabels, xticks etc.
	// In particular, if range() is specified then DXmin, DXmax == range;  regardless of xlabels, xticks etc.
	
	// First, sort out null-line
	local h0 = 0							// default
	
	// if `"`null2'"'!=`""' local nullopt `"null(`null2')"'	
	// Amended Jan 2020
	if inlist(trim("`null2'"), "none", "off") local nullopt `"null(`null2')"'
	opts_exclusive `"`nulloff' `null' `nullopt'"'

	if `"`nulloff'"'!=`""' local null nonull
	// "nulloff" and "nonull" are permitted alternatives to null(none|off),
	//  for compatibility with previous versions of -metan-
	
	else if `"`null2'"'!=`""' {
		if inlist("`null2'", "none", "off") local null nonull
		else {
			cap nois numlist "`null2'", min(1) max(1)
			if _rc {
				disp as err "error in {bf:null()} option"
				exit _rc
			}
			// local h0 = `null2'
			// May 2020: null2() should be given on same scale as xlabels, to match with fp()
			local h0 = cond(`"`eform'"'!=`""', ln(`null2'), `null2')
			
			if "`null'"!="nonull" local null
		}
	}
	if `"`influence'`denominator'"'!=`""' & inlist(trim("`null2'"), "", "none", "off") local null nonull
	// N.B. `null' now either contains nothing, or "nonull"
	//  and `h0' contains a number (defaulting to 0), denoting where the null-line will be placed if "`null'"==""
	// If `influence' or proportion (i.e. `denominator'), "nonull" is the default unless null2(#) is supplied.
	
	// Now find DXmin, DXmax; xticklist, xlablist, xlablim1
	summ `_LCI' if `touse', meanonly
	local DXmin = r(min)				// minimum confidence limit
	summ `_UCI' if `touse', meanonly
	local DXmax = r(max)				// maximum confidence limit

	if `"`rfdist'"'!=`""' {
		tokenize `rfdist'
		args _rfLCI _rfUCI

		if `"`rflevel'"'==`""' {
			local lciRFLevel : char `_rfLCI'[RFLevel]
			local uciRFLevel : char `_rfUCI'[RFLevel]
			if `"`lciRFLevel'"'!=`""' & `"`uciRFLevel'"'!=`""' & `"`lciRFLevel'"'!=`"`uciRFLevel'"' {
				nois disp as err "Conflicting confidence limit coverages for predictive interval"
				exit 198
			}
			local rflevel `lciRFLevel'
			if `"`rflevel'"'==`""' local rflevel `uciRFLevel'
		}
		if `"`rflevel'"'==`""' {		// if `rflevel' manually specified, use it in preference to the value stored in the variable characteristics
			local 0 `", `rflevel'"'
			syntax [, RFLevel(cilevel) ]
		}
		
		// Note, May 2020: if `rflevel' < `olevel' and low heterogeneity, then (rfLCI, rfUCI) might be tighter than (LCI, UCI)
		cap {
			assert missing(`_rfLCI', `_rfUCI') if `touse' & !inlist(`_USE', 3, 5, 4, 7)
			assert float(`_rfLCI') <= float(`_LCI') if `touse' & !missing(`_rfLCI', `_LCI') & float(`rflevel')>=float(`olevel')
			assert float(`_rfUCI') >= float(`_UCI') if `touse' & !missing(`_rfUCI', `_UCI') & float(`rflevel')>=float(`olevel')
		}
		if _rc {
			nois disp as err "Error in predictive interval data"
			exit 198
		}
	
		summ `_rfLCI' if `touse', meanonly		// N.B. unnecessary if passed thru from -metan-, since included in `_LCI'/`_UCI'
		local DXmin = min(`DXmin', r(min))		//  but need to do it anyway 
		summ `_rfUCI' if `touse', meanonly
		local DXmax = max(`DXmax', r(max))
		
		if `"`stats'"'==`""' {
			// Generate `rfdindent' to send to -ProcessColumns-
			// strwid is width of "_ES[_n-1]" as formatted by "%`fmtx'.`dp'f" so it lines up
			tempvar rfindent
			qui gen `rfindent' = string(`xexp'(`_ES'[_n-1]), `"%`fmtx'.`dp'f"') if `touse' & `_USE'==7
			/*
			qui gen `rfindent' = cond(`touse' * missing(`_ES') * !missing(`_rfLCI', `_rfUCI'), ///
				string(`xexp'(`_ES'[_n-1]), `"%`fmtx'.`dp'f"'), `""')
			*/
			
			// Find which column effect sizes (including predictive distribution limits) should appear in, to apply rfindent
			local rfcol=1
			while `"`: word `rfcol' of `rcols''"'!=`"_EFFECT"' & `rfcol' <= `rcolsN' {
				local ++rfcol
			}
			
			local rfcolopts `"rfindent(`rfindent') rfcol(`rfcol')"'
		}
		else {
			disp as err "Note: options {bf:rfdist} and {bf:nostats} specified together;"
			disp as err " predictive intervals will be presented graphically but will not appear in text columns"
		}
	}
	
	// March 2021: handle extreme case
	if missing(`DXmin') | missing(`DXmax') {
		summ `_ES' if `touse', meanonly
		if r(N) {
			if missing(`DXmin') local DXmin = r(min)
			if missing(`DXmax') local DXmax = r(max)
		}
		else {
			if missing(`DXmin') local DXmin = `h0'
			if missing(`DXmax') local DXmax = `h0'
		}
	}	
	
	cap nois ProcessXAxis `DXmin' `DXmax', `eform' h0(`h0') `null' `denominator' `colsonly' `graphopts'
	if _rc {
		if _rc==1 nois disp as err `"User break in {bf:forestplot.ProcessXAxis}"'
		nois disp as err `"Error in {bf:forestplot.ProcessXAxis}"'
		c_local err noerr		// tell calling program (e.g. -metan- ) not to also report an error
		exit _rc
	}
	if "`twowaynote'"!="" c_local twowaynote notwowaynote	// so that -metan- does not print an additional message regarding "xlabel" or "force"
	
	local CXmin = r(CXmin)		// limits of data plotting (i.e. off-scale arrows)... = DX by default
	local CXmax = r(CXmax)
	local DXmin = r(DXmin)		// limits of data plot region
	local DXmax = r(DXmax)
	
	return local range `"`DXmin' `DXmax'"'
	
	local xtitleval = r(xtitleval)	// position of xtitle [May 2024: not currently implemented]

	// May 2024
	local graphopts `"`r(xlabopt2)' `r(xlabopt)' `r(xmlabopt2)' `r(xmlabopt)' `r(favopt)' `r(xtickopt2)' `r(xtickopt)' `r(xmtickopt2)' `r(xmtickopt)' `r(options)'"'
	
	// Nov 2017
	local null      `"`r(null)'"'
	local rowsxlab  = r(rowsxlab)
	local rowsxmlab = r(rowsxmlab)
	local rowsfav   = r(rowsfav)
	
	
	** Need to make changes to pre-existing data now
	// e.g. adding new obs to the dataset to contain multi-line column headings
	//  so use -preserve-
	preserve

	// [added Nov 2018]
	// Make data obey the conventions of _USE
	qui replace `_USE' = 6 if !inrange(`_USE', 0, 7) & `touse'
	qui replace `_ES' = .  if `touse' & `_USE'==2
	qui replace `_LCI' = . if `touse' & `_USE'==2
	qui replace `_UCI' = . if `touse' & `_USE'==2
	if `"`names'"'==`""' {
		qui replace `_LABELS' = "" if `touse' & `_USE'==6
	}
	qui replace `_WT' = . if `touse' & inlist(`_USE', 2, 6) & `"`wt'"'==`""'
			
	
	* Find `lcimin' = left-most confidence limit among the "diamonds" (including predictive intervals)
	* (Note: this is *only* used within the `adjust' subroutine within ProcessColumns)
    tempvar lci2
	qui gen `lci2' = cond(`"`null'"'==`""', cond(`_LCI'>`h0', `h0', ///
		cond(`_LCI'>`CXmin', `_LCI', `CXmin')), cond(`_LCI'>`CXmin', `_LCI', `CXmin'))
	if `"`rfdist'"'!=`""' {
		qui replace `lci2' = cond(`"`null'"'==`""', cond(`_rfLCI'>`h0', `h0', ///
			cond(`_rfLCI'>`CXmin', `_rfLCI', `CXmin')), cond(`_rfLCI'>`CXmin', `_rfLCI', `CXmin'))
	}
	summ `lci2' if `touse' & inlist(`_USE', 3, 5, 7), meanonly
	local lcimin = cond(r(N), r(min), cond(`"`null'"'==`""', `h0', `CXmin'))
	drop `lci2'	

	* Unpack `usedims'
	local DXwidthChars = -9			// initialize
	if `"`usedims'"'!=`""' {
		cap confirm matrix `usedims'
		if _rc {
			nois disp as err "Error in option {bf:usedims()}: " _c
			confirm matrix `usedims'
		}
		
		local DXwidthChars = `usedims'[1, `=colnumb(matrix(`usedims'), "cdw")']
		confirm number `DXwidthChars'
		assert `DXwidthChars' >= 0

		local oldLCImin = `usedims'[1, `=colnumb(matrix(`usedims'), "lcimin")']
		confirm number `oldLCImin'		// can be <0
		local lcimin = min(`lcimin', `oldLCImin')
	}

	// Pass exactly one of `DXwidthChars' or `astext' to ProcessColumns
	// (if specified, `astext' trumps `DXwidthChars')
	if `"`usedims'"'!=`""' & `astext'==-9 {
		local astextopt `"dxwidthchars(`DXwidthChars')"'
	}
	else {
		local astext = cond(`astext'==-9, 50, `astext')
		cap assert `astext' > 0
		if _rc {
		    nois disp as err "error in option {bf:astext(}{it:#}{bf:)}: {it:#} must be in the range (0, 100]"
			exit 125
		}		
		local astextopt `"astext(`astext')"'
	}
	

	** Generate ordering variable (reverse sequential, since y axis runs bottom to top)
	// Need to do this *before* extra obs are added by ProcessColumns to hold title text
	// Apr 2020: furthermore, sort such that `touse' obs come *first* ... so need to sort on "negated" `touse'
	tempvar touse_neg id
	qui gen byte `touse_neg' = 1 - `touse'
	qui bysort `touse_neg' (`obs') : gen long `id' = _N - _n + 1 if `touse'
	drop `touse_neg'
	
	
	
	************************
	* LEFT & RIGHT COLUMNS *
	************************
	
	// Setup: generate tempvars to send to ProcessColumns
	foreach xx in left right {
		local x = substr("`xx'", 1, 1)		// extract "l" from "left" and "r" from "right"

		forvalues i=1/``x'colsN' {		// N.B. if `lcolsN' or `rcolsN'==0, this loop will be skipped
			tempvar `xx'`i'
			local `x'vallist ``x'vallist' ``xx'`i''			// store x-axis positions of columns
				
			local `x'coli : word `i' of ``x'cols'
			local f : format ``x'coli'
			tokenize `"`f'"', parse("%~s.,")
			if "`2'"=="~" {									// Modified Aug2023 to handle centered format
				confirm number `3'
				if `"`leftjustify'"'!=`""' local flen = -abs(`3')
				else local flen `2'`3'
			}
			else {
				confirm number `2'
				local flen = `2'
				if `"`leftjustify'"'!=`""' local flen = -abs(`2')
			}
			
			cap confirm string var ``x'coli'
			if !_rc local `xx'LB`i' : copy local `x'coli	// if string
			else {											// if numeric
				tempvar `xx'LB`i'
				if `"`: value label ``x'coli''"'!=`""' {	// if labelled (10th July 2017)
					qui decode ``x'coli', gen(``xx'LB`i'')
				}
				else qui gen str ``xx'LB`i'' = string(``x'coli', "`f'")
				qui replace ``xx'LB`i'' = "" if ``xx'LB`i'' == "."
				
				local colName : variable label ``x'coli'
				// Removed v3.0.1 for consistency with string variables
				// Now -forestplot- consistently honours *blank* varlabels
				// if `"`colName'"' == "" & `"``x'coli'"' !=`"`labels'"' local colName = `"``x'coli'"'
				label variable ``xx'LB`i'' `"`colName'"'
			}
			
			local `x'lablist ``x'lablist' ``xx'LB`i''	// store contents (text/numbers) of columns
			local `x'fmtlist ``x'fmtlist' `flen'		// desired max no. of characters based on format
		}
		
		if !`lcolsN' {
			tempvar left1
			local lvallist `left1'
		}
		
		local `x'optlist `x'vallist(``x'vallist') `x'lablist(``x'lablist') `x'fmtlist(``x'fmtlist')
	}
		
	
	// niche case:  possible that user-specified `_USE' already contains values of 9 for some reason
	// if so, change them to 99 (doesn't matter what value they are as long as not 0 to 6, or 9)
	// (and we are under -preserve- )
	qui replace `_USE' = 99 if `touse' & `_USE'==9	
	
	local oldN = _N
	cap nois ProcessColumns `_USE' `_EFFECT' if `touse', id(`id') `wt' ///
		lrcolsn(`lcolsN' `rcolsN') lcimin(`lcimin') dx(`DXmin' `DXmax') ///
		`loptlist' `roptlist' `rfcolopts' `astextopt' `adjust' `colsonly' `graphopts'
	
	if _rc {
		if _rc==1 nois disp as err `"User break in {bf:forestplot.ProcessColumns}"'
		else nois disp as err `"Error in {bf:forestplot.ProcessColumns}"'
		c_local err noerr		// tell calling program (e.g. -metan- ) not to also report an error
		exit _rc
	}
	
	local leftWDtot = r(leftWDtot)
	local rightWDtot = r(rightWDtot)
	local astext = r(astext)

	local AXmin = r(AXmin)
	local AXmax = r(AXmax)
	if `"`colsonly'"'!=`""' {
		if       `lcolsN' & !`rcolsN' local AXmax = `DXmin'
		else if !`lcolsN' &  `rcolsN' local AXmin = `DXmax'
		local AXval = (`AXmax' + `AXmin') / 2
	}
	
	// June 2023
	local lposlist `r(lposlist)'
	local rposlist `r(rposlist)'

	local graphopts `"`r(graphopts)'"'

	// Amended Apr 2020
	// New observations, added by ProcessColumns
	qui replace `touse' = 1 if missing(`touse') & !missing(`id')

	
	*** FIND OPTIMAL TEXT SIZE AND ASPECT RATIOS (given user input)
	// We already have an estimate of the height taken up by x-axis labelling (this is `rowsxlab' from ProcessXAxis)
	// Next, find basic height to send to GetAspectRatio
	// Apr 2020: Note that this was previously derived in terms of number of observations
	// but now we use `id' instead due to `double' option
	// qui count if `touse'
	// local height = r(N)
	summ `id' if `touse', meanonly
	if r(N) local height = r(max)
	else local height = 0
	

	// Jan 2020
	// need to account for observations which will ultimately *not* be displayed
	// i.e. either removed using "nooverall"/"nosubgroup"; or "hidden" using OCILineOpts
	local reduceHeight = 0
	if `"`overall'`subgroup'"'!=`""' {
		if `"`subgroup'"'!=`""' {
			qui count if `touse' & `_USE'==3
			local reduceHeight = r(N)
		}
		if `"`overall'"'!=`""' {
			qui count if `touse' & inlist(`_USE', 4, 5, 7)
			local reduceHeight = `reduceHeight' + r(N)
		}
	}
	else if `"`cumulative'`influence'"'!=`""' {
		// `cumulative' or `influence' implies "hide"
		qui count if `touse' & inlist(`_USE', 3, 5, 7)
		local reduceHeight = r(N)
	}
	else {			// user-specified "hide"
		UserSpecHide `_USE' if `touse', plotid(`plotid') `graphopts'
		local reduceHeight = r(N)
	}
	local height = `height' - `reduceHeight'
	
	qui count if `touse' & `_USE'==9
	if r(N) local ++height				// add 1 to overall height if titles present, to account for the "gap" in `id' (see later)
		
	local colWDtot = `leftWDtot' + `rightWDtot'
	if `"`usedims'"'==`""' {
		local DXwidthChars = `colWDtot'*((100/`astext') - 1)
	}

	// height of "xmlabel" text is assumed to be ~60% of "xlabel" text ... unless favours which uses xmlabel differently!
	local rowsxlabval = cond(`rowsfav', `rowsxlab', max(`rowsxlab', .6*`rowsxmlab'))
	
	GetAspectRatio, astext(`astext') colwdtot(`colWDtot') height(`height') rowsxlab(`rowsxlabval') rowsfav(`rowsfav') ///
		usedims(`usedims') `xtitle' `textsize' `colsonly' `graphopts'

	local graphopts `"`r(graphopts)'"'

	local xsize = r(xsize)
	local ysize = r(ysize)
	local fxsize = r(fxsize)
	local fysize = r(fysize)
	local yheight = r(yheight)
	local spacing = r(spacing)
	local textSize = r(textsize)			// textsize as calculated by GetAspectRatio
	local textSize2 = r(textsize2)			// textsize as modified post-hoc by textscale() option [May 2020]
	local approxChars = r(approxchars)
	local graphAspect = r(graphaspect)
	local plotAspect = r(plotaspect)

	* If specified, store in a matrix the quantities needed to recreate proportions in subsequent forestplot(s)
	// [`lcimin' added Sep 2017; `height' added Nov 2017]
	if `"`savedims'"'!=`""' {
		mat `savedims' = `DXwidthChars', `spacing', `plotAspect', `ysize', `xsize', `textSize', `height', `yheight', `lcimin'
		mat colnames `savedims' = cdw spacing aspect ysize xsize textsize height yheight lcimin
	}

	* Insert labsize(`textSize2') into existing x[m]labopt(s)
	local 0 `", `graphopts'"'
	syntax [, XLAbel(string asis) XMLabel(string asis) * ]
	local graphopts `"`options'"'

	while trim(`"`xlabel'`xmlabel'"')!=`""' {
		foreach xop in xlabel xmlabel {
			if `"``xop''"'!=`""' {
				local 0 `"``xop''"'
				syntax [anything(name=xcmd)] , [LABSize(string) LABGAP(string) FAVOURS * ]

				// colsonly: now add in "dummy" value to x[m]label command
				if `"`colsonly'"'!=`""' {
					gettoken tok rest : xcmd
					if `"`tok'"'==`"__DUMMY__"' local xcmd `AXval' `rest'
				}
				if "`xop'"=="xlabel" {
					local labsizeopt labsize(`textSize2')
					local labgapopt
				}
				else {
					local labsize = cond(`"`favours'"'!=`""', `textSize2', .6*`textSize2')
					local labsizeopt labsize(`labsize')
					if `"`favours'"'!=`""' local labgapopt labgap(5)
				}
				local newopts `"`newopts' `xop'(`xcmd', `labsizeopt' `labgapopt' `options')"'
			}
		}

		// Test for repeated options and loop if necessary
		// Parse for "add" and discard repeated options if appropriate
		// so that later parsing and updating/replacing of "labsize()" is accurate
		local 0 `", `graphopts'"'
		syntax [, XLAbel(string asis) XMLabel(string asis) * ]
		local graphopts `"`options'"'
	}		// end while loop

	// local graphopts `"xsize(`xsize') ysize(`ysize') fxsize(`fxsize') fysize(`fysize') aspect(`plotAspect') `graphopts'"'
	// Modified Jan 2018: f{x|y}size only if usedims/savedims
	local graphopts `"xsize(`xsize') ysize(`ysize') aspect(`plotAspect') `newopts' `macval(graphopts)'"'
	if trim(`"`savedims'`usedims'"')!=`""' local graphopts `"fxsize(`fxsize') fysize(`fysize') `macval(graphopts)'"'
		
	// Return useful quantities
	return scalar aspect = `plotAspect'
	return scalar astext = `astext'
	return scalar ldw = `leftWDtot'			// display width of left-hand side
	return scalar rdw = `rightWDtot'		// display width of right-hand side
	// local DXwidthChars = cond(`"`usedims'"'!=`""', `DXwidthChars', `colWDtot'*((100/`astext') - 1))
	return scalar cdw = `DXwidthChars'		// display width of centre (i.e. the "data" part of the plot)
	return scalar height = `height'
	return scalar spacing = `spacing'
	return scalar ysize = `ysize'
	return scalar xsize = `xsize'
	return scalar textsize = `textSize2'		// May 2020: if -metan9- option textsize() was applied, returns "post-hoc modified" textsize....
	if trim(`"`savedims'`usedims'"')!=`""' {	// ... which may differ from the `textsize' value stored in matrix `savedims'
		return scalar fysize = `fysize'
		return scalar fxsize = `fxsize'
	}


	
	************************************
	* Build plot commands from options *
	************************************

	// Commands for plotting columns of text (lcols/rcols)
	forvalues i = 1/`lcolsN' {
		gettoken lpos`i' lposlist : lposlist
		local lcolCommands `"`macval(lcolCommands)' scatter `id' `left`i'' if `touse', msymbol(none) mlabel(`leftLB`i'') mlabcolor(black) mlabpos(`lpos`i'') mlabgap(0) mlabsize(`textSize2') ||"'
	}
	forvalues i = 1/`rcolsN' {
		gettoken rpos`i' rposlist : rposlist
		local rcolCommands `"`macval(rcolCommands)' scatter `id' `right`i'' if `touse', msymbol(none) mlabel(`rightLB`i'') mlabcolor(black) mlabpos(`rpos`i'') mlabgap(0) mlabsize(`textSize2') ||"'
	}	
	

	** Prepare tempvars...
	// ...for diamonds
	tempvar DiamX DiamY1 DiamY2
	local diamlist `DiamX' `DiamY1' `DiamY2'

	// ...for "overall effect" lines
	// Jan 2020: now including overall confidence limit lines
	tempvar ovLine ovMin ovMax ovLineLCI ovLineUCI ovLineX
	local ovlist `ovLine' `ovMin' `ovMax' `ovLineLCI' `ovLineUCI' `ovLineX'

	// ...for off-scale arrows
	tempvar offscaleL offscaleR
	local offsclist `offscaleL' `offscaleR'

	// ...for predictive intervals
	// Jan 2020: now including confidence limit lines
	if `"`rfdist'"'!=`""' {
		tempvar rfLoffscaleL rfLoffscaleR rfRoffscaleL rfRoffscaleR rfLineLCI rfLineUCI rfLineX
		local rflist `rfLoffscaleL' `rfLoffscaleR' `rfRoffscaleL' `rfRoffscaleR' `rfLineLCI' `rfLineUCI' `rfLineX'
	}
		
	// ...for multiple plotids and/or for area plots
	tempvar tousePlotID touseDiam touseOCI touseRFCI
	local tvopts `"diamlist(`diamlist') ovlist(`ovlist') offsclist(`offsclist') rflist(`rflist') touseextra(`tousePlotID' `touseDiam' `touseOCI' `touseRFCI')"'
	
	// August 2018: N.B. unusually, have to pass `touse' as an option here (rather than using marksample)
	// since we need to have the same tempname appearing in the created plot commands
	cap nois BuildPlotCmds `_USE' `_ES' `_LCI' `_UCI', touse(`touse') id(`id') ///
		plotid(`plotid') dataid(`dataid') `newwt' h0(`h0') `null' `colsonly' ///
		`cumulative' `influence' `interaction' `overall' `subgroup' `graphopts' ///
		wgt(`_WT') rfdist(`_rfLCI' `_rfUCI') cxlist(`CXmin' `CXmax') `tvopts'
	
	if _rc {
		if _rc==1 disp as err "User break"
		else disp as err `"Error in {bf:forestplot.BuildPlotCmds}"'
		c_local err noerr		// tell calling subroutine not to also report an error
		exit _rc
	}

	local RFPlot        `"`s(rfplot)'"'
	local PCIPlot       `"`s(pciplot)'"'
	local diamPlot      `"`s(diamplot)'"'
	local pointPlot     `"`s(pointplot)'"'
	local ppointPlot    `"`s(ppointplot)'"'
	local olineAreaPlot `"`s(olineareaplot)'"'
	local borderCommand `"`s(bordercommand)'"'

	local graphopts     `"`s(options)'"'
	
	// Nov 2021: see notes within BuildPlotCmds
	if `"`s(g_overlay_ci)'"'!=`""' {
		local firstPlot  `"`s(ciplot)'"'
		local secondPlot `"`s(scplot)'"'
	}
	else {		// current default
		local firstPlot  `"`s(scplot)'"'
		local secondPlot `"`s(ciplot)'"'
	}
	if `"`s(g_olinefirst)'"'!=`""' {
		local olinePlotFirst `"`s(olineplot)'"'
	}
	else local olinePlot     `"`s(olineplot)'"'
	if `"`s(g_nlinefirst)'"'!=`""' {
		local nullCommandFirst `"`s(nullcommand)'"'
	}
	else local nullCommand     `"`s(nullcommand)'"'
	

	qui count if `touse'
	if !r(N) {
		nois disp as err "no observations"
		exit 2000
	}
	return scalar obs = r(N)

	
	
	***************************
	***     DRAW GRAPH      ***
	***************************

	// First, if `useopts' and `graphopts' both supplied, check for repeated (non-Stata graph) options in `graphopts' which would cause -twoway- to fail
	//  (otherwise, onus is on user as usual)
	if `"`useopts'"'!=`""' & `"`orig_gropts'"'!=`""' {
		local 0 `", `graphopts'"'
		syntax [, BY(varname) EFORM EFFect(string asis) LABels(varname string) DP(integer 2) KEEPALL ///
			INTERaction LCols(namelist) RCols(namelist) LEFTJustify COLSONLY RFDIST(varlist numeric min=2 max=2) ///
			NULLOFF noNAmes noNULL NULL2(string) noKEEPVars noOVerall noSTATs noSUbgroup noWT LEVEL(cilevel) ///
			XTItle(passthru) FAVours(passthru) /// /* N.B. -xtitle- is parsed here so that a blank title can be inserted if necessary */
			CUmulative INFluence /// /* only needed in order to switch _USE==3 back to _USE==1
			/// /* Sub-plot identifier for applying different appearance options, and dataset identifier to separate plots */
			PLOTID(string) DATAID(string) ///
			/// /* "fine-tuning" options */
			SAVEDIms(name) USEDIms(name) ASText(real -9) noADJust ///
			FP(string) /// 		/*(deprecated; now a favours() suboption)*/
			KEEPXLabs /// 	/*(undocumented; colsonly option)*/
			RAnge(string) CIRAnge(string) /// /* from ProcessXAxis*/
			DXWIDTHChars(real -9) LBUFfer(real 0) RBUFfer(real 1) /// /* from ProcessColumns */
			noADJust noLCOLSCHeck TArget(integer 0) MAXWidth(integer 0) MAXLines(integer 0) noTRUNCate ///
			ADDHeight(real 0) /// /* from GetAspectRatio */
			CLASSIC noDIAmonds WGT(varname numeric) NEWwt BOXscale(real 100.0) noBOX /// /* from BuildPlotCmds */
			/// /* standard options */
			BOXOPts(string asis) DIAMOPts(string asis) POINTOPts(string asis) CIOPts(string asis) OLINEOPts(string asis) ///
			NLINEOPts(string asis) HLINEOPts(string asis) ///
			/// /* non-diamond and predictive interval options */
			PPOINTOPts(string asis) PCIOPts(string asis) RFOPts(string asis) * ]
		
		local graphopts `"`macval(options)'"'
	}
	
	// August 2023: quickly parse for legend() option; if not present, set legend(off)
	// Legends cannot (currently) be automated; responsibility is to the user to sort them out
	local 0 `", `graphopts'"'
	syntax [, LEGend(string asis) * ]
	if `"`legend'"'==`""' local legend_opt legend(off)
	
	local xtitleopt = cond(`"`xtitle'"'==`""', `"xtitle("")"', `"`xtitle'"')		// to prevent tempvar name being printed as xtitle

	summ `id', meanonly
	// local DYmin = r(min) - 1			// amended Apr 2020
	local DYmin = 0
	local DYmax = r(max) + 1
		
	// Re-ordered 28th June 2017 so that all twoway options are given together at the end	
	#delimit ;

	twoway

	/* Nov 2017: order was: columns, overall, weighted, diamonds */

	/* Nov 2021: if requested, place overall and null lines underneath everything else */
		`olinePlotFirst' `nullCommandFirst'
	
	/* Jan 2020: if applicable, OVERALL CI AREA PLOT first, so that data points remain visible */
		`olineAreaPlot'
	
	/* WEIGHTED SCATTERPLOT BOXES (plus plot-specific options) */ 
	/*  and CONFIDENCE INTERVALS (incl. "offscale" if necessary) */
		`firstPlot' `secondPlot'
	
	/* OVERALL AND NULL LINES (plus plot-specific options) (Nov 2021: unless placed underneath; see above) */ 
		`olinePlot' `nullCommand'
	
	/* DIAMONDS (or markers+CIs if appropriate) FOR SUMMARY ESTIMATES */
	/* (and Prediction Intervals if appropriate; plus plot-specific options) */
	/*  then last of all PLOT EFFECT MARKERS to clarify */
		`RFPlot' `PCIPlot' `diamPlot' `pointPlot' `ppointPlot' 
	
	/* COLUMN VARIBLES (including effect sizes and weights on RHS by default) */
		`lcolCommands' `rcolCommands'

	/* FAVOURS OR XTITLE */
	/* do these first, so that their options may be overwritten by the user */
		, `favopt' `xtitleopt'
	
	/* Y-AXIS OPTIONS */
	// Note that, as yscale is merged-implicit, range(`AXmin' `AXmax') noline will take precedence over any user-specified range() sub-option to yscale,
	// ...but other yscale() options will be honored.  Users cannot over-ride the y-range; nor can they supply ylabels or ytitle.
		yscale(range(`DYmin' `DYmax') noline) ylabel(none) ytitle(`""') `borderCommand'
	
	/* X-AXIS OPTIONS */
	// Note that, as xscale is merged-implicit, range(`AXmin' `AXmax') will take precedence over any user-specified range() sub-option to xscale,
	// ...but other xscale() options will be honored.  Users should specify the x-range via the separate, command-specific range() option.
		xscale(range(`AXmin' `AXmax')) `xlabopt' `xmlabopt' `xtickopt' `xmtickopt' `legend_opt'

	/* OTHER TWOWAY OPTIONS (`graphopts' = user-specified) */
		`graphopts' plotregion(margin(zero)) ;

	#delimit cr

end





program define getWidth, sortpreserve
version 9.0

//	ROSS HARRIS, 13TH JULY 2006
//	TEXT SIZES VARY DEPENDING ON CHARACTER
//	THIS PROGRAM GENERATES APPROXIMATE DISPLAY WIDTH OF A STRING
//  (in terms of the current graphics font)
//	FIRST ARG IS STRING TO MEASURE, SECOND THE NEW VARIABLE

//	PREVIOUS CODE DROPPED COMPLETELY AND REPLACED WITH SUGGESTION
//	FROM Jeff Pitblado

// Updated August 2016 by David Fisher (added "touse" and "replace" functionality)

syntax anything [if] [in] [, REPLACE]

assert `: word count `anything''==2
tokenize `anything'
marksample touse

if `"`replace'"'==`""' {		// assume `2' is newvar
	confirm new variable `2'
	qui gen `2' = 0 if `touse'
}
else {
	confirm numeric variable `2'
	qui replace `2' = 0 if `touse'
}

qui {
	count if `touse'
	local N = r(N)
	tempvar obs
	bys `touse' : gen int `obs' = _n if `touse'
	sort `obs'
	forvalues i = 1/`N'{
		local this = `1'[`i']
		local width: _length `"`this'"'
		replace `2' =  `width' /*+1*/ in `i'	// "+1" blanked out by DF; add back on at point of use if necessary
	}
} // end qui

end



* exit

//	METAN UPDATE
//	ROSS HARRIS, DEC 2006
//	MAIN UPDATE IS GRAPHICS IN THE _dispgby PROGRAM
//	ADDITIONAL OPTIONS ARE lcols AND rcols
//	THESE AFFECT DISPLAY ONLY AND ALLOW USER TO SPECIFY
//	VARIABLES AS A FORM OF TABLE. THIS EXTENDS THE label(namevar yearvar)
//	SYNTAX, ALLOWING AS MANY LEFT COLUMNS AS REQUIRED (WELL, LIMIT IS 10)
//	IF rcols IS OMMITTED DEFAULT IS THE STUDY EFFECT (95% CI) AND WEIGHT
//	AS BEFORE- THESE ARE ALWAYS IN UNLESS OMITTED USING OPTIONS
//	ANYTHING ADDED TO rcols COMES AFTER THIS.


********************
** May 2007 fixes **
********************

//	"nostandard" had disappeared from help file- back in
//	I sq. in return list
//	sorted out the extra top line that appears in column labels
//	fixed when using aspect ratio using xsize and ysize so inner bit matches graph area- i.e., get rid of spaces for long/wide graphs
//	variable display format preserved for lcols and rcols
//	abbreviated varlist now allowed
//	between groups het. only available with fixed
//	warnings if any heterogeneity with fixed (for between group het if any sub group has het, overall est if any het)
// 	nulloff option to get rid of line




******************
* DF subroutines *
******************


* CheckOpts
// Based on the built-in _check_eformopt.ado,
//   but expanded from -eform- to general effect specifications.
// This program is used by -ipdmetan-, -(ad)metan- and -forestplot-
// Not all aspects are relevant to all programs,
//   but easier to maintain just a single subroutine!

program define CheckOpts, sclass

	syntax [name(name=cmdname)] [, soptions OPts(string asis) ESTVAR(name) ]
	
	if "`cmdname'"!="" {
		_check_eformopt `cmdname', `soptions' eformopts(`opts')
	}
	else _get_eformopts, `soptions' eformopts(`opts') allowed(__all__)
	local summstat = cond(`"`s(opt)'"'==`"eform"', `""', `"`s(opt)'"')

	if "`summstat'"=="rrr" {
		local effect `"Risk ratio"'		// Stata by default refers to this as a "Relative Risk Ratio" or "RRR"
		local summstat rr				//  ... but in MA context most users will expect "Risk Ratio"
	}
	else if "`summstat'"=="nohr" {		// nohr and noshr are accepted by _get_eformopts
		local effect `"Haz. ratio"'		//  but are not assigned names; do this manually
		local summstat hr
		local logopt nohr
	}
	else if "`summstat'"=="noshr" {
		local effect `"SHR"'
		local summstat shr
		local logopt noshr
	}
	else local effect `"`s(str)'"'

	if "`estvar'"=="_cons" {			// if constant model, make use of eform_cons_ti if available
		local effect = cond(`"`s(eform_cons_ti)'"'!=`""', `"`s(eform_cons_ti)'"', `"`effect'"')
	}
	
	local 0 `", `s(eform)'"'
	syntax [, EFORM(string asis) * ]
	local eform = cond(`"`eform'"'!=`""', "eform", "")
	
	// Next, parse `s(options)' to extract anything that wouldn't usually be interpreted by _check_eformopt
	//  that is: mean differences (`smd', `wmd' with synonym `md'); `rd' (unless -binreg-);
	//  `coef'/`log' and `nohr'/`noshr' (which all imply `log')
	// (N.B. do this even if a valid option was found by _check_eformopt, since we still need to check for multiple options)
	local 0 `", `s(options)'"'
	syntax [, COEF LOG NOHR NOSHR RD SMD WMD MD * ]

	// identify multiple options; exit with error if found
	opts_exclusive "`coef' `log' `nohr' `noshr'"
	if `"`summstat'"'!=`""' {
		if trim(`"`md'`smd'`wmd'`rr'`rd'`nohr'`noshr'"')!=`""' {
			opts_exclusive "`summstat' `md' `smd' `wmd' `rr' `rd' `nohr' `noshr'"
		}
	}
	
	// if "nonstandard" effect option used
	else {
		if trim(`"`md'`wmd'"')!=`""' {		// MD and WMD are synonyms
			local effect WMD
			local summstat wmd
		}
		else {
			local effect = cond("`smd'"!="", `"SMD"', ///
				cond("`rd'"!="", `"Risk Diff."', `"`effect'"'))
			local summstat = cond(`"`summstat'"'==`""', trim(`"`smd'`rd'"'), `"`summstat'"')
		}
		else if "`nohr'"!="" {
			local effect `"Haz. ratio"'
			local summstat hr
			local logopt nohr
		}
		else if "`noshr'"!="" {
			local effect `"SHR"'
			local summstat shr
			local logopt noshr
		}		

		// now check against program properties and issue warning
		if "`cmdname'"!="" {
			local props : properties `cmdname'
			if "`cmdname'"=="binreg" local props `props' rd
			if !`:list summstat in props' {
				cap _get_eformopts, eformopts(`summstat')
				if _rc {
					disp as err `"Note: option {bf:`summstat'} does not appear in properties of command {bf:`cmdname'}"'
				}
			}
		}
	}
	
	// log always takes priority over eform
	// ==> cancel eform if appropriate
	local log = cond(trim(`"`coef'`logopt'"')!=`""', "log", "`log'")					// `coef' is a synonym for `log'; `logopt' was defined earlier
	if `"`log'"'!=`""' {
		if inlist("`summstat'", "rd", "smd", "wmd") {
			nois disp as err "Log option only appropriate with ratio statistics"
			exit 198
		}
		local eform
	}
	
	sreturn clear
	sreturn local logopt = trim(`"`coef'`logopt'"')		// "original" log option
	sreturn local log      `"`log'"'					// either "log" or nothing
	sreturn local eform    `"`eform'"'					// either "eform" or nothing
	sreturn local summstat `"`summstat'"'				// if `eform', original eform option
	sreturn local effect   `"`effect'"'
	sreturn local options  `"`macval(options)'"'

end




*********************************************************************************

* Subroutine to sort out labels and ticks for x-axis, and find DXmin/DXmax (and CXmin/CXmax if different)
* Created August 2016
* Modified & renamed May 2024

program define ProcessXAxis, rclass

	syntax anything [, RAnge(string) CIRAnge(string) EFORM H0(real 0) noNULL DENOMinator(passthru) COLSONLY FAVours(string asis) ///
		FP(string) FORCE /* deprecated -metan9- options; now handled differently */ * ]
		
	local graphopts `"`options'"'
	tokenize `anything'
	args DXmin DXmax	

	
	* Initial parse of xlabel and xtick
	// [added May 2020] In case old (v3.x and earlier) syntax is used, with comma-separated values and no sub-options
	// Otherwise, ignore and send through as-is to -twoway- to pick up any other issues
	// Note: doesn't apply to xmlabel, xmtick as these were not allowed by -metan9-
	// Note: MAY 2024: Look for repeated options -- these would not have been *expected* by -metan9-
	// ... but -twoway- would still have accepted them if supplied
	local 0 `", `graphopts'"'
	syntax [, XLAbel(string asis) XTick(string) * ]
	local graphopts `"`options'"'

	while trim(`"`xlabel'`xtick'"')!=`""' {
		foreach xop in xlabel xtick {
			ParseOldXLabel `"``xop''"', xop(`xop') h0(`h0') `eform' `force' `twowaynote'
			if `"`r(xlablist)'"'!=`""' local `xop'new `"``xop'new' `xop'(`r(xlablist)')"'
		}
		local 0 `", `graphopts'"'
		syntax [, XLAbel(string asis) XTick(string) * ]
		local graphopts `"`options'"'
	}
	if "`twowaynote'"!="" c_local twowaynote notwowaynote	// so that -metan- does not print an additional message regarding "xlabel" or "force"	
	
	* If `eform', need to extract correct format to use when assembling labels in exponentiated scale
	if `"`eform'"'!=`""' {
		local use_format
		local formatopts `"`graphopts' `xlabelnew'"'
		local 0 `", `formatopts'"'
		syntax [, XLAbel(string asis) XMLabel(string asis) * ]
		local formatopts `"`options'"'
		while trim(`"`xlabel'`xmlabel'"')!=`""' {
			foreach xop in xlabel xmlabel {
				local 0 `"``xop''"'		// xlabel, xmlabel
				syntax [anything] , [FORMAT(string) * ]	
				if `"`format'"'!=`""' local use_format : copy local format		// format() is right-most
			}
			local 0 `", `formatopts'"'
			syntax [, XLAbel(string asis) XMLabel(string asis) * ]
			local formatopts `"`options'"'			
		}
	}	
	
	* Full parse x[m]label and x[m]tick, if supplied by user
	* (Note: we now assume all options follow standard Stata -twoway- syntax)
	*  - Extract numlists for labels & ticks, from which to calculate size of plot (CXmin/max, DXmin/max etc.)
	*  - If `eform', interpret user-supplied label values as on the exponentiated scale; apply labels on the interval scale accordingly
	*  - Calculate no. of rows in case of `colsonly'
	* But keep repeated options etc. as-is to send to -twoway- , so that subtleties are honoured
	local 0 `", `graphopts' `xlabelnew' `xticknew'"'
	syntax [, XLAbel(string asis) XMLabel(string asis) XTick(string) XMTick(string) * ]
	local graphopts `"`options'"'
	
	local rowsxmlab = 0
	local rowsxlab = 0
	local firstadd = 1
	while trim(`"`xlabel'`xmlabel'`xtick'`xmtick'"')!=`""' {
		foreach xop in xlabel xmlabel xtick xmtick {
			local xab : copy local xop
			if "`xop'"=="xlabel" local xab xlab
			else if "`xop'"=="xmlabel" local xab xmlab
			
			local 0 `"``xop''"'
			syntax [anything(name=`xab'cmd)] , [FORCE ADD ADDNEW /*colsonly-specific option*/ ALTernate /*rightmost, unless "add|addnew" */ * ]
			
			// Parse x[m]lablist and obtain numlist (Nov 2017)
			ProcessXLabels ``xab'cmd', dx(`DXmin' `DXmax') xop(`xop') format(`use_format') `eform' `colsonly'
			
			// Add results to previous (if repeated options with `add')
			if trim(`"`add'`addnew'"')==`""' {
				local `xab'list `"`r(xlablist)'"'
				if trim(`"`r(xlabcmd)'`options'"')!=`""' {
					local `xab'opt `"`xop'(`r(xlabcmd)', `options')"'
				}
			}
			else {
				if `"`colsonly'"'!=`""' & `"`addnew'"'!=`""' {
					if `firstadd' local firstadd = 0
					else local addopt add
					
					local `xab'list2 `"``xab'list2' `r(xlablist)'"'							// append values
					if trim(`"`r(xlabcmd)'`options'"')!=`""' {
						local `xab'opt2 `"``xab'opt2' `xop'(`r(xlabcmd)', `options' `addopt')"'	// repeated options + sub-options
					}					
					if trim(`"``xab'opt2'"')!=`""' local addcustom add custom		// for later
				}

				local `xab'list `"``xab'list' `r(xlablist)'"'						// append values
				if trim(`"`r(xlabcmd)'`options'"')!=`""' {
					local `xab'opt `"``xab'opt' `xop'(`r(xlabcmd)', `options' add)"'	// repeated options + sub-options
				}
			}
			if !inlist("`xop'", "xtick", "xmtick") {
				local rows`xab' = max(`rows`xab'', `=`r(rows)' + (`"`alternate'"'!=`""')')
			}
			
			// `force' option
			if `"`force'"'!=`""' {
				if `"`xop'"'!=`"xlabel"' {			// "force" option only applies to xlab, not xmlab or ticks
					nois disp as err "option {bf:force} is not allowed with {bf:`xop'()}"
					exit 198
				}
				if "`cirange'"!="" {
					disp as err `"Note: both {bf:cirange()} and {bf:xlabel(, force)} were specifed; {bf:cirange()} takes precedence"'
				}
				else if `"`xlablist'"'!=`""' {
					local xlablist2 : copy local xlablist
					local min : word 1 of `xlablist2'
					if inlist(`"`min'"', `"none"', `"."') {
						gettoken none xlablist2 : xlablist
					}
					numlist `"`xlablist2'"', sort
					local n : word count `r(numlist)'
					local min : word 1 of `r(numlist)'
					local max : word `n' of `r(numlist)'
					if `"`CRXmin'"'==`""' local CRXmin = `min'
					else {
						local CRXmin = max(`CRXmin', `min')		// if multiple "force" options, use most restrictive
					}
					if `"`CRXmax'"'==`""' local CRXmax = `max'
					else {
						local CRXmax = min(`CRXmax', `max')		// if multiple "force" options, use most restrictive
					}
					local forceopt force	// indicator that "force" has been specified
				}
			}
		}		// end foreach

		// Test for repeated options and loop if necessary
		// Parse for "add" and discard repeated options if appropriate
		// so that later parsing and updating/replacing of "labsize()" is accurate
		local 0 `", `graphopts'"'
		syntax [, XLAbel(string asis) XMLabel(string asis) XTick(string) XMTick(string) * ]
		local graphopts `"`options'"'
	}		// end while loop
		
	
	* If `colsonly', blank out the labels, and make ticks and gridlines invisible
	if `"`colsonly'"'!=`""' {
		foreach xop in xlabel xmlabel xtick xmtick {
			local xab : copy local xop
			if "`xop'"=="xlabel" local xab xlab
			else if "`xop'"=="xmlabel" local xab xmlab

			if inlist("`xop'", "xlabel", "xmlabel") {
				if `"``xab'opt'"'!=`""' {
					forvalues i=1/`rows`xab'' {
						local `xab'txt `"``xab'txt' `" "'"'
					}
					if `rows`xab'' > 1 local `xab'txt `"`"``xab'txt'"'"'
					local `xab'opt `"`xop'( __DUMMY__ ``xab'txt', tlc(none) glc(none) `addcustom')"'
				}
			}
			else {		// Process ticklists: these are easier as no labels
				if `"``xab'opt'"'!=`""' {
					local `xab'opt `"`xop'( __DUMMY__ , tlc(none) glc(none) `addcustom')"'
				}
			}
		}
	}
	
	
	* Parse `range' and `cirange'
	// in both cases, "min" and "max" refer to range of data in terms of LCI, UCI
	// (that is, initial values of `DXmin', `DXmax')
	foreach op in range cirange {
		if `"``op''"'==`""' continue
		local opmin = cond("`op'"=="range", "RXmin", "CXmin")
		local opmax = cond("`op'"=="range", "RXmax", "CXmax") 
		
		tokenize `"``op''"'
		cap {
			assert `"`2'"'!=`""'
			assert `"`3'"'==`""'
		}
		if _rc {
			disp as err `"option {bf:`op'()} must contain exactly two elements"'
			exit 198
		}
		
		// if "min", "max" used
		if inlist(`"`1'"', "min", "max") | inlist(`"`2'"', "min", "max") {
			if `"`eform'"'!=`""' {
				forvalues i=1/2 {
					cap confirm number ``i''
					if !_rc local `i' = ln(``i'')
				}
			}
			local `op' `"`1' `2'"'
			local `op' = subinstr(`"``op''"', `"min"', `"`DXmin'"', .)
			local `op' = subinstr(`"``op''"', `"max"', `"`DXmax'"', .)
			numlist `"``op''"', min(2) max(2) sort
			local `op' = r(numlist)
			tokenize `"``op''"'
			args `opmin' `opmax'
		}	
		
		else {
			if `"`eform'"'!=`""' {
				numlist `"``op''"', min(2) max(2) range(>0) sort
				local `op' `"`=ln(`1')' `=ln(`2')'"'
			}
			else {
				numlist `"``op''"', min(2) max(2) sort
				local `op' = r(numlist)
			}
			tokenize `"``op''"'
			args `opmin' `opmax'
		}
	}
	
	// "force" option
	if trim(`"`CRXmin'`CRXmax'"')!=`""' {
		if `"`range'"'==`""' {				// if `range' not specified, default to "forced" xlab limits
			local RXmin = `CRXmin'
			local RXmax = `CRXmax'
			local range = trim(`"`CRXmin' `CRXmax'"')
		}
		else {				// otherwise, set `cirange' instead (see message above)
			local CXmin = `CRXmin'
			local CXmax = `CRXmax'
			local cirange = trim(`"`CRXmin' `CRXmax'"')
		}
	}
	
	* Check validity of user-defined values
	if `"`range'"'!=`""' & `"`cirange'"'!=`""' {
		cap {
			assert `RXmin' <= `CXmin'
			assert `RXmax' >= `CXmax'
		}
		if _rc {
			disp as err "interval defined by {opt cirange()} (or {bf:xlabel(, force)}) must lie within that defined by {opt range()}"
			exit 198
		}
	}

	// changed Sep 2017 for v2.1
	else if `"`cirange'"'==`""' & `"`range'"'!=`""' {
		local CXmin = max(`RXmin', `DXmin')
		local CXmax = min(`RXmax', `DXmax')
	}
	
	// Jan 2018: Now re-set DXmin/DXmax if RXmin/RXmax are defined
	// CHECK CONSEQUENCES OF THIS CAREFULLY
	if trim(`"`RXmin'`RXmax'"')!=`""' {
		local DXmin = `RXmin'
		local DXmax = `RXmax'
	}
	
	// remove null line if lies outside range of x values to be plotted
	if `"`null'"'==`""' & trim(`"`cirange'`range'`forceopt'"')!=`""' {
		local removeNull = 0
		if `"`cirange'"'!=`""' local removeNull = (`h0' < `CXmin' | `h0' > `CXmax')
		else                   local removeNull = (`h0' < `RXmin' | `h0' > `RXmax')
		if `removeNull' {
			nois disp as err "null line lies outside of user-specified x-axis range and will be suppressed"
			local null nonull
		}
	}
	return local null `null'

	
	* Apply automated values if -xlabel- not supplied by user
	// MAY 2024: Note: if xmlabel() is used, AutoXLabel is still potentially run; this matches with standard -twoway- behaviour
	local xlablim1 = 0		// init
	local xlablist_all `"`xlablist' `xlablist2'"'
	local xlablist_all : list uniq xlablist_all
	if inlist(`"`xlablist_all'"', `"none"', `"."', `"none ."', `". none"') local xlablist_all none
	if `"`xlablist_all'"'==`""' {
		AutoXLabel `DXmin' `DXmax', range(`range') `eform' format(`use_format') h0(`h0') `null' `denominator'
		
		local DXmin = `r(DXmin)'
		local DXmax  = `r(DXmax)'
		local xlablim1 = `r(xlablim1)'
		
		local xlablist `"`r(xlablist)'"'
		local xlabopt `"`r(xlabopt)' `xlabopt'"'
		
		// Added Feb 2018: If automatic labelling, set rows to 1 (rowsxmlab remains at 0)
		local rowsxlab = 1
		if `"`colsonly'"'!=`""' local xlabopt `"xlabel(__DUMMY__ `" "', tlc(none) glc(none))"'
	}		// end if "`xlablist'" == ""
		
	// Final parsing of x-axis labelling quantities (excluding "favours" and [xab]list2/newadd ), to form `XLmin' `XLmax'
	local xlablist_all `"`xlablist' `xticklist' `xmticklist'"'
	local xlablist_all : list uniq xlablist_all
	if inlist(`"`xlablist_all'"', `"none"', `"."', `"none ."', `". none"') local xlablist_all none
	cap assert `"`xlablist_all'"'!=`""'
	if _rc {
		disp as err "Something has gone wrong with x-axis value labelling"
		exit 198
	}
	if `"`xlablist_all'"'==`"none"' {
		local XLmin = `h0'
		local XLmax = `h0'
	}
	else {
		numlist `"`xlablist' `xticklist' `xmticklist'"', sort
		local n : word count `r(numlist)' 
		local XLmin : word 1 of `r(numlist)'
		local XLmax : word `n' of `r(numlist)'
	}
	
	* Use symmetrical plot area (around `h0'), unless data "too far" from null
	if trim(`"`range'`cirange'`forceopt'"')==`""' {

		// if "too far", adjust `CXmin' and/or `CXmax' to reflect this
		//   where "too far" ==> max(abs(`CXmin'-`h0'), abs(`CXmax'-`h0')) > `CXmax' - `CXmin'
		local TooFar = 0
		if "`null'"=="" | `h0' != 0 {		
			if `h0' - `DXmax' > `DXmax' - `DXmin' {							// data "too far" to the left
				local DXmax = max(`h0' + .5*(`DXmax'-`DXmin'), `XLmax')		// clip the right-hand side
				local TooFar = 1
			}	
			if `DXmin' - `h0' > `DXmax' - `DXmin' {							// data "too far" to the right
				local DXmin = min(`h0' - .5*(`DXmax'-`DXmin'), `XLmin')		// clip the left-hand side
				local TooFar = 1
			}
		}
		if `TooFar' {
			local DXmin = -max(abs(`DXmin'), abs(`DXmax'))
			local DXmax =  max(abs(`DXmin'), abs(`DXmax'))
		}
	}
	
	* Final calculation of DXmin, DXmax
	if trim(`"`RXmin'`RXmax'"')!=`""' {
		numlist `"`RXmin' `RXmax'"', sort
	}
	else {
		numlist `"`DXmin' `DXmax' `XLmin' `XLmax'"', sort
	}
	local n : word count `r(numlist)' 
	local DXmin : word 1 of `r(numlist)'
	local DXmax : word `n' of `r(numlist)'
	
	if trim(`"`CXmin'`CXmax'"')==`""' {
		local CXmin = `DXmin'
		local CXmax = `DXmax'
	}	
	
	
	* Now parse `favours' option
	*  - Use similar approach to x[m]label, and ultimately translate into an additional xmlabel option
	*  - Calculate no. of rows in case of `colsonly'
	local rowsfav = 0
	if `"`favours'"' != `""' {
		local oldfp : copy local fp	
		local 0 `"`favours'"'
		syntax [anything(everything)] [, FP(string) noSYMmetric /// /* these two are needed right now, others parsed simply to isolate inappropriate options */
			FORMAT(string) ANGLE(string) LABGAP(string) LABSTYLE(string) LABSize(string) LABColor(string) noSYMmetric * ]
		if `"`oldfp'"'!=`""' local fp : copy local oldfp
		if `"`options'"' != `""' {
			nois disp as err `"inappropriate suboptions found in {bf:favours()}"'
			exit 198
		}
		
		* Parse text, and count how many rows of text there are (i.e. separated with pairs of quotes)
		local rowsleftfav = 0
		local rowsrightfav = 0

		gettoken leftfav rest : anything, parse("#") quotes		
		if `"`leftfav'"'!=`"#"' {
			while `"`rest'"'!=`""' {
				local ++rowsleftfav
				gettoken next rest : rest, parse("#") quotes
				if `"`next'"'==`"#"' continue, break
				local leftfav `"`leftfav' `next'"'
			}
		}
		else local leftfav `""'		
		local rightfav = trim(`"`rest'"')
		if `"`rightfav'"'!=`""' {
			while `"`rest'"'!=`""' {
				local ++rowsrightfav
				gettoken next rest : rest, quotes
			}
		}
		local rowsfav = max(1, `rowsleftfav', `rowsrightfav')

		// Feb 2021: Remove quotes if only a single line
		if `rowsleftfav'==1 {
		    gettoken new : leftfav, qed(qed)
			if `qed' local leftfav : copy local new
		}
		if `rowsrightfav'==1 {
		    gettoken new : rightfav, qed(qed)
			if `qed' local rightfav : copy local new
		}

		// modified Jan 30th 2018, and again May 21st 2018
		if `"`fp'"'==`""' {
			// August 2018: default is...
			// May 2018: use smaller of distances from h0 to min(DXmin, XLmin) or max(DXmax, XLmax)
			local fpmin = min(`DXmin', `XLmin')
			local fpmax = max(`DXmax', `XLmax')
			
			if `"`symmetric'"'==`""' {
				local fp =  min(cond(`fpmin' <= `h0' & `"`leftfav'"'!=`""',  (`h0' - `fpmin')/2, .), ///
								cond(`fpmax' >= `h0' & `"`rightfav'"'!=`""', (`fpmax' - `h0')/2, .))
				local leftfp  = cond(`fpmin' <= `h0' & `"`leftfav'"'!=`""',  `"`=`h0' - `fp'' `"`leftfav'"'"',  `""')
				local rightfp = cond(`fpmax' >= `h0' & `"`rightfav'"'!=`""', `"`=`h0' + `fp'' `"`rightfav'"'"', `""')
			}
			
			// ...but may be overruled with option `nosymmetric', e.g. if distances are extremely unbalanced
			else {
				local leftfp  = cond(`fpmin' <= `h0' & `"`leftfav'"'!=`""',  `"`=(`h0' + `fpmin')/2' `"`leftfav'"'"',  `""')
				local rightfp = cond(`fpmax' >= `h0' & `"`rightfav'"'!=`""', `"`=(`h0' + `fpmax')/2' `"`rightfav'"'"', `""')
			}
		}
		
		// modified Jan 2020
		// User-specified fp()
		else {
			numlist `"`fp'"', miss max(2)
			tokenize `fp'
			args fpleft fpright
			if `"`eform'"'!=`""' local fpleft = ln(`fpleft')			// fp() should be given on same scale as xlabels

			if `"`fpright'"'==`""' {		// only one value given
				local fpleft  = cond(`fpleft' <= `h0', `fpleft', 2*`h0' - `fpleft')
				local fpright = 2*`h0' - `fpleft'
			}
			else {		// two values given: should be one either side of null line)
				cap assert `fpleft' <= `h0'
				if _rc {
					if `h0' != 0 local extra `" (`h0')"'
					nois disp as err `"Error in {bf:fp()}: left-hand value should lie to the left of the null value`extra'"'
					exit 198
				}
				cap assert `fpright' >= `h0'
				if _rc {
					if `h0' != 0 local extra `" (`h0')"'
					nois disp as err `"Error in {bf:fp()}: right-hand value should lie to the right of the null value`extra'"'
					exit 198
				}
			}
			local leftfp  `fpleft' `"`leftfav'"'
			local rightfp `fpright' `"`rightfav'"'
		}

		// Nov 2017 [modified Feb 2018]
		assert (`rowsfav'>0) == (trim(`"`leftfp'`rightfp'"')!=`""')
		if `rowsfav' {
			if `"`colsonly'"'!=`""' {
				forvalues i=1/`rowsfav' {
					local favtxt `"`favtxt' `" "'"'
				}
				if `rowsfav' > 1 local favtxt `"`"`favtxt'"'"'
				local dummy __DUMMY__
			}
			else local favtxt `leftfp' `rightfp'
			local favopt `"xmlabel(`dummy' `favtxt', tlc(none) glc(none) favours `addcustom' `favopt')"'		
		}
	}		
	
	// Position of xtitle [May 2024: not currently implemented]
	local xtitleval = cond("`xlablist'"=="", `xlablim1', .5*(`CXmin' + `CXmax'))
	return scalar xtitleval = `xtitleval'	
	
	// Return scalars
	return scalar CXmin = `CXmin'
	return scalar CXmax = `CXmax'
	return scalar DXmin = `DXmin'
	return scalar DXmax = `DXmax'
	
	// moved Feb 2018; modified Oct 2018; modified May 2024
	return scalar rowsxlab  = `rowsxlab'
	return scalar rowsxmlab = `rowsxmlab'
	return scalar rowsfav   = `rowsfav'

	return local xlabopt   `"`xlabopt'"'
	return local xmlabopt  `"`xmlabopt'"'
	return local favopt    `"`favopt'"'
	return local xtickopt  `"`xtickopt'"'
	return local xmtickopt `"`xmtickopt'"'
	
	// New May 2024: for use with `colsonly'
	return local xlabopt2   `"`xlabopt2'"'
	return local xmlabopt2  `"`xmlabopt2'"'
	return local xtickopt2  `"`xtickopt2'"'
	return local xmtickopt2 `"`xmtickopt2'"'	

	return local options `"`graphopts'"'

end


* ParseOldXLabel: Initial parse of xlabel and xtick, in case old (v3.x and earlier) syntax is used
// (with comma-separated values and no sub-options)
// Originally written May 2020; moved into separate subroutine May 2024
// subroutine of ProcessXAxis
program define ParseOldXLabel, rclass

	syntax [anything(name=xlabcmd)], XOP(string) /*for error messages*/ [ H0(real 0) EFORM FORCE noTWOWAYNOTE ]

	local done = 0
	local comma = 0
	local csv = 1
	local lblcmd
	tokenize `xlabcmd', parse(",")

	if inlist(`"`1'"', `"none"', `"minmax"') | substr(`"`1'"', 1, 1)==`"#"' {
		gettoken xlablist : xlabcmd		// return original xlabel option as-is; presumably using modern Stata -twoway- syntax
	}
	else {
		while `"`1'"' != `""' {
			cap confirm number `1'
			if !_rc {
				if `"`2'"'==`""' & `"`lblcmd'"'==`""' local csv = 0
				local lblcmd `"`lblcmd' `1'"'
			}
			else {
				cap assert `"`1'"'==`","'
				if !_rc local comma = 1
				else local csv = 0
			}
			mac shift
		}
		if `csv' {		// originally a comma-separated list of numbers; but now commas replaced by spaces
			if `"`lblcmd'"'!=`""' {
				capture numlist `"`lblcmd'"'
				if _rc {
					nois disp as err `"error in option {bf:`xlname'()}: invalid numlist"'
					exit _rc
				}
				local xlablist = r(numlist)

				if `comma' {										
					// [Oct 2020:] If `h0' is absent, add it back in.
					// Previous versions of -metan- added h0 by default (unless "nonull"), so that e.g. "xlabel(.1, 10) eform" would result in .1, 1 and 10 being marked.
					// With the "new" syntax based on standard -twoway- options, `h0' needs to be included in xlabel() in order for it to appear.					
					if `"`null'"'==`""' {
						local newh0 = cond(`"`eform'"'!=`""', exp(`h0'), `h0')
						if !`: list newh0 in xlablist' local xlablist `xlablist' `newh0'
					}
					numlist `"`xlablist'"', sort
					local xlablist = r(numlist)
					
					if !`done' & `"`twowaynote'"'==`""' {
						nois disp as err _n `"Note: with {bf:metan} version 4 and above, the preferred syntax is for {bf:`xop'()}"'
						nois disp as err `" to contain a standard Stata numlist, so e.g. {bf:`xop'(`xlablist')}; see {help numlist:help numlist}"'
					}
					local done = 1
					c_local twowaynote notwowaynote		// so that -metan- does not print an additional message regarding "force"
				}
			}
		}
		else gettoken xlablist : xlabcmd		// return original xlabel option as-is; presumably using modern Stata -twoway- syntax

		// convert legacy -force- option into modern twoway xlabel option
		if `"`xop'"'==`"xlabel"' & `"`force'"'!=`""' & `csv' {
			if `done' local xlablist `"`xlablist', force"'
			else {
				if `"`xlablist'"'==`""' {
					nois disp as err `"main option {bf:force} not allowed without {bf:xlabel()}"'
				}
				else nois disp as err `"option {bf:force} only allowed as a suboption to {bf:xlabel()}"'
				exit 198
			}
			c_local twowaynote notwowaynote		// so that -metan- does not print an additional message regarding "force"
		}
	}
	
	return local xlablist `"`xlablist'"'

end


* ProcessXLabels: Parse user-specified x[m]label() and x[m]tick() options
// Moved into separate subroutine May 2024; now also handles repeated options
// subroutine of ProcessXAxis
program define ProcessXLabels, rclass
	
	syntax [anything(name=xlabcmd)], XOP(string) /*for error messages*/ DX(numlist min=2 max=2) /*in case of "minmax" rule*/ ///
		[ EFORM COLSONLY FORMAT(string) /*KEEPXLabs*/ ]

	local rows = 0	// init
		
	// First, look at ticks; these are easier (no labels!)
	if inlist("`xop'", "xtick", "xmtick") {
		if `"`xlabcmd'"'!=`""' {
			cap numlist `"`xlabcmd'"'
			if _rc {
				disp as err `"invalid label specifier, : `xlabcmd'"'
				exit 198
			}
			if `"`eform'"'!=`""' {						// assume given on exponentiated scale if "eform" specified, so need to take logs
				cap numlist "`xlabcmd'", range(>0)		// ...in which case, all values must be greater than zero
				if _rc {
					disp as err `"option {bf:eform} specified, but {bf:`xop'()} contains non-positive values"'
					exit 198
				}
				local exlabcmd `"`xlabcmd'"'
				local xlabcmd
				foreach xi of numlist `exlabcmd' {
					local xlabcmd `"`xlabcmd' `=ln(`xi')'"'
				}
			}
			local newxlabcmd: copy local xlabcmd	// to match with code further down
			local xlablist: copy local xlabcmd		// to match with code further down
		}
	}
	// end of ticks
	
	else {
		local rest : copy local xlabcmd
		while `"`rest'"'!=`""' | `"`lbl'"'!=`""' {			// Feb 2018: added the second part of this stmt
			if `"`lbl'"'!=`""' local lbl2 `"`lbl'"'			// Nov 2017: user-specified labels need to go round the loop once, before being applied
			local lbl
			
			gettoken tok rest : rest, qed(qed)
			if `"`tok'"'!=`""' {
			
				// if text label found, check for embedded quotes (i.e. multiple lines)
				if `qed' {
					local rest2 `"`"`tok'"'"'
					gettoken el : rest2, qed(qed2)
					if !`qed2' {
						disp as err `"invalid label specifier, : ``xl'list':"'
						exit 198
					}
					local newxlabcmd `"`newxlabcmd' `rest2'"'
					local newlist
					local rest2 : copy local el
					while `"`rest2'"'!=`""' {
						gettoken el rest3 : rest2, quotes
						if `"`el'"'==`"`""'"' {
							// local newlist : list rest2 - el	// modified Feb 2018; check
							continue, break
						}
						local newlist `"`newlist' `el'"'
						local rest2 `"`rest3'"'
					}
					local rows = max(`rows', `: word count `newlist'')
					local lbl2				
				}	// end if `qed'
				
				// else, check if valid numlist
				else {
					if substr(`"`tok'"', 1, 1)==`"#"' {
						local hash `"#"'
						if substr(`"`tok'"', 2, 1)==`"#"' local hash `"##"'
						disp as err `"Cannot use the {bf:`hash'}# syntax in the {bf:`xop'()} option of {bf:forestplot}; please use a {it:numlist} instead"'
						exit 198
					}
					if inlist(`"`tok'"', `"none"', `"."') local rule_none : copy local tok
					else {
						if `"`tok'"'==`"minmax"' local tok `DXmin' `DXmax'
						numlist `"`tok'"'
						local rows = max(`rows', 1)

						if `"`eform'"'!=`""' {
							cap numlist `"`tok'"', range(>0)
							if _rc {
								disp as err `"option {bf:eform} specified, but {bf:`xop'()} contains non-positive values"'
								exit 198
							}
						
							// if eform, need to expand numlist and take logs
							local nl = r(numlist)
							local N : word count `nl'
							forvalues i=1/`N' {
								local el : word `i' of `nl'
								local xlablist `"`xlablist' `=ln(`el')'"'
								local newxli `"`=ln(`el')'"'
								
								local lbl = cond("`format'"=="", string(`el'), string(`el', "`format'"))
								if `i'==1 & `"`lbl2'"'!=`""' local newxli `"`"`lbl2'"' `newxli'"'
								if `i'<`N'                   local newxli `"`newxli' `"`lbl'"'"'
								local lbl2
								// don't add the last label yet, in case user has specified their own label
								
								local newxlabcmd `"`newxlabcmd' `newxli'"'
							}
						}
					
						// else, can simply add unexpanded numlist
						else {
							local xlablist `"`xlablist' `tok'"'
							local newxlabcmd `"`newxlabcmd' `tok'"'
							local lbl2
						}
					}
				}		// end else
			}		// end if `"`tok'"'!=`""'
				
			// if lbl, add it now
			if `"`lbl2'"'!=`""' {
				local newxlabcmd `"`newxlabcmd' `"`lbl2'"'"'
				local lbl
				local lbl2
			}

		}	// end while loop
	}		// end else (if not ticks)
	
	local xlablist = trim(`"`rule_none' `xlablist'"')
	local xlabcmd = trim(`"`rule_none' `newxlabcmd'"')

	cap assert `"`xlabcmd'"'==`""' if `"`xlablist'"'==`""'
	if _rc {
		disp as err "Error in {bf:`xop'()}"
		exit 198
	}

	return local xlablist `"`xlablist'"'
	return local xlabcmd `"`xlabcmd'"'		// Note: xlabcmd and xlablist should be identical except that xlabcmd may also have labels
	
	return scalar rows = `rows'
end


* AutoXLabel: If xlabel not supplied by user, choose sensible values.
// Default is for symmetrical limits, with 3 labelled values including null
// N.B. First modified from original -metan- code by DF, March 2013
//  with further improvements by DF, January 2015
// Modifed April 2017 to avoid interminable looping if [base]^`mag' = missing
// Modified & renamed May 2024
// subroutine of ProcessXAxis
program define AutoXLabel, rclass

	syntax anything [, RANGE(numlist min=2 max=2) EFORM FORMAT(string) H0(real 0) noNULL FORCE DENOMinator(string) ]
	tokenize `anything'
	args DXmin DXmax
	tokenize `range'
	args RXmin RXmax

	local xlablim1 = 0	// init
	
	// [Mar 2020] If `proportion', simply choose 0, .5 and 1 ... [Mar 2021] multiplied by `denominator'
	// [Apr 2021] ... but only if `range' not specified and smaller than DXmin/DXmax
	if "`denominator'"!="" {
		cap confirm number `denominator'
		if _rc {
			nois disp as err `"`denominator' found where number expected in option {bf:denominator(#)}"'
			exit 198
		}
		
		local xlablist
		if `"`range'"'!=`""' {
			local ii = max(`RXmin', 0)
			local xlablist `"`xlablist' `ii'"'
			local ii = min(`RXmax', `denominator')
			local xlablist `"`xlablist' `ii'"'
		}
		else {
			foreach i of numlist 0 .5 1 {
				local ii = `denominator' * `i'
				local xlablist `"`xlablist' `ii'"'
			}
		}
		local xlabopt `"`xlablist'"'
	}
	else {

		// If null line, choose values based around `h0'
		// (i.e. `xlabinit1' = `h0'... but `h0' is automatically selected anyway so no need to explicitly define `xlabinit1')
		if "`null'" == "" | `h0' != 0 {		// [N.B. "h0 != 0" added Jan 2020]
			local xlabinit2 = max(abs(`DXmin' - `h0'), abs(`DXmax' - `h0'))
			local xlabinit "`xlabinit2'"
		}
		
		// if `nulloff', choose values in two stages: firstly based on the midpoint between CXmin and CXmax (`xlab[init|lim]1')
		//  and then based on the difference between CXmin/CXmax and the midpoint (`xlab[init|lim]2')
		else {
			local xlabinit1 = (`DXmax' + `DXmin')/2
			local xlabinit2 = abs(`DXmax' - `xlabinit1')		// N.B. same as abs(`CXmin' - `xlabinit1')
			if float(`xlabinit1') != 0 {
				local xlabinit "`=abs(`xlabinit1')' `xlabinit2'"
			}
			else local xlabinit `xlabinit2'
		}
		assert "`xlabinit'"!=""
		assert "`xlabinit2'"!=""
		assert `: word count `xlabinit'' == ("`null'"!="" & `h0'==0)*(float(`DXmax')!=-float(`DXmin')) + 1		// should be >= 1
		
		local counter = 1
		foreach xval of numlist `xlabinit' {
		
			if `"`eform'"'==`""' {						// linear scale
				local mag = floor(log10(`xval'))
				local xdiff = abs(`xval'-`mag')
				foreach i of numlist 1 2 5 10 {
					local ii = `i' * 10^`mag'
					if missing(`mag') local ii = 0		// March 2021: catch extreme case
					if missing(`ii') {
						local ii = `=`i'-1' * 10^`mag'
						local xdiff = abs(float(`xval' - `ii'))
						local xlablim = `ii'
						continue, break
					}
					else if abs(float(`xval' - `ii')) <= float(`xdiff') {
						local xdiff = abs(float(`xval' - `ii'))
						local xlablim = `ii'
					}
				}
			}
			else {										// log scale
				local mag = round(`xval'/ln(2))
				local xdiff = abs(`xval' - ln(2))
				forvalues i=1/`mag' {
					local ii = ln(2^`i')
					if missing(`ii') {
						local ii = ln(2^`=`i'-1')
						local xdiff = abs(float(`xval' - `ii'))
						local xlablim = `ii'
						continue, break
					}
					else if abs(float(`xval' - `ii')) <= float(`xdiff') {
						local xdiff = abs(float(`xval' - `ii'))
						local xlablim = `ii'
					}
				}
				
				// if effect is small, use 1.5, 1.33, 1.25 or 1.11 instead, as appropriate
				foreach i of numlist 1.5 `=1/0.75' 1.25 `=1/0.9' {
					local ii = ln(`i')
					if abs(float(`xval' - `ii')) <= float(`xdiff') {
						local xdiff = abs(float(`xval' - `ii'))
						local xlablim = `ii'
					}
				}	
			}
			
			// if nonull, center limits around `xlablim1', which should have been optimized by the above code
			if "`null'" != "" & `h0'==0 {		// nonull
				if `counter'==1 {
					local xlablim1 = `xlablim'*sign(`xlabinit1')
				}
				if `counter'>1 | `: word count `xlabinit''==1 {
					local xlablim2 = `xlablim'
					local xlablims `"`=`xlablim1'+`xlablim2'' `=`xlablim1'-`xlablim2''"'
				}
			}
			else local xlablims `"`xlablims' `xlablim'"'
			local ++counter

		}	// end foreach xval of numlist `xlabinit'
			
		// if nulloff, don't recalculate CXmin/CXmax
		if "`null'" != "" & `h0'==0 numlist `"`xlablim1' `xlablims'"'
		else {
			numlist `"`=`h0' - `xlablims'' `h0' `=`h0' + `xlablims''"', sort	// default: limits symmetrical about `h0'
			tokenize `"`r(numlist)'"'

			// if data are "too far" from null (`h0'), take one limit (but not the other) plus null
			//   where "too far" ==> abs(`CXmin' - `h0') > `CXmax' - `CXmin'
			//   (this works whether data are "too far" to the left OR right, since our limits are symmetrical about `h0')
			if abs(`DXmin' - `h0') > `DXmax' - `DXmin' {
				if `3' > `DXmax'      numlist `"`1' `h0'"'
				else if `1' < `DXmin' numlist `"`h0' `3'"'
			}
			else if trim("`range'`cirange'`forceopt'")=="" {		// "standard" situation
				numlist `"`1' `h0' `3'"'
				local DXmin = `h0' - `xlabinit2'
				local DXmax = `h0' + `xlabinit2'
			}
		}
		local xlablist=r(numlist)
	}
		
	// if log scale, label with exponentiated values
	local xlabopt `"`xlablist'"'
	if `"`eform'"'!=`""' {
		local xlabopt
		foreach xi of numlist `xlablist' {
			local lbl = cond("`format'"=="", string(exp(`xi')), string(exp(`xi'), "`format'"))
			local xlabopt `"`xlabopt' `xi' `"`lbl'"'"'				
		}
	}

	return scalar DXmin = `DXmin'
	return scalar DXmax = `DXmax'
	return scalar xlablim1 = `xlablim1'
	
	return local xlablist `"`xlablist'"'
	return local xlabopt `"xlabel(`xlabopt')"'

end

// End of subroutines of ProcessXAXis


	
*********************************************************************************

* Process left and right columns -- obtain co-ordinates etc.
program define ProcessColumns, rclass

	syntax varlist(min=1 max=2) [if] [in], ID(varname numeric) LRCOLSN(numlist integer >=0) LCIMIN(real) DX(numlist min=2 max=2) ///
		[LVALlist(namelist) LLABlist(varlist) LFMTLIST(string) ///
		 RVALlist(namelist) RLABlist(varlist) RFMTLIST(string) RFINDENT(varname) RFCOL(integer 1) ///
		 DXWIDTHChars(real -9) ASText(integer -9) LBUFfer(real 0) RBUFfer(real 1) ///
		 noADJust noLCOLSCHeck TArget(integer 0) MAXWidth(integer 0) MAXLines(integer 0) noTRUNCate noWT DOUBLE COLSONLY * ]
	
	local graphopts `"`options' `double'"'
	
	marksample touse, novarlist
	
	// rename and unpack
	local DXwidthChars : copy local dxwidthchars

	tokenize `varlist'
	args _USE _EFFECT		// Oct 2020: _EFFECT is only used if `double', to prevent doubling of _EFFECT variable

	tokenize `lrcolsn'
	args lcolsN rcolsN
	
	tokenize `dx'
	args DXmin DXmax
	
	tempvar strlen strwid
	local digitwid : _length 0		// width of a digit (e.g. "0") in current graphics font = roughly average non-space character width
	local spacewid : _length " "	// width of a space in current graphics font

	summ `id' if `touse', meanonly
	assert r(min)==1
	local maxid = r(max)
	local multip = 1
	local add = 0

	quietly {
		// Apr 2020
		// DOUBLE LINE OPTION
		if `"`double'"'!=`""' & (`lcolsN' + `rcolsN' - ("`_EFFECT'"!="") - ("`wt'"=="")) {
			tempvar expand
			expand 2 if `touse' & inlist(`_USE', 1, 2), gen(`expand')
			replace `_USE' = 6 if `touse' & `expand'
			
			// TITLES CLOSER TOGETHER, GAP BENEATH
			local multip = 0.45
			local add = 0.5
		}
		local maxN = _N
		
		
		** Left columns
		local leftWDtot = 0
		local nlines = 0
		forvalues i = 1 / `lcolsN' {
			local leftLB`i' : word `i' of `llablist'
			local fmtlen    : word `i' of `lfmtlist'
			
			// Aug 2023: remove "~" symbol (centered format) if necessary
			tokenize `fmtlen', parse("~")
			if "`1'"=="~" local fmtlen `2'
			confirm integer number `fmtlen'
			
			gen long `strlen' = length(`leftLB`i'')
			summ `strlen' if `touse', meanonly
			local maxlen = r(max)		// max length of existing text

			// Apr 2020
			** DOUBLE LINE OPTION
			if `"`double'"'!=`""' {
			    forvalues j = 1 / `maxid' {
					summ `_USE' in `j', meanonly
					if inlist(`r(min)', 1, 2) {
						summ `id' in `j', meanonly
						local idj = r(min)
						local leftLBj = `leftLB`i''[`j']
						SpreadTitle `"`leftLBj'"', target(`=round(`maxlen'/2)') maxlines(2) notruncate
						replace `leftLB`i'' = `"`r(title1)'"' if `touse' & `id'==`idj' & !`expand'
						replace `leftLB`i'' = `"`r(title2)'"' if `touse' & `id'==`idj' & `expand'
					}
				}				
				getWidth `leftLB`i'' `strwid'
				summ `strwid' if `touse', meanonly
				local leftWD`i' = r(max)	// exact width of `maxlen' string
			}
			
			else {
				getWidth `leftLB`i'' `strwid'
				summ `strwid' if `touse', meanonly
				local maxwid = r(max)		// max width of existing text
				
				local leftWD`i' = cond(abs(`fmtlen') <= `maxlen', `maxwid', ///		// exact width of `maxlen' string
					abs(`fmtlen')*`digitwid')										// approx. max width (based on `digitwid')
			}

			
			** Check whether title string is longer than the data itself
			// If so, potentially allow spread over a suitable number of lines
			// [DF JAN 2015: Future work might be to re-write (incl. SpreadTitle) to use width rather than length??]

			// If more than one lcol, restrict to width of "data only" (i.e. _USE==1, 2).
			// Otherwise, title may be as long as the max string length in the column.
			// [Note that, as the title isn't stored as data (yet), the max string length does NOT account for the title string itself.]
			if `lcolsN' > 1 local anduse `"& inlist(`_USE', 1, 2)"'
			summ `strlen' if `touse' `anduse', meanonly
			local maxlen = r(max)
	
			local colName : variable label `leftLB`i''
			if `"`colName'"'!=`""' {

				if `target' <= 0 | missing(`target') {
					if `maxwidth' local target_opt = `maxwidth'
					else if "`double'"=="" {
						local target_opt = max(abs(`fmtlen'), `maxlen')
					}
					else local target_opt = `maxlen'
				}
				local maxwidth_opt = cond(`maxwidth', `maxwidth', `=2*`target_opt'')
				SpreadTitle `"`colName'"', target(`target_opt') maxwidth(`maxwidth_opt') maxlines(`maxlines') `truncate'
				
				if `r(nlines)' > `nlines' {
					local oldN = _N
					set obs `=`oldN' + `r(nlines)' - `nlines''
					local nlines = r(nlines)
					
					replace `_USE' = 9 if _n > `oldN'
					replace `touse' = 1 if _n > `oldN'
					replace `id' = `maxid' + (_n - `maxN')*`multip' + `add' + 1 if _n > `oldN'
					// "+1" leaves a one-line gap between titles & main data
				}
				
				local l = `nlines' - `r(nlines)'
				forvalues j = `r(nlines)'(-1)1 {
					local k = _N - (`j' + `l') + 1
					replace `leftLB`i'' = `"`r(title`j')'"' in `k'
				}
				
				getWidth `leftLB`i'' `strwid', replace			// re-calculate `strwid' to include titles

				summ `strwid' if `touse', meanonly
				local maxwid = r(max)
				local leftWD`i' = max(`leftWD`i'', `maxwid')	// in case title is necessarily longer than the variable, even after SpreadTitle
			}
			
			local leftWD`i' = `leftWD`i'' + (2 - (`i'==`lcolsN'))*`digitwid'	// having calculated the indent, add a buffer (2x except for last col)
			local leftWDtot = `leftWDtot' + `leftWD`i''							// running calculation of total width (including titles)
			
			drop `strlen' `strwid'
		}								// end of forvalues i=1/`lcolsN'
		
		
		** Right columns
		local rightWDtot = 0
		forvalues i=1/`rcolsN' {		// if `rcolsN'==0, loop will be skipped
			local rightLB`i' : word `i' of `rlablist'
			local fmtlen     : word `i' of `rfmtlist'

			// Aug 2023: remove "~" symbol (centered format) if necessary
			tokenize `fmtlen', parse("~")
			if "`1'"=="~" local fmtlen `2'
			confirm integer number `fmtlen'		
			
			gen long `strlen' = length(`rightLB`i'')
			summ `strlen' if `touse', meanonly
			local maxlen = r(max)		// max length of existing text

			// Apr 2020
			** DOUBLE LINE OPTION
			if `"`double'"'!=`""' {
			    forvalues j = 1 / `maxid' {
					summ `_USE' in `j', meanonly
					if inlist(`r(min)', 1, 2) {
						summ `id' in `j', meanonly
						local idj = r(min)
						local rightLBj = `rightLB`i''[`j']
						
						if `"`rightLB`i''"'!=`"`_EFFECT'"' {
							SpreadTitle `"`rightLBj'"', target(`=round(`maxlen'/2)') maxlines(2) notruncate
							replace `rightLB`i'' = `"`r(title1)'"' if `id'==`idj' & !`expand'
							replace `rightLB`i'' = `"`r(title2)'"' if `id'==`idj' & `expand'
						}
						else {		// Oct 2020: if _EFFECT, simply blank out the duplicated second line
							replace `rightLB`i'' = `""' if `id'==`idj' & `expand'							
						}
					}
				}
				getWidth `rightLB`i'' `strwid'
				summ `strwid' if `touse', meanonly
				local rightWD`i' = r(max)	// exact width of `maxlen' string
			}
			
			else {
				getWidth `rightLB`i'' `strwid'
				summ `strwid' if `touse', meanonly		
				local maxwid = r(max)		// max width of existing text

				local rightWD`i' = cond(abs(`fmtlen') <= `maxlen', `maxwid', ///	// exact width of `maxlen' string
					abs(`fmtlen')*`digitwid')										// approx. max width (based on `digitwid')
			}
			
			
			** Check whether title string is longer than the data itself
			// If so, spread it over a suitable number of lines
			// [DF JAN 2015: Future work might be to re-write (incl. SpreadTitle) to use width rather than length??]
			local colName : variable label `rightLB`i''
			if `"`colName'"'!=`""' {

				// June 2020
				// If _EFFECT column, make sure a line break is not placed in the middle of "(95% CI)"
				local ci_break = 0
				local strpos1 = strpos(`"`colName'"', `"("')
				local strpos2 = strpos(`"`colName'"', `"% CI)"')
				if `strpos2' & (`strpos2' - `strpos1' <= 3) {
				    local colName = subinstr(`"`colName'"', `"% CI)"', `"%_CI)"', 1)
					local ci_break = 1
				}
			
				if `target' <= 0 | missing(`target') {
					if `maxwidth' local target_opt = `maxwidth'
					else if "`double'"=="" {
						local target_opt = max(abs(`fmtlen'), `maxlen')
					}
					else local target_opt = `maxlen'
				}
				local maxwidth_opt = cond(`maxwidth', `maxwidth', `=2*`target_opt'')
				SpreadTitle `"`colName'"', target(`target_opt') maxwidth(`maxwidth_opt') maxlines(`maxlines') `truncate'

				if `r(nlines)' > `nlines' {
					local oldN = _N
					set obs `=`oldN' + `r(nlines)' - `nlines''
					local nlines = r(nlines)
					
					replace `_USE' = 9 if _n > `oldN'
					replace `touse' = 1 if _n > `oldN'
					replace `id' = `maxid' + (_n - `maxN')*`multip' + `add' + 1 if _n > `oldN'
					// "+1" leaves a one-line gap between titles & main data
				}
				
				local l = `nlines' - `r(nlines)'
				forvalues j = `r(nlines)'(-1)1 {
					local k = _N - (`j' + `l') + 1
					
					// June 2020
					// Reset the "(95% CI)" string, if appropriate
					local rtitlej `"`r(title`j')'"'
					if `ci_break' {
						local strpos1 = strpos(`"`rtitlej'"', `"("')
						local strpos2 = strpos(`"`rtitlej'"', `"%_CI)"')
						if `strpos2' & (`strpos2' - `strpos1' <= 3) {
							local rtitlej = subinstr(`"`rtitlej'"', `"%_CI)"', `"% CI)"', 1)
							local ci_break = 1
						}
					}
					replace `rightLB`i'' = `"`rtitlej'"' in `k'
				}
				
				getWidth `rightLB`i'' `strwid', replace			// re-calculate `strwid' to include titles
				
				summ `strwid' if `touse', meanonly
				local maxwid = r(max)
				local rightWD`i' = max(`rightWD`i'', `maxwid')		// in case title is necessarily longer than the variable, even after SpreadTitle
			}
			
			local rightWD`i' = `rightWD`i'' + (2 - (`i'==`rcolsN'))*`digitwid'		// having calculated the indent, add a buffer (2x except for last col)
			local rightWDtot = `rightWDtot' + `rightWD`i''							// running calculation of total width (incl. buffer)
			drop `strlen' `strwid'
		}								// end of forvalues i=1/`rcols'

		if !`rcolsN' & `"`colsonly'"'!=`""' local rightWDtot = 0		// if `colsonly', set to zero... [ADDED MAY 2024]
		else {
			local rightWDtot = `rightWDtot' + `rbuffer'*`digitwid'		// ...otherwise use a minimal buffer (default 1x but can be overwritten)
			local leftWDtot = max(`leftWDtot', `digitwid')				// ...before first RHS column and after last
		}

		
		** "Adjust" routine
		
		*  Notes:
		// Unless we're dealing with a very non-standard user-specific case,
		//   effect sizes corresponding to pooled diamonds (_USE==3, 5) will usually be much tighter around the null value than individual effects (_USE==1, 2).
		// The longest strings of text are also likely to be found in _USE==0, 3, 4, 5, since these contain subgroup headings and heterogeneity info.
		// Therefore, we may be able to improve the aesthetics of the plot by:
		//  (1) allowing text in LH columns for _USE==3, 5 to overlap text in LH columns for _USE==1, 2;
		//  (2) allowing text in LH columns for _USE==3, 5 to extend into the central plot area, beyond the default limit of `DXmin' but without overwriting plot elements.
		
		*  However, there are some considerations:
		// - LH text columns for _USE==1, 2 must *never* extend beyond `DXmin' (o/w long study labels and long CI limits might be overwritten)
		// - Column titles (i.e. variable labels; _USE==9) may only be extended for the last (i.e. right-most) left-hand column
		// - LH text columns for _USE==0, 3, 4, 5 may only be extended if there is no data in the remaining LH columns (if any) to their right
		// - In particular, if data exists in LH columns to the right, default behaviour is for "heterogeneity info" to be placed on a new line (_USE==4)
		//     rather than at the end of the "pooled overall/subgroup" text (_USE==3, 5).
		//     This may be overruled using `noextraline' with -(ad)metan- which implies `nolcolcheck' with -forestplot-
		// - _USE==6 represents a blank line, so these rows are irrelevant to the calculations.  The user may place text in such rows at their own discretion; it may get overwritten.
		
		*  Hence, the strategy is:
		// - Recalculate column widths (`leftWD`i'') restricting to _USE==1, 2, 9 (except last column, for which exclude _USE==9)
		// - BUT if a subsequent LH column has data in _USE==0, 3, 5 then previous adjustments are cancelled (unless `nolcolcheck')
		// - In this way, build up a recalculated total width (`leftWDtotNoTi').  If this is less than the original total (`leftWDtot'), then there is scope for "adjustment" (see below).

		if "`adjust'" == "" {

			// initialise locals
			local leftWDtotTi = 0
			local leftWDtotNoTi = 0
			// local adjustTot = 0
			// local adjustNew = 0
			
			// May 2018
			// If `nocolscheck', any lengthy text will be in _USE==4 rather than 3 or 5;  and such text should only exist in the first column so may be ignored

			// June 2018: this section re-written
			// Re-calculate widths of `lcols' for study estimates only (i.e. _USE==1, 2; this is `leftWD`i'NoTi')
			local lastcol = 1
			forvalues i=1/`lcolsN' {
				local fmtlen : word `i' of `lfmtlist'	// desired max no. of characters based on format -- also shows whether left- or right-justified

				// Aug 2023: remove "~" symbol (centered format) if necessary
				tokenize `fmtlen', parse("~")
				if "`1'"=="~" local fmtlen `2'
				
				// Check for data in observations *other* than study estimates (i.e. _USE==0, 3, 5, 7)
				// if there is, this becomes `lastcol'
				gen long `strlen' = length(`leftLB`i'')
				summ `strlen' if `touse' & inlist(`_USE', 0, 3, 5, 7), meanonly
				if r(N) & r(max) local lastcol = `i'

				// Now compare "total width" with "width for study estimates only" for current column only
				// (including titles, UNLESS last column of all (`lcolsN'); so that, if multiple columns, adjusted width of first column includes title
				//   and hence, second column doesn't obscure it)
				summ `strlen' if `touse' & (inlist(`_USE', 1, 2) | (`i'<`lcolsN' & `_USE'==9)), meanonly
				if !r(N) local leftWD`i'NoTi = 0		// if summary diamonds only (added Sep 2017 for v2.1)
				else {
					local maxlen = r(max)				// max length of text for study estimates only
					
					getWidth `leftLB`i'' `strwid'
					summ `strwid' if `touse' & (inlist(`_USE', 1, 2) | (`i'<`lcolsN' & `_USE'==9)), meanonly
					local maxwid = r(max)				// max width of text for study estimates only
					
					if "`double'"!="" local leftWD`i'NoTi = `maxwid'
					else {
						local leftWD`i'NoTi = cond(abs(`fmtlen') <= `maxlen', `maxwid', ///		// exact width of `maxlen' string
							abs(`fmtlen')*`digitwid')											// approx. max width (based on `digitwid')
					}
					// replace `lindent`i'NoTi' = cond(`fmtlen'>0, `leftWD`i'NoTi' - `strwid', 0)	// indent if right-justified
					drop `strwid'
				}
				local leftWD`i'NoTi = `leftWD`i'NoTi' + (2 - (`i'==`lcolsN'))*`digitwid'	// having calculated the indent, add a buffer (2x except for last col)
				
				drop `strlen'
			}
			
			// Finally, iterate `leftWDtotTi' ("unadjusted" widths up to and including `lastcol')
			//  and `leftWDtotNoTi' ("unadjusted" widths up to `lastcol', then "adjusted" widths)
			// Plus, if appropriate, cancel previous *single* adjustments
			//  (the above code only handles the running totals)
			if `"`lcolscheck'"'!=`""' local lastcol = 1
			forvalues i=1/`lcolsN' {
				if `i' < `lastcol' {
					local leftWD`i'NoTi = `leftWD`i''
					// replace `lindent`i'NoTi' = `lindent`i''
					local leftWDtotTi = `leftWDtotTi' + `leftWD`i''
				}
				else if `i' == `lastcol' {
					local leftWDtotTi = `leftWDtotTi' + `leftWD`i''
				}
				local leftWDtotNoTi = `leftWDtotNoTi' + `leftWD`i'NoTi'
			}
		
			// If appropriate, allow _USE=0,3,4,5 to extend into main plot by a factor of (lcimin-DXmin)/DXwidth
			//  where `lcimin' is the left-most confidence limit among the "diamonds" (including prediction intervals)
			// i.e. 1 + ((`lcimin'-`DXmin')/`DXwidth') * ((100-`astext')/`astext')) is the percentage increase
			// to apply to `leftWDtot'+`rightWDtot' in order to obtain `newleftWDtot'+`rightWDtot'.
			// Then rearrange to find `newleftWDtot'.
			if `leftWDtotNoTi' < `leftWDtot' {
			
				// June 2018:
				// Firstly, reset `leftWDtot'
				local leftWDtot = max(`leftWDtotTi', `leftWDtotNoTi')

				// sort out astext... need to do this now, but will be recalculated later (line 890)
				if `DXwidthChars'!=-9 & `astext'==-9 {
					local astext2 = (`leftWDtot' + `rightWDtot')/`DXwidthChars'
					local astext = 100 * `astext2'/(1 + `astext2')
				}
				else {
					local astext = cond(`astext'==-9, 50, `astext')
					assert `astext' >= 0
					local astext2 = `astext'/(100 - `astext')
				}
				
				// define some additional locals to make final formula clearer
				local totWD = `leftWDtot' + `rightWDtot'
				local lciWD = (`lcimin' - `DXmin')/(`DXmax' - `DXmin')
				local newleftWDtot = cond(`DXwidthChars'==-9, ///
					(`totWD' / ((`lciWD'/`astext2') + 1)) - `rightWDtot', ///
					`leftWDtot' - `lciWD'*`DXwidthChars')
					
				// Finally, reset `leftWDtot' once more
				// BUT don't make it any less than `leftWDtotNoTi', *unless* there are no obs with inlist(`_USE', 1, 2)
				// o/w longest study labels might overwrite longest CIs.
				count if `touse' & inlist(`_USE', 1, 2)
				local leftWDtot = cond(r(N), max(`leftWDtotNoTi', `newleftWDtot'), `newleftWDtot')
				
				// ...and similarly replace individual column widths
				forvalues i=1/`lcolsN' {
					local leftWD`i' = `leftWD`i'NoTi'
					// replace `lindent`i'' = `lindent`i'NoTi'
				}
			}
		}		// end if "`adjust'" == ""

		if !`lcolsN' & `"`colsonly'"'!=`""' local leftWDtot = 0			// if `colsonly', set to zero... [ADDED MAY 2024]
		else {
			local leftWDtot = `leftWDtot' + `lbuffer'*`digitwid'		// LHS buffer; default is zero
			local leftWDtot = max(`leftWDtot', `digitwid')				// ...otherwise use a minimal buffer for LHS of plotted data
		}
		
		// Calculate `textWD', using `astext' (% of graph width taken by text)
		//  to relate the width of plot area in "plot units" to the width of the columns in "text units"
		if `DXwidthChars'!=-9 & (`astext'==-9 | `"`newleftWDtot'"'!=`""') {
			local astext2 = (`leftWDtot' + `rightWDtot')/`DXwidthChars'
			local astext = 100 * `astext2'/(1 + `astext2')
			// local astext = cond(`DXwidthChars'>0, 100 * `astext2'/(1 + `astext2'), 100)		// added Feb 2018
		}
		else {
			local astext = cond(`astext'==-9, 50, `astext')
			assert `astext' >= 0
			local astext2 = `astext'/(100 - `astext')
		}
		local textWD = `astext2' * (`DXmax' - `DXmin')/(`leftWDtot' + `rightWDtot')

		// Generate positions of columns, in terms of "plot co-ordinates"
		// (N.B. although the "starting positions", `leftWD`i'' and `rightWD`i'', are constants, there will be indents if right-justified
		//      and anyway, all will need to be stored in variables for use with -twoway-)
		local leftWDruntot = 0
		forvalues i = 1/`lcolsN' {
			local left`i' : word `i' of `lvallist'		// extract next tempvar name from predefined list
			
			// June 2023: deprecate indentation in favour of use of mlabpos()
			local nextval = `DXmin' - (`leftWDtot' - `leftWDruntot')*`textWD'
			local leftWDruntot = `leftWDruntot' + `leftWD`i''	// iterate
			local nextpos 3
			gen double `left`i'' = `nextval'			// default, if left-justified

			// Aug 2023: allow centered formatting
			local fmtlen : word `i' of `lfmtlist'
			tokenize `fmtlen', parse("~")
			if "`1'"=="~" {
				// if centered, place halfway between this position and the next and use mlabpos(0)
				local nextnextval = `DXmin' - (`leftWDtot' - `leftWDruntot' + (2 - (`i'==`lcolsN'))*`digitwid')*`textWD'
				replace `left`i'' = (`left`i'' + `nextnextval')/2
				local nextpos 0
			}
			else if `fmtlen'>=0 {
				local nextnextval = `DXmin' - (`leftWDtot' - `leftWDruntot' + (2 - (`i'==`lcolsN'))*`digitwid')*`textWD'
				replace `left`i'' = `nextnextval'		// if right-justified; remove buffer from position value
				local nextpos 9
			}
			local lposlist `lposlist' `nextpos'
		}
		if !`lcolsN' {		// Added July 2015
			local left1 : word 1 of `lvallist'
			gen `left1' = `DXmin' - 2*`digitwid'*`textWD'
		}
		
		if `"`rfindent'"'!=`""' {
			tempvar rindent
			gen `rindent' = .
		}
		local rightWDruntot = `digitwid'		// initial 1x buffer
		forvalues i = 1/`rcolsN' {				// if `rcolsN'=0 then loop will be skipped
			local right`i' : word `i' of `rvallist'		// extract next tempvar name from predefined list
			
			// June 2023: deprecate indentation in favour of use of mlabpos()
			local nextval = `DXmax' + `rightWDruntot'*`textWD'
			local rightWDruntot = `rightWDruntot' + `rightWD`i''	// iterate
			local nextpos 3
			gen double `right`i'' = `nextval'			// default, if left-justified
			
			local fmtlen : word `i' of `rfmtlist'
			tokenize `fmtlen', parse("~")
			if "`1'"=="~" {
				// if centered, place halfway between this position and the next and use mlabpos(0)
				local nextnextval = `DXmax' + (`rightWDruntot' - (2 - (`i'==`rcolsN'))*`digitwid')*`textWD'
				replace `right`i'' = (`right`i'' + `nextnextval')/2
				local nextpos 0
			}

			// special case: if rfdist and left-justified, impose a small indent so that the CIs line up
			else if `"`rfindent'"'!=`""' & `i'==`rfcol' & `fmtlen'<0 {
				getWidth `rfindent' `rindent' if `touse' & !missing(`rfindent'), replace
				replace `right`i'' = `right`i'' + (`rindent' + `spacewid')*`textWD' if `touse' & !missing(`rfindent')
			}
			
			// if right-justified, obtain position of *next* column and use mlabpos(); but remove buffer from position value
			else if `fmtlen'>=0 {
				local nextnextval = `DXmax' + (`rightWDruntot' - (2 - (`i'==`rcolsN'))*`digitwid')*`textWD'
				replace `right`i'' = `nextnextval'
				local nextpos 9
			}
			
			local rposlist `rposlist' `nextpos'
		}		

		// Finish off `double'
		if `"`double'"'!=`""' {
			recast float `id' 
			replace `id' = `id' - 0.45 if `expand'==1
		}
	
	}		// end quietly
	
	
	// AXmin AXmax ARE THE OVERALL LEFT AND RIGHT COORDS
	summ `left1' if `touse', meanonly
	local AXmin = r(min)
	local AXmax = `DXmax' + `rightWDtot'*`textWD'
	
	return scalar leftWDtot = `leftWDtot'
	return scalar rightWDtot = `rightWDtot'
	return scalar AXmin = `AXmin'
	return scalar AXmax = `AXmax'
	return scalar astext = `astext'
	
	// June 2023
	return local lposlist `lposlist'
	return local rposlist `rposlist'
	
	return local graphopts `"`graphopts'"'

end


	

* Subroutine to "spread" titles out over multiple lines if appropriate
// Updated July 2014
// August 2016: identical program now used here, in admetan.ado, and in ipdover.ado
// May 2017: updated to accept substrings delineated by quotes (c.f. multi-line axis titles)
// August 2017: updated for better handling of maxlines()
// March 2018: updated to receive text in quotes, hence both avoiding parsing problems with commas, and maintaining spacing
// May 2018 and Nov 2018: updated truncation procedure

// subroutine of ProcessColumns

program define SpreadTitle, rclass

	syntax [anything(name=title id="title string")] [, TArget(integer 0) MAXWidth(integer 0) MAXLines(integer 0) noTRUNCate noUPDATE ]
	* Target = aim for this width, but allow expansion if alternative is wrapping "too early" (i.e before line is adequately filled)
	//         (may be replaced by `titlelen'/`maxlines' if `maxlines' and `notruncate' are also specified)
	* Maxwidth = absolute maximum width ... but will be increased if a "long" string is encountered before the last line
	* Maxlines = maximum no. lines (default 3)
	* noTruncate = don't truncate final line if "too long" (even if greater than `maxwidth')
	* noUpdate = don't update `target' if `maxwidth' is increased (see above)
	
	tokenize `title'
	if `"`1'"'==`""' {
		return scalar nlines = 0
		return scalar maxwidth = 0
		exit
	}
	
	if `maxwidth' & !`maxlines' {
		cap assert `maxwidth'>=`target'
		if _rc {
			nois disp as err `"{bf:maxwidth()} must be greater than or equal to {bf:target()}"'
			exit 198
		}
	}


	** Find length of title string, or maximum length of multi-line title string
	// First run: strip off outer quotes if necessary, but watch out for initial/final spaces!
	gettoken tok : title, qed(qed)
	cap assert `"`tok'"'==`"`1'"'
	if _rc {
		gettoken tok rest : tok, qed(qed)
		assert `"`tok'"'==`"`1'"'
		local title1 title1				// specifies that title is not multi-line
	}
	local currentlen = length(`"`1'"')
	local titlelen   = length(`"`1'"')
	
	// Subsequent runs: successive calls to -gettoken-, monitoring quotes with the qed() option
	macro shift
	while `"`1'"'!=`""' {
		local oldqed = `qed'
		gettoken tok rest : rest, qed(qed)
		assert `"`tok'"'==`"`1'"'
		if !`oldqed' & !`qed' local currentlen = `currentlen' + 1 + length(`"`1'"')
		else {
			local titlelen = max(`titlelen', `currentlen')
			local currentlen = length(`"`1'"')
		}
		macro shift
	}
	local titlelen = max(`titlelen', `currentlen')
	
	// Save user-specified parameter values separately
	local target_orig = `target'
	local maxwidth_orig = `maxwidth'
	local maxlines_orig = `maxlines'
	
	// Now finalise `target' and calculate `spread'
	local maxlines = cond(`maxlines_orig', `maxlines_orig', 3)	// use a default value for `maxlines' of 3 in these calculations
	local target = cond(`target_orig', `target_orig', ///
		cond(`maxwidth_orig', min(`maxwidth_orig', `titlelen'/`maxlines'), `titlelen'/`maxlines'))
	local spread = min(int(`titlelen'/`target') + 1, `maxlines')
	local crit = cond(`maxwidth_orig', min(`maxwidth_orig', `titlelen'/`spread'), `titlelen'/`spread')


	** If substrings are present, delineated by quotes, treat this as a line-break
	// Hence, need to first process each substring separately and obtain parameters,
	// then select the most appropriate overall parameters given the user-specified options,
	// and finally create the final line-by-line output strings.
	tokenize `title'
	local line = 1
	local title`line' : copy local 1				// i.e. `"`title`line''"'==`"`1'"'
	local newwidth = length(`"`title`line''"')

	// if first "word" is by itself longer than `maxwidth' ...
	if `maxwidth' & !(`maxlines' & (`line'==`maxlines')) {
	
		// ... reset parameters and start over
		while length(`"`1'"') > `maxwidth' {
			local maxwidth = length(`"`1'"')
			local target = cond(`target_orig', cond(`"`update'"'!=`""', `target_orig', `target_orig' + `maxwidth' - `maxwidth_orig'), ///
				cond(`maxwidth', min(`maxwidth', `titlelen'/`maxlines'), `titlelen'/`maxlines'))
			local spread = min(int(`titlelen'/`target') + 1, `maxlines')
			local crit = cond(`maxwidth', min(`maxwidth', `titlelen'/`spread'), `titlelen'/`spread')
		}
	}
	
	macro shift
	local next : copy local 1		// i.e. `"`next'"'==`"`1'"' (was `"`2'"' before macro shift!)
	while `"`1'"' != `""' {
		// local check = `"`title`line''"' + `" "' + `"`next'"'			// (potential) next iteration of `title`line''
		local check `"`title`line'' `next'"'							// (amended Apr 2018 due to local x = "" issue with version <13)
		if length(`"`check'"') > `crit' {								// if longer than ideal...
																		// ...and further from target than before, or greater than maxwidth
			if abs(length(`"`check'"') - `crit') > abs(length(`"`title`line''"') - `crit') ///
					| (`maxwidth' & (length(`"`check'"') > `maxwidth')) {
				if `maxlines' & (`line'==`maxlines') {					// if reached max no. of lines
					local title`line' : copy local check				//   - use next iteration anyway (to be truncated)

					macro shift
					local next : copy local 1
					local newwidth = max(`newwidth', length(`"`title`line''"'))		// update `newwidth'					
					continue, break
				}
				else {										// otherwise:
					local ++line							//  - new line
					
					// if first "word" of new line (i.e. `next') is by itself longer than `maxwidth' ...
					if `maxwidth' & (length(`"`next'"') > `maxwidth') {
					
						// ... if we're on the last line or last token, continue as normal ...
						if !((`maxlines' & (`line'==`maxlines')) | `"`2'"'==`""') {
						
							// ... but otherwise, reset parameters and start over
							local maxwidth = length(`"`next'"')
							local target = cond(`target_orig', cond(`"`update'"'!=`""', `target_orig', `target_orig' + `maxwidth' - `maxwidth_orig'), ///
								cond(`maxwidth', min(`maxwidth', `titlelen'/`maxlines'), `titlelen'/`maxlines'))
							local spread = min(int(`titlelen'/`target') + 1, `maxlines')
							local crit = cond(`maxwidth', min(`maxwidth', `titlelen'/`spread'), `titlelen'/`spread')
							
							// restart loop
							tokenize `title'
							local tok = 1
							local line = 1
							local title`line' : copy local 1				// i.e. `"`title`line''"'==`"`1'"'
							local newwidth = length(`"`title`line''"')
							macro shift
							local next : copy local 1		// i.e. `"`next'"'==`"`1'"' (was `"`2'"' before macro shift!)
							continue
						}
					}
					
					local title`line' : copy local next		//  - begin new line with next word
				}
			}
			else local title`line' : copy local check		// else use next iteration
			
		}
		else local title`line' : copy local check			// else use next iteration

		macro shift
		local next : copy local 1
		local newwidth = max(`newwidth', length(`"`title`line''"'))		// update `newwidth'
	}																	// (N.B. won't be done if reached max no. of lines, as loop broken)


	* Return strings
	forvalues i=1/`line' {
	
		// truncate if appropriate (last line only)
		if `i'==`line' & "`truncate'"=="" & `maxwidth' {
			local title`i' = substr(`"`title`i''"', 1, `maxwidth')
		}
		return local title`i' `"`title`i''"'
	}
	
	* Return values
	return scalar nlines = `line'
	return scalar maxwidth = min(`newwidth', `maxwidth')
	return scalar target = `target'
	
end




*********************************************************************************

program define UserSpecHide, rclass

	syntax varname [if] [in], PLOTID(varname numeric) [ OCILINEOPts(string asis) RFCILINEOPts(string asis) * ]
	local _USE : copy local varlist
	marksample touse
	local reduceHeight = 0
	
	local 0 `", `ocilineopts'"'
	syntax [, HIDE * ]
	if `"`hide'"'!=`""' {
		qui count if `touse' & inlist(`_USE', 3, 5, 7)
		local reduceHeight = r(N)
	}
	else {
		local 0 `", `rfcilineopts'"'
		syntax [, HIDE * ]
		if `"`hide'"'!=`""' {
			qui count if `touse' & inlist(`_USE', 3, 5, 7)
			local reduceHeight = r(N)
		}
		else {
			summ `plotid' if `touse', meanonly
			forvalues p = 1/`r(max)' {
				local hide
				local 0 `", `graphopts'"'
				syntax [, OCILINE`p'opts(string asis) RFCILINE`p'opts(string asis) * ]
				local 0 `", `ociline`p'opts'"'
				syntax [, HIDE * ]
				if `"`hide'"'!=`""' {
					qui count if `touse' & `plotid'==`p' & inlist(`_USE', 3, 5, 7)
					local reduceHeight = `reduceHeight' + r(N)
				}
				else {
					local 0 `", `rfciline`p'opts'"'
					syntax [, HIDE * ]
					if `"`hide'"'!=`""' {
						qui count if `touse' & `plotid'==`p' & inlist(`_USE', 3, 5, 7)
						local reduceHeight = `reduceHeight' + r(N)
					}
				}
			}
		}
	}
	return scalar N = `reduceHeight'
	
end




*********************************************************************************

*** FIND OPTIMAL TEXT SIZE AND ASPECT RATIOS (given user input)

// Notes:  (David Fisher, July 2014)
	
// Let X, Y be dimensions of graphregion (outer; controlled by xsize(), ysize()); x, y be dimensions of plotregion (inner; controlled by aspect()).
// `approxChars' is the approximate width of the plot, in "character units" (i.e. width of [LHS text + RHS text] divided by `astext')
	
// Note that a "character unit" is the width of a character relative to its height; 
//  hence `height' is the approximate height of the plot, in terms of both rows of text (with zero gap between rows) AND "character units".
	
// If Y/X = `graphAspect'<1, `textSize' is the height of a row of text relative to Y; otherwise it is height relative to X.
// (Note that the default `graphAspect' = 4/5.5 = 0.73 < 1)
// We then let `approxChars' = x, and manipulate to find the optimum text size for the plot layout.

// FEB 2015: `textsize' is deprecated, since it causes problems with spilling on the RHS.
// Instead, using `spacing' to fine-tune the aspect ratio (and hence the text size)
//   or use `aspect' to completely user-define the aspect ratio.
// MAY 2020: Following discussion with Jonathan Sterne, option textsize() has been reinstated
// But it works *at the end*, after the aspect ratio has already been calculated -- so it's "use at your own risk"
// Internally, it is renamed to `textscale', since it is actually a scale, and it avoids clashing with already-coded `textsize'

//  - Note that this code has been changed considerably from the original -metan9- code.

// Moved into separate subroutine Nov 2017 (for v2.2 beta)

program define GetAspectRatio, rclass

	syntax [, ASTEXT(real 50) COLWDTOT(real 0) HEIGHT(real 0) USEDIMS(name) ///
		ASPECT(real -9) SPacing(real -9) XSIZe(real -9) YSIZe(real -9) FXSIZe(real -9) FYSIZe(real -9) ///
		TItle(string asis) SUBtitle(string asis) CAPTION(string asis) NOTE2(string asis) noNOTE noWARNing ///
		XTItle(string asis) ROWSFAV(real 0) ADDHeight(real 0) /*(undocumented)*/ ///
		TEXTSize(real 100.0) /// /* legacy -metan9- option, implemented here as a post-hoc option; use at own risk */
		ROWSXLAB(real 0) /*DXWIDTHChars(real -9)*/ DOUBLE COLSONLY * ]
	
	local graphopts `"`options'"'
	
	// Error message copied directly from -metan9-
	if `textsize' < 20 | `textsize' > 500 {
		di as error "Text scale (TEXTSize) must be within 20-500"
		di as error "Value is character size relative to graph"
		di as error "Outside range will either be unreadable or too large"
		exit 198
	}
	local textscale : copy local textsize	// rename to `textscale' for internal use...
	local textsize							// ... and reset `textsize' macro [May 2020]
	
	* Unpack `usedims'
	local DXwidthChars : copy local dxwidthchars		// added Feb 2018: clarity
	local DXwidthChars = -9		// initialize
	local oldTextSize = -9		// initialize
	if `"`usedims'"'!=`""' {
		local DXwidthChars = `usedims'[1, `=colnumb(matrix(`usedims'), "cdw")']
		local spacing = cond(`spacing'==-9, `usedims'[1, `=colnumb(matrix(`usedims'), "spacing")'], `spacing')
		local oldPlotAspect = `usedims'[1, `=colnumb(matrix(`usedims'), "aspect")']		// modified Nov 2017
		local oldXSize = `usedims'[1, `=colnumb(matrix(`usedims'), "xsize")']
		local oldYSize = `usedims'[1, `=colnumb(matrix(`usedims'), "ysize")']
		local oldTextSize = `usedims'[1, `=colnumb(matrix(`usedims'), "textsize")']
		local oldHeight = `usedims'[1, `=colnumb(matrix(`usedims'), "height")']			// added Sep 2017
		local oldYheight = `usedims'[1, `=colnumb(matrix(`usedims'), "yheight")']		// added Sep 2017
		
		numlist "`DXwidthChars' `spacing' `oldPlotAspect' `oldXSize' `oldYSize' `oldTextSize' `oldHeight' `oldYheight'", min(8) max(8) range(>=0)
	}


	* Obtain number of rows within each title element
	// (see help title_options)
	// [modified Nov 2017]
	// (N.B. favours will be done separately)
	// [modified Feb 2018]
	// [Jan 2019: converted to subroutine for better parsing of compound quotes]
	foreach opt in title subtitle caption note xtitle {
		GetRows ``opt''
		local rows`opt' = r(rows)
	}

	local condtitle = 2*`rowstitle' + 1.5*`rowssubtitle' + 1.25*`rowscaption' + 1.25*`rowsnote'	// approximate multipliers for different text sizes + gaps
	local condtitle = `condtitle' + (`"`title'"'!=`""' & `"`subtitle'"'!=`""')					// additional gap between title and subtitle, if *both* specified
	local condtitle = `condtitle' + 2 + `addheight'												// add 2 for graphregion(margin())

	// Now derive small amounts `xdelta', `ydelta', to take account of the space taken up by titles etc.
	// Assume that, if plot is "full-width", then X = x * xdelta
	//  and that, if plot is "full-height", then Y = y * ydelta	
	// local ydelta = (`height' + `condtitle' + (`"`xlablist'"'!=`""') + `rowsfav' + `rowsxtitle')/`height'
	local ydelta = (`height' + `condtitle' + `rowsxlab' + `rowsfav' + `rowsxtitle')/`height'			// Nov 2017
	local xdelta = (`height' + `condtitle')/`height'		// Oct 2016: check logic of this, why difference in what is added??
	// Notes Feb 2015:
	// - could maybe be improved, but for now `addheight' option (undocumented) allows user to tweak
	// - also think about line widths (thicknesses), can we keep them constant-ish??
	// May 2016: yes, should be quite easy -- choose a reasonable value based on the height, then amend it in the same way as textsize	

	
	* Derive `approxChars', `spacing' and `plotAspect'
	// (possibly using saved "dimensions")
	// (for future: investigate using margins to "centre on DXwidth" within graphregion??)
	if `"`usedims'"'==`""' {
		local approxChars = 100*`colwdtot'/`astext'
		
		if `aspect' != -9 {					// user-specified aspect of plotregion
			if `spacing' == -9 local spacing = `aspect' * `approxChars' / `height'		// [modified Nov 2017]
			local plotAspect = `aspect'
		}
		else {								// if not user-specified
			// if "natural aspect" (`height'/`approxChars') is 2x1 or wider, use double spacing; else use 1.5-spacing
			// Apr 2020: if -double- option, increase the spacing again... 4/3 seems to work (N.B. this is 2/1.5, i.e. ratio of usual options)
			// (unless user-specified, in which case use that)
			if `spacing' == -9 local spacing = cond(`height'/`approxChars' <= .5, 2, 1.5)
			if `"`double'"'!=`""' local spacing = (4/3) * `spacing'
			local plotAspect = `spacing' * `height' / `approxChars'
		}
	}
	else {	// if `usedims' supplied
		local approxChars = `colwdtot' + cond(`"`colsonly'"'!=`""', 0, `DXwidthChars')		// modified Feb 2018
		local plotAspect = cond(`aspect'==-9, `spacing'*`height'/`approxChars', `aspect')
		// `spacing' here is from `usedims' unless over-ridden by user
	}
	numlist "`plotAspect' `spacing'", range(>=0)

	
	* Derive graphAspect = Y/X (defaults to 4/5.5  = 0.727 unless specified)
	// [modified Nov 2017]
	if `"`usedims'"'==`""' {
		local oldYSize = 4
		local oldXSize = 5.5
	}
	local graphAspect = cond(`ysize'==-9, `oldYSize', `ysize') ///
		/ cond(`xsize'==-9, `oldXSize', `xsize')
	
	// July 2015
	* Standard approach is now to use `graphAspect' and `plotAspect' to determine `textSize'.
	if `"`usedims'"'==`""' {
		
		// (1) If y/x < Y/X < 1 (i.e. plot takes up full width of "wide" graph) then X = x * xdelta
		//     ==> `textSize' = 100/Y = 100/(X * `graphAspect') = 100/(`xdelta' * `approxChars' * `graphAspect')
		if `graphAspect' <= 1 & `plotAspect' <= `graphAspect' {
			local textSize = 100 / (`xdelta' * `approxChars' * `graphAspect')
		}
		
		// (2) If Y/X < 1 and y/x > Y/X (i.e. plot is less wide than "wide" graph) then Y = y * ydelta
		//     ==> `textSize' = 100/Y = 100/(ydelta * x * `plotAspect') = 100 / (`ydelta' * `approxChars' * `plotAspect')
		else if `graphAspect' <= 1 & `plotAspect' > `graphAspect' {
			local textSize = 100 / (`ydelta' * `approxChars' * `plotAspect')
		}
			
		// (3) If y/x > Y/X > 1 (i.e. plot takes up full height of "tall" graph) then Y = y * ydelta
		//     ==> `textSize' = 100/X = 100 * `graphAspect'/(y * ydelta) = 100 * `graphAspect' / (`ydelta' * `approxChars' * `plotAspect')
		else if `graphAspect' > 1 & `plotAspect' > `graphAspect' {
			local textSize = (100 * `graphAspect') / (`ydelta' * `approxChars' * `plotAspect')
		}
			
		// (4) If Y/X > 1 and y/x < Y/X (i.e. plot is less tall than "tall" graph) then X = x * xdelta
		//     ==> `textSize' = 100/X = 100 / (`xdelta' * `approxChars')
		else if `graphAspect' > 1 & `plotAspect' <= `graphAspect' {
			local textSize = 100 / (`xdelta' * `approxChars')
		}
		
		// [added Nov 2017]
		// If Y/X = `graphAspect' <= 1 ("wide"), set fysize to 100; else ("tall") set fxsize to 100
		// in other words, min dimension is always 100; the other is >100
		local fxsize = cond(`fxsize' == -9, cond(`graphAspect' <= 1, 100/`graphAspect', 100), `fxsize')
		local fysize = cond(`fysize' == -9, cond(`graphAspect' <= 1, 100, 100*`graphAspect'), `fysize')
	}

	* Else if `usedims' supplied:
	* oldGraphAspect and oldPlotAspect would have been derived using the rules above
	* we immediately know the new plotAspect = `spacing'*`height'/`approxChars' (using new `approxChars')
	* (assuming the height is the same -- come back to this point maybe)
	* So:
	// (1) old y/x < Y/X < 1 ==> plot takes up full width
	// (a) if newplotAspect is wider still (new y/x < old y/x) then it will have to "shrink" (i.e. lose height)
	//     ==> widen newgraphAspect by the same amount?? (minus delta, because that will be constant)
	//     But, since in all cases Y is less than X, `textSize' is based on Y, so should still be correct.
	// (b) if newplotAspect is less wide (new y/x > old y/x) it will fit fine, so again `textSize' will be fine.
		
	// (2) old Y/X < 1, old y/x > Y/X (i.e. old plot is less wide than "wide" graph)
	// (a) if newplotAspect is wider, then everything is fine UNLESS new y/x ends up <Y/X.
	//     However, we're then in case (1)(a) so once newgraphAspect is widened, `textSize' should be fine.
	// (b) if newplotAspect is less wide, it will fit fine, so again `textSize' will be fine.
		
	// (3) If y/x > Y/X > 1 (i.e. plot takes up full height of "tall" graph)
	// (a) if newplotAspect is wider, then everything is fine UNLESS new y/x ends up <Y/X.
	//     ==> need to widen newgraphAspect (minus delta, because that will be constant)
	//     Then if newgraphAspect is still > 1, we're in case (1)(a) again
	//     BUT if newgraphAspect is now < 1, then we'll need to amend `textSize'.
	// (b) if newplotAspect is less wide, it will fit fine, so again `textSize' will be fine.
		
	// (4) If Y/X > 1 and y/x < Y/X (i.e. plot is less tall than "tall" graph) 
	// (a) if newplotAspect is wider, newgraphAspect will ALWAYS need to be widened to avoid "shrinkage"
	//     Then if newgraphAspect is still > 1, we're in case (1)(a) again
	//     BUT if newgraphAspect is now < 1, then we'll need to amend `textSize'.
	// (b) if newplotAspect is less wide, it will have to "expand" (i.e. gain height)	
	//     ==> *reduce* width of newgraphAspect	by the same amount
	//     But, since in all cases X is less than Y, `textSize' is based on X, so should still be correct.
		
	* So, scenarios in which to take action are:
	// (1)(a): increase width of newgraphAspect;
	//         no change to `textSize'
	// (2)(a): check new y/x: if y/x < Y/X then increase width of newgraphAspect;
	//         no change to `textSize'
	// (3)(a): check new y/x: if y/x < Y/X then increase width of newgraphAspect;
	//         then check new Y/X: if <1 then need to amend `textSize'
	// (4)(a): increase width of newgraphAspect;
	//         check new Y/X: if <1 then need to amend `textSize'
	// (4)(b): reduce width of newgraphAspect;
	//         no change to `textSize'		
	
	else {
		local textSize = `oldTextSize'				// tidy this up
			
		// 1a & 2a
		if `graphAspect' <= 1 & `plotAspect' <= `graphAspect' {
		
			if `xsize'==-9 | `ysize'==-9 {
				local graphAspect = `graphAspect' * `plotAspect' / `oldPlotAspect'

				// Modified Nov 2017
				if `xsize'==-9 & `ysize'==-9 local xsize = `oldYSize' / `graphAspect'
				else {
					if `xsize'==-9 local xsize = `ysize' / `graphAspect'
					else           local ysize = `xsize' * `graphAspect'
				}
			}
		}
			
		// 3a, 4a, 4b
		else if `graphAspect' > 1 & ///
			((`oldPlotAspect' > `graphAspect' & `plotAspect' <= `graphAspect') ///
			| (`oldPlotAspect' <= `graphAspect')) {

			if `xsize'==-9 | `ysize'==-9 {
				local oldGraphAspect = `graphAspect'
				local graphAspect = `oldGraphAspect' * `plotAspect' / `oldPlotAspect'

				// Modified Nov 2017
				if `xsize'==-9 & `ysize'==-9 local xsize = `oldYSize' / `graphAspect'
				else {
					if `xsize'==-9 local xsize = `ysize' / `graphAspect'
					else           local ysize = `xsize' * `graphAspect'
				}

				// 3a, 4a
				if `graphAspect' <= 1 {
					local textSize = `textSize' / `oldGraphAspect'
				}
			}
		}
		
		// Added Nov 2017, revised Feb 2018
		local fxsize = cond(`fxsize'==-9, 100*(`oldPlotAspect'/`plotAspect')*(`height'/`oldHeight')*(`oldXSize'/`oldYSize'), `fxsize')
		local fysize = cond(`fysize'==-9, 100*`ydelta'*`height'/`oldYheight', `fysize')
	}
	
	* Notes: for random-effects analyses, sample-size weights, or user-defined (will overwrite the first two)
	if `"`note2'"'!=`""' {
		local 0 `"`note2'"'
		syntax [anything(name=notetxt everything)] [, SIze(string) * ]
		if "`size'"=="" local size = `textSize' * .75 * `textscale'/100		// use 75% of text size used for rest of plot
		if "`colsonly'"!="" local notetxt `"" ""'							// added Feb 2018
		
		// May 2018: Having parsed the note, now suppress it if noWARNing or noNOTE
		if `"`warning'`note'"'==`""' local noteopt `"note(`notetxt', size(`size') `options')"'
	}
	
	// collect options relevant to GetAspectRatio which also need ultimately to be passed to -twoway-
	// N.B. *not* favours; instead returned as `leftfav' and 'rightfav'
	// [Feb 2018] Also *not* xtitle, as already parsed at beginning of code
	foreach opt in /*xtitle*/ title subtitle caption {
		if trim(`"``opt''"')!=`""' {
			local graphopts `"`graphopts' `opt'(``opt'')"'
		}
	}
	return local graphopts `"`graphopts' `noteopt'"'
	
	
	* Return scalars
	return scalar xsize = cond(`xsize'==-9, 5.5, `xsize')		// added Nov 2017
	return scalar ysize = cond(`ysize'==-9, 4, `ysize')			// added Nov 2017
	return scalar fxsize = `fxsize'
	return scalar fysize = `fysize'
	return scalar yheight = `ydelta'*`height'
	return scalar textsize = `textSize'						// textsize as calculated by this routine
	return scalar textsize2 = `textSize' * `textscale'/100	// textsize as modified post-hoc by textscale() option [May 2020]
	return scalar spacing = `spacing'
	return scalar approxchars = `approxChars'
	return scalar graphaspect = `graphAspect'
	return scalar plotaspect = `plotAspect'
		
end
		

* GetRows: subroutine of GetAspectRatio
// added Jan 2019
program define GetRows, rclass
	syntax [anything(id="text string")] [, *]
	local rows = 0
	if `"`anything'"'!=`""' {
		// March 2018
		// word count has trouble with apostrophes (but not double-quotes)
		// so replace them with "a" for the purposes of word-counting
		/*
		local rest : subinstr local anything `"'"' `"a"', all
		gettoken foo bar : rest, qed(q) quotes
		local rows = cond(`q', `: word count `rest'', 1)
		*/

		// Jan 2019: if title() etc. finds "" or `""' at the start, the title is set to nothing
		if substr(trim(`"`anything'"'), 1, 2)==`""""' | substr(trim(`"`anything'"'), 1, 4)==`"`""'"' {
			return scalar rows = 0
			exit
		}
		
		// Jan 2019: else, remove quotes using gettoken
		gettoken foo bar : anything, qed(q) quotes
		local rows = cond(`q', `: word count `anything'', 1)
	}
	return scalar rows = `rows'
end



*********************************************************************************

** Program to build plot commands for the different elements
// from plotopts and plot`p'opts

// August 2018: removed "sortpreserve" (since we are adding new obs).
// Instead, repect sort order (of `touse' `id') "manually".
// (N.B. no further sorting takes place in main routine hereafter.)

// August 2018: N.B. unusually, have to pass `touse' as an option here (rather than using marksample)
// since we need to have the same tempname appearing in the created plot commands

program define BuildPlotCmds, sclass

	syntax varlist(numeric min=4 max=4 default=none), TOUSE(varname numeric) ID(varname numeric) ///
		CXLIST(numlist min=2 max=2) ///
		[PLOTID(varname numeric) DATAID(varname numeric) NEWwt H0(real 0) noNULL ///
		CLASSIC noDIAmonds INTERaction COLSONLY CUmulative INFluence noOVerall noSUbgroup ///
		WGT(varname numeric) RFDIST(varlist numeric) BOXscale(real 100.0) noBOX ///
		DIAMLIST(namelist) OVLIST(namelist) OFFSCLIST(namelist) RFLIST(namelist) TOUSEEXTRA(namelist) * ]

	
	// JAN 2020:  This subroutine has been rearranged.
	// GENERAL IDEA:  we don't *need* the actual variables in order to build the plot commands; we just to know the variable *names*.
	// Therefore, we can build the plot commands *first*, and then mess about with the variables themselves afterwards.
	// This means e.g. we can first identify whether, and where, -expand- is needed for area plots (e.g. diamonds or CI area plots)
	//   and then do this work *later*, whilst accounting for "hidden" pooled observations (needed e.g. for `cumulative' or `influence').
	
	tokenize `varlist'
	args _USE _ES _LCI _UCI
	
	tokenize `cxlist'
	args CXmin CXmax
	
	local _WT `wgt'
	local awweight `"[aw= `_WT']"'		// moved here 30th Jan 2018
	
	if "`box'"!="" local oldbox nobox		// allow "global" option `nobox' for compatibility with -metan-
											// N.B. can't be used with plotid; instead box`p'opts(msymbol(none)) can be used

	** Some initial setup
	summ `plotid' if `touse', meanonly
	local np = r(max)
	cap confirm var `dataid'
	if _rc local nd = 1
	else {
		qui tab `dataid' if `touse'		// Nov 2021: changed from "summ `dataid'" as may not be ordinal
		local nd = r(r)
		local dataidopt `"& `dataid'==`dataid'[_n-1]"'
	}
		

	** SETUP OFF-SCALE ARROWS -- fairly straightforward
	// (include use==3, 5, 7 in case of pciopts/rfopts)
	tokenize `offsclist'
	args offscaleL offscaleR
	qui gen byte `offscaleL' = `touse' * inlist(`_USE', 1, 3, 5, 7) * (float(`_LCI') < float(`CXmin'))
	qui gen byte `offscaleR' = `touse' * inlist(`_USE', 1, 3, 5, 7) * (float(`_UCI') > float(`CXmax') & !missing(`_UCI'))

	// rfdist: only applies to use==3, 5, 7
	// BUT may need up to four tempvars in niche cases (e.g. only part of the rfCI is visible)
	// ==> to save on tempvars, only use them if more than one; o/w use local macros
	if `"`rfdist'"'!=`""' {
		tokenize `rfdist'
		args _rfLCI _rfUCI
	
		tokenize `rflist'
		args rfLoffscaleL rfRoffscaleR rfRoffscaleL rfLoffscaleR rfLineLCI rfLineUCI rfLineX

		local touse3 `"`touse' & inlist(`_USE', 3, 5, 7)"'
		qui count if `touse3'
		if r(N) {
			gen byte `rfLoffscaleL' = `touse3' * (float(`_rfLCI') < float(`CXmin'))
			gen byte `rfRoffscaleR' = `touse3' * (float(`_rfUCI') > float(`CXmax') & !missing(`_rfUCI'))
			
			qui count if `touse3' & float(`_UCI') < float(`CXmin')
			if r(N) {
				gen byte `rfRoffscaleL' = `touse3' * (float(`_UCI') < float(`CXmin'))
			}
			else {
				gen byte `rfRoffscaleL' = `touse3' * (float(`_LCI') > float(`CXmax') & !missing(`_LCI'))
			}
			
			qui count if `touse3' & float(`_LCI') > float(`CXmax') & !missing(`_LCI')
			if r(N) {
				gen byte `rfLoffscaleR' = `touse3' * (float(`_LCI') > float(`CXmax') & !missing(`_LCI'))
			}
			else {
				gen byte `rfLoffscaleR' = `touse3' * (float(`_UCI') < float(`CXmin'))
			}
		}
		else {
		    local rfLoffscaleL = 0
			local rfRoffscaleR = 0
		}
	}

	
	** "OVERALL EFFECT" LINES
	tokenize `ovlist'
	args ovLine ovMin ovMax ovLineLCI ovLineUCI ovLineX		// `ovLineLCI' `ovLineUCI' `ovLineX' added Jan 2020
		
	qui gen float `ovLine' = .
		
	// Construct groups of observations containing a single obs where _USE==3 or 5
	// Within each `dataid', such groups ("olinegroup") are identified by _USE==5 if present ("overall"), or _USE==3 otherwise ("subgroup").
	qui count if `touse' & inlist(`_USE', 3, 5)
	if r(N) {
		tempvar useno
		qui gen byte `useno' = `_USE' * inlist(`_USE', 3, 5) if `touse'
	
		sort `touse' `dataid' `id'
		qui by `touse' : replace `useno' = `useno'[_n-1] if _n>1 & `useno'<=`useno'[_n-1] `dataidopt'		// find the largest value (from 3 & 5) "so far"

		tempvar olinegroup check
		qui gen int `olinegroup' = (`_USE'==`useno') * (`useno'>0)
		qui by `touse' `dataid' : replace `olinegroup' = sum(`olinegroup') if inlist(`_USE', 1, 2, 3, 5)	// study obs & pooled results

		// "check": only draw oline if there are study obs in the same olinegroup
		qui gen byte `check' = inlist(`_USE', 1, 2) if `touse'
		qui bysort `touse' `dataid' `olinegroup' (`check') : replace `check' = `check'[_N]
		sort `touse' `dataid' `olinegroup' `id'
	
		// Store values for later plotting
		// [modified Jan 2020]
		qui by `touse' `dataid' `olinegroup' : replace `ovLine' = `_ES'[1] if `touse' & `check' & !( `_ES'[1] > `CXmax' |  `_ES'[1] < `CXmin')
	}
		
	// "flags" to identify dummy variables for multiple plotids,
	// and/or where area plots are needed, for later -expand- [added Jan 2020]
	tokenize `touseextra'
	args tv0 touseDiam touseOCI touseRFCI
	qui gen byte `touseDiam' = 2 * `touse' * (`"`cumulative'`influence'"'==`""')
	// 0 = hide (+ ociline); 1 = pci/ppoint (line); 2 = diamonds (area + no lines; default)
	qui gen byte `touseOCI' = 0		// 0 = no lines or area (default); 1 = lines; 2 = area (+ lines)
	if `"`rfdist'"'!=`""' qui gen byte `touseRFCI' = 0		// same
	
	
	
	** IF MULTIPLE PLOTIDs, or if dataid(varname, newwt) specified,
	// create dummy obs with global min & max weights, to maintain correct weighting throughout
	if (`np' > 1 | `"`newwt'"'!=`""') {		// Amended June 2015

		// create new `touse', including new dummy obs
		qui gen byte `tv0' = `touse'
		local tousePlotID `tv0'
		
		// find global min & max weights, to maintain consistency across subgroups
		if `"`newwt'"'==`""' {		// weight consistent across dataid, so just do this once
			summ `_WT' if `touse' & inlist(`_USE', 1, 2), meanonly
			local minwt = r(min)
			local maxwt = r(max)
		}
		
		local oldN = _N
		local newN = `oldN' + 2*`nd'*`np'	// N.B. `nd' indexes `dataid'; `np' indexes `plotid'
		qui set obs `newN'
		forvalues i=1/`nd' {
			forvalues j=1/`np' {
				
				// dataid-specific min/max weights required
				if `"`newwt'"'!=`""' {		// weight consistent across dataid, so just use locals
					summ `_WT' if `touse' & inlist(`_USE', 1, 2) & `dataid'==`i', meanonly	
					local minwt = r(min)
					local maxwt = r(max)
				}
				
				local k = `oldN' + (`i'-1)*2*`np' + 2*`j'
				if `"`dataidopt'"'!=`""' {
					qui replace `dataid' = `i' in `=`k'-1' / `k'
				}
				qui replace `plotid' = `j' in `=`k'-1' / `k'
				qui replace `_WT' = `minwt' in `=`k'-1'
				qui replace `_WT' = `maxwt' in `k'
			}
		}
		qui replace `_USE'   = 1 in `=`oldN' + 1' / `newN'
		qui replace `touse'  = 0 in `=`oldN' + 1' / `newN'
		qui replace `tousePlotID' = 1 in `=`oldN' + 1' / `newN'
	}
	// these dummy obs are identifiable by "`tousePlotID' & !`touse'"

	else local tousePlotID `touse'		// else, no need for separate variable `tousePlotID'
	
	
	
	** DEFAULTS
	
	* Default options for simple graph elements
	cap assert `boxscale' >=0
	if _rc == 9 {
		disp as err `"value of {bf:boxscale()} must be >= 0"'
		exit 125
	}
	else if _rc {
		disp as err `"error in {bf:boxscale()} option"'
		exit _rc
	}
	local boxSize = `boxscale'/150	
	
	local defShape = cond("`interaction'"!="", "circle", "square")
	local defColor = cond("`classic'"!="", "black", "180 180 180")
	local defBoxOpts `"mcolor("`defColor'") msymbol(`defShape') msize(`boxSize')"'
	if `"`oldbox'"'!=`""' local defBoxOpts `"msymbol(none)"'	// -metan- "nobox" option
	local defCIOpts `"lcolor(black) mcolor(black)"'				// includes "mcolor" for arrows (doesn't affect rspike/rcap)
	local defPointOpts `"msymbol(diamond) mcolor(black) msize(vsmall)"'
	local defOlineOpts `"lwidth(thin) lcolor(maroon) lpattern(shortdash)"'
	local defOCIlineOpts  `"`defOlineOpts'"'					// CI of overall effect
	local defRFCIlineOpts `"`defOlineOpts'"'					// CI of predictive interval
	
	// ...and for "pooled" estimates
	local defShape = cond("`interaction'"!="", "circle", "diamond")
	local defColor "0 0 100"
	// local defDiamOpts `"lcolor("`defColor'") lalign(center) fcolor("none")"'
	local defDiamOpts `"lcolor("`defColor'") fcolor("none")"'
	if "`c(stata_version)'"!="" {
		if c(stata_version)>=15.1 local defDiamOpts `"`defDiamOpts' lalign(center)"'	// v3.0.1: lalign() only valid for Stata 15+
	}
	local defPPointOpts `"msymbol("`defShape'") mlcolor("`defColor'") mfcolor("none")"'	// "pooled" point options (alternative to diamond)
	local defPCIOpts `"lcolor("`defColor'") mcolor("`defColor'")"'						// "pooled" CI options (alternative to diamond)
	local defRFOpts `"`defPCIOpts'"'													// prediction interval options (includes "mcolor" for arrows)

	local defHlineOpts `"lwidth(thin) lcolor(gs12)"'	// horizontal upper border line
	local defNlineOpts `"lwidth(thin) lcolor(black)"'	// null line
	
	
	** Default options for graph elements that may be plotted in more than one way
	// (plus, may as well parse some other options too, including disallowed ones)
	local 0 `", `options'"'
	syntax [, ///
		/// /* standard options */
		BOXOPts(string asis) DIAMOPts(string asis) POINTOPts(string asis) CIOPts(string asis) ///
		OLINEOPts(string asis) OCILINEOPts(string asis) RFCILINEOPts(string asis) ///
		HLINEOPts(string asis) NLINEOPts(string asis) ///
		/// /* non-diamond and prediction interval options */
		PPOINTOPts(string asis) PCIOPts(string asis) RFOPts(string asis) * ]

	local rest `"`options'"'
	
	* Overall and Null lines
	// NOTE NOV 2021: parse to find "global" noOVerlay options
	// everything else will be parsed later, with plot#opts
	foreach plot in oline nline {
		local 0 `", ``plot'opts'"'
		syntax [, noOVerlay * ]
		local g_`plot'first : copy local overlay
		local `plot'opts `"`macval(options)'"'
	}
	
	* Confidence intervals
	// since capped lines require a different -twoway- command (-rcap- vs -rspike-)
	if `"`rfdist'"'==`""' & `"`rfopts'"'!=`""' {
		nois disp as err `"predictive interval not specified; relevant options will be ignored"'
		local rfopts
	}

	// Same routine applies to study CIs, "pooled" CIs (alternative to diamond), and to prediction intervals:
	foreach plot in ci pci rf {

		// NOTE NOV 2021:
		// Currently we have an option "overlay" here for use with rfplotopts only
		// the default is "nooverlay" meaning that the pred. int. lines extend outwards from extremities of diamond
		// the option "overlay" instead places a single line passing straight through and over the top of the diamond.
		
		// It has been brought to my attention that it may be desirable for confidence interval lines to be *obscured* by weighted boxes
		// rather than to be seen overlaid on weighted boxes (current default -- so you can see e.g. very short CIs over large boxes)
		// however, the default behaviour should not be changed due to backwards-compatibility
		// solution: use *two* options:  "OVerlay" for rf;  and "noOVerlay" for ci/pci.
		
		// However, the new option noOVerlay behaves differently from old option OVerlay2:
		// - not allowed within the plotid-specific loops later on (because it's currently implemented as a "global" ordering of plot elements with the -twoway- command)
		// - similarly: it's not really *used* here; it's simply returned as-is (as an extra soption) to be picked up by the main -twoway- command.
		
		// options specific to rfplot
		if `"`plot'"'==`"rf"' local overlay_opt OVerlay SEPLine
		else                  local overlay_opt noOVerlay
		
		local 0 `", ``plot'opts'"'
		syntax [, LColor(passthru) MColor(passthru) LWidth(passthru) MLWidth(passthru) ///
			RCAP `overlay_opt' HORizontal VERTical * ]
			
		// disallowed options
		if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
			nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:`plot'opts()}"'
			exit 198
		}
		/*
		if `"`overlay'"'!=`""' & "`plot'"!="rf" {
			nois disp as err `"suboption {bf:overlay} not allowed in option {bf:`plot'opts()}"'
			exit 198
		}
		*/

		// rebuild the option list
		if `"`lcolor'"'!=`""' & `"`mcolor'"'==`""'  local mcolor = subinstr(`"`lcolor'"', "l", "m", 1)		// for pc(b)arrow
		if `"`lwidth'"'!=`""' & `"`mlwidth'"'==`""' local mlwidth m`lwidth'									// for pc(b)arrow
		local `plot'opts `"`mcolor' `lcolor' `mlwidth' `lwidth' `options'"'
		
		// "overlay" options (see "Note" above)
		local g_overlay_`plot' : copy local overlay
		if `"`plot'"'==`"rf"' {
			local g_sepline_`plot' : copy local sepline
			if `"`sepline'"'!=`""' local g_overlay_`plot' overlay		// -sepline- implies -overlay-
		}
		
		local uplot = upper("`plot'")
		local `uplot'PlotType = cond("`rcap'"=="", "rspike", "rcap")
	}
	
	* Diamonds
	// since if truncated (offscale), line options are removed from -rarea- and drawn separately
	local 0 `", `diamopts'"'
	syntax [, Color(passthru) LColor(passthru) ///
		HORizontal VERTical CMISsing(passthru) SORT * ]

	// disallowed options
	if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
		nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:diamopts()}"'
		exit 198
	}			
	if `"`cmissing'"'!=`""' {
		nois disp as err `"suboption {bf:cmissing()} not allowed in option {bf:diamopts()}"'
		exit 198
	}
	if `"`sort'"'!=`""' {
		nois disp as err `"suboption {bf:sort} not allowed in option {bf:diamopts()}"'
		exit 198
	}
	
	// rebuild the option list
	if `"`color'"'!=`""' & `"`lcolor'"'==`""' local lcolor l`color'		// convert `color' -rarea- option to `lcolor' -line- option
	local diamopts `"`color' `lcolor' `options'"'
	
	tokenize `diamlist'
	args DiamX DiamY1 DiamY2
	

	** PARSE PLOT#OPTS
	
	// Loop over possible values of `plotid' and test for plot#opts relating specifically to each value
	numlist "1/`np'"
	local plvals=r(numlist)			// need both of these as explicit numlists,
	local pplvals `plvals'			//    for later macro manipulations to remove specific values if necessary
	forvalues p = 1/`np' {

		local hide
		local 0 `", `rest'"'
		syntax [, ///
			/// /* standard options */
			BOX`p'opts(string asis) DIAM`p'opts(string asis) POINT`p'opts(string asis) CI`p'opts(string asis) ///
			OLINE`p'opts(string asis) OCILINE`p'opts(string asis) RFCILINE`p'opts(string asis) ///
			/// /* non-diamond and prediction interval options */
			PPOINT`p'opts(string asis) PCI`p'opts(string asis) RF`p'opts(string asis) * ]

		local rest `"`options'"'

		* Check if any options were found specifically for this value of `p'
		local checkopt = 0
		local optslist box diam point ci oline ociline rfciline ppoint pci rf
		foreach op of local optslist {
			if trim(`"``op'`p'opts'"') != `""' local checkopt = 1
		}
		if `checkopt' {
			
			local pplvals : list pplvals - p			// remove from list of "default" plotids
			
			
			* INDIVIDUAL STUDY MARKERS
			local touse2 `"`touse' & `_USE'==1 & `plotid'==`p'"'		// use local, not tempvar, so conditions are copied into plot commands
			qui count if `touse2'
			if r(N) {
			
				* WEIGHTED SCATTER PLOT
				local 0 `", `box`p'opts'"'
				syntax [, MLABEL(passthru) MSIZe(passthru) * ]			// check for disallowed options
				if `"`mlabel'"' != `""' {
					nois disp as err `"suboption {bf:mlabel()} not allowed in option {bf:box`p'opts()}"'
					exit 198
				}
				if `"`msize'"' != `""' {
					nois disp as err `"suboption {bf:msize()} not allowed in option {bf:box`p'opts()}"'
					exit 198
				}
				local scPlotOpts `"`defBoxOpts' `boxopts' `box`p'opts'"'
				summ `_WT' if `touse2', meanonly
				if !r(N) nois disp as err `"No weights found for {bf:plotid}==`p'"'
				else if `nd'==1 local scPlot`"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & `plotid'==`p', `macval(scPlotOpts)' ||"'
				else {
					forvalues d=1/`nd' {
						local scPlot `"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & `plotid'==`p' & `dataid'==`d', `macval(scPlotOpts)' ||"'
					}
				}		// N.B. scatter if `tousePlotID' <-- "dummy obs" for consistent weighting
				
				* CONFIDENCE INTERVAL PLOT
				local 0 `", `ci`p'opts'"'
				syntax [, LColor(passthru) MColor(passthru) LWidth(passthru) MLWidth(passthru) ///
					RCAP HORizontal VERTical /*Connect(string)*/ * ]								// check for disallowed options + rcap
				
				// disallowed options
				if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
					nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:ci`p'opts()}"'
					exit 198
				}
				/*
				if `"`connect'"'!=`""' {
					nois disp as err `"suboption {bf:connect()} not allowed in option {bf:ci`p'opts()}"'
					exit 198
				}
				*/
				
				// rebuild option list
				if `"`lcolor'"'!=`""' & `"`mcolor'"'==`""'  local mcolor = subinstr(`"`lcolor'"', "l", "m", 1)	// for pc(b)arrow
				if `"`lwidth'"'!=`""' & `"`mlwidth'"'==`""' local mlwidth m`lwidth'								// for pc(b)arrow
				local CIPlot`p'Opts `"`defCIOpts' `ciopts' `mcolor' `lcolor' `mlwidth' `lwidth' `options'"'		// main options first, then options specific to plot `p'
				local CIPlot`p'Type = cond("`rcap'"=="", "`CIPlotType'", "rcap")
				
				// default: both ends within scale (i.e. no arrows)
				local CIPlot`"`macval(CIPlot)' `CIPlot`p'Type' `_LCI' `_UCI' `id' if `touse2' & !`offscaleL' & !`offscaleR', hor `macval(CIPlot`p'Opts)' ||"'

				// if arrows required
				qui count if `touse2' & `offscaleL' & `offscaleR'
				if r(N) {													// both ends off scale
					local CIPlot `"`macval(CIPlot)' pcbarrow `id' `_LCI' `id' `_UCI' if `touse2' & `offscaleL' & `offscaleR', `macval(CIPlot`p'Opts)' ||"'
				}
				qui count if `touse2' & `offscaleL' & !`offscaleR'
				if r(N) {													// only left off scale
					local CIPlot `"`macval(CIPlot)' pcarrow `id' `_UCI' `id' `_LCI' if `touse2' & `offscaleL' & !`offscaleR', `macval(CIPlot`p'Opts)' ||"'
					if "`CIPlot`p'Type'" == "rcap" {			// add cap to other end if appropriate
						local CIPlot `"`macval(CIPlot)' rcap `_UCI' `_UCI' `id' if `touse2' & `offscaleL' & !`offscaleR', hor `macval(CIPlot`p'Opts)' ||"'
					}
				}
				qui count if `touse2' & !`offscaleL' & `offscaleR'
				if r(N) {													// only right off scale
					local CIPlot `"`macval(CIPlot)' pcarrow `id' `_LCI' `id' `_UCI' if `touse2' & !`offscaleL' & `offscaleR', `macval(CIPlot`p'Opts)' ||"'
					if "`CIPlot`p'Type'" == "rcap" {			// add cap to other end if appropriate
						local CIPlot `"`macval(CIPlot)' rcap `_LCI' `_LCI' `id' if `touse2' & !`offscaleL' & `offscaleR', hor `macval(CIPlot`p'Opts)' ||"'
					}
				}

				* POINT PLOT (point estimates -- except if "classic")
				if "`classic'" == "" {
					local pointPlot`"`macval(pointPlot)' scatter `id' `_ES' if `touse2', `defPointOpts' `pointopts' `point`p'opts' ||"'
				}
			}			// end if r(N) [i.e. if any obs with _USE==1 & plotid==`p']

			
			* OVERALL LINE(S) (if appropriate)
			summ `ovLine' if `plotid'==`p', meanonly
			if r(N) {
				local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLine' if `touse' & `plotid'==`p', `defOlineOpts' `olineopts' `oline`p'opts' ||"'
			
			
				* PREDICTIVE INTERVAL CI LINES (and/or areas)
				// Do these before standard overall lines, in case of area plots
				//  want pred. int. area plot to be underneath the "standard" CI area plot
				// Added Jan 2020
				if trim(`"`rfcilineopts'`rfciline`p'opts'"') != `""' {
					if `"`rfdist'"'==`""' {
						nois disp as err `"predictive interval not specified; relevant suboptions for {bf:plotid==`p'} will be ignored"'
					}
					else {
						local 0 `", `rfciline`p'opts'"'
						syntax [, LINE AREA HIDE HORizontal VERTical Color(passthru) FColor(passthru) FIntensity(passthru) * ]
				
						// disallowed options
						if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
							nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:rfciline`p'opts()}"'
							exit 198
						}
						
						if `"`hide'"'!=`""' qui replace `touseDiam' = 0 if `plotid'==`p'

						// August 2023: don't display vertical lines if: (1) area plot requested; and (2) no explicit line options
						if !(`"`area'`color'`fcolor'`fintensity'"'!=`""' & `"`line'`options'"'==`""') {
							local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `rfLineLCI' if `touse' & `plotid'==`p', `defRFCIlineOpts' `rfcilineopts' `options' ||"'
							local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `rfLineUCI' if `touse' & `plotid'==`p', `defRFCIlineOpts' `rfcilineopts' `options' ||"'
						}
						
						// area plot -- use `touseRFCI'
						if `"`area'`color'`fcolor'`fintensity'"'!=`""' {
							local rfciline`p'opts `"`macval(rfciline`p'Opts)' `color' `fcolor' `fintensity' `options'"'
							local olineAreaPlot `"`macval(olineAreaPlot)' rarea `ovMin' `ovMax' `rfLineX' if `touseRFCI' & `plotid'==`p', `macval(rfciline`p'opts)' lwidth(none) cmissing(n) ||"'
							qui replace `touseRFCI' = 2 if `plotid'==`p'
						}
						else qui replace `touseRFCI' = 1 if `plotid'==`p'
					}
				}
			
				* OVERALL LINE(S) (and/or areas)
				// Added Jan 2020
				if `"`ocilineopts'`ociline`p'opts'`influence'"'!=`""' {
					local 0 `", `ociline`p'opts'"'
					syntax [, LINE AREA HIDE HORizontal VERTical Color(passthru) FColor(passthru) FIntensity(passthru) * ]

					// disallowed options
					if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
						nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:ociline`p'opts()}"'
						exit 198
					}
					
					if `"`hide'"'!=`""' qui replace `touseDiam' = 0 if `plotid'==`p'

					// August 2023: don't display vertical lines if: (1) area plot requested; and (2) no explicit line options
					if !(`"`area'`color'`fcolor'`fintensity'"'!=`""' & `"`line'`options'"'==`""') {
						local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLineLCI' if `touse' & `plotid'==`p', `defOCIlineOpts' `ocilineopts' `options' ||"'
						local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLineUCI' if `touse' & `plotid'==`p', `defOCIlineOpts' `ocilineopts' `options' ||"'
					}
					
					// area plot -- use `touseOCI'
					if "`area'`color'`fcolor'`fintensity'"!=`""' {
						local ociline`p'opts `"`ocilineopts' `color' `fcolor' `fintensity' `options'"'
						local olineAreaPlot `"`macval(olineAreaPlot)' rarea `ovMin' `ovMax' `ovLineX' if `touseOCI' & `plotid'==`p', `macval(ociline`p'opts)' lwidth(none) cmissing(n) ||"'
						qui replace `touseOCI' = 2 if `plotid'==`p'
					}
					else qui replace `touseOCI' = 1 if `plotid'==`p'
				}
			}			// end if r(N) [i.e. if any obs with `ovline' & plotid==`p']
				
			
			* POOLED EFFECT MARKERS
			local touse2 `"`touseDiam' & inlist(`_USE', 3, 5) & `plotid'==`p'"'		// use local, not tempvar, so conditions are copied into plot commands
																					// N.B. `touseDiam' implies `touse'
			// local touse3 : copy local touse2
			
			// June 2023: "don't plot data..." -- this is now assured, since that data is _USE==7, not included in touse3

			/*
			if `"`rfdist'"'!=`""' {													// Oct 2022: don't plot data from "second" _USE==3|5 row containing pred.int. text
				// local touse3 `"`touse3' & float(`_rfLCI')!=float(`_LCI') & float(`_rfUCI')!=float(`_UCI')"'
				local touse3 `"`touse3' & float(`_rfLCI')<=float(`_LCI') & float(`_rfUCI')>=float(`_UCI')"'
			}
			*/
			qui count if `touse2'
			if r(N) {
			
				* DIAMONDS:  DRAW POLYGONS WITH -twoway rarea-
				* Assume diamond if no "pooled point/CI" options and no "interaction" option
				if trim(`"`ppointopts'`ppoint`p'opts'`pciopts'`pci`p'opts'`interaction'`diamonds'"') == `""' {
				
					local 0 `", `diam`p'opts'"'
					syntax [, Color(passthru) LColor(passthru) ///
						HORizontal VERTical CMISsing(passthru) SORT * ]

					// disallowed options
					if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
						nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:diamopts()}"'
						exit 198
					}			
					if `"`cmissing'"'!=`""' {
						nois disp as err `"suboption {bf:cmissing()} not allowed in option {bf:diamopts()}"'
						exit 198
					}
					if `"`sort'"'!=`""' {
						nois disp as err `"suboption {bf:sort} not allowed in option {bf:diamopts()}"'
						exit 198
					}
					
					// rebuild option list
					if `"`color'"'!=`""' & `"`lcolor'"'==`""' local lcolor l`color'						// convert `color' -rarea- option to `lcolor' -line- option
					local diamPlot`p'Opts `"`defDiamOpts' `diamopts' `color' `lcolor' `options'"'		// main options first, then options specific to plot `p'
					
					// Now check whether any diamonds are offscale (niche case -- see also comments on ppoint below)
					// If so, will need to draw round the edges of the polygon, excepting the "offscale edges"
					//   and switch off the line options to -twoway rarea-
					// (draw these lines *after* drawing the area, though, so that the lines appear on top)
					qui count if `touse2' & (`offscaleL' | `offscaleR')
					if r(N) {
						local diam`p'Line `"line `DiamY1' `DiamX' if `touse2', `macval(diamPlot`p'Opts)' cmissing(n) ||"'
						local diam`p'Line `"`macval(diam`p'Line)' line `DiamY2' `DiamX' if `touse2', `macval(diamPlot`p'Opts)' cmissing(n) ||"'
						local diam`p'LWidth `"lwidth(none)"'
					}
					local diamPlot `"`macval(diamPlot)' rarea `DiamY1' `DiamY2' `DiamX' if `touse2', `macval(diamPlot`p'Opts)' `diam`p'LWidth' cmissing(n) || `diam`p'Line' "'
				}
				
				* POOLED EFFECTS - PPOINT/PCI
				else {
					if trim(`"`diam`p'opts'"') != `""' {
						nois disp as err `"Note: suboptions for both diamond and pooled point/CI specified for {bf:plotid}==`p';"'
						nois disp as err `"      diamond suboptions will be ignored"'
					}
				
					// shouldn't need to bother with arrows etc. here, as pooled effect should always be narrower than individual estimates
					// but do it anyway, just in case of non-obvious use case
					local 0 `", `pci`p'opts'"'
					syntax [, LColor(passthru) MColor(passthru) LWidth(passthru) MLWidth(passthru) ///
						RCAP HORizontal VERTical /*Connect(string)*/ * ]											// check for disallowed options + rcap
					
					// disallowed options
					if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
						nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option{bf:pci`p'opts()}"'
						exit 198
					}
					/*
					if `"`connect'"' != `""' {
						nois disp as err `"suboption {bf:connect()} not allowed in option {bf:pci`p'opts}"'
						exit 198
					}
					*/
					
					// rebuild option list
					if `"`lcolor'"'!=`""' & `"`mcolor'"'==`""'  local mcolor = subinstr(`"`lcolor'"', "l", "m", 1)		// for pc(b)arrow
					if `"`lwidth'"'!=`""' & `"`mlwidth'"'==`""' local mlwidth m`lwidth'									// for pc(b)arrow
					local PCIPlot`p'Opts `"`defPCIOpts' `pciopts' `mcolor' `lcolor' `mlwidth' `lwidth' `options'"'		// main options first, then options specific to plot `p'
					local PCIPlot`p'Type = cond("`rcap'"=="", "`PCIPlotType'", "rcap")
					
					// default: both ends within scale (i.e. no arrows)
					local PCIPlot `"`macval(PCIPlot)' `PCIPlot`p'Type' `_LCI' `_UCI' `id' if `touse2' & !`offscaleL' & !`offscaleR', hor `macval(PCIPlot`p'Opts)' ||"'

					// if arrows are required
					qui count if `touse2' & `offscaleL' & `offscaleR'
					if r(N) {													// both ends off scale
						local PCIPlot `"`macval(PCIPlot)' pcbarrow `id' `_LCI' `id' `_UCI' if `touse2' & `offscaleL' & `offscaleR', `macval(PCIPlot`p'Opts)' ||"'
					}
					qui count if `touse2' & `offscaleL' & !`offscaleR'
					if r(N) {													// only left off scale
						local PCIPlot `"`macval(PCIPlot)' pcarrow `id' `_UCI' `id' `_LCI' if `touse2' & `offscaleL' & !`offscaleR', `macval(PCIPlot`p'Opts)' ||"'
						if "`PCIPlot`p'Type'" == "rcap" {			// add cap to other end if appropriate
							local PCIPlot `"`macval(PCIPlot)' rcap `_UCI' `_UCI' `id' if `touse2' & `offscaleL' & !`offscaleR', hor `macval(PCIPlot`p'Opts)' ||"'
						}
					}
					qui count if `touse2' & !`offscaleL' & `offscaleR'
					if r(N) {													// only right off scale
						local PCIPlot `"`macval(PCIPlot)' pcarrow `id' `_LCI' `id' `_UCI' if `touse2' & !`offscaleL' & `offscaleR', `macval(PCIPlot`p'Opts)' ||"'
						if "`PCIPlot`p'Type'" == "rcap" {			// add cap to other end if appropriate
							local PCIPlot `"`macval(PCIPlot)' rcap `_LCI' `_LCI' `id' if `touse2' & !`offscaleL' & `offscaleR', hor `macval(PCIPlot`p'Opts)' ||"'
						}
					}				
					local ppointPlot `"`macval(ppointPlot)' scatter `id' `_ES' if `touse2', `defPPointOpts' `ppointopts' `ppoint`p'opts' ||"'
					
					qui replace `touseDiam' = 1 if `plotid'==`p'	// line, not area
				}
				
				* PREDICTION INTERVAL
				// if trim(`"`ppointopts'`ppoint`p'opts'`pciopts'`pci`p'opts'`interaction'`diamonds'"') == `""' {
				
				if trim(`"`rfopts'`rf`p'opts'"') != `""' {
					if `"`rfdist'"'==`""' {
						nois disp as err `"predictive interval not specified; relevant suboptions for {bf:plotid==`p'} will be ignored"'
					}
					else {
						local 0 `", `rf`p'opts'"'
						syntax [, LColor(passthru) MColor(passthru) LWidth(passthru) MLWidth(passthru) ///
							RCAP HORizontal VERTical /*Connect(string)*/ OVerlay SEPLine * ]				// check for disallowed options + rcap,
																											// plus additional options -overlay- and -sepline-
						if `"`sepline'"'!=`""' local overlay overlay	// -sepline- implies -overlay-
																										
						// disallowed options
						if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
							nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:rf`p'opts}"'
							exit 198
						}
						/*
						if `"`connect'"' != `""' {
							nois disp as err `"suboption {bf:connect()} not allowed in option {bf:rf`p'opts()}"'
							exit 198
						}
						*/
						
						// rebuild option list
						if `"`lcolor'"'!=`""' & `"`mcolor'"'==`""'  local mcolor = subinstr(`"`lcolor'"', "l", "m", 1)		// for pc(b)arrow
						if `"`lwidth'"'!=`""' & `"`mlwidth'"'==`""' local mlwidth m`lwidth'									// for pc(b)arrow
						local RFPlot`p'Opts `"`defRFOpts' `rfopts' `mcolor' `lcolor' `mlwidth' `lwidth' `options'"'		// main options first, then options specific to plot `p'
						local RFPlot`p'Type = cond("`rcap'"=="", "`RFPlotType'", "rcap")
						
						// if overlay, use same approach as for CI/PCI
						if trim(`"`overlay'`g_overlay_rf'"') != `""' {
							local touse_add `"`touseDiam' & `plotid'==`p' & float(`_rfUCI')>=float(`CXmin') & float(`_rfLCI')<=float(`CXmax')"'
							// ^^ Note: `touseDiam' & `plotid'==`p' is the previous definition of `touse2'

							// Oct 2022: option to plot prediction interval as separate line from confidence interval
							if trim(`"`sepline'`g_sepline_rf'"') != `""' local touse_add `"`touse_add' & `_USE'==7"'
							else                                         local touse_add `"`touse_add' & inlist(`_USE', 3, 5)"'

							/*
							if trim(`"`sepline'`g_sepline_rf'"') != `""' {
								 local touse_add `"`touse_add' & float(`_rfLCI')==float(`_LCI') & float(`_rfUCI')==float(`_UCI')"'
							}
							else local touse_add `"`touse_add' & float(`_rfLCI')!=float(`_LCI') & float(`_rfUCI')!=float(`_UCI')"'
							*/
							
							// default: both ends within scale (i.e. no arrows)
							// local touse3 `"`touse2' & !`rfLoffscaleL' & !`rfRoffscaleR' & `touse_add'"'
							local touse3 `"`touse_add' & !`rfLoffscaleL' & !`rfRoffscaleR'"'
							local RFPlot `"`macval(RFPlot)' `RFPlot`p'Type' `_rfLCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlot`p'Opts)' ||"'

							// if arrows required
							// local touse3 `"`touse2' & `rfLoffscaleL' & `rfRoffscaleR' & `touse_add'"'
							local touse3 `"`touse_add' & `rfLoffscaleL' & `rfRoffscaleR'"'
							qui count if `touse3'
							if r(N) {													// both ends off scale
								local RFPlot `"`macval(RFPlot)' pcbarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}
							// local touse3 `"`touse2' & `rfLoffscaleL' & !`rfRoffscaleR' & `touse_add'"'
							local touse3 `"`touse_add' & `rfLoffscaleL' & !`rfRoffscaleR'"'
							qui count if `touse3'
							if r(N) {													// only left off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfUCI' `id' `_rfLCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
								if "`RFPlotType'" == "rcap" {			// add cap to other end if appropriate
									local RFPlot `"`macval(RFPlot)' rcap `_rfUCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlot`p'Opts)' ||"'
								}
							}
							// local touse3 `"`touse2' & !`rfLoffscaleL' & `rfRoffscaleR' & `touse_add'"'
							local touse3 `"`touse_add' & !`rfLoffscaleL' & `rfRoffscaleR'"'
							qui count if `touse3'
							if r(N) {													// only right off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
								if "`RFPlotType'" == "rcap" {			// add cap to other end if appropriate
									local RFPlot `"`macval(RFPlot)' rcap `_rfLCI' `_rfLCI' `id' if `touse3', hor `macval(RFPlot`p'Opts)' ||"'
								}
							}
						}
						
						// otherwise, need to do it slightly differently, as we are dealing with two separate (left/right) lines
						// plus, note that `sepline' is assumed *not* to be relevant in this case; this simplies matters slightly
						// (because, if we are "not overlaying" around a diamond, then the line must be on the same row as the diamond)
						else {
							
							// June 2023: we can just use `touse2' as is; that is (reminder):
							// local touse2 `"`touseDiam' & inlist(`_USE', 3, 5) & `plotid'==`p'"'
						
							// identify special cases where only one line required, with two arrows
							local touse3 `"`touse2' & (`rfLoffscaleL' & `rfLoffscaleR') | (`rfRoffscaleL' & `rfRoffscaleR')"'
							qui count if `touse3'
							if r(N) {
								local RFPlot `"`macval(RFPlot)' pcbarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}
							
							// left-hand line
							local touse_add `"float(`_rfLCI')<=float(`CXmax') & float(`_rfLCI')!=float(`_LCI')"'

							local touse3 `"`touse2' & !`rfLoffscaleL' & !`rfLoffscaleR' & !`offscaleL' & `touse_add'"'
							local RFPlot `"`macval(RFPlot)' `RFPlot`p'Type' `_LCI' `_rfLCI' `id' if `touse3', hor `macval(RFPlot`p'Opts)' ||"'
							
							local touse3 `"`touse2' & `rfLoffscaleL' & !`rfLoffscaleR' & !`offscaleL' & `touse_add'"'
							qui count if `touse3'
							if r(N) {										// left-hand end off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_LCI' `id' `_rfLCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}

							local touse3 `"`touse2' & !`rfLoffscaleL' & `rfLoffscaleR' & !`offscaleL' & `touse_add'"'
							qui count if `touse3'
							if r(N) {										// right-hand end off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfLCI' `id' `_LCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}

							// right-hand line
							local touse_add `"float(`_rfUCI')>=float(`CXmin') & float(`_rfUCI')!=float(`_UCI')"'
							
							local touse3 `"`touse2' & !`rfRoffscaleL' & !`rfRoffscaleR' & !`offscaleR' & `touse_add'"'
							local RFPlot `"`macval(RFPlot)' `RFPlot`p'Type' `_UCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlot`p'Opts)' ||"'
							
							local touse3 `"`touse2' & `rfRoffscaleL' & !`rfRoffscaleR' & !`offscaleR' & `touse_add'"'
							qui count if `touse3'
							if r(N) {										// left-hand end off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfUCI' `id' `_UCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}

							local touse3 `"`touse2' & !`rfRoffscaleL' & `rfRoffscaleR' & !`offscaleR' & `touse_add'"'
							qui count if `touse3'
							if r(N) {										// right-hand end off scale
								local RFPlot `"`macval(RFPlot)' pcarrow `id' `_UCI' `id' `_rfUCI' if `touse3', `macval(RFPlot`p'Opts)' ||"'
							}
						}
					}			// end else [i.e. if rfdist]
				}			// if trim(`"`rf`p'opts'"')!=`""'
			}			// end if r(N) [i.e. if any obs with _USE==3,5 & plotid==`p']
		}		// end if trim(`"`box`p'opts'`diam`p'opts'`point`p'opts'`ci`p'opts'`oline`p'opts'`ppoint`p'opts'`pci`p'opts'"') != `""'
	}		// end forvalues p = 1/`np'


	* Find invalid/repeated options
	// any such options would generate a suitable error message at the plotting stage
	// so just exit here with error, to save the user's time
	if regexm(`"`rest'"', "(box|diam|point|ci|oline|ociline|ppoint|pci|rf|rfciline)([0-9]+)opt") {
		local badopt = regexs(1)
		local badp = regexs(2)
		
		if `: list badp in plvals' nois disp as err `"option {bf:`badopt'`badp'opts} supplied multiple times; should only be supplied once"'
		else nois disp as err `"`badp' is not a valid {bf:plotid} value"'
		exit 198
	}

	local opts_rest : copy local rest
	// sreturn local options `"`rest'"'	// This is now *just* the standard "twoway" options
										//   i.e. the specialist "forestplot" options have been filtered out
	
	
	* FORM "DEFAULT" TWOWAY PLOT COMMAND (if appropriate)
	// Changed so that FOR WEIGHTED SCATTER each pplval is plotted separately (otherwise weights get messed up)
	// Other (nonweighted) plots can continue to be plotted as before
	if `"`pplvals'"'!=`""' {
	
		local pplvals2 : copy local pplvals						// copy; only needed for weighted scatter plots
		local pplvals : subinstr local pplvals " " ",", all		// so that "inlist" may be used
		local hide
		
		
		* INDIVIDUAL STUDY MARKERS
		local touse2 `"`touse' & `_USE'==1 & inlist(`plotid', `pplvals')"'		// use local, not tempvar, so conditions are copied into plot commands
		qui count if `touse2'
		if r(N) {
		
			* WEIGHTED SCATTER PLOT
			local 0 `", `boxopts'"'
			syntax [, MLABEL(passthru) MSIZe(passthru) * ]	// check for disallowed options
			if `"`mlabel'"' != `""' {
				disp as err "boxopts: option mlabel() not allowed"
				exit 198
			}
			if `"`msize'"' != `""' {
				disp as err "boxopts: option msize() not allowed"
				exit 198
			}
			local scPlotOpts `"`defBoxOpts' `boxopts'"'
			
			if `"`pplvals'"'==`"`plvals'"' {		// if no plot#opts specified, can plot all plotid groups at once
				summ `_WT' if `touse2', meanonly
				if r(N) {
					if `nd'==1 local scPlot `"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & inlist(`plotid', `pplvals'), `macval(scPlotOpts)' ||"'
					else {
						forvalues d=1/`nd' {
							local scPlot `"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & inlist(`plotid', `pplvals') & `dataid'==`d', `macval(scPlotOpts)' ||"'
						}
					}
				}
			}
			else {		// else, need to plot each group separately to maintain correct weighting (July 2014)
				foreach p of local pplvals2 {
					summ `_WT' if `touse' & `_USE'==1 & `plotid'==`p', meanonly
					if r(N) {
						if `nd'==1 local scPlot `"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & `plotid'==`p', `macval(scPlotOpts)' ||"'
						else {
							forvalues d=1/`nd' {
								local scPlot `"`macval(scPlot)' scatter `id' `_ES' `awweight' if `tousePlotID' & `_USE'==1 & `plotid'==`p' & `dataid'==`d', `macval(scPlotOpts)' ||"'
							}
						}
					}
				}
			}		// N.B. scatter if `tousePlotID' <-- "dummy obs" for consistent weighting
			
			
			* CONFIDENCE INTERVAL PLOT
			// N.B. options already processed
			local CIPlotOpts `"`defCIOpts' `ciopts'"'
			
			// default: both ends within scale (i.e. no arrows)
			local CIPlot `"`macval(CIPlot)' `CIPlotType' `_LCI' `_UCI' `id' if `touse2' & !`offscaleL' & !`offscaleR', hor `macval(CIPlotOpts)' ||"'

			// if arrows required
			qui count if `touse2' & `offscaleL' & `offscaleR'
			if r(N) {													// both ends off scale
				local CIPlot `"`macval(CIPlot)' pcbarrow `id' `_LCI' `id' `_UCI' if `touse2' & `offscaleL' & `offscaleR', `macval(CIPlotOpts)' ||"'
			}
			qui count if `touse2' & `offscaleL' & !`offscaleR'
			if r(N) {													// only left off scale
				local CIPlot `"`macval(CIPlot)' pcarrow `id' `_UCI' `id' `_LCI' if `touse2' & `offscaleL' & !`offscaleR', `macval(CIPlotOpts)' ||"'
				if "`CIPlotType'" == "rcap" {			// add cap to other end if appropriate
					local CIPlot `"`macval(CIPlot)' rcap `_UCI' `_UCI' `id' if `touse2' & `offscaleL' & !`offscaleR', hor `macval(CIPlotOpts)' ||"'
				}
			}
			qui count if `touse2' & !`offscaleL' & `offscaleR'
			if r(N) {													// only right off scale
				local CIPlot `"`macval(CIPlot)' pcarrow `id' `_LCI' `id' `_UCI' if `touse2' & !`offscaleL' & `offscaleR', `macval(CIPlotOpts)' ||"'
				if "`CIPlotType'" == "rcap" {			// add cap to other end if appropriate
					local CIPlot `"`macval(CIPlot)' rcap `_LCI' `_LCI' `id' if `touse2' & !`offscaleL' & `offscaleR', hor `macval(CIPlotOpts)' ||"'
				}
			}

			
			* POINT PLOT (point estimates -- except if "classic")
			if "`classic'" == "" {
				local pointPlot `"`macval(pointPlot)' scatter `id' `_ES' if `touse2', `defPointOpts' `pointopts' ||"'
			}
		}			// end if r(N) [i.e. if any obs with _USE==1 & plotid==`ppvals']
		
		
		* OVERALL LINE(S) (if appropriate)
		summ `ovLine' if inlist(`plotid', `pplvals'), meanonly
		if r(N) {
			local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLine' if `touse' & inlist(`plotid', `pplvals'), `defOlineOpts' `olineopts' ||"'


			* PREDICTIVE INTERVAL CI LINES (and/or areas)
			// Do these before standard overall lines, in case of area plots
			//  want pred. int. area plot to be underneath the "standard" CI area plot
			// Added Jan 2020
			if trim(`"`rfcilineopts'"') != `""' {
				if `"`rfdist'"'==`""' {
					nois disp as err `"predictive interval not specified; relevant suboptions will be ignored"'
				}
				else {
					local 0 `", `rfcilineopts'"'
					syntax [, LINE AREA HIDE HORizontal VERTical Color(passthru) FColor(passthru) FIntensity(passthru) * ]
			
					// disallowed options
					if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
						nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:rfcilineopts()}"'
						exit 198
					}
					
					if `"`hide'"'!=`""' qui replace `touseDiam' = 0 if inlist(`plotid', `pplvals')

					// August 2023: don't display vertical lines if: (1) area plot requested; and (2) no explicit line options
					if !(`"`area'`color'`fcolor'`fintensity'"'!=`""' & `"`line'`options'"'==`""') {
						local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `rfLineLCI' if `touse' & inlist(`plotid', `pplvals'), `defRFCIlineOpts' `options' ||"'
						local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `rfLineUCI' if `touse' & inlist(`plotid', `pplvals'), `defRFCIlineOpts' `options' ||"'
					}
					
					// area plot -- use `touseRFCI'
					if `"`area'`color'`fcolor'`fintensity'"'!=`""' {
						local rfcilineopts `"`color' `fcolor' `fintensity' `options'"'
						local olineAreaPlot `"`macval(olineAreaPlot)' rarea `ovMin' `ovMax' `rfLineX' if `touseRFCI' & inlist(`plotid', `pplvals'), `rfcilineopts' lwidth(none) cmissing(n) ||"'
						qui replace `touseRFCI' = 2 if inlist(`plotid', `pplvals')
					}
					else qui replace `touseRFCI' = 1 if inlist(`plotid', `pplvals')
				}
			}
						
			* OVERALL CI LINES (and/or areas)
			// Added Jan 2020
			if `"`ocilineopts'`influence'"'!=`""' {
				local 0 `", `ocilineopts'"'
				syntax [, LINE AREA HIDE HORizontal VERTical Color(passthru) FColor(passthru) FIntensity(passthru) * ]

				// disallowed options
				if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
					nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:ociline`p'opts()}"'
					exit 198
				}
				
				if `"`hide'"'!=`""' qui replace `touseDiam' = 0 if inlist(`plotid', `pplvals')

				// August 2023: don't display vertical lines if: (1) area plot requested; and (2) no explicit line options
				if !(`"`area'`color'`fcolor'`fintensity'"'!=`""' & `"`line'`options'"'==`""') {
					local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLineLCI' if `touse' & inlist(`plotid', `pplvals'), `defOCIlineOpts' `options' ||"'
					local olinePlot `"`macval(olinePlot)' rspike `ovMin' `ovMax' `ovLineUCI' if `touse' & inlist(`plotid', `pplvals'), `defOCIlineOpts' `options' ||"'
				}
				
				// area plot -- use `touseOCI'
				if `"`area'`color'`fcolor'`fintensity'"'!=`""' {
					local ocilineopts `"`color' `fcolor' `fintensity' `options'"'
					local olineAreaPlot `"`macval(olineAreaPlot)' rarea `ovMin' `ovMax' `ovLineX' if `touseOCI' & inlist(`plotid', `pplvals'), `macval(ocilineopts)' lwidth(none) cmissing(n) ||"'
					qui replace `touseOCI' = 2 if inlist(`plotid', `pplvals')
				}
				else qui replace `touseOCI' = 1 if inlist(`plotid', `pplvals')
			}
		}			// end if r(N) [i.e. if any obs with `ovline' & inlist(plotid, `pplvals')]

		
		* POOLED EFFECT MARKERS		
		local touse2 `"`touseDiam' & inlist(`_USE', 3, 5) & inlist(`plotid', `pplvals')"'	// use local, not tempvar, so conditions are copied into plot commands
		// local touse3 : copy local touse2
		// nois list `_USE' `_ES' `_LCI' `_UCI' `_rfLCI' `_rfUCI' _EFFECT if `touse3'

		// June 2023: "don't plot data..." -- this is now assured, since that data is _USE==7, not included in touse3

		/*
		if `"`rfdist'"'!=`""' {																// Oct 2022: don't plot data from "second" _USE==3|5 row containing pred.int. text
			// local touse3 `"`touse3' & float(`_rfLCI')!=float(`_LCI') & float(`_rfUCI')!=float(`_UCI')"'
			local touse3 `"`touse3' & float(`_rfLCI')<=float(`_LCI') & float(`_rfUCI')>=float(`_UCI')"'
		}
		*/
		qui count if `touse2'
		if r(N) {

			* DIAMONDS - DRAW POLYGONS WITH -twoway rarea-
			* Assume diamond if no "pooled point/CI" options and no "interaction" option
			if trim(`"`ppointopts'`pciopts'`interaction'`diamonds'"') == `""' {
				local diamPlotOpts `"`defDiamOpts' `diamopts'"'
				
				// Now check whether any diamonds are offscale (niche case!)
				// If so, will need to draw round the edges of the polygon, excepting the "offscale edges"
				//   and switch off the line options to -twoway rarea-
				// (draw these lines *after* drawing the area, though, so that the lines appear on top)
				qui count if `touse2' & (`offscaleL' | `offscaleR')
				if r(N) {
					local diamLine `"line `DiamY1' `DiamX' if `touse2', `macval(diamPlotOpts)' cmissing(n) ||"'
					local diamLine `"`macval(diamLine)' line `DiamY2' `DiamX' if `touse2', `macval(diamPlotOpts)' cmissing(n) ||"'
					local diamLWidth `"lwidth(none)"'
				}
				local diamPlot `"`macval(diamPlot)' rarea `DiamY1' `DiamY2' `DiamX' if `touse2', `macval(diamPlotOpts)' `diamLWidth' cmissing(n) || `diamLine' "'
			}
			
		
			* POOLED EFFECT - PPOINT/PCI
			else {
				if trim(`"`diamopts'"') != `""' {
					nois disp as err `"Note: suboptions for both diamond and pooled point/CI specified;"'
					nois disp as err `"      diamond suboptions will be ignored"'
				}	

				// N.B. options already processed
				local PCIPlotOpts `"`defPCIOpts' `pciopts'"'
				
				// default: both ends within scale (i.e. no arrows)
				local PCIPlot `"`macval(PCIPlot)' `PCIPlotType' `_LCI' `_UCI' `id' if `touse2' & !`offscaleL' & !`offscaleR', hor `macval(PCIPlotOpts)' ||"'

				// if arrows are required
				qui count if `touse2' & `offscaleL' & `offscaleR'
				if r(N) {													// both ends off scale
					local PCIPlot `"`macval(PCIPlot)' pcbarrow `id' `_LCI' `id' `_UCI' if `touse2' & `offscaleL' & `offscaleR', `macval(PCIPlotOpts)' ||"'
				}
				qui count if `touse2' & `offscaleL' & !`offscaleR'
				if r(N) {													// only left off scale
					local PCIPlot `"`macval(PCIPlot)' pcarrow `id' `_UCI' `id' `_LCI' if `touse2' & `offscaleL' & !`offscaleR', `macval(PCIPlotOpts)' ||"'
					if "`PCIPlotType'" == "rcap" {			// add cap to other end if appropriate
						local PCIPlot `"`macval(PCIPlot)' rcap `_UCI' `_UCI' `id' if `touse2' & `offscaleL' & !`offscaleR', hor `macval(PCIPlotOpts)' ||"'
					}
				}
				qui count if `touse2' & !`offscaleL' & `offscaleR'
				if r(N) {													// only right off scale
					local PCIPlot `"`macval(PCIPlot)' pcarrow `id' `_LCI' `id' `_UCI' if `touse2' & !`offscaleL' & `offscaleR', `macval(PCIPlotOpts)' ||"'
					if "`PCIPlotType'" == "rcap" {			// add cap to other end if appropriate
						local PCIPlot `"`macval(PCIPlot)' rcap `_LCI' `_LCI' `id' if `touse2' & !`offscaleL' & `offscaleR', hor `macval(PCIPlotOpts)' ||"'
					}
				}				
				local ppointPlot `"`macval(ppointPlot)' scatter `id' `_ES' if `touse2', `defPPointOpts' `ppointopts' ||"'
				
				qui replace `touseDiam' = 1 if inlist(`plotid', `pplvals')		// line, not area
			}
		

			* PREDICTION INTERVAL
			if `"`rfdist'"'==`""' {
				if trim(`"`rfopts'"') != `""' {
					nois disp as err `"predictive interval not specified; relevant suboptions will be ignored"'
				}
			}
			
			else {
			
				// N.B. options already processed
				local RFPlotOpts `"`defRFOpts' `rfopts'"'
			
				// if overlay, use same approach as for CI/PCI
				if `"`g_overlay_rf'"'!=`""' {
					
					// local touse_add `"float(`_rfUCI')>=float(`CXmin') & float(`_rfLCI')<=float(`CXmax')"'
					local touse_add `"`touseDiam' & inlist(`plotid', `pplvals') & float(`_rfUCI')>=float(`CXmin') & float(`_rfLCI')<=float(`CXmax')"'
					// ^^ Note: `touseDiam' & inlist(`plotid', `pplvals') is the previous definition of `touse2'

					// Oct 2022: option to plot prediction interval as separate line from confidence interval
					// if `"`g_sepline_rf'"'!=`""' local touse_add `"`touse_add' & float(`_rfLCI')==float(`_LCI') & float(`_rfUCI')==float(`_UCI')"'
					// else                        local touse_add `"`touse_add' & float(`_rfLCI')!=float(`_LCI') & float(`_rfUCI')!=float(`_UCI')"'
					if `"`g_sepline_rf'"'!=`""' local touse_add `"`touse_add' & `_USE'==7"'
					else                        local touse_add `"`touse_add' & inlist(`_USE', 3, 5)"'
			
					// default: both ends within scale (i.e. no arrows)
					// local touse3 `"`touse2' & !`rfLoffscaleL' & !`rfRoffscaleR' & `touse_add'"'
					local touse3 `"`touse_add' & !`rfLoffscaleL' & !`rfRoffscaleR'"'
					local RFPlot `"`macval(RFPlot)' `RFPlotType' `_rfLCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlotOpts)' ||"'

					// if arrows required
					// local touse3 `"`touse2' & `rfLoffscaleL' & `rfRoffscaleR' & `touse_add'"'
					local touse3 `"`touse_add' & `rfLoffscaleL' & `rfRoffscaleR'"'
					qui count if `touse3'
					if r(N) {													// both ends off scale
						local RFPlot `"`macval(RFPlot)' pcbarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}
					// local touse3 `"`touse2' & `rfLoffscaleL' & !`rfRoffscaleR' & `touse_add'"'
					local touse3 `"`touse_add' & `rfLoffscaleL' & !`rfRoffscaleR'"'
					qui count if `touse3'
					if r(N) {													// only left off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfUCI' `id' `_rfLCI' if `touse3', `macval(RFPlotOpts)' ||"'
						if "`RFPlotType'" == "rcap" {			// add cap to other end if appropriate
							local RFPlot `"`macval(RFPlot)' rcap `_rfUCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlotOpts)' ||"'
						}
					}
					// local touse3 `"`touse2' & !`rfLoffscaleL' & `rfRoffscaleR' & `touse_add'"'
					local touse3 `"`touse_add' & !`rfLoffscaleL' & `rfRoffscaleR'"'
					qui count if `touse3'
					if r(N) {													// only right off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlotOpts)' ||"'
						if "`RFPlotType'" == "rcap" {			// add cap to other end if appropriate
							local RFPlot `"`macval(RFPlot)' rcap `_rfLCI' `_rfLCI' `id' if `touse3', hor `macval(RFPlotOpts)' ||"'
						}
					}
				}
				
				// otherwise, need to do it slightly differently, as we are dealing with two separate (left/right) lines
				// plus, note that `sepline' is assumed *not* to be relevant in this case; this simplies matters slightly
				// (because, if we are "not overlaying" around a diamond, then the line must be on the same row as the diamond)				
				else {
				
					// June 2023: we can just use `touse2' as is; that is (reminder):
					// local touse2 `"`touseDiam' & inlist(`_USE', 3, 5) & inlist(`plotid', `pplvals')"'
				
					// identify special cases where only one line required, with two arrows
					local touse3 `"`touse2' & (`rfLoffscaleL' & `rfLoffscaleR') | (`rfRoffscaleL' & `rfRoffscaleR')"'
					qui count if `touse3'
					if r(N) {
						local RFPlot `"`macval(RFPlot)' pcbarrow `id' `_rfLCI' `id' `_rfUCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}
					
					// left-hand line
					local touse_add `"float(`_rfLCI')<=float(`CXmax') & float(`_rfLCI')!=float(`_LCI')"'

					local touse3 `"`touse2' & !`rfLoffscaleL' & !`rfLoffscaleR' & !`offscaleL' & `touse_add'"'
					local RFPlot `"`macval(RFPlot)' `RFPlotType' `_LCI' `_rfLCI' `id' if `touse3', hor `macval(RFPlotOpts)' ||"'
					
					local touse3 `"`touse2' & `rfLoffscaleL' & !`rfLoffscaleR' & !`offscaleL' & `touse_add'"'
					qui count if `touse3'
					if r(N) {										// left-hand end off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_LCI' `id' `_rfLCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}

					local touse3 `"`touse2' & !`rfLoffscaleL' & `rfLoffscaleR' & !`offscaleL' & `touse_add'"'
					qui count if `touse3'
					if r(N) {										// right-hand end off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfLCI' `id' `_LCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}

					// right-hand line
					local touse_add `"float(`_rfUCI')>=float(`CXmin') & float(`_rfUCI')!=float(`_UCI')"'
					
					local touse3 `"`touse2' & !`rfRoffscaleL' & !`rfRoffscaleR' & !`offscaleR' & `touse_add'"'
					local RFPlot `"`macval(RFPlot)' `RFPlotType' `_UCI' `_rfUCI' `id' if `touse3', hor `macval(RFPlotOpts)' ||"'
					
					local touse3 `"`touse2' & `rfRoffscaleL' & !`rfRoffscaleR' & !`offscaleR' & `touse_add'"'
					qui count if `touse3'
					if r(N) {										// left-hand end off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_rfUCI' `id' `_UCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}

					local touse3 `"`touse2' & !`rfRoffscaleL' & `rfRoffscaleR' & !`offscaleR' & `touse_add'"'
					qui count if `touse3'
					if r(N) {										// right-hand end off scale
						local RFPlot `"`macval(RFPlot)' pcarrow `id' `_UCI' `id' `_rfUCI' if `touse3', `macval(RFPlotOpts)' ||"'
					}
				}
			}		// end if `"`rfdist'"'!=`""'
		}		// end if r(N) [i.e. if any obs with _USE==3,5 & plotid==`ppvals']
	}		// end if `"`pplvals'"'!=`""'
	
	// END GRAPH OPTS	
	
	
	* If necessary, finish off storing values for later plotting
	// added Jan 2020
	qui count if `touse' & `touseOCI'
	if r(N) {
		sort `touse' `dataid' `olinegroup' `id'
		qui by `touse' `dataid' `olinegroup' : gen `ovLineLCI' = `_LCI'[1] if `touse' & `check' & !(`_LCI'[1] > `CXmax' | `_LCI'[1] < `CXmin')
		qui by `touse' `dataid' `olinegroup' : gen `ovLineUCI' = `_UCI'[1] if `touse' & `check' & !(`_UCI'[1] > `CXmax' | `_UCI'[1] < `CXmin')
	}
	if `"`rfdist'"'!=`""' {
		qui count if `touse' & `touseRFCI'
		if r(N) {
			sort `touse' `dataid' `olinegroup' `id'
			qui by `touse' `dataid' `olinegroup' : gen `rfLineLCI' = `_rfLCI'[1] if `touse' & `check' & !(`_rfLCI'[1] > `CXmax' | `_rfLCI'[1] < `CXmin')
			qui by `touse' `dataid' `olinegroup' : gen `rfLineUCI' = `_rfUCI'[1] if `touse' & `check' & !(`_rfUCI'[1] > `CXmax' | `_rfUCI'[1] < `CXmin')
		}
	}
	
	
	// Now, having completed parsing graph opts, reset `touse' and `id' in case of any changes (e.g. "hidden" pooled obs)
	tempvar touse_id35
	qui gen byte `touse_id35' = `touse' * inlist(`_USE', 3, 5, 7) * !`touseDiam'		// `hide'
	
	// `id' : identify obs with `_USE'==3 or 5, and subtract 1 from obs above
	qui count if `touse_id35'
	if r(N) {
		tempvar id35
		qui bysort `touse' (`id') : gen long `id35' = sum(`touse_id35')
		qui replace `id' = `id' - `id35' if `touse'
		qui replace `touse' = 0 if `touse_id35'
	}
	
	// Having done this, limit the ovline variables to just the first observation within each olinegroup
	// (to prevent multiple overlapping lines from being drawn)
	sort `touse' `dataid' `olinegroup' `id'
	qui by `touse' `dataid' `olinegroup' : replace `ovLine'  = . if _n > 1
	qui by `touse' `dataid' `olinegroup' : gen `ovMin' = `id'[1]  - 0.5 if `touse' & _n==1 & !missing(`ovLine')
	qui by `touse' `dataid' `olinegroup' : gen `ovMax' = `id'[_N] + 0.5 if `touse' & _n==1 & !missing(`ovLine')

	qui count if `touse' & `touseOCI'
	if r(N) {
		qui by `touse' `dataid' `olinegroup' : replace `ovLineLCI' = . if _n > 1
		qui by `touse' `dataid' `olinegroup' : replace `ovLineUCI' = . if _n > 1
	}
	if `"`rfdist'"'!=`""' {
		qui count if `touse' & `touseRFCI'
		if r(N) {
			qui by `touse' `dataid' `olinegroup' : replace `rfLineLCI' = . if _n > 1
			qui by `touse' `dataid' `olinegroup' : replace `rfLineLCI' = . if _n > 1
		}
	}
	
	
	*** AREA PLOTS
	// Jan 2020: consider all these together, so that their sort orders don't cause conflicts

	// August 2018
	// DRAW DIAMONDS AS POLYGONS USING -twoway rarea-
	// SO THAT THEY MAY BE FILLED IN (also requires fewer variables)
	qui count if `touse' & inlist(`_USE', 3, 5) & `touseDiam'==2		// 2 = area (default)
	if !r(N) qui replace `touseDiam' = 1 if `touseDiam'>1				// to avoid error if no obs with _USE=3 or 5
	else {
		qui expand 4 if `touseDiam'==2 & inlist(`_USE', 3, 5)
		qui bysort `touse' `id' : replace `touseDiam' = (`touseDiam'>0) * _n
		qui replace `touseDiam' = 1 if `touseDiam'>1 & !inlist(`_USE', 3, 5)
		
		// x-coords
		qui gen float `DiamX' = cond(`offscaleL', `CXmin', `_LCI') if `touseDiam'==1 & float(`_ES') >= float(`CXmin')
		qui replace   `DiamX' = `_ES' if `touseDiam'==2
		qui replace   `DiamX' = `CXmin' if `touseDiam'==2 & float(`_ES') < `CXmin'
		qui replace   `DiamX' = `CXmax' if `touseDiam'==2 & float(`_ES') > `CXmax'
		qui replace   `DiamX' = . if `touseDiam'==2 & (float(`_UCI') < `CXmin' | float(`_LCI') > `CXmax')
		qui replace   `DiamX' = cond(`offscaleR', `CXmax', `_UCI') if `touseDiam'==3 & float(`_ES') <= float(`CXmax')
		qui replace   `DiamX' = . if `touseDiam'==4
		
		// upper y-coords
		qui gen float `DiamY1' = cond(`offscaleL', `id' + 0.4*( abs((`CXmin'-`_LCI')/(`_ES'-`_LCI')) ), `id') if `touseDiam'==1 & float(`_ES') >= float(`CXmin')
		qui replace   `DiamY1' = `id' + 0.4 if `touseDiam'==2
		qui replace   `DiamY1' = `id' + 0.4*( abs((`_UCI'-`CXmin')/(`_UCI'-`_ES')) ) if `touseDiam'==2 & float(`_ES') < float(`CXmin')
		qui replace   `DiamY1' = `id' + 0.4*( abs((`CXmax'-`_LCI')/(`_ES'-`_LCI')) ) if `touseDiam'==2 & float(`_ES') > float(`CXmax')
		qui replace   `DiamY1' = cond(`offscaleR', `id' + 0.4*( abs((`_UCI'-`CXmax')/(`_UCI'-`_ES')) ), `id') if `touseDiam'==3 & float(`_ES') <= float(`CXmax')
		qui replace   `DiamY1' = . if `touseDiam'==4
		
		// lower y-coords
		qui gen float `DiamY2' = cond(`offscaleL', `id' - 0.4*( abs((`CXmin'-`_LCI')/(`_ES'-`_LCI')) ), `id') if `touseDiam'==1 & float(`_ES') >= float(`CXmin')
		qui replace   `DiamY2' = `id' - 0.4 if `touseDiam'==2
		qui replace   `DiamY2' = `id' - 0.4*( abs((`_UCI'-`CXmin')/(`_UCI'-`_ES')) ) if `touseDiam'==2 & float(`_ES') < float(`CXmin')
		qui replace   `DiamY2' = `id' - 0.4*( abs((`CXmax'-`_LCI')/(`_ES'-`_LCI')) ) if `touseDiam'==2 & float(`_ES') > float(`CXmax')
		qui replace   `DiamY2' = cond(`offscaleR', `id' - 0.4*( abs((`_UCI'-`CXmax')/(`_UCI'-`_ES')) ), `id') if `touseDiam'==3 & float(`_ES') <= float(`CXmax')
		qui replace   `DiamY2' = . if `touseDiam'==4
	}
	
	// OCILine area plots
	qui count if `touse' & `touseOCI'==2		// 2 = area
	if r(N) {
		qui count if `touse' & `touseOCI'==2 & !missing(`ovLineLCI', `ovLineUCI')
		if r(N) {
			qui expand 3 if `touse' & `touseOCI'==2 & !missing(`ovLineLCI', `ovLineUCI')
			qui bysort `touse' `id' (`touseDiam') : replace `touseOCI' = (`touseOCI'>0) * _n
			qui gen float `ovLineX' = cond(`offscaleL', `CXmin', `ovLineLCI') if `touseOCI'==1 & float(`_ES') >= float(`CXmin')
			qui replace   `ovLineX' = cond(`offscaleR', `CXmax', `ovLineUCI') if `touseOCI'==2 & float(`_ES') <= float(`CXmax')
			qui replace   `ovLineX' = . if `touseOCI'==3
		}
	}
		
	// RFCILine area plots
	if `"`rfdist'"'!=`""' {
		qui count if `touse' & `touseRFCI'==2		// 2 = area
		if r(N) {
			qui count if `touse' & `touseRFCI'==2 & !missing(`rfLineLCI', `rfLineUCI')
			if r(N) {
				qui expand 3 if `touse' & `touseRFCI'==2 & !missing(`rfLineLCI', `rfLineUCI')
				qui bysort `touse' `id' (`touseDiam' `touseOCI') : replace `touseRFCI' = (`touseRFCI'>0) * _n
				qui gen float `rfLineX' = cond(`rfLoffscaleL', `CXmin', `rfLineLCI') if `touseRFCI'==1 & float(`_ES') >= float(`CXmin')
				qui replace   `rfLineX' = cond(`rfRoffscaleR', `CXmax', `rfLineUCI') if `touseRFCI'==2 & float(`_ES') <= float(`CXmax')
				qui replace   `rfLineX' = . if `touseRFCI'==3
			}
		}
	}

	qui replace `touse' = 0 if `touseDiam' > 1 | `touseOCI' > 1
	if `"`rfdist'"'!=`""' {
		qui replace `touse' = 0 if `touseRFCI' > 1
	}
	
	* Now truncate CIs at CXmin/CXmax
	qui {
		local touse2 `"`touse' * inlist(`_USE', 1, 3, 5, 7)"'

		replace `_LCI' = `CXmin' if `offscaleL'
		replace `_UCI' = `CXmax' if `offscaleR'
		replace `_LCI' = . if `touse2' & float(`_UCI') < float(`CXmin')
		replace `_UCI' = . if `touse2' & float(`_LCI') > float(`CXmax')
		replace `_ES'  = . if `touse2' & float(`_ES')  < float(`CXmin')
		replace `_ES'  = . if `touse2' & float(`_ES')  > float(`CXmax')

		if `"`rfdist'"'!=`""' {
			
			// Standard case:
			tempvar rflci2
			clonevar `rflci2' = `_rfLCI'
			replace `_rfLCI' = . if `touse2' & (`offscaleL' | float(`_rfLCI') < float(`CXmin'))
			replace `_rfUCI' = . if `touse2' & (`offscaleR' | (float(`rflci2') > float(`CXmax') & !missing(`rflci2')))
			drop `rflci2'
			
			replace `_rfLCI' = `CXmin' if `rfLoffscaleL'
			replace `_rfUCI' = `CXmax' if `rfRoffscaleR'
		
			// Niche case:
			// If one end of both CI and rfCI are offscale in same direction,
			// and the other end of the CI is *also* outside the CXmin/CXmax limits (albeit not marked as offscale)
			// (i.e. the only visible piece will be *part of one end* of the rfCI)
			// then that piece of the rfCI needs an arrow pointing *towards* _ES.
			// (This will need checking for again when it comes to constructing the rfplot)
			cap confirm numeric var `rfRoffscaleL'
			if !_rc {
				replace `_rfLCI' = `CXmin' if `touse2' & `rfRoffscaleL'
				replace `_UCI'   = `CXmin' if `touse2' & `rfRoffscaleL'
			}
			else local rfRoffscaleL = 0
			
			cap confirm numeric var `rfLoffscaleR'
			if !_rc {
				replace `_rfUCI' = `CXmax' if `touse2' & `rfLoffscaleR'
				replace `_LCI'   = `CXmax' if `touse2' & `rfLoffscaleR'
			}
			else local rfLoffscaleR = 0
		}
	}
	
	// null line, and upper horizontal border line
	// amended Nov 2021	
	summ `id' if `touse' & `_USE'==9, meanonly
	if r(N) {
		local borderline = r(min) - 1 - 0.25
	}
	else {
		summ `id' if `touse' & `_USE'!=9, meanonly
		local borderline = r(max) + 1 - 0.25
	}	
	
	// horizontal "border" line between data and headings
	local 0 `", `hlineopts'"'
	syntax [, HORizontal VERTical /*Connect(string)*/ * ]
	if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
		nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:hlineopts()}"'
		exit 198
	}
	local borderCommand `"yline(`borderline', `defHlineOpts' `options')"'

	// null line (unless switched off)
	if "`null'" == "" {
		local 0 `", `nlineopts'"'
		syntax [, HORizontal VERTical /*Connect(string)*/ * ]
		if `"`horizontal'"'!=`""' | `"`vertical'"'!=`""' {
			nois disp as err `"suboptions {bf:horizontal} and {bf:vertical} not allowed in option {bf:nlineopts()}"'
			exit 198
		}
		/*
		if `"`connect'"' != `""' {
			nois disp as err `"suboption {bf:connect()} not allowed in option {bf:nlineopts()}"'
			exit 198
		}
		*/
		
		// DF: modified to use added line approach instead of pcspike (less complex & poss. more efficient as fewer vars)
		local nullCommand `" function y=`h0', horiz range(0 `borderline') n(2) `defNlineOpts' `options' ||"'
	}

	
	sreturn clear
	sreturn local options `"`macval(opts_rest)'"'	// This is now *just* the standard "twoway" options
													//   i.e. the specialist "forestplot" options have been filtered out
	
	// Return plot commands...
	sreturn local bordercommand `"`borderCommand'"'
	
	// ... unless `colsonly'
	if `"`colsonly'"'==`""' {
		sreturn local scplot        `"`scPlot'"'
		sreturn local ciplot        `"`CIPlot'"'
		sreturn local rfplot        `"`RFPlot'"'
		sreturn local pciplot       `"`PCIPlot'"'
		sreturn local diamplot      `"`diamPlot'"'
		sreturn local pointplot     `"`pointPlot'"'
		sreturn local ppointplot    `"`ppointPlot'"'
		sreturn local olineplot     `"`olinePlot'"'
		sreturn local olineareaplot `"`olineAreaPlot'"'
		sreturn local nullcommand   `"`nullCommand'"'
		
		// Nov 2021: see notes above
		sreturn local g_olinefirst  `"`g_olinefirst'"'
		sreturn local g_nlinefirst  `"`g_nlinefirst'"'
		sreturn local g_overlay_ci  `"`g_overlay_ci'"'
	}
	
end