many changes

.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

.gitignore

@@ -0,0 +1,4 @@
+/docs/build
+build/
+.vscode/
+.DS_Store

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.

docs/CNAME

@@ -0,0 +1 @@
+www.pnne.net

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)

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

docs/source/_static/CNAME

@@ -0,0 +1 @@
+www.pnne.net

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
+}

docs/source/_templates/layout.html

@@ -0,0 +1,18 @@
+{# _templates/layout.html #}
+
+{% extends "!layout.html" %}
+
+{% block button %}
+{% endblock %}
+
+{% block footer %}
+<footer class="bd-footer">
+  <div class="bd-footer__inner bd-page-width">
+    <div class="footer-items__start">    
+        <div class="footer-item">
+          <p>© Copyright 2023, <a href="https://sites.google.com/site/yanhaomaxwei/" target="_blank">Yanhao "Max" Wei</a>, 
+                                <a href="https://jiangzhenling.com/" target="_blank">Zhenling Jiang </a>.</p>
+    </div>                      
+  </div>
+</footer>
+{% endblock %}

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
+
+   <a href="https://github.com/pnnehome/code_matlab" target="_blank">this github repository</a>
+
+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.
+

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
+}

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
+}

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