Repository: statsmodels/statsmodels

Issue:
REF: move PCA to a new `multivariate` folder
PCA is a full model version, and is traditional categorized under `multivariate`. So `multivariate` should be the permanent location, even if there is nothing else there right now.

(e.g. see https://github.com/JuliaStats/MultivariateStats.jl  for a list)

Given that PCA has been in master for a year (and the never released 0.7), we might want to deprecate the current module location.

what else goes into multivariate?:
scikit-learn has more of the relevant classes. So it's not urgent for us unless there is a statistics part to add. The biggest item would be factor analysis, I guess.
The only (IIRC) item that I have right now are the main parts of canonical correlation, especially with tests on eigen values or rank. Also MANOVA is related.
(possible alternative location for the hypothesis tests is a `stats.multivariate` module)



Discussion:
@bashtage

@kshedden   Do you know of anything that should get higher priorities in this area?

Perhaps Multidimensional Scaling (MDS).

I don't know anything about MDS, the Wikipedia page references
http://scikit-learn.org/stable/modules/generated/sklearn.manifold.MDS.html

What is the final call for this @josef-pkt ?

Multivariate seems reasonable.  Not sure it maters much since `PCA` is exposed through api.


Resolving patch:
diff --git a/statsmodels/api.py b/statsmodels/api.py
--- a/statsmodels/api.py
+++ b/statsmodels/api.py
@@ -24,12 +24,12 @@
 from .stats import api as stats
 from .emplike import api as emplike
 from .duration import api as duration
+from .multivariate.pca import PCA
 
 from .formula import api as formula
 
 from .iolib.smpickle import load_pickle as load
 
-from .tools.pca import PCA
 from .tools.print_version import show_versions
 from .tools.web import webdoc
 
diff --git a/statsmodels/tools/pca.py b/statsmodels/multivariate/pca.py
similarity index 100%
rename from statsmodels/tools/pca.py
rename to statsmodels/multivariate/pca.py
diff --git a/statsmodels/tsa/statespace/dynamic_factor.py b/statsmodels/tsa/statespace/dynamic_factor.py
--- a/statsmodels/tsa/statespace/dynamic_factor.py
+++ b/statsmodels/tsa/statespace/dynamic_factor.py
@@ -19,7 +19,7 @@
     constrain_stationary_multivariate, unconstrain_stationary_multivariate
 )
 from scipy.linalg import solve_discrete_lyapunov
-from statsmodels.tools.pca import PCA
+from statsmodels.multivariate.pca import PCA
 from statsmodels.regression.linear_model import OLS
 from statsmodels.tsa.vector_ar.var_model import VAR
 from statsmodels.tools.tools import Bunch


Test patch:
diff --git a/statsmodels/tools/tests/results/__init__.py b/statsmodels/multivariate/__init__.py
similarity index 100%
rename from statsmodels/tools/tests/results/__init__.py
rename to statsmodels/multivariate/__init__.py
diff --git a/statsmodels/multivariate/tests/__init__.py b/statsmodels/multivariate/tests/__init__.py
new file mode 100644
diff --git a/statsmodels/multivariate/tests/results/__init__.py b/statsmodels/multivariate/tests/results/__init__.py
new file mode 100644
diff --git a/statsmodels/tools/tests/results/datamlw.py b/statsmodels/multivariate/tests/results/datamlw.py
similarity index 100%
rename from statsmodels/tools/tests/results/datamlw.py
rename to statsmodels/multivariate/tests/results/datamlw.py
diff --git a/statsmodels/tools/tests/test_pca.py b/statsmodels/multivariate/tests/test_pca.py
similarity index 99%
rename from statsmodels/tools/tests/test_pca.py
rename to statsmodels/multivariate/tests/test_pca.py
--- a/statsmodels/tools/tests/test_pca.py
+++ b/statsmodels/multivariate/tests/test_pca.py
@@ -14,8 +14,8 @@
 except ImportError:
     missing_matplotlib = True
 
-from statsmodels.tools.pca import PCA
-from statsmodels.tools.tests.results.datamlw import data, princomp1, princomp2
+from statsmodels.multivariate.pca import PCA
+from statsmodels.multivariate.tests.results.datamlw import data, princomp1, princomp2
 from statsmodels.compat.numpy import nanmean
 
 DECIMAL_5 = .00001