Mplot (#108)

* Add mplot (for multiple models) function
* Closes #59 
* Closes #67 
* Closes #87 
* Closes #88
* Closes #89
* Closes #99

Makefile

@@ -15,7 +15,7 @@ notebook:
 	cd examples && runpynb readme-examples.ipynb
 
 BLACK_OPTS := -l 95
-SRC_FILES := arg_validators dataframe_utils graph_utils plot text_utils
+SRC_FILES := arg_validators dataframe_utils graph_utils text_utils plot mplot
 SRC_FILES := $(addprefix forestplot/, $(addsuffix .py, $(SRC_FILES))) 
 .PHONY: lint
 lint: # Check with mypy, pyflakes, black

README.md

@@ -36,6 +36,7 @@ Additional options allow easy addition of columns in the `dataframe` as annotati
 > - [Quick Start](#quick-start)
 > - [Some Examples with Customizations](#some-examples-with-customizations)
 > - [Gallery and API Options](#gallery-and-api-options)
+> - [Multi-models](#multi-models)
 > - [Known Issues](#known-issues)
 > - [Background and Additional Resources](#background-and-additional-resources)
 > - [Contributing](#contributing)
@@ -257,6 +258,57 @@ fp.forestplot(df,  # the dataframe with results data
 </details>
 <p align="right">(<a href="#top">back to top</a>)</p>
 
+<!------------------- Multi-models ------------------->
+## Multi-models[![](https://raw.githubusercontent.com/LSYS/forestplot/main/docs/images/pin.svg)](#multi-models)
+
+For coefficient plots where each variable can have multiple estimates (each `model` has one).
+
+```python
+import forestplot as fp
+
+df_mmodel = pd.read_csv("../examples/data/sleep-mmodel.csv").query(
+    "model=='all' | model=='young kids'"
+)
+df_mmodel.head(3)
+```
+
+|    | var   |       coef |       se |         T |     pval |       r2 |     adj_r2 |         ll |      hl | model      | group         | label       |
+|---:|:------|-----------:|---------:|----------:|---------:|---------:|-----------:|-----------:|--------:|:-----------|:--------------|:------------|
+|  0 | age   |   0.994889 |  1.96925 |  0.505213 | 0.613625 | 0.127289 |  0.103656  |   -2.87382 |  4.8636 | all        | age           | in years    |
+|  3 | age   |  22.634    | 15.4953  |  1.4607   | 0.149315 | 0.178147 | -0.0136188 |   -8.36124 | 53.6293 | young kids | age           | in years    |
+|  4 | black | -84.7966   | 82.1501  | -1.03222  | 0.302454 | 0.127289 |  0.103656  | -246.186   | 76.5925 | all        | other factors | =1 if black |
+
+```python
+fp.mforestplot(
+    dataframe=df_mmodel,
+    estimate="coef",
+    ll="ll",
+    hl="hl",
+    varlabel="label",
+    capitalize="capitalize",
+    model_col="model",
+    color_alt_rows=True,
+    groupvar="group",
+    table=True,
+    rightannote=["var", "group"],
+    right_annoteheaders=["Source", "Group"],
+    xlabel="Coefficient (95% CI)",
+    modellabels=["Have young kids", "Full sample"],
+    xticks=[-1200, -600, 0, 600],
+    mcolor=["#CC6677", "#4477AA"],
+    # Additional kwargs for customizations
+    **{
+        "markersize": 30,
+        # override default vertical offset between models (0.0 to 1.0)
+        "offset": 0.35,  
+        "xlinestyle": (0, (10, 5)),  # long dash for x-reference line
+        "xlinecolor": ".8",  # gray color for x-reference line
+    },
+)
+```
+<p align="left"><img width="100%" src="https://raw.githubusercontent.com/LSYS/forestplot/mplot-dev/docs/images/multimodel.png"></p>
+
+Please note: This module is still experimental. See [this jupyter notebook](https://nbviewer.org/github/LSYS/forestplot/blob/mplot-dev/examples/test-multmodel-sleep.ipynb) for more examples and tweaks.
 
 <!------------------- GALLERY AND API OPTIONS ------------------->
 ## Gallery and API Options[![](https://raw.githubusercontent.com/LSYS/forestplot/main/docs/images/pin.svg)](#gallery-and-api-options)

examples/data/sleep-mmodel.csv

@@ -0,0 +1,57 @@
+var,coef,se,T,pval,r2,adj_r2,ll,hl,model,group,label
+age,0.99488919909132,1.9692489158653246,0.5052125158358395,0.6136248760479441,0.12728876841881298,0.10365635595820055,-2.8738245461702143,4.863602944352854,all,age,in years
+age,1.4828927472424902,2.8854619757926523,0.5139186583233804,0.6077171047169159,0.18038221190248027,0.13910649595512325,-4.197237184638171,7.163022679123152,men,age,in years
+age,0.953199898987002,2.9432093495480007,0.32386411762839373,0.7463430958352442,0.10910549372734824,0.05342458708530751,-4.846720706047407,6.75312050402141,women,age,in years
+age,22.634017225177878,15.49532005480011,1.4607002078776912,0.14931480960176477,0.17814691642754532,-0.013618803072694252,-8.361237717039167,53.62927216739492,young kids,age,in years
+black,-84.79661217544819,82.15012465488611,-1.0322152587312559,0.3024539030548957,0.12728876841881298,0.10365635595820055,-246.18571533392443,76.59249098302806,all,other factors,=1 if black
+black,-132.96710936577898,132.581166096424,-1.0029109961898683,0.31677594790578495,0.18038221190248027,0.13910649595512325,-393.95763922402284,128.02342049246488,men,other factors,=1 if black
+black,-68.35063065532516,108.90175418428296,-0.6276357177834123,0.5308818950534195,0.10910549372734824,0.05342458708530751,-282.95362113400626,146.25235982335596,women,other factors,=1 if black
+black,-119.74103936970126,296.4329532300549,-0.40393970395313283,0.6876932233318072,0.17814691642754532,-0.013618803072694252,-712.6952298056457,473.21315106624314,young kids,other factors,=1 if black
+clerical,22.505827481347207,48.96326328570245,0.45964721244221146,0.6459626857575079,0.12728876841881298,0.10365635595820055,-73.6855925875676,118.69724755026202,all,occupation,=1 if clerical worker
+clerical,-229.27596235505098,102.88822122848798,-2.228398543754476,0.026653770224379605,0.18038221190248027,0.13910649595512325,-431.81492143364045,-26.737003276461508,men,occupation,=1 if clerical worker
+clerical,106.5072576745419,61.1273211607197,1.7423838580216282,0.08281375364786414,0.10910549372734824,0.05342458708530751,-13.950911427517042,226.96542677660085,women,occupation,=1 if clerical worker
+clerical,-239.90257363807342,211.76019987926273,-1.1328973705864291,0.2617642403464634,0.17814691642754532,-0.013618803072694252,-663.4860400434246,183.68089276727778,young kids,occupation,=1 if clerical worker
+construc,113.9295583737603,105.04513651515707,1.0845771841833085,0.2786144612102424,0.12728876841881298,0.10365635595820055,-92.43824014829062,320.2973568958112,all,occupation,=1 if construction worker
+construc,65.69605933555773,107.88920815173707,0.6089215081008081,0.5430737247378323,0.18038221190248027,0.13910649595512325,-146.6875124081796,278.07963107929504,men,occupation,=1 if construction worker
+construc,361.75642960038044,428.2648335748007,0.8447026261314451,0.3991781717050136,0.10910549372734824,0.05342458708530751,-482.1869456962427,1205.6998048970036,women,occupation,=1 if construction worker
+construc,-186.41520083935393,358.22350129635726,-0.5203879705400266,0.604708210492017,0.17814691642754532,-0.013618803072694252,-902.9688899343187,530.1384882556108,young kids,occupation,=1 if construction worker
+educ,-7.210558397084539,7.516735606083484,-0.9592672637373134,0.33787250903288846,0.12728876841881298,0.10365635595820055,-21.977659764751728,7.55654297058265,all,labor factors,years of schooling
+educ,-7.545419560820269,9.72034104139323,-0.7762504966326546,0.4382610079422641,0.18038221190248027,0.13910649595512325,-26.680241145893653,11.589402024253113,men,labor factors,years of schooling
+educ,-6.278396591271823,11.869882954315754,-0.5289350042823354,0.5973742665985272,0.10910549372734824,0.05342458708530751,-29.66931804803307,17.11252486548942,women,labor factors,years of schooling
+educ,-20.972115853313863,26.97403159331749,-0.7774928186303995,0.43992297847502027,0.17814691642754532,-0.013618803072694252,-74.92821247458355,32.98398076795583,young kids,labor factors,years of schooling
+gdhlth,-82.58043355263888,58.2047169680557,-1.4187928033042618,0.15656198407017147,0.12728876841881298,0.10365635595820055,-196.9272724713884,31.766405366110618,all,health factors,=1 if in good or excel. health
+gdhlth,-188.28450807319786,80.4765387271364,-2.339619857553702,0.0200113537818631,0.18038221190248027,0.13910649595512325,-346.70530871902446,-29.863707427371253,men,health factors,=1 if in good or excel. health
+gdhlth,-24.491583169191312,87.716866542274,-0.2792117882754956,0.780339918384747,0.10910549372734824,0.05342458708530751,-197.3474018508352,148.3642355124526,women,health factors,=1 if in good or excel. health
+gdhlth,-141.81497580656173,203.21302167135576,-0.6978636242903301,0.4879582244422951,0.17814691642754532,-0.013618803072694252,-548.3015402664399,264.67158865331646,young kids,health factors,=1 if in good or excel. health
+lhrwage,21.60569674505552,31.989300709296707,0.6754038464734707,0.4997211854315843,0.12728876841881298,0.10365635595820055,-41.23930286789559,84.45069635800664,all,labor factors,log hourly wage
+lhrwage,3.5447518688419417,47.045922578822974,0.0753466331307011,0.9399931101323359,0.18038221190248027,0.13910649595512325,-89.06674509586989,96.15624883355378,men,labor factors,log hourly wage
+lhrwage,-22.5804823252749,53.782320170113664,-0.4198495389163717,0.6749977887003282,0.10910549372734824,0.05342458708530751,-128.56451196594747,83.40354731539766,women,labor factors,log hourly wage
+lhrwage,35.609316976870375,122.3237377739899,0.29110716877098325,0.7719733324342494,0.17814691642754532,-0.013618803072694252,-209.07458915614382,280.29322310988454,young kids,labor factors,log hourly wage
+prot,-9.249429608907253,39.7714621826478,-0.23256448471594685,0.8161916436328263,0.12728876841881298,0.10365635595820055,-87.38297645285611,68.88411723504161,all,other factors,=1 if Protestant
+prot,-20.967327503532506,52.20106018322577,-0.4016647828595275,0.6882393483114742,0.18038221190248027,0.13910649595512325,-123.72688798645723,81.79223297939222,men,other factors,=1 if Protestant
+prot,1.0666432850620384,61.89804739666575,0.017232260627327883,0.986266664673677,0.10910549372734824,0.05342458708530751,-120.91032738556035,123.04361395568444,women,other factors,=1 if Protestant
+prot,-24.173124098859226,127.56649739999632,-0.18949429976949358,0.8503450117765196,0.17814691642754532,-0.013618803072694252,-279.34411088810623,230.9978626903878,young kids,other factors,=1 if Protestant
+selfe,-21.27417859824218,63.303918327210305,-0.33606416728074434,0.7369588252939454,0.12728876841881298,0.10365635595820055,-145.63872032189542,103.09036312541107,all,labor factors,=1 if self employed
+selfe,3.4840942455998385,77.58570652121905,0.044906393223949924,0.964214160112589,0.18038221190248027,0.13910649595512325,-149.246004987894,156.21419347909367,men,labor factors,=1 if self employed
+selfe,-90.68593564430114,112.55649657600425,-0.8056925935240449,0.42127457554209236,0.10910549372734824,0.05342458708530751,-312.4910015401089,131.11913025150665,women,labor factors,=1 if self employed
+selfe,-370.9565115107388,241.15347311683067,-1.538259046059946,0.12924271026812853,0.17814691642754532,-0.013618803072694252,-853.3352783269672,111.42225530548967,young kids,labor factors,=1 if self employed
+smsa,-40.65355700424955,39.50772275371498,-1.0290027916232358,0.30395952409445154,0.12728876841881298,0.10365635595820055,-118.26897109938261,36.96185709088351,all,area of residence,=1 if live in smsa
+smsa,-27.631427416163216,52.418592857611465,-0.5271302778237585,0.5985235118106444,0.18038221190248027,0.13910649595512325,-130.81920835921053,75.55635352688411,men,area of residence,=1 if live in smsa
+smsa,-57.146400428034234,61.521030174672646,-0.928892124624412,0.35394487787468343,0.10910549372734824,0.05342458708530751,-178.38041682847313,64.08761597240468,women,area of residence,=1 if live in smsa
+smsa,43.42957155402094,138.68308939805914,0.31315693746456685,0.7552474332941742,0.17814691642754532,-0.013618803072694252,-233.9779099865449,320.83705309458674,young kids,area of residence,=1 if live in smsa
+south,82.48697958253655,46.37757109786662,1.7785963695354232,0.07589350453103752,0.12728876841881298,0.10365635595820055,-8.624685038753597,173.5986442038267,all,area of residence,=1 if live in south
+south,79.40169407723894,64.43983230307614,1.2321834374706864,0.2189216981608257,0.18038221190248027,0.13910649595512325,-47.450305131492144,206.25369328597003,men,area of residence,=1 if live in south
+south,114.62293382753175,69.30049378126785,1.6539988039524578,0.09952837233805101,0.10910549372734824,0.05342458708530751,-21.941378827550423,251.18724648261394,women,area of residence,=1 if live in south
+south,71.85138083602305,136.01011187506683,0.5282796980714398,0.5992538218558838,0.17814691642754532,-0.013618803072694252,-200.2093495895635,343.9121112616096,young kids,area of residence,=1 if live in south
+spsepay,-0.0010054015767941848,0.002647615337851829,-0.3797385377023568,0.7042954459596942,0.12728876841881298,0.10365635595820055,-0.006206808959675351,0.004196005806086981,all,other factors,spousal wage income
+spsepay,0.0030693469858871225,0.0049240034441705854,0.623343793457507,0.533569693312251,0.18038221190248027,0.13910649595512325,-0.006623721085208695,0.01276241505698294,men,other factors,spousal wage income
+spsepay,-0.0005081661923143077,0.0036213813114609078,-0.14032385673004633,0.8885302141467499,0.10910549372734824,0.05342458708530751,-0.0076444998990057005,0.006628167514377085,women,other factors,spousal wage income
+spsepay,-0.0047013059752814,0.01144291160114906,-0.4108487541588026,0.6826470962008051,0.17814691642754532,-0.013618803072694252,-0.027590537117622167,0.018187925167059367,young kids,other factors,spousal wage income
+totwrk,-0.1519224329433428,0.020366493775550474,-7.459429915507711,3.698705255539423e-13,0.12728876841881298,0.10365635595820055,-0.19193369499227117,-0.11191117089441441,all,labor factors,mins worked per week
+totwrk,-0.19100803367191987,0.029765234919101078,-6.41715189519117,5.964764273464163e-10,0.18038221190248027,0.13910649595512325,-0.2496019098733212,-0.13241415747051855,men,labor factors,mins worked per week
+totwrk,-0.1255122674915504,0.0327128882144724,-3.8367834313089766,0.00016213485682276793,0.10910549372734824,0.05342458708530751,-0.18997664357626337,-0.06104789140683743,women,labor factors,mins worked per week
+totwrk,-0.11299498951128406,0.07636280752220165,-1.479712351833476,0.14418175650843867,0.17814691642754532,-0.013618803072694252,-0.2657433470078354,0.039753367985267324,young kids,labor factors,mins worked per week
+yrsmarr,-0.07595761901493851,2.009355661684067,-0.03780197824773214,0.9698601588766725,0.12728876841881298,0.10365635595820055,-4.023463596978298,3.8715483589484214,all,family factors,years married
+yrsmarr,0.2241161052983935,2.93479128035093,0.0763652620882786,0.939183433631042,0.18038221190248027,0.13910649595512325,-5.553120238550619,6.001352449147406,men,family factors,years married
+yrsmarr,-1.4141371514041594,2.9319849741652555,-0.48231391492951575,0.630053922467078,0.10910549372734824,0.05342458708530751,-7.191938879277817,4.363664576469498,women,family factors,years married
+yrsmarr,-31.211144074101608,16.91401104102699,-1.8452834161214147,0.06993266917751552,0.17814691642754532,-0.013618803072694252,-65.04420350482327,2.621915356620054,young kids,family factors,years married