Skip to content

Commit 924a86f

Browse files
desilinguistdesilinguist
committed
Add important notes to documentation.
- Also re-organize the documentation to make it clearer and more readable.
1 parent 68000f7 commit 924a86f

File tree

4 files changed

+124
-95
lines changed

4 files changed

+124
-95
lines changed

‎doc/factor_analyzer.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
.. _factor_analyzer_api:
22

3-
factor\_analyzer package
4-
========================
3+
API documentation
4+
=================
55

66
:py:mod:`factor\_analyzer\.factor\_analyzer` Module
77
---------------------------------------------------

‎doc/index.rst‎

Lines changed: 8 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -19,105 +19,20 @@ Both the EFA and CFA classes within this package are fully compatible with
1919
``scikit-learn``. Portions of this code are ported from the excellent R library
2020
``psych``, and the ``sem`` package provided inspiration for the CFA class.
2121

22-
Description
23-
============
22+
.. important::
2423

25-
Exploratory factor analysis (EFA) is a statistical technique used to
26-
identify latent relationships among sets of observed variables in a
27-
dataset. In particular, EFA seeks to model a large set of observed
28-
variables as linear combinations of some smaller set of unobserved,
29-
latent factors. The matrix of weights, or factor loadings, generated
30-
from an EFA model describes the underlying relationships between each
31-
variable and the latent factors.
24+
Please make sure to read the :ref:`important notes <important_notes>` section if you encounter any
25+
unexpected results.
3226

33-
Confirmatory factor analysis (CFA), a closely associated technique, is
34-
used to test a priori hypothesis about latent relationships among sets
35-
of observed variables. In CFA, the researcher specifies the expected pattern
36-
of factor loadings (and possibly other constraints), and fits a model according
37-
to this specification.
3827

39-
Typically, a number of factors (K) in an EFA or CFA model is selected
40-
such that it is substantially smaller than the number of variables. The
41-
factor analysis model can be estimated using a variety of standard
42-
estimation methods, including but not limited MINRES or ML.
43-
44-
Factor loadings are similar to standardized regression coefficients, and
45-
variables with higher loadings on a particular factor can be interpreted
46-
as explaining a larger proportion of the variation in that factor. In the
47-
case of EFA, factor loading matrices are usually rotated after the factor
48-
analysis model is estimated in order to produce a simpler, more interpretable
49-
structure to identify which variables are loading on a particular factor.
50-
51-
Two common types of rotations are:
52-
53-
1. The **varimax** rotation, which rotates the factor loading matrix so
54-
as to maximize the sum of the variance of squared loadings, while
55-
preserving the orthogonality of the loading matrix.
56-
57-
2. The **promax** rotation, a method for oblique rotation, which builds
58-
upon the varimax rotation, but ultimately allows factors to become
59-
correlated.
60-
61-
This package includes a :mod:`~factor_analyzer.factor_analyzer` module with a
62-
stand-alone :class:`~factor_analyzer.factor_analyzer.FactorAnalyzer` class. The
63-
class includes :meth:`~factor_analyzer.factor_analyzer.FactorAnalyzer.fit()`
64-
and :meth:`~factor_analyzer.factor_analyzer.FactorAnalyzer.transform()`
65-
methods that enable users to perform factor analysis and score new data using
66-
the fitted factor model. Users can also perform optional rotations on a factor
67-
loading matrix using the :class:`~factor_analyzer.rotator.Rotator` class.
68-
69-
The following rotation options are available in both
70-
:class:`~factor_analyzer.factor_analyzer.FactorAnalyzer` and
71-
:class:`~factor_analyzer.rotator.Rotator`:
72-
73-
(a) varimax (orthogonal rotation)
74-
(b) promax (oblique rotation)
75-
(c) oblimin (oblique rotation)
76-
(d) oblimax (orthogonal rotation)
77-
(e) quartimin (oblique rotation)
78-
(f) quartimax (orthogonal rotation)
79-
(g) equamax (orthogonal rotation)
80-
(h) geomin_obl (oblique rotation)
81-
(i) geomin_ort (orthogonal rotation)
82-
83-
In addition, the package includes a
84-
:mod:`~factor_analyzer.confirmatory_factor_analyzer` module with a stand-alone
85-
:class:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer`
86-
class. The class includes
87-
:meth:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer.fit()`
88-
and
89-
:meth:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer.transform()`
90-
that enable users to perform confirmatory factor analysis and score new data
91-
using the fitted model. Performing CFA requires users to specify in advance a
92-
model specification with the expected factor loading relationships. This can be
93-
done using the
94-
:class:`~factor_analyzer.confirmatory_factor_analyzer.ModelSpecificationParser`
95-
class.
96-
97-
Requirements
98-
==================
99-
- Python 3.7 or higher
100-
- ``numpy``
101-
- ``pandas``
102-
- ``scipy``
103-
- ``scikit-learn``
104-
- ``pre-commit``
105-
106-
Installation
107-
==================
108-
109-
You can install this package via ``pip`` with:
110-
111-
``$ pip install factor_analyzer``
112-
113-
Alternatively, you can install via ``conda`` with:
114-
115-
``$ conda install -c ets factor_analyzer``
28+
Documentation
29+
=============
11630

11731
.. toctree::
118-
:maxdepth: 2
119-
:caption: Contents:
32+
:maxdepth: 3
12033

34+
introduction
35+
notes
12136
factor_analyzer
12237

12338

‎doc/introduction.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
Introduction
2+
============
3+
4+
Exploratory factor analysis (EFA) is a statistical technique used to
5+
identify latent relationships among sets of observed variables in a
6+
dataset. In particular, EFA seeks to model a large set of observed
7+
variables as linear combinations of some smaller set of unobserved,
8+
latent factors. The matrix of weights, or factor loadings, generated
9+
from an EFA model describes the underlying relationships between each
10+
variable and the latent factors.
11+
12+
Confirmatory factor analysis (CFA), a closely associated technique, is
13+
used to test a priori hypothesis about latent relationships among sets
14+
of observed variables. In CFA, the researcher specifies the expected pattern
15+
of factor loadings (and possibly other constraints), and fits a model according
16+
to this specification.
17+
18+
Typically, a number of factors (K) in an EFA or CFA model is selected
19+
such that it is substantially smaller than the number of variables. The
20+
factor analysis model can be estimated using a variety of standard
21+
estimation methods, including but not limited MINRES or ML.
22+
23+
Factor loadings are similar to standardized regression coefficients, and
24+
variables with higher loadings on a particular factor can be interpreted
25+
as explaining a larger proportion of the variation in that factor. In the
26+
case of EFA, factor loading matrices are usually rotated after the factor
27+
analysis model is estimated in order to produce a simpler, more interpretable
28+
structure to identify which variables are loading on a particular factor.
29+
30+
Two common types of rotations are:
31+
32+
1. The **varimax** rotation, which rotates the factor loading matrix so
33+
as to maximize the sum of the variance of squared loadings, while
34+
preserving the orthogonality of the loading matrix.
35+
36+
2. The **promax** rotation, a method for oblique rotation, which builds
37+
upon the varimax rotation, but ultimately allows factors to become
38+
correlated.
39+
40+
This package includes a :mod:`~factor_analyzer.factor_analyzer` module with a
41+
stand-alone :class:`~factor_analyzer.factor_analyzer.FactorAnalyzer` class. The
42+
class includes :meth:`~factor_analyzer.factor_analyzer.FactorAnalyzer.fit()`
43+
and :meth:`~factor_analyzer.factor_analyzer.FactorAnalyzer.transform()`
44+
methods that enable users to perform factor analysis and score new data using
45+
the fitted factor model. Users can also perform optional rotations on a factor
46+
loading matrix using the :class:`~factor_analyzer.rotator.Rotator` class.
47+
48+
The following rotation options are available in both
49+
:class:`~factor_analyzer.factor_analyzer.FactorAnalyzer` and
50+
:class:`~factor_analyzer.rotator.Rotator`:
51+
52+
(a) varimax (orthogonal rotation)
53+
(b) promax (oblique rotation)
54+
(c) oblimin (oblique rotation)
55+
(d) oblimax (orthogonal rotation)
56+
(e) quartimin (oblique rotation)
57+
(f) quartimax (orthogonal rotation)
58+
(g) equamax (orthogonal rotation)
59+
(h) geomin_obl (oblique rotation)
60+
(i) geomin_ort (orthogonal rotation)
61+
62+
In addition, the package includes a
63+
:mod:`~factor_analyzer.confirmatory_factor_analyzer` module with a stand-alone
64+
:class:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer`
65+
class. The class includes
66+
:meth:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer.fit()`
67+
and
68+
:meth:`~factor_analyzer.confirmatory_factor_analyzer.ConfirmatoryFactorAnalyzer.transform()`
69+
that enable users to perform confirmatory factor analysis and score new data
70+
using the fitted model. Performing CFA requires users to specify in advance a
71+
model specification with the expected factor loading relationships. This can be
72+
done using the
73+
:class:`~factor_analyzer.confirmatory_factor_analyzer.ModelSpecificationParser`
74+
class.
75+
76+
Requirements
77+
------------
78+
- Python 3.7 or higher
79+
- ``numpy``
80+
- ``pandas``
81+
- ``scipy``
82+
- ``scikit-learn``
83+
- ``pre-commit``
84+
85+
Installation
86+
------------
87+
88+
You can install this package via ``pip`` with:
89+
90+
``$ pip install factor_analyzer``
91+
92+
Alternatively, you can install via ``conda`` with:
93+
94+
``$ conda install -c ets factor_analyzer``

‎doc/notes.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. _important_notes:
2+
3+
Important notes
4+
===============
5+
6+
1. It is possible that `factor_analyzer` may return the loading for a factor
7+
that has all negative entries whereas SPSS/R may return the same loading
8+
with all positive entries. This is not a bug. This can happen if the
9+
eigenvalue decomposition returns an eigenvector with all negative entries,
10+
which is not unusual since if :math:`v` is an eigenvector, then so is
11+
:math:`\alpha * v`, where :math:`\alpha` is any scalar (:math:`\ne 0`).
12+
Additionally, signs on factor loadings are also kind of meaningless because
13+
all they do is flip the (already arbitrary) interpretation of the latent
14+
factor. For more details, please refer to
15+
`this Github issue <https://github.com/EducationalTestingService/factor_analyzer/issues/89>`__.
16+
2. When using equamax rotation, you must compute the correct value of
17+
:math:`\kappa` yourself and pass it using the `rotation_kwargs` argument.
18+
This is different from SPSS which computes the value of :math:`\kappa`
19+
internally. For more details, please refer to
20+
`this Github issue <https://github.com/EducationalTestingService/factor_analyzer/issues/90>`__.

0 commit comments

Comments
 (0)