updates to docs

Author: jbiggsets

doc/conf.py

@@ -58,7 +58,7 @@
 
 # General information about the project.
 project = 'factor_analyzer'
-copyright = '2017, Jeremy Biggs'
+copyright = '2019, Jeremy Biggs'
 author = 'Jeremy Biggs'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -183,8 +183,6 @@
      'Miscellaneous'),
 ]
 
-
-
 # -- Options for Epub output ----------------------------------------------
 
 # Bibliographic Dublin Core info.
@@ -205,7 +203,5 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {'https://docs.python.org/': None}

doc/factor_analyzer.rst

@@ -15,6 +15,13 @@ factor\_analyzer package
     :undoc-members:
     :show-inheritance:
 
+:py:mod:`factor\_analyzer\.confirmatory\_factor\_analyzer` Module
+--------------------------------------------------------
+.. automodule:: factor_analyzer.confirmatory_factor_analyzer
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 :py:mod:`factor\_analyzer\.rotator` Module
 --------------------------------------------------------
 .. automodule:: factor_analyzer.rotator

doc/index.rst

@@ -6,45 +6,89 @@
 Welcome to the FactorAnalyzer documentation!
 ==============================================
 
-This is Python module to perform exploratory factor analysis, with optional varimax and promax rotations. Estimation can be performed using a minimum residual (minres) solution, or maximum likelihood estimation (MLE).
-
-Portions of this code are ported from the excellent R library psych.
+This is a Python module to perform exploratory and factor analysis (EFA), with several 
+optional rotations. It also includes a class to perform confirmatory factor
+analysis (CFA), with certain pre-defined constraints. In expoloratory factor analysis,
+factor extraction can be performed using a variety of estimation techniques. The
+``factor_analyzer`` package allows users to perfrom EFA using either (1) a minimum
+residual (MINRES) solution, (2) a maximum likelihood (ML) solution, or (3) a principal
+factor solution. However, CFA can only be performe using an ML solution.
+
+Both the EFA and CFA classes within this package are fully compatible with `scikit-learn`.
+Portions of this code are ported from the excellent R library `psych`, and the `sem`
+package provided inspiration for the CFA class.
 
 Description
-==================
-
-Exploratory factor analysis (EFA) is a statistical technique used to identify latent relationships among sets of observed variables in a dataset. In particular, EFA seeks to model a large set of observed variables as linear combinations of some smaller set of unobserved, latent factors.
-
-The matrix of weights, or factor loadings, generated from an EFA model describes the underlying relationships between each variable and the latent factors. Typically, a number of factors (K) is selected such that is substantially smaller than the number of variables. The factor analysis model can be estimated using a variety of standard estimation methods, including but not limited to OLS, minres, or MLE.
-
-This package includes a stand-alone Python module with a ``FactorAnalyzer()`` class. The class includes an ``analyze()`` method that allows users to perform factor analysis using either minres or MLE, with optional rotations on the factor loading matrices. The package also offers a stand-alone ``Rotator()`` class to perform common rotations on an unrotated loading matrix.
-
-The ``factor_analyzer`` package offers the following rotation methods:
-
-* The **varimax** (orthogonal)
-
-* The **promax** (oblique)
-
-* The **quartimax** (orthogonal)
-
-* The **quartimin** (oblique)
-
-* The **obliimax** (orthogonal)
-
-* The **oblimin** (oblique)
-
-* The **obliimax** (orthogonal)
-
-* The **equamax** (orthogonal)
-
-This package includes a stand-alone Python module with a ``FactorAnalyzer()`` class. The class includes an ``analyze()`` method that allows users to perform factor analysis using either minres or MLE, with optional promax or varimax rotations on the factor loading matrices. The package also offers a stand-alone ``Rotator()`` class to perform common rotations on an unrotated loading matrix.
+============
+
+Exploratory factor analysis (EFA) is a statistical technique used to
+identify latent relationships among sets of observed variables in a
+dataset. In particular, EFA seeks to model a large set of observed
+variables as linear combinations of some smaller set of unobserved,
+latent factors. The matrix of weights, or factor loadings, generated
+from an EFA model describes the underlying relationships between each
+variable and the latent factors.
+
+Confirmatory factor analysis (CFA), a closely associated technique, is
+used to test an a priori hypothesis about latent relationships among sets
+of observed variables. In CFA, the researcher specifies the expected pattern
+of factor loadings (and possibly other constraints), and fits a model according
+to this specification.
+
+Typically, a number of factors (K) in an EFA or CFA model is selected
+such that it is substantially smaller than the number of variables. The
+factor analysis model can be estimated using a variety of standard
+estimation methods, including but not limited MINRES or ML.
+
+Factor loadings are similar to standardized regression coefficients, and
+variables with higher loadings on a particular factor can be interpreted
+as explaining a larger proportion of the variation in that factor. In the
+case of EFA, factor loading matrices are usually rotated after the factor
+analysis model is estimated in order to produce a simpler, more interpretable
+structure to identify which variables are loading on a particular factor.
+
+Two common types of rotations are:
+
+1. The **varimax** rotation, which rotates the factor loading matrix so
+   as to maximize the sum of the variance of squared loadings, while
+   preserving the orthogonality of the loading matrix.
+
+2. The **promax** rotation, a method for oblique rotation, which builds
+   upon the varimax rotation, but ultimately allows factors to become
+   correlated.
+
+This package includes a ``factor_analyzer`` module with a stand-alone
+``FactorAnalyzer`` class. The class includes ``fit()`` and ``transform()`` 
+methods that enable users to perform factor analysis and score new data
+using the fitted factor model. Users can also perform optional otations
+on a factor loading matrix using the ``Rotator`` class.
+
+The following rotation options are available in both ``FactorAnalyzer`` 
+and ``Rotator``:
+
+    (a) varimax (orthogonal rotation)
+    (b) promax (oblique rotation)
+    (c) oblimin (oblique rotation)
+    (d) oblimax (orthogonal rotation)
+    (e) quartimin (oblique rotation)
+    (f) quartimax (orthogonal rotation)
+    (g) equamax (orthogonal rotation)
+
+In adddition, the package includes a ``confirmatory_factor_analyzer``
+module with a stand-alone ``ConfirmatoryFactorAnalyzer`` class. The
+class includes ``fit()`` and ``transform()``  that enable users to perform
+confirmatory factor analysis and score new data using the fitted model.
+Performing CFA requires users to specify in advance a model specification
+with the expected factor loading relationships. This can be done using
+the ``ModelSpecificationParser`` class.
 
 Requirements
 ==================
-- Python 3.4 or higher
-- ``numpy``
-- ``pandas``
-- ``scipy``
+-  Python 3.4 or higher
+-  ``numpy``
+-  ``pandas``
+-  ``scipy``
+-  ``scikit-learn``
 
 Installation
 ==================
@@ -55,14 +99,16 @@ You can install this package via ``pip`` with:
 
 Alternatively, you can install via ``conda`` with:
 
-``$ conda install -c desilinguist factor_analyzer``
+``$ conda install -c ets factor_analyzer``
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    factor_analyzer
 
+   confirmatory_factor_analyzer
+
    rotator