updating readme, tests, and recipe

Author: jbiggsets

README.rst

@@ -12,14 +12,17 @@ FactorAnalyzer
     :target: https://anaconda.org/desilinguist/factor_analyzer/
 
 
-This is a Python module to perform confirmatory and exploratory and factor
-analysis, with several optional rotations. With exploratory factor analysis,
-estimation can be performed using a minimum residual (minres) solution
-(identitical to unweighted least squares), or maximum likelihood estimation (MLE).
-Confirmatory factor analysis can only be performed using a MLE solution.
-This code is fully compatible with `sklearn`.
-
-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.
 
 Please see the `official documentation <http://factor-analyzer.readthedocs.io/en/latest/index.html>`__ for additional details.
 
@@ -38,12 +41,13 @@ 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 other possible constraints on the model.
+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 to OLS, minres, or MLE.
+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
@@ -63,14 +67,13 @@ Two common types of rotations are:
    correlated.
 
 This package includes a ``factor_analyzer`` module with a stand-alone
-``FactorAnalyzer`` class. The class includes a ``fit()`` 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.
+``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 rotations options are available in both `FactorAnalyzer`
-and `Rotator`:
+The following `rotations options are available in both ``FactorAnalyzer``
+and ``Rotator``:
 
     (a) varimax (orthogonal rotation)
     (b) promax (oblique rotation)
@@ -82,10 +85,11 @@ and `Rotator`:
 
 In adddition, the package includes a ``confirmatory_factor_analyzer``
 module with a stand-alone ``ConfirmatoryFactorAnalyzer`` class. The
-class includes a ``fit()`` method that allows users to perform
-confirmatory factor analysis using MLE. Performing CFA requires users
-to specify a model with the expected factor loading relationships. This
-can be done using the ``ModelSpecificationParser`` class.
+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.
 
 Examples
 --------
@@ -177,7 +181,7 @@ Requirements
 -  ``numpy``
 -  ``pandas``
 -  ``scipy``
--  ``scikit-learn==0.20.1``
+-  ``scikit-learn``
 
 Contributing
 ------------
@@ -194,7 +198,7 @@ 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``
 
 License
 -------

conda-recipe/factor_analyzer/meta.yaml

@@ -1,5 +1,5 @@
 {% set name = "factor_analyzer" %}
-{% set version = "0.3.0" %}
+{% set version = "0.2.3" %}
 {% set file_ext = "tar.gz" %}
 {% set hash_type = "sha256" %}
 {% set hash_value = "94ea4c7d46e846cc7174787adce47156cf58dc257905c878edc5181b4fa300ed" %}

conda_requirements.txt

@@ -1,4 +1,4 @@
-python>=3.6
+python>=3.4
 pandas
 scipy=1.2.1
 numpy=1.16.2

factor_analyzer/confirmatory_factor_analyzer.py

@@ -44,6 +44,12 @@ class ModelSpecification:
         The error variance specification
     factor_covs : array-like
         The factor covariance specification.
+    factor_names : list of str or None
+        A list of factor names, if available.
+        Defaults to None.
+    variable_names : list of str or None
+        A list of variable names, if available.
+        Defaults to None.
 
     Attributes
     ----------
@@ -67,12 +73,18 @@ class ModelSpecification:
         The indexes of "free" error variance parameters.
     factor_covs_free : numpy array
         The indexes of "free" factor covariance parameters.
+    factor_names : list of str or None
+        A list of factor names, if available.
+    variable_names : list of str or None
+        A list of variable names, if available.
     """
 
     def __init__(self,
                  loadings,
                  n_factors,
-                 n_variables):
+                 n_variables,
+                 factor_names=None,
+                 variable_names=None):
 
         assert isinstance(loadings, np.ndarray)
         assert loadings.shape[0] == n_variables
@@ -81,6 +93,8 @@ def __init__(self,
         self._loadings = loadings
         self._n_factors = n_factors
         self._n_variables = n_variables
+        self._factor_names = factor_names
+        self._variable_names = variable_names
 
         self._n_lower_diag = get_symmetric_lower_idxs(n_factors, False).shape[0]
 
@@ -134,14 +148,22 @@ def n_factors(self):
     def n_lower_diag(self):
         return self._n_lower_diag
 
+    @property
+    def factor_names(self):
+        return self._factor_names
+
+    @property
+    def variable_names(self):
+        return self._variable_names
+
     def get_model_specification_as_dict(self):
         """
         Get the model specification as a dictionary.
 
         Returns
         -------
         model_specification : dict
-            The model specification parameters,
+            The model specification keys and values,
             as a dictionary.
         """
         return {'loadings': self._loadings.copy(),
@@ -152,7 +174,9 @@ def get_model_specification_as_dict(self):
                 'factor_covs_free': self._factor_covs_free.copy(),
                 'n_variables': self._n_variables,
                 'n_factors': self._n_factors,
-                'n_lower_diag': self._n_lower_diag}
+                'n_lower_diag': self._n_lower_diag,
+                'variable_names': self._variable_names,
+                'factor_names': self._factor_names}
 
 
 class ModelSpecificationParser:
@@ -169,7 +193,10 @@ def parse_model_specification_from_dict(X, specification=None):
         Generate the model specification from a
         dictionary. The keys in the dictionary
         should be the factor names, and the values
-        should be the feature names.
+        should be the feature names. If this method
+        is used to create the ``ModelSpecification``,
+        then factor names and variable names will
+        be added as properties to that object.
 
         Parameters
         ----------
@@ -201,6 +228,7 @@ def parse_model_specification_from_dict(X, specification=None):
         >>> model_spec = ModelSpecificationParser.parse_model_specification_from_dict(X, model_dict)
         """
         if specification is None:
+            factor_names, variable_names = None, None
             n_variables, n_factors = X.shape[1], X.shape[1]
             loadings = np.ones((n_factors, n_factors), dtype=int)
         elif isinstance(specification, dict):
@@ -219,15 +247,20 @@ def parse_model_specification_from_dict(X, specification=None):
 
         return ModelSpecification(**{'loadings': loadings,
                                      'n_variables': n_variables,
-                                     'n_factors': n_factors})
+                                     'n_factors': n_factors,
+                                     'factor_names': factor_names,
+                                     'variable_names': variable_names})
 
     @staticmethod
     def parse_model_specification_from_array(X, specification=None):
         """
         Generate the model specification from
         an array. The columns should correspond to
         the factors, and the rows should correspond to
-        the variables.
+        the variables. If this method is used to create
+        the ``ModelSpecification``, then no factor names
+        and variable names will be added as properties
+        to that object.
 
         Parameters
         ----------
@@ -285,32 +318,32 @@ class ConfirmatoryFactorAnalyzer(BaseEstimator, TransformerMixin):
     Parameters
     ----------
     specification : ModelSpecificaition object or None, optional
-        A model specification. This must be an ModelSpecificaiton object
+        A model specification. This must be a ``ModelSpecificaiton`` object
         or None. If None, the ModelSpecification will be generated assuming
         that n_factors == n_variables, and that all variables load on all
-        factors.
+        factors. Note that this could mean the factor model is not
+        identified, and the optimization could fail.
         Defaults to None.
     n_obs : int or None, optional
         The number of observations in the original
-        data set. If this is not passed and `is_cov=True`,
-        then a reduced form of the objective function will
-        be used.
+        data set. If this is not passed and `is_cov_matrix=True`,
+        then an error will be raised.
         Defaults to None.
     is_cov_matrix : bool, optional
-        Whether the input `data` is a
+        Whether the input `X` is a
         covariance matrix. If False,
-        assume it is the full data set
+        assume it is the full data set.
         Defaults to False.
     bounds : list of tuples or None, optional
         A list of minimum and maximum
         boundaries for each element of the
         input array. This must equal `x0`,
         which is the input array from your
         parsed and combined model specification.
-        The length is ((n_factors * n_variables) +
-        n_variables + n_factors + (((n_factors * n_factors) -
-        n_factors) // 2)
-        If None, noting will be bounded.
+        The length is:
+          ((n_factors * n_variables) + n_variables + n_factors + 
+          (((n_factors * n_factors) - n_factors) // 2)
+        If None, nothing will be bounded.
         Defaults to None.
     max_iter : int, optional
         The maximum number of iterations
@@ -328,7 +361,7 @@ class ConfirmatoryFactorAnalyzer(BaseEstimator, TransformerMixin):
     Raises
     ------
     ValueError
-        If is_cov_matrix is True, and n_obs
+        If ``is_cov_matrix`` is True, and n_obs
         is not provided.
 
     Attributes
@@ -581,7 +614,7 @@ def fit(self, X, y=None):
 
         Parameters
         ----------
-        X : numpy array
+        X : array-like
             The data to use for confirmatory
             factor analysis. If this is just a
             covariance matrix, make sure `is_cov_matrix`
@@ -590,12 +623,14 @@ def fit(self, X, y=None):
 
         Raises
         ------
+        ValueError
+            If the specification is not None or a
+            ``ModelSpecification`` object
+        AssertionError
+            If ``is_cov_matrix=True`` and the matrix
+            is not square.
         AssertionError
             If len(bounds) != len(x0)
-            If `is_cov=True` and the shame is not square or equal to the
-            number of variables.
-        ValueError
-            If `fix_first=True` and `factor_vars` exists in the model.
 
         Examples
         --------
@@ -734,7 +769,7 @@ def transform(self, X):
 
         Returns
         -------
-        X_new : numpy array, shape (n_samples, n_components)
+        scores : numpy array, shape (n_samples, n_components)
             The latent variables of X.
 
         Examples
@@ -852,7 +887,7 @@ def get_model_implied_cov(self):
         error = np.diag(self.error_vars_.flatten())
         return self.loadings_.dot(self.factor_varcovs_).dot(self.loadings_.T) + error
 
-    def get_derivatives_implied_cov(self):
+    def _get_derivatives_implied_cov(self):
         """
         Compute the derivatives for the implied covariance
         matrix (sigma).
@@ -913,7 +948,7 @@ def get_derivatives_implied_cov(self):
                 error_covs_dx[:, self.model.error_vars_free].copy(),
                 intercept_dx)
 
-    def get_derivatives_implied_mu(self):
+    def _get_derivatives_implied_mu(self):
         """
         Compute the "derivatives" for the implied means.
         Note that the derivatives of the implied means
@@ -1002,12 +1037,12 @@ def get_standard_errors(self):
         (loadings_dx,
          factor_covs_dx,
          error_covs_dx,
-         intercept_dx) = self.get_derivatives_implied_cov()
+         intercept_dx) = self._get_derivatives_implied_cov()
 
         (loadings_dx_mu,
          factor_covs_dx_mu,
          error_covs_dx_mu,
-         intercept_dx_mu) = self.get_derivatives_implied_mu()
+         intercept_dx_mu) = self._get_derivatives_implied_mu()
 
         # combine all of our derivatives; below we will  merge all of these
         # together in a single matrix, delta, to use the delta rule