From 45b30a9b1f56376b3eb2b84970956a9687bdda24 Mon Sep 17 00:00:00 2001 From: pnnehome Date: Tue, 14 Nov 2023 15:58:46 -0800 Subject: [PATCH] many changes --- .github/workflows/deploy.yml | 33 ++++++ .gitignore | 4 + README.rst | 5 + docs/CNAME | 1 + docs/Makefile | 20 ++++ docs/make.bat | 35 +++++++ docs/source/_static/CNAME | 1 + docs/source/_static/custom.css | 34 +++++++ docs/source/_static/logo.png | Bin 0 -> 7970 bytes docs/source/_templates/layout.html | 18 ++++ docs/source/code/code.rst | 125 +++++++++++++++++++++++ docs/source/conf.py | 43 ++++++++ docs/source/conf.py.bk | 44 ++++++++ docs/source/contact/contact.rst | 14 +++ docs/source/home/home.rst | 146 +++++++++++++++++++++++++++ docs/source/index.rst | 157 +++++++++++++++++++++++++++++ requirements.txt | 3 + 17 files changed, 683 insertions(+) create mode 100644 .github/workflows/deploy.yml create mode 100644 .gitignore create mode 100644 README.rst create mode 100644 docs/CNAME create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_static/CNAME create mode 100644 docs/source/_static/custom.css create mode 100644 docs/source/_static/logo.png create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/code/code.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/conf.py.bk create mode 100644 docs/source/contact/contact.rst create mode 100644 docs/source/home/home.rst create mode 100644 docs/source/index.rst create mode 100644 requirements.txt diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..258b6c1 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,33 @@ +name: Build and Deploy Sphinx Docs + +on: push + +jobs: + build_and_deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - name: Checkout code + uses: actions/checkout@v3 + - name: Install python + uses: actions/setup-python@v4 + with: + python-version: '3.9' + - name: Install dependencies and the python package + run: | + pip install -r requirements.txt + - name: Build docs + run: | + cd docs # Change to your Sphinx docs directory if not 'docs' + make html + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: html-docs + path: docs/build/html/ + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build/html # Adjust path to match where your HTML files are generated \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..06dbb34 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +/docs/build +build/ +.vscode/ +.DS_Store \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..b884c10 --- /dev/null +++ b/README.rst @@ -0,0 +1,5 @@ +Lumache +======= + +**Lumache** (/lu'make/) is a Python library for cooks and food lovers that +creates recipes mixing random ingredients. diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..4a244c0 --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +www.pnne.net \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_static/CNAME b/docs/source/_static/CNAME new file mode 100644 index 0000000..4a244c0 --- /dev/null +++ b/docs/source/_static/CNAME @@ -0,0 +1 @@ +www.pnne.net \ No newline at end of file diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..0657b8c --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,34 @@ +.red-text { + color: red; +} + +.green-text { + color: green; +} + +.dodgerblue-text { + color: dodgerblue; +} + +.goldenrod-text { + color: goldenrod +} + +.purple-text { + color: purple +} + +.brown-text { + color: brown +} + +.highlight-console pre { + font-size: 14px; +/* font-family: "Consolas", monospace */ +} + +code { +/* font-family: "Consolas", monospace; */ + font-size: 14px; + color:dodgerblue +} diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..2a880e00c431444af5bf66299e9154481710b723 GIT binary patch literal 7970 zcmaJ`cRbtCyG|nb5;S&fvG-m@(b%)Gx7tcowWzH|>{**?YZO&#k1Dlijnb;UmD)91 zin`z4`}^Gc-<8id=Sa@TdCz&D^SsX+i`7#nC8j5aKp>==8Y%{0x$^G;2*7uRx-S7> z0rfIa$3QAa8MnZHa872L&bqn~KCliz@SzkCynju=7X(TV!T;|%1fm6H_}{t#l;=Nf zU=T>OD+Kp&@*c1t^3*W*f;F`$r(4aLU8m6DI+54|U& znv~BP&6=fg5XKgLTMr-Vk7Pw*9avH1B=$&Z?9ElYFeMqIaJEAKrOU~OOHX}siULYn zN?n@xW_CU9oSr_f+V--OiR_F3L&Z5E1{Oi?qT?yy) z{eepB7Bk3$7GD3!m(SSMExxhuICs%Yy2admdi9Mj<-O>6bjRd7OVzo?2k$nsjm1}X zs@g|k_j;=buGL6b6s#_fKP#GePvqtxKV^UL*|C5UOBaeDv!x%tM9F&J+kMfX1_YjL zqT}M@9SCs@STi6`<`HJ1%#eFh&$5Pbq45C&!nUG2-;Gi=2is3xm#&+T??tk!!GrKEl_Pi(EDN($i+Hcz?1&3F^M^p<%i$SPp@9QW3pF z3x`n}XI)n@;KD4F>dAH9@23imALLX&!0$+?;$EcoJA?8eCR zv{@;KJ`z#qVH8D`TZ!2cQGYTE%QVaG`gH9p%4sv_YT_{Gk=$5?;6Ev|5>Ix`^bHI! ztHvW#b2{&xhG@oX9Qr%{?#?$GE(fQ?k^>Q;!;`ekzs!7cO3a+QmY!Z)pX@KlRaZec z1w)b3kJmqC1cTP3&3;8kObAVg9zJ{)(&2Cctz(Ql_!~3WDbdS@6L%TqFz*}A5$~5^ zwz|vACSunGe_SPU(>7H^vo8|4v(IZ-0{=yR|GY%^Il+-A9y=1(K`K4ZN+W1N)sy*w zti>t&PA>blAatRug?RACd|FVebL*{l!A%q7g6}x{VhqWN33jr zEAL(W7^oSX@2002DN4z{9Hw;j=X8)?oJ!Pff+sn3g5y3lrWKEjP7F6;AYkfG!*RP; zhZyO%-~3~sc+=#|J!*{3`b562Sboa5gPK|g9uz14+GDv0c%eoA02AZmt*`%#5I!?_ zz+2Bt=J;gi>~0&Ih;0W%|6_p9zLH-7MvN^KpZv5>C5X7bL0+S2LYhk~z7Ftrp3E-;B({371 zr58C;VPzh!u!U0R4rk)01Z)*&u|a7xfg0w_nO2;sI5@s{yG$JvUTu&@SITcv!TKt2 zW%5!3^WL^IeB#6OJKH7+_?VqNJT(-uo8$Dx?Y5{tv(0g_se@}xf_2bgX&uW{=5t~d%^5OWSCKhb0X@SJqk`VxCrx}yiLWoD(7+_jyrFkA!^Be!1=KC#n%v5(+t3k1rQ?T($5wTsRd7ZO)PCCmM_45p^)Vc}* zA9~DRnM~1CNf9}ATUuBWp@M&FsgrUEp@BGhvZZM$L~h*<+gD^yBfy{VR0Jlbm!Og5A$}G*rGKoCC`f%_}oLO&7NM5to`06HEZNUHv^36@~?>kx}7^;-au^q%GPgnlq~hz+ploMX22KV#%@5 zO87piSNG8nmI}q|OGBp`D;joNYM6+_T%F6E?e`MYq=tOB>bENq3dZv^Lfuc`dM{*) zD`Hz2jR`nu!I8kpMHoHu;>od55JZ6(Pcy3;DLOY+0RviV~|R!94k&>?U)&39=twzLwsJ2Z0_yiLMRz{W;x*7D&;Nl~?7 z|G+eW$pOs~>PU%@*OYRfX3Z47`%;#n^QX!z2m|ra%mErFyEBH~+Y`K;`BJBmb4S9k zRz}?cjnD%@n^rTUH&`_Foa0cYVAmbUxL}?YqRr-GKrz`#j;xQHTceIf7NR6a07vxx z8+cc0GwCaME_Z0W>&@|x!Gm`?))InN2;7gnuWeFgBbY1wP>760VK?BG4qMQk2*21& z7`QJ?zdIYK%|h&X%OXVhljy|N)W@w#I6woWhUVD!lc0Rg=_V!%3)#YCYIF|SK(h(| zt!!YC@l={4$+ld1qhDlTF*)!3_aPZLm6uuC{eYuE?!i_*)GPlDI_h3eIyAX0nuI8? z(%tWdQ5mkFp7QjaWm8huCwY40@<;$_ev}{ujc^+Goy<>*wNBdOZNY)#g{p{0SEo}5 zcNf;9X%Jywf1;DPm$EtAP;SKRY!U(fXnMws^rMw%mXhHyo=9{q%DJlX!JKo=+V#LQ z_Fk~6@=76iVBKzw1vXz{URQB+mK*~2yZM&I;W6pXR2BDe$nOQ;DZtj*8CWY&j#f$I z(iKY!eyZ%5GtAzBxyS4^MPEZzOdzq??8Uux!jJNLdcL0J$iAPf@MoamLEal$aIGKD zQnjx)o{M1rR4E31s-+eC^TixEwJR_F z4qj5xd`%#8DL8t>bp@Wt?fz_|?%sG>&7j)~IGaeT_nw_Q6s7$M5QN>ZG~`=%`wgi) zsy|z$ul|kd2`GS6$Atd620RU2*+21zCmct=1cECnwoJIy`!Vo$>QU!*)Sv*k=gxt&0e%WbL@!KDeiUXSxDmPY@NQ$O<}WsuV8sF5P^*_lk-4S`!4 zxyi)$GY1Ojc*)#R`R8#kp65(IUCcs8Un$;|x=*86_@)z0yWTuLUZk%2WAsIDI3~c@0b)C^`6+-a{P#9dfCVR)wxC8}#yYJpCC&(7x zs6vdT7_`{r1+s_1L;QyBA&=_8-%P4-FX8{*3dvQ$7Q*Z~syxmx>@O~&A&dIwgN&d- za;ro38m3!%>LS|JYt)l;(-7dS(Ti``78(XZM6(!_zvN>+QGx^S( zn`gzSc;vZsv=AkoocAVc#;dGi15Z_ZXLJI5>Dr}_c^U79JkqrsBF>yy;{iv@K3c_X zPF1~{bNVdtUGDLB4L;cO-3!k9+PCbC1HvM)(7df%N^hUlTV}*CM9_Usu9mm1b=1^) z<2;;=wrKL$8zi&qO^Bnb2MOXoR$j0uY;L(tR8xx(z>ycIWGn4LqkO2t38?lp#U44Z z8p#Z=*L_x?e0qK5>lStSXQv7uPUnOs?TYgq(!nq(N0W`{5MPcAeNl>G69*wP6q&2d zXi1Za+-L60@ND%l>mrG!qd3H%9eEJ0HaNO^5XEe=tiOVD635r7&~&9>)fVt@g!oAx ze^F+q=pK(m`H9OMYG#^Q^2MWGD2igT8A3Nf#5}R#+rR}PoujMa_zCXsFRFc-*N6I@ zT=)G3n1nrKrc*Ofc>CaKu{qhBYa(e1+;1-3^&Pw6&eYMu$T0Tw@-SLssXC6DzeN7V zL6WL9g}s_tjlC*1WXALiH|#KX4pl6pC6X8C0KBMq%_%94QP>+TzhKu^nH zE1~gQBTd1wpKTZWWBhm^>%W=+;XcyUUfy4e==+=Z+Ak*YLl_eo3nat^?j3{RqxAyH zGQID;l;>Oj1-$JuWIrX|r}y9bQf#2Ua7T#W+WF6%{|$bhMpPxQ^eFsC80!LyI=i+< zZ4oPg~pYPr95LNpPPA*~aW8w=`qt(}Q3U1u=!QQv>EZ4lCoo=q0EJW%< zHH0vmMN<)JW3|)1Zuk$a67p!dtc9}JnrzK(l$4t!!Q^shMDK&91ul=ab7yEBm)S!B ztM^!ySiCq+M(32Eg8Bz#Ny|oNf*ot{ki?j0ae)v-$v+O^SA_G4>btKA-sY4=K#Ow) zHXYi?bL7S!N1Mvg0xyQ)*D1fejKiGI8YgI>1wGIZ_)4}*WxoSIC-R)f6&#! zk&$=%j#ERFu;}dgt-xO?O5Gi?Vn7~eb|}(t6SNssW6#ktHs^-IS?GL79)y~TJKD;O zfE`XASWU$T5<#osi5_5Of1!oeRO5V<^PA1=aRK&@)0jLqFt_h5=8?|N%o zzR|dFdi}8dY9m+Zxkhm6C$)ym2kKUr)&255+f-$L2w8$sdP>8~jLS`4+mkWMD6Q6o z@rq(%4C8o=K+(ePc)b(ynlC)ny?PH3-lLk6Z%NVnp>`33=gO_-*rkw*2Og;n*Ocry z&yCk(7eCwYfIV&o|B-N|5jkZ3K8Mv7$_+y5n=e1%1lM}@#e$&bn z5}>kWU)Jqe%`vAI@Mtr3Z36=%WnKjUjy0b|TUDc{s@r&B6K2{uJW)6Jnj(2bu-$V@ zert*8s};+d=}4I9+ixnl(!rjkuSD$SFkEg7&bRyLy5bn#)R7w{O1SIjk~4<#;)+O9 zF|o%L{S-)o$qA8Y;3;H;kAP}azvHFJY~A7`81<{Cf15+ct4JcPw?9qT;XMQ+NX-#Q zUkS6;-JnDKGF?H7de+04j&vC`{N6!ohr$>r)eWM$(ur7d}FI8vg`G`p9F#2 zw-4tDIX>em#n9*UrTg3+IVz~ zxVOO=SG}yyZ&3w-p4c495~lU!`leaE7~TI~&y?xKUb2CdPlKrA0J6aFHl8JRyBuyD z!HiFv;ZG@ub7key%R})6c+0jgNoRi4&J^I)fWn2$QVpzPs*S@^Qe^>cYn8bYq=}m5 zT>A(D-7^wK0WHxIvqXhRQ;UaEzOBk%gnm58uawAlG6^VhV ztr8`R@zIslE5(>~RC5GQ7OYv@ouqSRpl?u8UrO(ij*LWiG@^`j9s|o^8(f|tt}$E_;aqK-p~ma~`MR_~lyAKv{4oq4*^`)*w2pE0-(S zk7setE;-<I&$4dhUBgt%7Y>6nPa2yg-)%<#V)UT0Tr_M8D`=AJ0ve;C%Zv)2n zfNGEt#p0DukF4=bUw-Y8mMG{mhVuf{?fq-s<>(m&2qG~a>_WMCMjVeei>m-~rXCC7e05Ff0gZvNxm2zq+x^D^|UZ3 zcq(Ev0#rnlP|sMNUW%SxgAP=d>F^l|EndbUj%9W^SA(lkemyn^1Q~nICpdaId$|Xn zZ+-YlD6HOP)QdqsLhD#UPcgjHsg+sJq=EArMvouY}^SOI8VGrgS ziGtj@%d?8G182RtJzSn(Q1hTad#;oY3SU2p^N$lrXx6$lGV)Al(G6|&F`(gLw5JGy zBszzf0jlDt9X&Rn3M0NX9F^|*x7lC!swv>6tk;IlUB*AZ_I3ha2-6V24k`~24_yPz zg6>Bm^$MHkC~}mE4+W2BY8C3LF6B_rc4JDI#>zZ}<)8%`3;_#-ozus5+wc#1TQLwz z@{k|SIxpqTHI?j{^38d1p8n=F_K_}6$>*b$E&aL-t7$JAIYbyRVGiuzw;&du^t$!L zkhe{p+uN~0e0kfcDbl6+x{k}$rex7@4Tt`u(_QY-IE^pRl$T5^2n!@2+uGMB&h?J6 zD_QaH^zV)7%B`aZ@^>eaAg#w&%&T~WWc40W^?Jb7W~AtFZr*z?Xi_ zNikS(;$m20>kzH?_UD^zvSeP6^C&}JQiqUtJ;Kpf)VQO|abtJb;{You%Ujcrm7AHa z*+P$bTcr*j0V5!?I*=Mo0%$Uv03Y8GoZv!UCjmkY9gYg2F_jtX%bXdbN0Z1VN^Wug z#1h^(E>nhVxXZ+i#4mz3W0khr*LO&ayY?9rM%jRgQ+D-+fA@EaS=>`CQcJA0m#W7A zzCRcD%2T!$TAFB+@bEA_NLsMBqMUyA8@r#;V4fhpBk!h{e4V`) z%byq--X~}{B*a2rNxmAYXNeuf|FO14uSpMx|W8ycX$I8>M`X?9!XyXJjI2 z06p(;;KdpY6=ns$T&1|JNZ#LK=Z@L@@g9-L)1N%Zq;Po`ABHl$KUH}uz?U>5LW9PQ zFjv^N#^_G8rmT2V108uI{PGHoL)BX1nl(VdT}J^aeR2N_M3Yea$4*ll|6U%E8UTIS z+zPz>tdkJx0lzG)qo$>e2h%fK9vJg;Fy(QmvhsOdt=cV=AU>8{BrJ3(LE2~Ah*DSM zo1GQlGLpMKb5lzH7#AgcPYK*IoAH@t3l}#j2|gV5I^dl2*Vfl)-3bX238616P(^-v z!`rqZn z=n;#W5*{pM!#!mD+DNiD8@W2~UnRaVqoVt5@B8B})@7Gb=hb|D2h64mH*ppxml~@c z+;%i7CdA`)pp*m~PR4g}NN?hE{v;_<&jIeu3LcKCqM4d^8Q}5Ovce5@#84v|WRYs^aAPP)NAy_cE z)wSH?kAgk`&T{G!Srl!wKh8#u@xSCz*Z=xhu^EdG`0?6%2DK#3V9SxKk&`>2v{L$p zA{OrfL14LBziQK6xb3X)sOVcgae=A4exBf{{zQEOi;xjH%*KV0S?-B|&+d~9K4YqH z95^ZTiJUL+QxFPHgza(Q=sC9}L^Q;F7Oz}h!jjmtS%-2A*S4kQcr9l~d9^?5Tv6=rwMb2`S5E~xY*pKzx092+)EJpvP#(qF-e=3QWt;=G zk$K0zp8>OE$neavM`=9YCg1csEANe?^&yWenMCqx8fe9$-YbQ7?}Gbq$VOkAzqr|e zetdBlk&@EZV+rWhI+qx15)G<(3xX>I)bya16ZxdSx&8n9Xq^%UCJKml$z0 +
+
+
+

© Copyright 2023, Yanhao "Max" Wei, + Zhenling Jiang .

+
+
+ +{% endblock %} diff --git a/docs/source/code/code.rst b/docs/source/code/code.rst new file mode 100644 index 0000000..902cd8d --- /dev/null +++ b/docs/source/code/code.rst @@ -0,0 +1,125 @@ +:html_theme.sidebar_secondary.remove: + +:parenttoc: True + +.. _code: + +Code +============ + +| + +You can find the Matlab (R2023b) files in |code_link| (still in beta version). + +.. |code_link| raw:: html + + this github repository + +Below are documentation for the files. We suggest you first read the example in :ref:`home`, which is an easier way to get an idea of how the code works. + +| + +Current settings on the range of data accepted by pNNE: + +\*Current settings are relatively restrictive as pNNE is still in beta stage. We can change these settings in the next version of pNNE if there are requests to do so. Please contact us if you want to see a setting broadened. + +.. role:: brown-text + +- :brown-text:`Sample size`: n ≥ 1000 number of consumers (or search sessions). +- :brown-text:`Number of options` per consumer: 15 ≤ J ≤ 35. +- Numbers of :brown-text:`product attributes`, :brown-text:`consumer attributes`, and :brown-text:`advertising attributes`: 2 ≤ p ≤ 8, 0 ≤ c ≤ 5, and 0 ≤ a ≤ 2. +- :brown-text:`Buy rate` (fraction of consumers who bought inside good) is between 0.5% and 70%. +- :brown-text:`Search rate` (fraction of consumers who went beyond free search) is between 1% and 80%. +- :brown-text:`Average number of searches` per consumer is between 1 and 5. + +| + +``trained_nne.mat`` + +This file stores the trained neural net as well as some settings. + +- ``nne``: a structure that stores the trained neural net, as well as some settings used in training, such as the largest number of product attributes allowed, the smallest sample size allowed, the range of search model parameters considered, etc. + +| + +``nne_estimate.m`` + +The main function to apply pNNE to your data. + +.. code-block:: console + + result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx, se=false, checks=true) + + +Inputs: + +- ``nne``: as described before, from trained_nne.mat. +- ``Y``: nJ by 2 matrix. Y(J*(i-1)+j, 1) indicates whether consumer i searched option j. Y(J*(i-1)+j, 2) indicates whether consumer i bought option j. +- ``Xp``: nJ by p matrix. Xp(J*(i-1)+j, :) stores the product attributes of option j for consumer i. +- ``Xa``: nJ by a matrix. Xa(J*(i-1)+j, :) stores the marketing attributes of option j for consumer i. +- ``Xc``: n by c matrix. Xc(i, :) stores the consumer attributes of consumer i. +- ``consumer_idx``: nJ by 1 vector. consumer_idx(J*(i-1)+1:J*i) = i. +- ``se=false``: optional input. Set to true to calculate bootstrap standard errors. +- ``checks=true``: optional input. Set to false to omit all sanity checks. + +Outputs: + +- ``result``: a table listing parameters and their estimates. If se=false, it has an additional column of standard errors. + +| + +``moments.m`` + +This function is used by nne_estimate.m. The function computes summary moments from data. These summary moments +are then fed into the neural net as inputs. + +| + +``regress_coef.m`` + +This function is used by moments.m. The function does ridge linear, logit, and multinomial logit regressions. +These regressions are applied to the data to produce some of the summary moments. + +| + +``mseLayer.m`` + +This function is a custom neural net layer used by our trained neural net. It is basically the same as +Matlab's built-in regressionLayer.m, except that it has some minor customization to better suit pNNE training. + +| + +``search_stat.m`` + +This function calculates some summary statistics of the data. It is used by nne_estimate.m to perform +a part of the data saneity checks. + +| + +``curve.mat`` + +This file stores the relation describing how log search cost affects reservation utility. + +- curve: a table that stores a grid of log search cost and corresponding reservation utility. + +| + +``search_model.m`` + +The function that codes the search model. This function is used in training but not in estimation. +We provide it for reference purpose. It is also useful if you want to conduct Monte Carlo experiments. + +.. code-block:: console + + Y = search_model(par, curve, Xp, Xa, Xc, consumer_idx) + +Inputs: + +- ``par``: vector of parameter value. First a+1 entries are α. Next c+1 entries are η. Last p entries are β. +- ``curve``: as described before, from curve.mat. +- ``Xp``, Xa, Xc, and consumer_idx: as described before. + +Outputs + +- ``Y``: as described above. Simulated search and purchase choices. + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..443fb33 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,43 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'pNNE' +copyright = "2023, Yanhao 'Max' Wei, Zhenling Jiang" +author = "Yanhao 'Max' Wei, Zhenling Jiang" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc' +] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' +html_static_path = ['_static'] +html_css_files = [ + 'custom.css', +] +html_logo = '_static/logo.png' + + +html_theme_options = { + "navbar_persistent":[], + "logo": { + "link": "https://pnnehome.github.io", + "text": "pNNE" + }, + "show_prev_next": False +} diff --git a/docs/source/conf.py.bk b/docs/source/conf.py.bk new file mode 100644 index 0000000..9fdc4eb --- /dev/null +++ b/docs/source/conf.py.bk @@ -0,0 +1,44 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'pNNE' +copyright = "2023, Yanhao 'Max' Wei, Zhenling Jiang" +author = "Yanhao 'Max' Wei, Zhenling Jiang" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinxcontrib.matlab', + 'sphinx.ext.autodoc' +] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' +html_static_path = ['_static'] +html_css_files = [ + 'custom.css', +] +html_logo = '_static/logo.png' + + +html_theme_options = { + "navbar_persistent":[], + "logo": { + "link": "https://pnnehome.github.io", + "text": "pNNE" + }, + "show_prev_next": False +} diff --git a/docs/source/contact/contact.rst b/docs/source/contact/contact.rst new file mode 100644 index 0000000..8056005 --- /dev/null +++ b/docs/source/contact/contact.rst @@ -0,0 +1,14 @@ +:html_theme.sidebar_secondary.remove: + +:parenttoc: True + +.. _contact: + +Contact +============ + +| + +Yanhao 'Max' Wei, Marshall School of Business, University of Southern California + +Zhenling Jiang, Wharton School, University of Pennsylvania diff --git a/docs/source/home/home.rst b/docs/source/home/home.rst new file mode 100644 index 0000000..4c74644 --- /dev/null +++ b/docs/source/home/home.rst @@ -0,0 +1,146 @@ +:html_theme.sidebar_secondary.remove: + +:parenttoc: True + +.. _home: + +Welcome to pNNE +=============== + +| + +This website provides a pre-trained estimator for consumer search model. + +The estimator is built as pNNE (pre-trained neural net estimator). The idea is to allocate the bulk of work to pre-training. So an end user can estimate the structural econometric model as easy as a reduced-form model. + +Below is a brief overview how to apply pNNE to your search data. For Matlab code and description, go to :ref:`code` page. + +| + +The main function to execute estimation is ``nne_estimate.m``, as shown below. + +.. code-block:: console + + result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx) + +The required inputs: (i) ``nne`` stores the trained neural net and some pre-defined settings, available from the file ``trained_nne.mat``, and (ii) ``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index`` store your data. + +The output: ``result`` is a table storing the parameter estimate of a standard consumer search model. + +Below shows an example. The total execution time is 0.78 sec on a laptop, including overheads such as some data sanity checks. + +.. code-block:: console + + >> load('trained_nne.mat', 'nne') + >> tic + result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx); + toc + Elapsed time is 0.784314 seconds. + >> result + result = 8×2 table + name val + ---------- ------- + "\alpha_0" -6.4546 + "\alpha_1" -0.11333 + "\eta_0" 5.929 + "\eta_1" -0.048687 + "\eta_2" 0.22004 + "\eta_3" 0.052894 + "\beta_1" 0.25836 + "\beta_2" -0.53811 + +The rest of this page gives more details on the search model, how to format data (``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index``), and how to get standard errors. + +| + +1) The search model +------------------- +The econometric model to be estimated is a standard sequential search model. Each consumer faces J products (or options). She decides which options to search and which option to buy. Searching a product incurs a search cost but also reveals some utility for the product. + +A typical setting for the model is consumer search online, where a "consumer" is a "search session." A consumer is shown a list of products. Clicking a product for more information is a search. After searching, the consumer may buy one product or an outside good. The list page usually shows some product attributes (e.g., review rating) that affect consumer utility for products. In addition, there may be some consumer attributes (e.g., past spending, visit time) that affect consumer outside utility. There may also be advertising attributes (e.g., ranking in the list) that affect search costs. + +There are three sets of parameters: :math:`\beta` describes how product attributes affect utility, :math:`\eta` describes how consumer attributes affect outside utility, and :math:`\alpha` describes how advertising attributes affect search costs. + +A free search is endowed, to accommodate most data where consumer searches at least once. + +| + +2) Data format +----------------- + +Oraganize data into five arrays: ``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index``. Respectively: ``Xp`` stores product attributes; ``Xa`` stores advertising attributes; and ``Xc`` stores consumer attributes; ``Y`` stores search and purchase outcomes; ``consumer_index`` identifies consumers. + +In the example below, there are n=10,000 consumers (or search sessions) and each consumer has J=20 options for search. There are 2 product attributes, 1 advertising attribute, and 3 consumer attributes. + +.. code-block:: console + + >> whos Xp Xa Xc Y consumer_idx + + Name Size Bytes Class Attributes + + Xa 200000x1 1600000 double + Xc 10000x3 240000 double + Xp 200000x2 3200000 double + consumer_idx 200000x1 1600000 double + Y 200000x2 3200000 double + +Below previews the first rows of ``Xp``, ``Xa``, ``Y``, and ``consumer_index``. Variable ``Y`` has two columns; the 1st column indicates search and 2nd column indicates purchase. We see that the first consumer searched option 1, 3, 4, and 8. She bought option 3. + +.. code-block:: console + + >> table(consumer_idx, Y, Xp, Xa) + ans = 200000×4 table + consumer_idx Y Xp Xa + ____________ ______ ______________ __ + 1 1 0 4 0.67743 0 + 1 0 0 5 1.1052 0 + 1 1 1 1 -0.24542 0 + 1 1 0 5 0.78452 0 + 1 0 0 4 0.10519 0 + 1 0 0 5 0.068463 0 + 1 0 0 4 0.35691 1 + 1 1 0 5 0.61307 0 + 1 0 0 3 1.1809 1 + 1 0 0 5 0.91391 0 + 1 0 0 5 0.054537 0 + 1 0 0 3 1.0015 0 + 1 0 0 5 0.73938 0 + 1 0 0 3 -0.020808 0 + 1 0 0 5 0.23587 0 + 1 0 0 5 0.43236 1 + 1 0 0 5 -0.040968 0 + 1 0 0 5 0.4916 0 + 1 0 0 2 0.96498 0 + 1 0 0 2 0.46767 0 + 2 1 0 3 0.72159 1 + 2 0 0 5 -0.39847 0 + 2 0 0 5 0.73669 1 + : : : : + +Consumer attributes ``Xc``, not displayed here, should have the same number of rows as the number of consumers (10,000 in this example). + +If data did not feature advertising attributes, we'd let ``Xa`` be 200,000 by 0 (no columns). If data did not feature consumer attributes, we'd let ``Xc`` be 10,000 by 0. + +| + +3) Bootstrap standard errors +---------------------------- +The nne_estimate function has standard error calculation built in. Simply add ``"se = true"`` option as shown below. The output will include an additional column of standard errors. The calculation bootstraps 50 samples so execution time will be longer, but it can take advantage of parallel computing toolbox if installed. + +.. code-block:: console + + >> result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx, se = true); + >> result + result = 8×3 table + + name val se + __________ _________ ________ + "\alpha_0" -6.4546 0.071848 + "\alpha_1" -0.11333 0.044997 + "\eta_0" 5.929 0.061318 + "\eta_1" -0.048687 0.011513 + "\eta_2" 0.22004 0.029282 + "\eta_3" 0.052894 0.023437 + "\beta_1" 0.25836 0.004951 + "\beta_2" -0.53811 0.011032 + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..94b9cf3 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,157 @@ +:html_theme.sidebar_secondary.remove: + +.. pNNE documentation master file, created by + sphinx-quickstart on Mon Sep 18 12:08:20 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. toctree:: + :maxdepth: 3 + +.. toctree:: + :hidden: + + Home + Code + Contact + +Welcome to pNNE +=============== + +| + +This website provides a pre-trained estimator for consumer search model. + +The estimator is built as pNNE (pre-trained neural net estimator). The idea is to allocate the bulk of work to pre-training. So an end user can estimate the structural econometric model as easy as a reduced-form model. + +Below is a brief overview how to apply pNNE to your search data. For Matlab code and description, go to :ref:`code` page. + +| + +The main function to execute estimation is ``nne_estimate.m``, as shown below. + +.. code-block:: console + + result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx) + +The required inputs: (i) ``nne`` stores the trained neural net and some pre-defined settings, available from the file ``trained_nne.mat``, and (ii) ``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index`` store your data. + +The output: ``result`` is a table storing the parameter estimate of a standard consumer search model. + +Below shows an example. The total execution time is 0.78 sec on a laptop, including overheads such as some data sanity checks. + +.. code-block:: console + + >> load('trained_nne.mat', 'nne') + >> tic + result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx); + toc + Elapsed time is 0.784314 seconds. + >> result + result = 8×2 table + name val + ---------- ------- + "\alpha_0" -6.4546 + "\alpha_1" -0.11333 + "\eta_0" 5.929 + "\eta_1" -0.048687 + "\eta_2" 0.22004 + "\eta_3" 0.052894 + "\beta_1" 0.25836 + "\beta_2" -0.53811 + +The rest of this page gives more details on the search model, how to format data (``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index``), and how to get standard errors. + +| + +1) The search model +------------------- +The econometric model to be estimated is a standard sequential search model. Each consumer faces J products (or options). She decides which options to search and which option to buy. Searching a product incurs a search cost but also reveals some utility for the product. + +A typical setting for the model is consumer search online, where a "consumer" is a "search session." A consumer is shown a list of products. Clicking a product for more information is a search. After searching, the consumer may buy one product or an outside good. The list page usually shows some product attributes (e.g., review rating) that affect consumer utility for products. In addition, there may be some consumer attributes (e.g., past spending, visit time) that affect consumer outside utility. There may also be advertising attributes (e.g., ranking in the list) that affect search costs. + +There are three sets of parameters: :math:`\beta` describes how product attributes affect utility, :math:`\eta` describes how consumer attributes affect outside utility, and :math:`\alpha` describes how advertising attributes affect search costs. + +A free search is endowed, to accommodate most data where consumer searches at least once. + +| + +2) Data format +----------------- + +Oraganize data into five arrays: ``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index``. Respectively: ``Xp`` stores product attributes; ``Xa`` stores advertising attributes; and ``Xc`` stores consumer attributes; ``Y`` stores search and purchase outcomes; ``consumer_index`` identifies consumers. + +In the example below, there are n=10,000 consumers (or search sessions) and each consumer has J=20 options for search. There are 2 product attributes, 1 advertising attribute, and 3 consumer attributes. + +.. code-block:: console + + >> whos Xp Xa Xc Y consumer_idx + + Name Size Bytes Class Attributes + + Xa 200000x1 1600000 double + Xc 10000x3 240000 double + Xp 200000x2 3200000 double + consumer_idx 200000x1 1600000 double + Y 200000x2 3200000 double + +Below previews the first rows of ``Xp``, ``Xa``, ``Y``, and ``consumer_index``. Variable ``Y`` has two columns; the 1st column indicates search and 2nd column indicates purchase. We see that the first consumer searched option 1, 3, 4, and 8. She bought option 3. + +.. code-block:: console + + >> table(consumer_idx, Y, Xp, Xa) + ans = 200000×4 table + consumer_idx Y Xp Xa + ____________ ______ ______________ __ + 1 1 0 4 0.67743 0 + 1 0 0 5 1.1052 0 + 1 1 1 1 -0.24542 0 + 1 1 0 5 0.78452 0 + 1 0 0 4 0.10519 0 + 1 0 0 5 0.068463 0 + 1 0 0 4 0.35691 1 + 1 1 0 5 0.61307 0 + 1 0 0 3 1.1809 1 + 1 0 0 5 0.91391 0 + 1 0 0 5 0.054537 0 + 1 0 0 3 1.0015 0 + 1 0 0 5 0.73938 0 + 1 0 0 3 -0.020808 0 + 1 0 0 5 0.23587 0 + 1 0 0 5 0.43236 1 + 1 0 0 5 -0.040968 0 + 1 0 0 5 0.4916 0 + 1 0 0 2 0.96498 0 + 1 0 0 2 0.46767 0 + 2 1 0 3 0.72159 1 + 2 0 0 5 -0.39847 0 + 2 0 0 5 0.73669 1 + : : : : + +Consumer attributes ``Xc``, not displayed here, should have the same number of rows as the number of consumers (10,000 in this example). + +If data did not feature advertising attributes, we'd let ``Xa`` be 200,000 by 0 (no columns). If data did not feature consumer attributes, we'd let ``Xc`` be 10,000 by 0. + +| + +3) Bootstrap standard errors +---------------------------- +The nne_estimate function has standard error calculation built in. Simply add ``"se = true"`` option as shown below. The output will include an additional column of standard errors. The calculation bootstraps 50 samples so execution time will be longer, but it can take advantage of parallel computing toolbox if installed. + +.. code-block:: console + + >> result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx, se = true); + >> result + result = 8×3 table + + name val se + __________ _________ ________ + "\alpha_0" -6.4546 0.071848 + "\alpha_1" -0.11333 0.044997 + "\eta_0" 5.929 0.061318 + "\eta_1" -0.048687 0.011513 + "\eta_2" 0.22004 0.029282 + "\eta_3" 0.052894 0.023437 + "\beta_1" 0.25836 0.004951 + "\beta_2" -0.53811 0.011032 + diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..04d1ffb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,3 @@ +sphinx==7.2.6 +pydata-sphinx-theme==0.14.0 +sphinxcontrib-matlabdomain \ No newline at end of file