Comprehensive docs clean up

AGENTS.md

@@ -0,0 +1,48 @@
+# TreeCorr Codex Notes
+
+## Python Environment
+Use the conda environment at:
+- `/Users/Mike/miniforge3/envs/py3.12`
+
+Conda activation from Codex shells should source:
+- `/Users/Mike/lsst/lsstsw/miniconda/etc/profile.d/conda.sh`
+
+Then activate by full path:
+```bash
+source /Users/Mike/lsst/lsstsw/miniconda/etc/profile.d/conda.sh
+conda activate /Users/Mike/miniforge3/envs/py3.12
+```
+
+## Sphinx Docs Build
+Use this sequence to build docs in Codex:
+```bash
+source /Users/Mike/lsst/lsstsw/miniconda/etc/profile.d/conda.sh
+conda activate /Users/Mike/miniforge3/envs/py3.12
+export LC_ALL=C LANG=C
+cd /Users/Mike/rmjarvis/TreeCorr/docs
+make html
+```
+
+Rationale:
+- `py3.12` is not always discoverable by name from the conda install on PATH, so full-path
+  activation is more reliable.
+- Setting `LC_ALL`/`LANG` avoids locale errors when invoking Sphinx.
+
+## TreeCorr Documentation Conventions
+- Prefer "data are" (treat "data" as plural) except when clearly used as a mass noun.
+- Target a 100-character line length for prose/code comments where practical.
+- Do not rewrite or shorten long URLs only to satisfy line-length limits.
+- Keep existing documentation images unless there is a concrete issue requiring a change.
+- Preserve intentional diction choices (e.g. keep "Contrariwise" where used intentionally).
+
+## Documentation Scope Priorities
+- Prioritize user-facing `.rst` pages and Python docstrings in `treecorr/*.py`.
+- Config-only docs are lower priority unless explicitly requested.
+
+## Routine Ignore Rules
+- Ignore `/Users/Mike/rmjarvis/TreeCorr/docs/_build/` during normal edits/reviews.
+- Do not edit `docs/Makefile` just for style/line-length cleanup.
+
+## Typo Sweep Rule
+- When a typo is found, grep the whole repo for that same typo pattern (excluding build/data
+  artifacts) and fix all clear occurrences in the same pass.

README.rst

@@ -1,5 +1,5 @@
-.. image:: https://travis-ci.org/rmjarvis/TreeCorr.svg?branch=main
-        :target: https://travis-ci.org/rmjarvis/TreeCorr
+.. image:: https://github.com/rmjarvis/TreeCorr/actions/workflows/ci.yml/badge.svg
+        :target: https://github.com/rmjarvis/TreeCorr/actions/workflows/ci.yml
 .. image:: https://codecov.io/gh/rmjarvis/TreeCorr/branch/main/graph/badge.svg
         :target: https://codecov.io/gh/rmjarvis/TreeCorr
 
@@ -8,13 +8,17 @@ functions.
 
 - The code is hosted at https://github.com/rmjarvis/TreeCorr
 - It can compute correlations of regular number counts, weak lensing shears, or
-  scalar quantities such as convergence or CMB temperature fluctutations.
+  scalar quantities such as convergence or CMB temperature fluctuations.
 - 2-point correlations may be auto-correlations or cross-correlations.  This
-  includes shear-shear, count-shear, count-count, kappa-kappa, etc.  (Any
-  combination of shear, kappa, and counts.)
-- 3-point correlations currently can only be auto-correlations.  This includes
-  shear-shear-shear, count-count-count, and kappa-kappa-kappa.  The cross
-  varieties are planned to be added in the near future.
+  includes shear-shear (aka GG), count-shear (NG), count-count (NN), kappa-kappa (KK), etc.
+  (Any combination of shear, kappa, and counts.)
+- 3-point correlations include both auto-correlations (e.g. NNN, KKK, GGG)
+  and mixed cross-correlations (e.g. NNG, NKK, KGG and permutations).
+- Additional field types with non-zero spin are supported in two-point
+  correlations, including vectors (spin-1, V), shear (spin-2, G), trefoil
+  (spin-3, T), and quatrefoil (spin-4, Q).
+  Three-point correlations currently support N, K, and G fields (including mixed
+  combinations such as NNG, NKK, KGG and permutations).
 - Both 2- and 3-point functions can be done with the correct curved-sky
   calculation using RA, Dec coordinates, on a Euclidean tangent plane, or in
   3D using either (RA,Dec,r) or (x,y,z) positions.
@@ -28,7 +32,7 @@ functions.
   for a bin size b=0.1 in log(r).  It scales as b^(-2).  This is the slowest
   of the various kinds of 2-point correlations, so others will be a bit faster,
   but with the same scaling with N and b.
-- The running time for 3-point functions are highly variable depending on the
+- The running time for 3-point functions is highly variable depending on the
   range of triangle geometries you are calculating.  They are significantly
   slower than the 2-point functions, but many orders of magnitude faster than
   brute force algorithms.
@@ -38,8 +42,8 @@ functions.
   I've made since then, but this will suffice as a reference for now.)
 - If you use the three-point multipole functionality of TreeCorr, please also
   reference **Porth et al, 2023, arXiv:2309.08601**
-- Record on the Astrophyics Source Code Library: http://ascl.net/1508.007
-- Developed by Mike Jarvis.  Fee free to contact me with questions or comments
+- Record on the Astrophysics Source Code Library: https://ascl.net/1508.007
+- Developed by Mike Jarvis.  Feel free to contact me with questions or comments
   at mikejarvis17 at gmail.  Or post an issue (see below) if you have any
   problems with the code.
 
@@ -68,7 +72,7 @@ or::
 
     conda update -c conda-forge treecorr
 
-Depending on the write permissions of the python distribution for your specific
+Depending on the write permissions of the Python distribution for your specific
 system, you might need to use one of the following variants for pip installation::
 
     sudo pip install treecorr
@@ -131,7 +135,7 @@ that is also relatively straightforward:
         potentially useful.
 
         - fitsio is required for reading FITS catalogs or writing to FITS output files.
-        - pandas will signficantly speed up reading from ASCII catalogs.
+        - pandas will significantly speed up reading from ASCII catalogs.
         - pandas and pyarrow are required for reading Parquet files.
         - h5py is required for reading HDF5 catalogs.
         - mpi4py is required for running TreeCorr across multiple machines using MPI.
@@ -154,12 +158,11 @@ that is also relatively straightforward:
 3. Install
 ^^^^^^^^^^
 
-   You can then install TreeCorr from the local distribution.  Typically this would be the
-   command::
+   You can then install TreeCorr from the local distribution.  Typically this would be::
 
         pip install .
 
-   If you don't have write permission in your python distribution, you might need
+   If you don't have write permission in your Python distribution, you might need
    to use::
 
         pip install . --user
@@ -171,7 +174,7 @@ that is also relatively straightforward:
         Installing corr2 script to /anaconda3/bin
 
    or similar in the output to see where the scripts are installed.  If the
-   directory is not in your path, you will also get a warning message at the
+   directory is not in your PATH, you will also get a warning message at the
    end letting you know which directory you should add to your path if you want
    to run these scripts.
 
@@ -189,7 +192,7 @@ that is also relatively straightforward:
 Two-point Correlations
 ----------------------
 
-This software is able to compute a variety of two-point correlations:
+TreeCorr can compute a variety of two-point correlations:
 
 :NN:  The normal two-point correlation function of number counts (typically
       galaxy counts).
@@ -207,7 +210,7 @@ This software is able to compute a variety of two-point correlations:
       quantity.
 
 :KG:  Cross-correlation of convergence with shear.  Like the NG calculation, but
-      weighting the pairs by the kappa values the foreground points.
+      weighting the pairs by the kappa values of the foreground points.
 
 There are also additional combinations involving complex fields with different spin
 than 2 (shear is a spin-2 field).  See `Two-point Correlation Functions
@@ -216,13 +219,13 @@ than 2 (shear is a spin-2 field).  See `Two-point Correlation Functions
 Three-point Correlations
 ------------------------
 
-Three point correlation functions are significantly more complicated, being functions
+Three-point correlation functions are significantly more complicated, being functions
 of three parameters defining the triangle size and shape, rather than just a single
 separation.  For cross-correlations, there are also issues related to whether one wants
-to allow the different catalogs to take all possible vertices in the triangles are be
+to allow the different catalogs to take all possible vertices in the triangles or be
 fixed to a particular vertex.
 
-This software is able to compute the following three-point auto-correlations:
+TreeCorr can compute the following three-point auto-correlations:
 
 :NNN: Three-point correlation function of number counts.
 
@@ -233,11 +236,11 @@ This software is able to compute the following three-point auto-correlations:
 :KKK: Three-point kappa correlation function.  Again, "kappa" here can be any
       scalar quantity.
 
-It is also possible to compute cross correlations combining two of these types, such
-as NNG, NKK, KGK, etc..  The ordering of the letters indicates which type is placed
-at which numbered vertex in the triangles where the first vertex is opposite d1, the
-second opposite d2, and the third opposite d3.  The meaning of the three side lengths
-is particular to the choice of binning.
+It is also possible to compute cross-correlations combining two of these types, such
+as NNG, NKK, KGK, etc.  The ordering of the letters indicates which type is placed
+at each numbered vertex in the triangle: the first vertex is opposite d1, the
+second is opposite d2, and the third is opposite d3.  The meaning of the three
+side lengths is particular to the choice of binning.
 
 See `Three-point Correlation Functions
 <https://rmjarvis.github.io/TreeCorr/_build/html/correlation3.html>`_ for more details.
@@ -251,18 +254,18 @@ which is the name of a configuration file::
     corr2 config_file
     corr3 config_file
 
-A sample configuration file for corr2 is provided, called sample.params.
+A sample configuration file for corr2 is provided, called sample_config.yaml.
 See `Configuration Parameters <https://rmjarvis.github.io/TreeCorr/_build/html/params.html>`_
 for the complete documentation about the allowed parameters.
 
 You can also specify parameters on the command line after the name of
-the configuration file. e.g.::
+the configuration file. For example::
 
     corr2 config_file file_name=file1.dat gg_file_name=file1.out
     corr2 config_file file_name=file2.dat gg_file_name=file2.out
     ...
 
-This can be useful when running the program from a script for lots of input
+This can be useful when running the program from a script for many input
 files.
 
 See `Using configuration files <https://rmjarvis.github.io/TreeCorr/_build/html/scripts.html>`_
@@ -271,15 +274,15 @@ for more details.
 Using the Python module
 -----------------------
 
-The typical usage in python is in three stages:
+The typical usage in Python has three stages:
 
 1. Define one or more Catalogs with the input data to be correlated.
 2. Define the correlation function that you want to perform on those data.
 3. Run the correlation by calling ``process``.
 4. Maybe write the results to a file or use them in some way.
 
-For instance, computing a shear-shear correlation from an input file stored
-in a fits file would look something like the following::
+For instance, computing a shear-shear correlation from an input catalog stored
+in a FITS file would look something like the following::
 
     >>> import treecorr
     >>> cat = treecorr.Catalog('cat.fits', ra_col='RA', dec_col='DEC',
@@ -299,7 +302,7 @@ Or for a more involved worked example, see our `Jupyter notebook tutorial
 <https://github.com/rmjarvis/TreeCorr/blob/main/tests/Tutorial.ipynb>`_.
 
 And for the complete details about all aspects of the code, see the `Sphinx-generated
-documentation <http://rmjarvis.github.io/TreeCorr>`_.
+documentation <https://rmjarvis.github.io/TreeCorr>`_.
 
 
 Reporting bugs
@@ -321,3 +324,22 @@ issue and fill in the details of the feature you would like added to TreeCorr.
 Or if there is already an issue for your desired feature, please add to the
 discussion, describing your use case.  The more people who say they want a
 feature, the more likely I am to get around to it sooner than later.
+
+
+Since Jarvis, Bernstein, and Jain (2004)
+----------------------------------------
+
+The 2004 paper remains the foundational reference for TreeCorr's tree-based
+correlation algorithms. Current TreeCorr includes additional capabilities that
+were introduced later, including:
+
+* mixed-type three-point cross-correlations
+* patch-based covariance estimates and cross-patch weighting options
+* multipole three-point algorithm support (``bin_type='LogMultipole'`` and
+  fast ``'multipole'`` algorithm for ``'LogSAS'`` binning)
+* expanded field support in two-point calculations (``Z``, ``V``, ``T``, ``Q``)
+
+References:
+
+* `Jarvis, Bernstein, and Jain (2004) <https://arxiv.org/abs/astro-ph/0307393>`_
+* `Porth et al. (2023) <https://arxiv.org/abs/2309.08601>`_

TreeCorr_LICENSE

@@ -10,7 +10,7 @@ modification, are permitted provided that the following conditions are met:
    this list of conditions and the following disclaimer in the documentation
    and/or other materials provided with the distribution. 
 
-This software is based in part upon work supported by the the University of 
+This software is based in part upon work supported by the University of
 Pennsylvania.  Any opinions, findings and conclusions or recommendations
 expressed in this material are those of the author(s) and do not necessarily
 reflect the views of the University of Pennsylvania.
@@ -25,4 +25,3 @@ software or any products related to or derived from the software, or for
 lost profits, business interruption, or indirect special or consequential 
 damages of any kind. 
 
-

docs/binning.rst

@@ -229,7 +229,7 @@ angle_slop
 
 For some calculations, the angular orientation of the line between two points is relevant
 to the correlation.  For most complex quantities (e.g. shear), the value used in the correlation
-has to be projected onto the the line between the two points (for two-point correlations) or
+has to be projected onto the line between the two points (for two-point correlations) or
 the centroid of the triangle (for three-point correlations).  Even for scalar quantities,
 three-point correlations using the multipole method also use the angular direction of the
 lines between points.

docs/binning3pt.rst

@@ -3,7 +3,7 @@ Binning for three-point correlations
 
 The binning in the three-point case is somewhat more complicated than for
 two-point functions, since we need to characterize the geometry of triangles.
-There are currently three different binnings available, which
+There are currently three different binning schemes available, which
 may be specified using the ``bin_type`` parameter in `Corr3`.
 
 .. note::
@@ -16,18 +16,18 @@ may be specified using the ``bin_type`` parameter in `Corr3`.
     this definition of vertices has the right field in the corresponding vertex.
     E.g. NNG only keeps triangles that have the G field in vertex 3.  For triangles
     with the G field in vertex 1 or 2, you would need to use GNN and NGN respectively.
-    To fully characterize the full set of 3-point correlation information of the
-    three fields with mixed type, you need all three of these.
+    To fully characterize the 3-point correlation information for three mixed-type fields,
+    you need all three of these.
 
 See also `Other options for binning` for additional parameters that are relevant to
 the binning. These all work the same way for three-point functions as for
-two-point function.
+two-point functions.
 
 "LogRUV"
 --------
 
 This binning option uses a Side-Side-Side (SSS) characterization of the triangle.
-Thre three side lengths of the triangle are measured (using whatever `Metric <Metrics>`
+The three side lengths of the triangle are measured (using whatever `Metric <Metrics>`
 is being used).  Then we sort their lengths so that :math:`d_1 \ge d_2 \ge d_3`.
 
 If we just binned directly in these three side lengths, then the range of valid
@@ -43,13 +43,13 @@ quantities which have better-behaved ranges:
 
 With this reparametrization, :math:`u` and :math:`v` are each limited to the range
 :math:`[0,1]`, independent of the values of the other parameters.  The :math:`r`
-parameter defines the overall size of the triangle, and that can range of whatever
-set of values the user wants.
+parameter defines the overall size of the triangle, and that can range over
+whatever set of values the user wants.
 
 This provides a unique definition for any triangle, except for a mirror reflection.
-Two congruent triangles (that are not isoceles or equilateral) are not necessarily
-equivalent for 3-point correlations.  The orienation of the sides matters, at least
-in many use cases.  So we need to keep track of that.  We choose to do so in the 
+Two congruent triangles (that are not isosceles or equilateral) are not necessarily
+equivalent for 3-point correlations.  The orientation of the sides matters, at least
+in many use cases.  So we need to keep track of that.  We choose to do so in the
 sign of :math:`v`, where positive values mean that the sides :math:`d_1`,
 :math:`d_2` and :math:`d_3` are oriented in counter-clockwise order.
 Negative values of :math:`v` mean they are oriented in clockwise order.
@@ -58,11 +58,11 @@ Negative values of :math:`v` mean they are oriented in clockwise order.
 
     This binning can only use the 'triangle' algorithm, which is generally much
     slower than the 'multipole' algorithm.  For most purposes, we recommend using
-    `"LogSAS"` instead, which can use the 'multpole' algorithm to calculate the
+    `"LogSAS"` instead, which can use the 'multipole' algorithm to calculate the
     correlation function.  See `Three-point Algorithm` below for more discussion
     about this.
 
-The binning of :math:`r` works the same was as `"Log"` for two-point correlations.
+The binning of :math:`r` works the same way as `"Log"` for two-point correlations.
 That is, the binning is specified using any 3 of the following 4 parameters:
 
     - ``nbins``       How many bins to use.
@@ -98,7 +98,7 @@ being used for the binning are called :math:`d_2` and :math:`d_3`.  The angle
 between these two sides is called :math:`\phi`, and the side opposite it
 (not used for binning) is :math:`d_1`.
 
-The two sides, :math:`d_2` and :math:`d_3` are each binned the same was as
+The two sides, :math:`d_2` and :math:`d_3` are each binned the same way as
 `"Log"` binning for two-point correlations.
 That is, the binning is specified using any 3 of the following 4 parameters:
 
@@ -176,7 +176,7 @@ section 4.2. (We no longer implement the algorithm described in section 4.3 due
 considerations.)  This algorithm is much faster than a brute-force calculation, but it is
 still quite slow compared to the new multipole algorithm.
 
-Starting in version 5.0, we now also implement the algorthm developed by
+Starting in version 5.0, we now also implement the algorithm developed by
 `Porth et al (2024, A&A, 689, 224)
 <https://ui.adsabs.harvard.edu/abs/2024A%26A...689A.227P/abstract>`_,
 called 'multipole' in TreeCorr, which is much faster for typical data sets.

docs/catalog.rst

@@ -26,7 +26,8 @@ Other utilities related to catalogs
     treecorr.calculateVarQ
 .. automodule:: treecorr.catalog
     :members:
-    :exclude-members: Catalog, read_catalogs, calculateVarK, calculateVarZ, calculateVarV, calculateVarG, calculateVarT, calculateVatQ
+    :exclude-members: Catalog, read_catalogs, calculateVarK, calculateVarZ, calculateVarV,
+        calculateVarG, calculateVarT, calculateVarQ
 
 File Readers
 ------------