Merge pull request #10 from bystrogenomics/feature/better_documentation

austinTalbot7241993 · web-flow · commit 48d17b3c8c26 · 2025-12-09T22:44:40.000-05:00
One more
diff --git a/covtest/methods/hypothesis_identity.py b/covtest/methods/hypothesis_identity.py
@@ -484,12 +484,6 @@ def srivastava2011_single_sample(X, Sigma="identity"):
         - 'p_value' : float
             Two-sided p-value.
 
-    References
-    ----------
-    .. [1] Srivastava, M. S., & Yanagihara, H. (2011). "Testing
-           the equality of several covariance matrices with fewer
-           observations than the dimension." Journal of
-           Multivariate Analysis.
     """
     X = validate_data_matrix(X)
     p = X.shape[1]
diff --git a/docs/api/covtest.datasets.rst b/docs/api/covtest.datasets.rst
@@ -0,0 +1,20 @@
+.. _covtest-datasets:
+
+Datasets
+========
+
+This page documents the dataset loading utilities implemented in :mod:`covtest.datasets`.
+These functions allow loading standard datasets for testing covariance methods.
+
+.. currentmodule:: covtest.datasets.loader
+
+.. automodule:: covtest.datasets.loader
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   load_mnist
+   load_tcga
+   load_iris
diff --git a/docs/api/covtest.diagnostics.rst b/docs/api/covtest.diagnostics.rst
@@ -0,0 +1,40 @@
+.. _covtest-diagnostics:
+
+Diagnostics
+===========
+
+This page documents the diagnostic utilities implemented in :mod:`covtest.diagnostics`.
+These include tests for multivariate normality and tools for evaluating p-value distributions.
+
+Assumptions and normality tests
+-------------------------------
+
+.. currentmodule:: covtest.diagnostics.assumptions
+
+.. automodule:: covtest.diagnostics.assumptions
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   eigen_spectrum
+   mardia_tests
+   shapiro_francia_w
+   royston_test
+   hz_test
+   condition_and_rank
+
+P-value evaluation
+------------------
+
+.. currentmodule:: covtest.diagnostics.evaluate_pvalues
+
+.. automodule:: covtest.diagnostics.evaluate_pvalues
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   analyze_pvalues
diff --git a/docs/api/covtest.plotting.rst b/docs/api/covtest.plotting.rst
@@ -0,0 +1,67 @@
+.. _covtest-plotting:
+
+Plotting utilities
+==================
+
+This page documents the plotting utilities implemented in :mod:`covtest.plotting`.
+These include functions for visualizing power curves, p-value distributions,
+and covariance matrix structures.
+
+Power analysis plots
+--------------------
+
+.. currentmodule:: covtest.plotting.alternative
+
+.. automodule:: covtest.plotting.alternative
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   plot_power_curve
+   plot_power_heatmap
+   plot_mean_pvalue
+   plot_pvalue_distributions
+   plot_power_curves_multi_alpha
+
+Null distribution diagnostics
+-----------------------------
+
+.. currentmodule:: covtest.plotting.null
+
+.. automodule:: covtest.plotting.null
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   plot_pval_histogram
+   plot_pval_qq
+   plot_pval_ecdf
+   plot_pval_cumdev
+   plot_pval_obs_vs_exp
+   plot_pval_survival
+   plot_pval_running_mean
+   plot_pval_zdist
+   plot_pval_calibration
+   qq_plot_log_p
+   pvalue_histogram
+   plot_pval_diagnostics
+   plot_pvalue_diagnostics_grid
+
+Structure visualization
+-----------------------
+
+.. currentmodule:: covtest.plotting.structure
+
+.. automodule:: covtest.plotting.structure
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   plot_eigen_scree
+   plot_matrix_structure
diff --git a/docs/api/covtest.simulation.rst b/docs/api/covtest.simulation.rst
@@ -0,0 +1,45 @@
+.. _covtest-simulation:
+
+Simulation utilities
+====================
+
+This page documents the simulation utilities implemented in :mod:`covtest.simulation`.
+These include functions for generating covariance matrices with specific structures
+and generating multivariate data from various distributions.
+
+Covariance matrix generation
+----------------------------
+
+.. currentmodule:: covtest.simulation.generate_covariances
+
+.. automodule:: covtest.simulation.generate_covariances
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   sample_goe
+   sample_cov_uniform_correlation
+   generate_spectral_cov
+   generate_toeplitz_cov
+   generate_block_diagonal_cov
+   generate_low_rank_cov
+   generate_sparse_precision_cov
+   generate_marchenko_pastur
+   generate_spiked_covariance
+
+Data generation
+---------------
+
+.. currentmodule:: covtest.simulation.generate_data
+
+.. automodule:: covtest.simulation.generate_data
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   generate_heavy_tailed_samples
+   generate_heavy_tailed_alternative
diff --git a/docs/api/covtest.testing.rst b/docs/api/covtest.testing.rst
@@ -0,0 +1,24 @@
+.. _covtest-testing:
+
+Testing utilities
+=================
+
+This page documents the testing and benchmarking utilities implemented
+in :mod:`covtest.testing`.
+
+Benchmarking
+------------
+
+.. currentmodule:: covtest.testing.timing
+
+.. automodule:: covtest.testing.timing
+   :no-members:
+
+.. autosummary::
+   :toctree: generated/
+   :template: function.rst
+
+   benchmark_computation_dimension
+   benchmark_computation_sample_size
+   plot_computation_dimension
+   plot_computation_sample_size
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,7 +14,7 @@
 # Project information
 # -------------------------------------------------------------------
 project = "scikit-covtest"
-author = "Your Name"
+author = "Austin Talbot"
 
 # Try to get the version from the package if available
 try:
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,16 +1,78 @@
 scikit-covtest documentation
 ============================
 
+scikit-covtest is a Python package for high dimensional covariance matrix
+testing, with a focus on both classical and high-dimensional tests
+
+It provides statistically principled tests for:
+
+- Identity and sphericity of covariance matrices
+- Proportionality between two covariance matrices
+- Two-sample equality testing in high dimensions
+- Multiple testing control for large test families
+
+The library is designed for:
+
+- Statistical genomics and gene expression analysis
+- High dimensional machine learning diagnostics
+- Simulation driven theoretical validation
+- Large scale hypothesis testing pipelines
+
+Installation
+------------
+
+Install from PyPI:
+
+.. code-block:: bash
+
+   pip install scikit-covtest
+
+Or install from source:
+
+.. code-block:: bash
+
+   git clone https://github.com/bystrogenomics/scikit-covtest.git
+   cd scikit-covtest
+   pip install .
+
+Quickstart
+----------
+
+Minimal example using a covariance identity test:
+
+.. code-block:: python
+
+   import numpy as np
+   from covtest.methods import hypothesis_identity as hi
+
+   rng = np.random.default_rng(0)
+   X = rng.normal(size=(200, 50))
+
+   result = hi.ahmad2015_identity(X)
+   print("Statistic: ", result['stat'])
+   print("p-value: ", result['p_value'])
+
+User guide
+----------
+
 .. toctree::
    :maxdepth: 2
    :caption: User guide
 
    user_guide/multiple_testing
 
+API reference
+-------------
+
 .. toctree::
    :maxdepth: 1
    :caption: API reference
 
-   api/covtest.multiplicity
+   api/covtest.datasets
+   api/covtest.diagnostics
    api/covtest.methods
+   api/covtest.multiplicity
+   api/covtest.plotting
+   api/covtest.simulation
+   api/covtest.testing
 
