fixes for major update in 05-2024

docs/source/code/code.rst

@@ -9,26 +9,26 @@ Code
 
 You can find the Matlab (R2024a) files in this `GitHub directory <https://github.com/pnnehome/code_matlab>`_ (still in beta version).
 
-Below are documentation for the files. However, we suggest first reading the example in :ref:`home <home>`, which is an easier way to get an idea of how the code works.
+Below is documentation for the files. However, we suggest first reading the example in :ref:`home <home>`, which is an easier way to get a general idea of how the code works.
 
 Range of data accepted:
 '''''''''''''''''''''''''
 
 .. role:: note-text
 
-Below list the current settings on the data dimensions accepted by pre-trained NNE. (:note-text:`Note\: current settings are relatively restrictive as pre-trained NNE is still in beta stage. We can change these settings in the next version of pre-trained NNE if there are requests. Please feel free to contact us.`)
+Below list the current settings on the data dimensions accepted by the main file ``nne_estimate.m``. (:note-text:`Note\: current settings are relatively restrictive as pre-trained NNE is still in beta stage. We can change these settings in the next version of pre-trained NNE if there are requests. Please feel free to contact us.`)
 
-- **Sample size**: :math:`n` ≥ 1000 consumers (or search sessions).
-- **Number of options**: 15 ≤ :math:`J` ≤ 35.
-- Number of **product attributes** is between 2 and 8. 
-- Number of **consumer attributes** is between 0 and 5. 
-- Number of **advertising attributes** is between 0 and 2.
+- **Sample size**: :math:`n` ≥ 1000 consumers (or search sessions). **Number of options**: 15 ≤ :math:`J` ≤ 35.
+- Number of **product attributes** is ≥ 2 and ≤ 8. 
+- Number of **consumer attributes** is ≤ 5. 
+- Number of **advertising attributes** is ≤ 2.
 
 In addition, the NNE is pre-trained on data with following characteristics. If your data's characterstics fall outside these ranges, the pre-trained NNE may not work as intended.
 
-- **Buy rate** (fraction of consumers who bought inside good) is between 0.5% and 70%. 
-- **Search rate** (fraction of consumers who went beyond free search) is between 1% and 80%. 
-- **Average number of searches** per consumer is between 1 and 5.
+- **Buy rate** (fraction of consumers who bought inside good) is 0.5% ~ 70%. 
+- **Search rate** (fraction of consumers who went beyond free search) is 1% ~ 80%. 
+- **Average number of searches** per consumer is 1 ~ 5.
+
 
 Description of files 
 '''''''''''''''''''''''
@@ -39,7 +39,7 @@ Description of files
 
 This file stores the trained neural net as well as pre-defined settings.
 
-- ``nne``: a structure that stores the trained neural net, as well as some settings used in training, such as the smallest sample size, the range on the number of product attributes, the prior of search model parameters, etc.
+- ``nne``: a structure that stores the trained neural net, as well as some settings used in training, such as the range of data dimensions and the prior of search model parameters.
 
 
 ``nne_estimate.m`` 
@@ -49,7 +49,7 @@ This is the main function that applies pre-trained NNE to your data.
 
 .. code-block:: console
 
-    result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx, se=false, checks=true)
+    result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx, se = false, checks = true)
 
 Inputs:
 
@@ -59,12 +59,12 @@ Inputs:
 - ``Xa``: a matrix with :math:`nJ` rows. The :math:`((i-1)J+j)`\th row stores the advertising attributes of product :math:`j` for consumer :math:`i`.
 - ``Xc``: a matrix with :math:`n` rows. The :math:`i`\th row stores the consumer attributes of consumer :math:`i`.
 - ``consumer_idx``: a column vector with :math:`nJ` values. The :math:`((i-1)J+j)`\th value equals :math:`i`.
-- ``se=false``: optional input. Set it to "true" to calculate bootstrap standard errors.
-- ``checks=true``: optional input. Set it to "false" to omit all sanity checks.
+- ``se = false``: optional input. Set it to "true" to calculate bootstrap standard errors.
+- ``checks = true``: optional input. Set it to "false" to omit all sanity checks.
 
 Outputs:
 
-- ``result``: a table showing parameter estimate and bootstrap standard errors (if ``se=true``).
+- ``result``: a table showing parameter estimate and bootstrap standard errors (if ``se = true``).
 
 
 ``moments.m`` 
@@ -74,7 +74,7 @@ This function is used by ``nne_estimate.m``. It computes moments from data. The
 
 ``reg_logit.m`` 
 """"""""""""""""""""""""
-This function is used by ``moments.m``. It performs ridge logit regression or multinomial logit regression. It runs faster than Matlab built-in regression and significantly sped up pre-training. The faster execution is less important when applying the pre-trained NNE. Nevertheless, we use it when applying the pre-trained NNE.
+This function is used by ``moments.m``. It performs ridge logit regression or ridge multinomial-logit regression. It runs faster than Matlab built-in regressions and significantly sped up pre-training. The faster execution is less important when applying the pre-trained NNE. Nevertheless, we make use of it when applying the pre-trained NNE.
 
 
 ``reg_linear.m`` 
@@ -91,14 +91,13 @@ This function calculates some summary statistics of the data. It is used by ``nn
 """"""""""""""""""""""""
 This function winsorizes the far outliers in data. We suggest applying it to your data before applying the pre-trained NNE. For example, Xp = winsorize(Xp).
 
-
 |
 
 :note-text:`Note\: The following files are not required in applying the pre-trained NNE. They are provided nevertheless for reference purposes.`
 
 ``curve.mat``
 """"""""""""""""""""""""
-This file stores a lookup table for the relation between search cost and reservation utility. This relation is useful when we compute the optimal consumer choices under the sequential search model.
+This file stores a lookup table for the relation between search cost and reservation utility. This relation is useful when we compute the optimal consumer choices in the sequential search model.
 
 
 ``search_model.m``

docs/source/data/data.rst

@@ -7,7 +7,7 @@
 Data
 ============
 
-We share four sample datasets on which one can apply the pre-trained NNE.  You can find them in Matlab formats at `GitHub directory <https://github.com/pnnehome/code_matlab>`_. These datasets are used in Wei and Jiang (2024b) (see `papers`_) and come from sources with direct public access. More detailed descriptions of these datasets can be found in the paper too.
+We share four sample datasets on which one can apply the pre-trained NNE.  You can find them in Matlab formats at `GitHub directory <https://github.com/pnnehome/code_matlab>`_. These datasets are used in :ref:`Wei and Jiang (2024b) <papers_data>` and come from sources with direct public access. More detailed descriptions of these datasets can be found in the paper too.
 
 
 Information of the datasets
@@ -38,6 +38,8 @@ This dataset consists of the search sessions made on the mobile channel from the
 
 |
 
+.. _papers_data:
+
 Papers
 ---------------
 

docs/source/index.rst

@@ -23,11 +23,9 @@ Welcome to Pre-trained NNE
 
 (:note-text:`Note\: This website is still under construction. Last update on May 20, 2024.`)
 
-This is the companion website for Wei and Jiang (2024b) (see `papers`_). The website provides a pre-trained estimator for a consumer search model used in economics & marketing. The idea is to allocate the bulk of work to pre-training. So an end user can estimate a structural econometric model as easy as a reduced-form model.
+This is the companion website for :ref:`Wei and Jiang (2024b) <papers_home>`. It provides a pre-trained estimator for a consumer search model used in economics & marketing. It is based on a neural net that recognizes search model parameters from data patterns. We call it pre-trained neural net estimator (NNE). The approach extends :ref:`Wei and Jiang (2024a) <papers_home>` and is generally applicable to structural models. But here we focus on a consumer search model.
 
-The estimator is based on a neural net that recognizes structural parameters from data patterns. We call it pre-trained neural net estimator (NNE). The approach extends Wei and Jiang (2024a) (see `papers`_) and it is generally applicable to many structural models. But here we focus on a consumer search model.
-
-Below is a brief overview of applying pre-trained NNE to your search data. For Matlab code and documentation, see :ref:`code <code>` page.
+Below is a brief overview of applying pre-trained NNE to your search data. For Matlab code and documentation, see :ref:`code <code>` page. For examples to try out, see :ref:`data <data>` page.
 
 Overview
 ------------------
@@ -40,7 +38,7 @@ The main function to execute estimation is ``nne_estimate.m``, as shown below.
 
 Explanation for inputs and output: 
 
-* Input ``nne`` stores the trained neural net and some pre-defined settings, available from the file ``trained_nne.mat``;
+* Input ``nne`` stores the trained neural net and some pre-defined settings, available from the file ``trained_nne.mat``.
 * Inputs ``Xp``, ``Xa``, ``Xc``, ``Y``, and ``consumer_index`` store your data (more on them below).
 * Output ``result`` is a table storing the parameter estimate for the search model.
 
@@ -68,28 +66,30 @@ Below shows an example. The total execution time is 0.78 sec on a laptop. The ti
 
 The rest of this page gives more details on the search model, how to format your data, and how to get standard errors.
 
+
 1) The search model
 """"""""""""""""""""""
-Sequential search models have been commonly applied in economics and marketing. Each consumer faces :math:`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 that product.  The search model estimated by the pre-trained NNE here is a standard one. The exact specification of it is given in Wei and Jiang (2024b) (see `papers`_). Here we give a high-level description.
+Sequential search models have been commonly applied in economics & marketing. A consumer faces :math:`J` products (or options). She decides which options to search and which option to buy. Searching an option incurs a search cost but also reveals some utility for that option.  The search model estimated by the pre-trained NNE here is a standard one. The exact specification of it is given in :ref:`Wei and Jiang (2024b) <papers_home>`. Here we give a high-level description:
+
+* A consumer searches and chooses among a list of products, plus an outside good. A free search is endowed (because in most data each consumer searches at least once).
+* The list shows some **product attributes** that affect consumer's utility for products. The effects of these attributes are described by coefficients :math:`\beta`.
+* There may be some **consumer attributes** that affect consumer's outside utility. The effects of these attributes are described by coefficients :math:`\eta`.
+* There may also be **advertising attributes** that affect search costs (but not utility). The effects of these attributes are described by coefficients :math:`\alpha`. 
 
-* A consumer searches and chooses among a list of products, plus an outside good. A free search is endowed, because in most data each consumer searches at least once.
-* The list shows some **product attributes** that affect consumer's utility for products. How each product attribute affects utility is described by coefficients :math:`\beta`.
-* There may be some **consumer attributes** that affect consumer's outside utility. How each consumer attribute affects outside utility is described by coefficients :math:`\eta`.
-* There may also be **advertising attributes** (e.g., ranking in the list) that affect search costs. How each advertising attribute affects search cost is described by coefficients :math:`\alpha`. 
+For a survey on empirical applications of search models, see :ref:`Ursu, Steiler, & Honka (2022) <papers_home>`.
 
-For a survey on empirical applications of search models, see Ursu, Steiler, & Honka (2022) (see `papers`_). Optimal search behavior was studied in Weitzman (1979) (see `papers`_).
 
 2) Data format
 """"""""""""""""""""""
 To use the pre-trained NNE, organize data into five arrays: ``Y``, ``Xp``, ``Xa``, ``Xc``, and ``consumer_index``. Respectively, they store search & purchase outcomes, product attributes, advertising attributes, consumer attributes, and consumer identifiers.
 
-Below, we illustrate with an example of shopping on an online retailer. There are :math:`n` = 10,000 consumers and :math:`J` = 15 options per consumer. Below previews the first rows of  ``consumer_index``, ``Y``, ``Xp``, and ``Xa``. We see:
+Below, we illustrate with an example of shopping at an online retailer. There are :math:`n` = 10,000 consumers and :math:`J` = 15 options per consumer. Below shows a preview of the top rows of  ``consumer_index``, ``Y``, ``Xp``, and ``Xa``. Note there are :math:`nJ` rows in total. We see:
 
-* ``consumer_idx`` is :math:`nJ` by 1. Each row indicates the consumer (or search session).
+* ``consumer_idx`` is a column vector. Each value indicates the consumer.
 * ``Y`` has two columns; the 1st column indicates search and 2nd column indicates purchase. In this example, we see the first consumer searched the 1st, 3rd, and 8th options. She bought the 3rd option. 
 * ``Xp`` stores product attributes. In this example, there are two product attributes: a 1-5 product rating and log price. 
 * ``Xa`` stores advertising attributes. In this example, there is one advertising attribute: whether the product is highlighted on the retailer website.
-* ``Xc`` stores consumer attributes. It is not displayed below. It has only :math:`n` rows, one for each consumer.
+* ``Xc`` stores consumer attributes. It is not previewed below. It has only :math:`n` rows, one for each consumer.
 
 .. code-block:: console
 
@@ -117,7 +117,7 @@ Below, we illustrate with an example of shopping on an online retailer. There ar
            2        0    0    5      0.73669    1 
          :            :             :           : 
 
-Below show the dimensions of each variable. If your data did not feature advertising or consumer attributes, you can let ``Xa`` or ``Xc`` be an empty matrix.
+Below show the dimensions of each variable. Outside this example, if your data do not feature advertising or consumer attributes, you can let ``Xa`` or ``Xc`` be an empty matrix.
 
 .. code-block:: console
 
@@ -132,30 +132,11 @@ Below show the dimensions of each variable. If your data did not feature adverti
        Y                 150000x2         2400000        double 
 
 
-3) Reading results
+3) Bootstrap standard errors
 """"""""""""""""""""""""""""""
-Below reproduces the parameter estimate shown earlier (in `Overview`_). We see :math:`\alpha_1` is negative, indicating that the products highlighted by the retailer enjoy a lower search cost (so they are more likely to be searched). We see :math:`\beta_1` is positive, indicating that consumer utility increases with product rating. We see :math:`\eta_1` is negative, indicating that the outside utility decreases with the first consumer attribute.
+The ``nne_estimate.m`` 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 somewhat longer, but it can take advantage of parallel computing toolbox if installed.
 
-.. code-block:: console
-
-   >> load('trained_nne.mat', 'nne')
-   >> result = nne_estimate(nne, Y, Xp, Xa, Xc, consumer_idx)
-   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
-
-
-4) Bootstrap standard errors
-""""""""""""""""""""""""""""""
-The ``nne_estimate.m`` 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 somewhat longer, but it can take advantage of parallel computing toolbox if installed.
+We see :math:`\alpha_1` is negative, indicating that the products highlighted by the retailer enjoy a lower search cost (so they are more likely to be searched). We see :math:`\beta_1` is positive, indicating that consumer utility increases with product rating. We see :math:`\eta_1` is negative, indicating that the outside utility decreases with the first consumer attribute.
 
 .. code-block:: console
 
@@ -178,15 +159,15 @@ The ``nne_estimate.m`` function has standard error calculation built in. Simply
 
 |
 
+.. _papers_home:
+
 Papers
 ---------------
 
 Wei, Yanhao 'Max' and Zhenling Jiang (2024a), "Estimating Parameters of Structural Models with Neural Networks," Accepted at Marketing Science. 
 
 Wei, Yanhao 'Max' and Zhenling Jiang (2024b), "A Pre-trained Estimator for Consumer Search Models."
 
-Weitzman, Martin L. (1979): “Optimal Search for the Best Alternative,” Econometrica.
-
 Ursu, Raluca, Stephan Steiler, and Elisabeth Honka (2022), "The Sequential Search Model: A Framework for Empirical Research." 
 
 |