{"id":16285926,"url":"https://github.com/rmjarvis/treecorr","last_synced_at":"2025-05-16T12:12:17.501Z","repository":{"id":18899216,"uuid":"22117429","full_name":"rmjarvis/TreeCorr","owner":"rmjarvis","description":"Code for efficiently computing 2-point and 3-point correlation functions. For documentation, go to","archived":false,"fork":false,"pushed_at":"2025-04-09T15:11:44.000Z","size":59037,"stargazers_count":105,"open_issues_count":5,"forks_count":37,"subscribers_count":11,"default_branch":"releases/5.1","last_synced_at":"2025-05-11T11:17:41.269Z","etag":null,"topics":["astronomy","correlation","des","largescalestructure","lsst","python","weaklensing"],"latest_commit_sha":null,"homepage":"http://rmjarvis.github.io/TreeCorr/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rmjarvis.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-22T19:19:26.000Z","updated_at":"2025-04-26T19:05:36.000Z","dependencies_parsed_at":"2024-01-02T19:42:04.202Z","dependency_job_id":"f034fcb6-6abf-4e25-8688-6fe7bbbbe5e3","html_url":"https://github.com/rmjarvis/TreeCorr","commit_stats":{"total_commits":1413,"total_committers":6,"mean_commits":235.5,"dds":0.03609341825902335,"last_synced_commit":"3b6b5b376e02cceac7f6c493c25cc397d8a41454"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmjarvis%2FTreeCorr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmjarvis%2FTreeCorr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmjarvis%2FTreeCorr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rmjarvis%2FTreeCorr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rmjarvis","download_url":"https://codeload.github.com/rmjarvis/TreeCorr/tar.gz/refs/heads/releases/5.1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254527099,"owners_count":22085919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","correlation","des","largescalestructure","lsst","python","weaklensing"],"created_at":"2024-10-10T19:26:32.610Z","updated_at":"2025-05-16T12:12:12.479Z","avatar_url":"https://github.com/rmjarvis.png","language":"Python","readme":".. image:: https://travis-ci.org/rmjarvis/TreeCorr.svg?branch=main\n        :target: https://travis-ci.org/rmjarvis/TreeCorr\n.. image:: https://codecov.io/gh/rmjarvis/TreeCorr/branch/main/graph/badge.svg\n        :target: https://codecov.io/gh/rmjarvis/TreeCorr\n\nTreeCorr is a package for efficiently computing 2-point and 3-point correlation\nfunctions.\n\n- The code is hosted at https://github.com/rmjarvis/TreeCorr\n- It can compute correlations of regular number counts, weak lensing shears, or\n  scalar quantities such as convergence or CMB temperature fluctutations.\n- 2-point correlations may be auto-correlations or cross-correlations.  This\n  includes shear-shear, count-shear, count-count, kappa-kappa, etc.  (Any\n  combination of shear, kappa, and counts.)\n- 3-point correlations currently can only be auto-correlations.  This includes\n  shear-shear-shear, count-count-count, and kappa-kappa-kappa.  The cross\n  varieties are planned to be added in the near future.\n- Both 2- and 3-point functions can be done with the correct curved-sky\n  calculation using RA, Dec coordinates, on a Euclidean tangent plane, or in\n  3D using either (RA,Dec,r) or (x,y,z) positions.\n- The front end is in Python, which can be used as a Python module or as a\n  standalone executable using configuration files. (The executable is corr2\n  for 2-point and corr3 for 3-point.)\n- The actual computation of the correlation functions is done in C++ using ball\n  trees (similar to kd trees), which make the calculation extremely efficient.\n- When available, OpenMP is used to run in parallel on multi-core machines.\n- Approximate running time for 2-point shear-shear is ~30 sec * (N/10^6) / core\n  for a bin size b=0.1 in log(r).  It scales as b^(-2).  This is the slowest\n  of the various kinds of 2-point correlations, so others will be a bit faster,\n  but with the same scaling with N and b.\n- The running time for 3-point functions are highly variable depending on the\n  range of triangle geometries you are calculating.  They are significantly\n  slower than the 2-point functions, but many orders of magnitude faster than\n  brute force algorithms.\n- **If you use TreeCorr in published research, please reference:\n  Jarvis, Bernstein, \u0026 Jain, 2004, MNRAS, 352, 338**\n  (I'm working on new paper about TreeCorr, including some of the improvements\n  I've made since then, but this will suffice as a reference for now.)\n- If you use the three-point multipole functionality of TreeCorr, please also\n  reference **Porth et al, 2023, arXiv:2309.08601**\n- Record on the Astrophyics Source Code Library: http://ascl.net/1508.007\n- Developed by Mike Jarvis.  Fee free to contact me with questions or comments\n  at mikejarvis17 at gmail.  Or post an issue (see below) if you have any\n  problems with the code.\n\nThe code is licensed under a FreeBSD license.  Essentially, you can use the\ncode in any way you want, but if you distribute it, you need to include the\nfile ``TreeCorr_LICENSE`` with the distribution.  See that file for details.\n\n\nInstallation\n------------\n\nThe easiest ways to install TreeCorr are either with pip::\n\n    pip install treecorr\n\nor with conda::\n\n    conda install -c conda-forge treecorr\n\nIf you have previously installed TreeCorr, and want to upgrade to a new\nreleased version, you should do::\n\n    pip install treecorr --upgrade\n\nor::\n\n    conda update -c conda-forge treecorr\n\nDepending on the write permissions of the python distribution for your specific\nsystem, you might need to use one of the following variants for pip installation::\n\n    sudo pip install treecorr\n    pip install treecorr --user\n\nThe latter installs the Python module into ``~/.local/lib/python3.X/site-packages``,\nwhich is normally already in your PYTHONPATH, but it puts the executables\n``corr2`` and ``corr3`` into ``~/.local/bin`` which is probably not in your PATH.\nTo use these scripts, you should add this directory to your PATH.  If you would\nrather install into a different prefix rather than ~/.local, you can use::\n\n    pip install treecorr --install-option=\"--prefix=PREFIX\"\n\nThis would install the executables into ``PREFIX/bin`` and the Python module\ninto ``PREFIX/lib/python3.X/site-packages``.\n\n\nIf you would rather download the tarball and install TreeCorr yourself,\nthat is also relatively straightforward:\n\n1. Download TreeCorr\n^^^^^^^^^^^^^^^^^^^^\n\n   You can download the latest tarball from::\n\n        https://github.com/rmjarvis/TreeCorr/releases/\n\n   Or you can clone the repository using either of the following::\n\n        git clone git@github.com:rmjarvis/TreeCorr.git\n        git clone https://github.com/rmjarvis/TreeCorr.git\n\n   which will start out in the current stable release branch.\n\n   Either way, cd into the TreeCorr directory.\n\n2. Install dependencies\n^^^^^^^^^^^^^^^^^^^^^^^\n\n   All required dependencies should be installed automatically for you by\n   pip or conda, so you should not need to worry about these.  But if you\n   are interested, the dependencies are:\n\n    - numpy\n    - pyyaml\n    - LSSTDESC.Coord\n    - pybind11\n\n   They can all be installed at once by running::\n\n        pip install -r requirements.txt\n\n   or::\n\n        conda install -c conda-forge treecorr --only-deps\n\n   .. note::\n\n        Several additional modules are not required for basic TreeCorr operations, but are\n        potentially useful.\n\n        - fitsio is required for reading FITS catalogs or writing to FITS output files.\n        - pandas will signficantly speed up reading from ASCII catalogs.\n        - pandas and pyarrow are required for reading Parquet files.\n        - h5py is required for reading HDF5 catalogs.\n        - mpi4py is required for running TreeCorr across multiple machines using MPI.\n\n        These are all pip installable::\n\n            pip install fitsio\n            pip install pandas\n            pip install pyarrow\n            pip install h5py\n            pip install mpi4py\n\n        But they are not installed with TreeCorr automatically.\n\n        Also, beware that many HPC machines (e.g. NERSC) have special instructions for installing\n        mpi4py, so the above command may not work on such systems.  If you have trouble, look\n        for specialized instructions about how to install mpi4py properly on your system.\n\n\n3. Install\n^^^^^^^^^^\n\n   You can then install TreeCorr from the local distribution.  Typically this would be the\n   command::\n\n        pip install .\n\n   If you don't have write permission in your python distribution, you might need\n   to use::\n\n        pip install . --user\n\n   In addition to installing the Python module ``treecorr``, this will install\n   the executables ``corr2`` and ``corr3`` in a ``bin`` folder somewhere on your\n   system.  Look for a line like::\n\n        Installing corr2 script to /anaconda3/bin\n\n   or similar in the output to see where the scripts are installed.  If the\n   directory is not in your path, you will also get a warning message at the\n   end letting you know which directory you should add to your path if you want\n   to run these scripts.\n\n\n4. Run Tests (optional)\n^^^^^^^^^^^^^^^^^^^^^^^\n\n   If you want to run the unit tests, you can do the following::\n\n        pip install -r test_requirements.txt\n        cd tests\n        pytest\n\n\nTwo-point Correlations\n----------------------\n\nThis software is able to compute a variety of two-point correlations:\n\n:NN:  The normal two-point correlation function of number counts (typically\n      galaxy counts).\n\n:GG:  Two-point shear-shear correlation function.\n\n:KK:  Nominally the two-point kappa-kappa correlation function, although any\n      scalar quantity can be used as \"kappa\".  In lensing, kappa is the\n      convergence, but this could be used for temperature, size, etc.\n\n:NG:  Cross-correlation of counts with shear.  This is what is often called\n      galaxy-galaxy lensing.\n\n:NK:  Cross-correlation of counts with kappa.  Again, \"kappa\" here can be any scalar\n      quantity.\n\n:KG:  Cross-correlation of convergence with shear.  Like the NG calculation, but\n      weighting the pairs by the kappa values the foreground points.\n\nThere are also additional combinations involving complex fields with different spin\nthan 2 (shear is a spin-2 field).  See `Two-point Correlation Functions\n\u003chttps://rmjarvis.github.io/TreeCorr/_build/html/correlation2.html\u003e`_ for more details.\n\nThree-point Correlations\n------------------------\n\nThis software is not yet able to compute three-point cross-correlations, so the\nonly avaiable three-point correlations are:\n\n:NNN: Three-point correlation function of number counts.\n\n:GGG: Three-point shear correlation function.  We use the \"natural components\"\n      called Gamma, described by Schneider \u0026 Lombardi (2003) (Astron.Astrophys.\n      397, 809) using the triangle centroid as the reference point.\n\n:KKK: Three-point kappa correlation function.  Again, \"kappa\" here can be any\n      scalar quantity.\n\nSee `Three-point Correlation Functions\n\u003chttps://rmjarvis.github.io/TreeCorr/_build/html/correlation3.html\u003e`_ for more details.\n\nRunning corr2 and corr3\n-----------------------\n\nThe executables corr2 and corr3 each take one required command-line argument,\nwhich is the name of a configuration file::\n\n    corr2 config_file\n    corr3 config_file\n\nA sample configuration file for corr2 is provided, called sample.params.\nSee `Configuration Parameters \u003chttps://rmjarvis.github.io/TreeCorr/_build/html/params.html\u003e`_\nfor the complete documentation about the allowed parameters.\n\nYou can also specify parameters on the command line after the name of\nthe configuration file. e.g.::\n\n    corr2 config_file file_name=file1.dat gg_file_name=file1.out\n    corr2 config_file file_name=file2.dat gg_file_name=file2.out\n    ...\n\nThis can be useful when running the program from a script for lots of input\nfiles.\n\nSee `Using configuration files \u003chttps://rmjarvis.github.io/TreeCorr/_build/html/scripts.html\u003e`_\nfor more details.\n\nUsing the Python module\n-----------------------\n\nThe typical usage in python is in three stages:\n\n1. Define one or more Catalogs with the input data to be correlated.\n2. Define the correlation function that you want to perform on those data.\n3. Run the correlation by calling ``process``.\n4. Maybe write the results to a file or use them in some way.\n\nFor instance, computing a shear-shear correlation from an input file stored\nin a fits file would look something like the following::\n\n    \u003e\u003e\u003e import treecorr\n    \u003e\u003e\u003e cat = treecorr.Catalog('cat.fits', ra_col='RA', dec_col='DEC',\n    ...                        ra_units='degrees', dec_units='degrees',\n    ...                        g1_col='GAMMA1', g2_col='GAMMA2')\n    \u003e\u003e\u003e gg = treecorr.GGCorrelation(min_sep=1., max_sep=100., bin_size=0.1,\n    ...                             sep_units='arcmin')\n    \u003e\u003e\u003e gg.process(cat)\n    \u003e\u003e\u003e xip = gg.xip  # The xi_plus correlation function\n    \u003e\u003e\u003e xim = gg.xim  # The xi_minus correlation function\n    \u003e\u003e\u003e gg.write('gg.out')  # Write results to a file\n\nFor more details, see our slightly longer `Getting Started Guide\n\u003chttps://rmjarvis.github.io/TreeCorr/_build/html/guide.html\u003e`_.\n\nOr for a more involved worked example, see our `Jupyter notebook tutorial\n\u003chttps://github.com/rmjarvis/TreeCorr/blob/main/tests/Tutorial.ipynb\u003e`_.\n\nAnd for the complete details about all aspects of the code, see the `Sphinx-generated\ndocumentation \u003chttp://rmjarvis.github.io/TreeCorr\u003e`_.\n\n\nReporting bugs\n--------------\n\nIf you find a bug running the code, please report it at:\n\nhttps://github.com/rmjarvis/TreeCorr/issues\n\nClick \"New Issue\", which will open up a form for you to fill in with the\ndetails of the problem you are having.\n\n\nRequesting features\n-------------------\n\nIf you would like to request a new feature, do the same thing.  Open a new\nissue and fill in the details of the feature you would like added to TreeCorr.\nOr if there is already an issue for your desired feature, please add to the\ndiscussion, describing your use case.  The more people who say they want a\nfeature, the more likely I am to get around to it sooner than later.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmjarvis%2Ftreecorr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frmjarvis%2Ftreecorr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frmjarvis%2Ftreecorr/lists"}