*! Version 1.6 22May2022 of help file for 1.6 of pvenn2.ado by Mead Over

*! Based on pvenn.sthlp by Wenfeng Gong & Jan Osterman 23 Nov 2011

Version 1.6, 22May2022. Available from: CGD's Stata Programs

Title

pvenn2 -- Proportional Venn diagrams. Enhanced version of pvenn

Syntax

pvenn2 [var1 [... var3]] [if]
[, [manual_mode_opts] options]

manual_mode_opts

Main
plabel(lblname [lblname ...]) specifies a list of label names for the populations or subsets.

pA(#) specifies the size of population A.

pB(#) specifies the size of population B.

pC(#) specifies the size of population C.

pAB(#) specifies the size of overlap between population A & B.

pAC(#) specifies the size of overlap between population A & C.

pBC(#) specifies the size of overlap between population B & C.

ptotal(#) specifies the size of total population.

Main
ang(#) specifies the angle between the connecting lines of circle A/B center and the X axis, that is the relative location of circle B to circle A; default is 0.

pos(#) specifies the relative location of circle C to circle A & B; default is 1.

drawtotal(#) draw a rectangle outside all circles to represent the total population size; default is 1.

drawlabel(#) draw labels in circles indicating names of the populations; default is 1.

lc(colorstylelist) specifies a line color for each circle and rectangle; default colors are determined by the selected graphics scheme.

lp(linepatternstylelist) specifies a line pattern for each circle and rectangle; default is "solid solid solid solid".

lw(linewidthstylelist) specifies a line widths for each circle and rectangle; default is "0.8 0.8 0.8 0.8".

n(#) specify the points (#*2) used to draw a circle; default is 2,000.

twoway_options specify additional twoway options (but not all of them are allowed).
Some that are allowed are listed below and further described here.

text(#y #x "text) specify contents and location of added text

legend(passthru) specify legend options

note(passthru) append a note underneath the graph

title(passthru) display a title at the top of the graph

subtitle(passthru) display a subtitle at the top of the graph

nolabel Omit variable names, which otherwise appear as labels at the center of each circle

name(passthru) name the memory graph for recall e.g. with the graph combine command

saving(passthru) save the graph to disk.

scheme(schemes) Select a graph scheme which will affect the default colors and appearance of the Venn diagram.

* All additional otherwise unspecified options are passed through to Stata's function graphing command

Description

pvenn2 produces proportioned and positioned Venn diagrams,
supporting 2-circle and 3-circle Venn diagrams, as well as a 1-circle diagram. pvenn2 can also draw a rectangle
outside all circles to proportionally represent the total population size, when it is possible.
Proportional Venn diagrams attempts to make each of the zones (the circles, the area between the circles and the outside rectangle,
and the set intersections) proportional
to the population (value) assigned to the zone. Note that, the overlap regions
of 3-circle Venn diagrams are not always to scale, because an
ideal solution is generally not possible using circles. See Micallef & Rodgers (2014)
for a less-constrained approach using ellipses that nevertheless can fail to reproduce proportionately
sized representations of the sizes of set intersections for some data.
Also see Lauritsen's 1998 Stata program venndiag, updated in 2009, that makes a proportionate Venn diagram
composed of circles, rectangles or ellipses, but uses Stata's original gr7 graph tools.

The core code for pvenn2 and for most of this help file was published in October, 2011 on SSC by Wenfeng Gong & Jan Osterman
of the Duke Center for Health Policy as the program pvenn.
The enhancements in pvenn2 (relative to the November, 2011 version 1.0 of pvenn)
consist of (a) the calculation and display of the size of the intersection among all three sets, pABC;
(b) increased control over the text and labels;
(c) the default addition of an informative legend which can be suppressed by legend(off);
(d) control over the graph's appearance using the option scheme(schemes);
(e) options to save and name the created graph
and (f) implementation of -if- to restrict analysis to a subset of the data in memory.
This help file is also enhanced with typo corrections, additional references, corrected examples
and the addition of the "Also See" and "Jump To" dialogs above.

As is the case for pvenn, there are two ways to use pvenn2:

1. Generating Venn diagrams from data: pvenn2 can draw Venn diagrams from one, two, or three variables.
The variables must only have values of 0 and 1, where 1 means a positive observation (the observation is a member of the associated set)
and 0 means a negative observation (the observation is not a member of that set).
With one variable specified, a 1-circle diagram is drawn with an area representing the size of the associated set of positive observations.
If drawtotal(1) is also specified, pvenn2 encloses the circle in a rectangle, with the area between the circle and
the rectangle being proportional to the number of observations which are in the total population but not in the set.
With two or three variables specified, 2-circle or 3-circle proportional Venn diagrams can be created.
The following example data set has 3 variables and 9 observations. pvenn2 produces the Venn diagram directly from the data.

clear
input popA popB popC
1 0 0
1 1 0
0 1 1
0 0 1
1 0 1
1 1 1
0 0 0
0 0 0
0 0 0
end

list popA popB popC

+--------------------+
| popA popB popC |
+--------------------+
1. | 1 0 0 |
2. | 1 1 0 |
3. | 0 1 1 |
4. | 0 0 1 |
5. | 1 0 1 |
+--------------------+
6. | 1 1 1 |
7. | 0 0 0 |
8. | 0 0 0 |
9. | 0 0 0 |
+--------------------+

. pvenn2 popA popB popC

popA | Freq. Percent Cum.

+

0 | 5 55.56 55.56

1 | 4 44.44 100.00

+

Total | 9 100.00

| popB

popA | 0 1 | Total

+
+

0 | 4 1 | 5

1 | 2 2 | 4

+
+

Total | 6 3 | 9

| popC

popA | 0 1 | Total

+
+

0 | 3 2 | 5

1 | 2 2 | 4

+
+

Total | 5 4 | 9

| popC

popB | 0 1 | Total

+
+

0 | 4 2 | 6

1 | 1 2 | 3

+
+

Total | 5 4 | 9

Sizes of subsets:
Set A: Population_A as identified by the variable popA: 4
Set B: Population_B as identified by the variable popB: 3
Set C: Population_C as identified by the variable popC: 4
AB Overlap: 2
AC Overlap: 2
BC Overlap: 2
ABC Overlap: 1
Total population: 9
Draw total population rectangle (0,not; 1, yes): 1
Rotation angle of circle B: 0
Relative position of circle C (1,clockwise; -1,counterclockwise): 1

The above example illustrates a limitation of using circles to construct a proportional Venn diagram.
In the above data the intersection between any two of the three sets contains two observations,
while the intersection of all three sets contains a single observation.
In the Venn diagram constructed by this program, the areas of all three intersections of two sets look approximately equal and might plausibly
each represent two observations. But the area of the intersection of all three sets
represent only one observation, and thus should be half the size of the area of any of the two-set intersections.
Inspection of the graph reveals that the area of intersection of all three sets is larger than half the area of any
of the two-set intersections, and thus too large. For an arbitrary data set, proportional representation of the areas
of all intersections is not possible using circles. But for most data sets,
the proportional representation using circles works pretty well. Caveat emptor.
See the references for further discussion.

2. Generating Venn diagrams from manual inputs: When no variable is specified, pvenn2 can draw Venn diagrams using manual_mode_opts.
In the above example,

. pvenn2 popA popB popC

is equivalent to

. pvenn2, plabel(popA popB popC) pA(4) pB(3) pC(4) pAB(2) pAC(2) pBC(2) pABC(1) ptotal(9)

Options Generating Venn diagrams from manual inputs

Main

The manual_mode_opts options are functional only when no variable is specified.

plabel(lblname [lblname ...]) specifies a list of label names for the populations.
To fit into the Venn diagram and its legend, the label names should be short.
If possible, avoid spaces or other punctuation in the names.
If a space is desired in the label, use an underscore character ("_"),
because by default all underscore characters in these label names
are replaced with a space in the display.
If option plabel() is omitted, the default names for up to three populations
are "Population_A", "Population_B" and "Population_C".

pA(#) specifies the size of population A; default is 0. If pA(0), circle A is not drawn.

pB(#) specifies the size of population B; default is 0. If pB(0), circle B is not drawn.

pC(#) specifies the size of population C; default is 0. If pC(0), circle C is not drawn.

pAB(#) specifies the size of overlap between population A & B; default is 0.

pAC(#) specifies the size of overlap between population A & C; default is 0.

pBC(#) specifies the size of overlap between population B & C; default is 0.

pABC(#) specifies the size of overlap of populations A, B & C; default is 0.

ptotal(#) specifies the size of total population; default is 0. If ptotal(0) is specified, outside rectangle is not drawn.

Options

Main

ang(#) specifies the angle between the connecting lines of circle A/B center and the X axis, that is the relative location of circle B to circle A; default is 0.

pos(#) specifies the relative location of circle C to circle A & B; default is 1.
pos(1) circle C is drawn clockwise to the circle A & B; pos(-1) circle C is drawn counterclockwise to the circle A & B.

lc(colorstylelist) specifies a line color for each circle and rectangle;
default colors for the circles are the first three colors in the user's active graph scheme.
The default color for the rectangle is the color the active scheme assigns to axes, which is typically black.
The sequence is circleA, circleB, circleC, and outside rectangle. Use . to skip an item in the list.
The color scheme used in pvenn can be reproduced by specifying the option
lc(cranberry emerald brown lavender).

lp(linepatternstylelist) specifies a line pattern for each circle and rectangle; default is "solid solid solid solid".
The sequence is circleA, circleB, circleC, and outside rectangle. Use . to skip an item in the list.

lw(linewidthstylelist) specifies a line widths for each circle and rectangle; default is "0.8 0.8 0.8 0.8".
The sequence is circleA, circleB, circleC, and outside rectangle. Use . to skip an item in the list.

drawtotal(1) draw a rectangle outside all circles to represent the total population size; default is 1. drawtotal(0) suppresses the rectangle.

drawlabel(1) draw labels in circles indicating names of the populations; default is 1. drawlabel(0) suppresses the display of labels.

n(#) specify the points (#*2) used to draw a circle; default is 2,000,
but sometimes leaves a small gap at clock position 3 of a circle. This gap can be closed
by increasing the number of points to 20,000 which is the default in pvenn
or to an even larger value. Large values of n(#) slow the production of the plot.
Refer to help twoway_function.

twoway_options specifies additional twoway options (not all of which are allowed). Useful allowed options
include title_options plus additional options listed below.

Added by Mead Over

text(string) specify the contents and location of added text.
The text is centered in a rectangle defined by three points: point (0,0) is the center of the rectangle,
(1,1) is the northeast corner and (-1,-1) is the southwest corner.

legend(passthru) use legend options to replace the default legend. To suppress pvenn2's default legend, specify legend(off).

note(passthru) append a note underneath the graph

title(passthru) display a title at the top of the graph

subtitle(passthru) display a subtitle at the top of the graph

nolabel Do not label the circles with the variable names

name(passthru) name the memory graph for recall e.g. with the graph combine command

saving(passthru) save the graph to disk.

plotregion(region_options) By specifying region_options, the user can, for example, override the default margin(marginstyle),
which is vlarge with drawtotal(0) or medlarge with drawtotal(1).
This is useful when parts of the graph or its labels extend beyond the borders of the page.

scheme(schemes) Select a graph scheme which will affect the default colors and appearance of the Venn diagram.
To list the schemes installed on your computer type graph query, schemes at the Stata dot prompt.
Additional user-contributed schemes are available online. See for example s2clr_on_white, which can be installed
here.

Examples

1. Generating Venn diagrams from data:

The examples below highlight the use of the pvenn plot on the nlsw88 dataset, which is pre-installed with Stata software.

Click below to load dataset

sysuse nlsw88

Click below (after the dataset is loaded) to see the intersections among "never married" "college graduate" and "lives in south".

pvenn2 never_married collgrad south

pvenn2 never_married collgrad south, ang(30) drawtotal(0) pos(-1)

The options lcolor, lwidth, lcolor and lpattern can enhance the appearance of the the displayed circles and rectangle.

pvenn2 never_married collgrad south, drawtotal(1) lc("black" "red") lw(0.1 0.3 0.5 0.8) lp("_" "." "dash_dot" "-")

Click below to see how the circle labels can be suppressed using the option nolabel
and instead use a legend and user-specified text to annotate the plot.
Note that the keys in the legend must be 1, 3 and 5 rather than 1, 2, 3.
(This is because pvenn2 draws two half-circles for each of the depicted sets.)

pvenn2 never_married collgrad south, ang(30) drawtotal(1) legend(order(1 "Never married" 3 "College graduate" 5 "South") col(1) pos(3)) nolabel text(0 .6 "27") note("27 individuals are in the intersection of the three sets")

Click below to see the intersections among "married" "lives in south" and "lives in central city".

pvenn2 married south c_city

In this case, total population cannot be represented as an outside rectangle,
because the smallest rectangle containing the circles has too much area
in proportion to the areas in the circles. This phenomenom is inherent
in the attempt to construct a proportionate Venn diagram using only circles
embedded in a rectangle.

2. Generating Venn diagrams from manual inputs:

1-circle diagram:

pvenn2, pA(10) pB(0) pC(0) pAB(0) pAC(0) pBC(0) ang(30) ptotal(30) drawtotal(1) pos(-1) plabel("Max" "Jan" "Winston")

2-circle Venn diagram:

pvenn2, pA(10) pB(0) pC(30) pAB(0) pAC(3) pBC(0) ptotal(100) ang(30) drawtotal(1) pos(-1) plabel("Max" "Jan" "Winston")

pvenn2, pA(10) pB(30) pC(0) pAB(0) pAC(0) pBC(3) ptotal(100) ang(30) drawtotal(1) pos(-1) plabel("Max" "Jan" "Winston")

3-circle Venn diagram:

pvenn2, pA(10) pB(30) pC(20) pAB(4) pAC(5) pBC(3) pABC(1) ang(30) ptotal(90) drawtotal(0) pos(1) plabel("Max" "Jan" "Winston") title(Example)

pvenn2, pA(45) pB(25) pC(50) pAB(18) pAC(5) pBC(3) pABC(1) ptotal(150) ang(120) drawtotal(1) pos(-1) plabel("Max" "Jan" "Winston") title(Example)

pvenn2, pA(10) pB(30) pC(20) pAB(0) pAC(0) pBC(3) ang(30) drawtotal(1) pos(-1) plabel("Max" "Jan" "Winston") title(Example)

References

Alexandersson, A. 1998. gr32: Confidence
ellipses. Stata Technical Bulletin 46: 10-13. In
Stata Technical Bulletin Reprints, vol. 8, 54-57. College Station, TX:
Stata Press.

------. 2004. Graphing confidence ellipses: An update of
ellip for Stata 8. Stata Journal 4(3): 242-256.

McCartin, B. 2003. A Geometric Characterization of Linear
Regression. Statistics: A Journal of Theoretical and Applied Statistics
37(2): 101-117.

Micallef L, Rodgers P (2014) eulerAPE: Drawing Area-Proportional 3-Venn Diagrams Using Ellipses. PLoS ONE 9(7): e101717. https://doi.org/10.1371/journal.pone.0101717

Lauritsen, Jens M. (1998) "VENNDIAG: Stata module to generate Venn diagrams," Statistical Software Components S361502, Boston College Department of Economics, revised 01 Apr 2009.
Available here. A PDF of his original 1998 article in Stata's STB is available
here.

Euler diagram. 12 January 2022, 17:40 UTC. In Wikipedia: The Free Encyclopedia. Wikimedia Foundation Inc. Encyclopedia on-line. Available from https://en.wikipedia.org/wiki/Euler_diagram. Internet. Retrieved 1 February 2022.

Authors

Version 1.0 of the original program pvenn and its help file can be downloaded
here. They were written in 2011 by:

Wenfeng (Winston) Gong & Jan Osterman;
Center for Health Policy and Inequity Research at Duke University, Durham, NC.
Email gongwenf@gmail.com

Mead Over has added additional
functionality from May, 2015 to the present. Contact him at:
Email: MOver@CGDev.Org or the original authors
with any problems or suggestions.