Merge pull request #962 from Christopher-Bradshaw/docs-readthrough

Docs readthrough [WIP]

Author: aphearin

docs/index.rst

@@ -26,6 +26,7 @@ Getting Started
    quickstart_and_tutorials/index
    function_usage/index
    source_notes/index
+   quickstart_and_tutorials/development/index
 
 ***********
 What's New?

docs/quickstart_and_tutorials/development/getting_started.rst

@@ -0,0 +1,49 @@
+.. _getting_started_developers:
+
+*************************
+Contributing to Halotools
+*************************
+
+All halotools development happens in the github repository. To contribute, first clone the repo.
+Then install the dependencies listed on the :ref:`step_by_step_install` page.
+
+
+Code
+====
+
+Halotools contains a compiled component. To compile all cython (``.pyx``) files inplace run, ::
+
+   python3 setup.py build_ext --inplace
+
+If you modify a ``.pyx`` file use the same command to recompile it. Subsequent runs will only compile files whose source has changed and so will be much quicker.
+
+Halotools also has comprehensive unit tests and uses pytest. To run all tests, assuming you are in the base of the repository, first change directory into ``halotools`` and then run ``pytest``. ::
+
+   cd halotools
+   pytest
+
+If you have made a change and only want to run a subset of tests run,  ::
+
+   pytest -k tests_matching_this_string_will_run
+
+Run ``pytest --help`` for a full list of options.
+
+
+Docs
+====
+
+First ensure that the halotools package and sphinx are installed. From the base of the repository run, ::
+
+   pip3 install -e .
+   pip3 install sphinx==1.3.1 # see docs/conf.py for the sphinx version
+
+Then build documentation with, ::
+
+   cd docs
+   make html
+
+You can see the built documentation in ``docs/_build/html/``. The easiest way to view it in your browser is to spin up a local server. One way to do this is to run, from the built directory, ::
+
+   python3 -m http.server
+
+The docs should then be viewable at ``localhost:8000`` (the port will be logged when you start the server).

docs/quickstart_and_tutorials/development/index.rst

@@ -14,5 +14,6 @@ contribute to the Halotools code base.
 
    staying_up_to_date
    bug_reports
+   getting_started
    contributors
    ../../changelog

halotools/empirical_models/abunmatch/bin_free_cam.py

@@ -11,9 +11,14 @@ def conditional_abunmatch(x, y, x2, y2, nwin, add_subgrid_noise=True,
             assume_x_is_sorted=False, assume_x2_is_sorted=False, return_indexes=False):
     r"""
     Given a set of input points with primary property `x` and secondary property `y`,
-    use conditional abundance matching to map new values `ynew` onto the input points
-    such that :math:`P(<y_{\rm new} | x) = P(<y_2 | x)`, and also that
-    `y` and `ynew` are in monotonic correspondence at fixed `x`.
+    and a mapping between that primary property and another secondary property
+    (`y2 | x2`), assign values of the `y2` property to the input points.
+
+    The `y2` that is assigned (`ynew`) is in monotonic correspondence with `y` at
+    fixed `x`. Therefore, :math:`P(<y_{\rm new} | x) = P(<y | x)`.
+
+    See :ref:`cam_tutorial` demonstrating how to use this function in galaxy-halo
+    modeling with several worked examples.
 
     Parameters
     ----------
@@ -24,10 +29,10 @@ def conditional_abunmatch(x, y, x2, y2, nwin, add_subgrid_noise=True,
         Numpy array of shape (n1, ) storing the secondary property of the input points.
 
     x2 : ndarray
-        Numpy array of shape (n2, ) storing the primary property of the desired distribution.
+        Numpy array of shape (n2, ) storing the primary property of the desired distribution. This should be the same physical property (e.g. halo mass) as x.
 
     y2 : ndarray
-        Numpy array of shape (n2, ) storing the secondary property of the desired distribution.
+        Numpy array of shape (n2, ) storing the secondary property of the desired distribution. This is a different physical property to y.
 
     nwin : int
         Odd integer specifying the size of the window
@@ -75,9 +80,6 @@ def conditional_abunmatch(x, y, x2, y2, nwin, add_subgrid_noise=True,
     values of ``window_length`` must exceed 100. Values more tha a few hundred are
     likely overkill when using the (recommended) sub-grid noise option.
 
-    See :ref:`cam_tutorial` demonstrating how to use this
-    function in galaxy-halo modeling with several worked examples.
-
     With the release of Halotools v0.7, this function replaced a previous function
     of the same name. The old function is now called
     `~halotools.empirical_models.conditional_abunmatch_bin_based`.

halotools/empirical_models/abunmatch/noisy_percentile.py

@@ -69,7 +69,7 @@ def noisy_percentile(percentile, correlation_coeff, seed=None, random_percentile
     Returns
     -------
     noisy_percentile : ndarray
-        Numpy array of shape (ngals, ) storing an array such that
+        Numpy array of shape (npts, ) storing an array such that
         the Spearman rank-order correlation coefficient between
         ``percentile`` and ``noisy_percentile`` is equal to the input
         ``correlation_coeff``.

halotools/mock_observables/catalog_analysis_helpers.py

@@ -131,7 +131,7 @@ def return_xyz_formatted_array(x, y, z, period=np.inf,
         galaxy positions under the distant-observer approximation.
         Default is no distortions.
 
-    cosmology : object, optional
+    cosmology : astropy.cosmology.Cosmology, optional
         Cosmology to assume when applying redshift-space distortions,
         e.g., the cosmology of the simulation.
         Default is set in `sim_manager.sim_defaults`.
@@ -264,7 +264,7 @@ def apply_zspace_distortion(true_pos, peculiar_velocity, redshift, cosmology, Lb
         redshift of the snapshot. If using a lightcone, this argument is the
         redshift of each point.
 
-    cosmology : object
+    cosmology : astropy.cosmology.Cosmology
         Cosmology to assume when applying redshift-space distortions,
         e.g., the cosmology of the simulation.
 
@@ -308,9 +308,9 @@ def cuboid_subvolume_labels(sample, Nsub, Lbox):
 
     Nsub : array_like
         Length-3 numpy array of integers indicating how many times to split the volume
-        along each dimension.  If single integer, N, is supplied, ``Nsub`` is set to
+        along each dimension.  If a single integer, N, is supplied, ``Nsub`` is set to
         [N,N,N], and the volume is split along each dimension N times.  The total number
-        of subvolumes is then given by numpy.prod(Nsub).
+        of subvolumes is given by numpy.prod(Nsub).
 
     Lbox : array_like
         Length-3 numpy array definging the lengths of the sides of the cubical volume
@@ -320,7 +320,7 @@ def cuboid_subvolume_labels(sample, Nsub, Lbox):
     Returns
     -------
     labels : numpy.array
-        numpy array with integer labels in the range [1,numpy.prod(Nsub)] indicating
+        (Npts, ) numpy array with integer labels in the range [1,numpy.prod(Nsub)] indicating
         the subvolume each point in ``sample`` occupies.
 
     N_sub_vol : int

halotools/mock_observables/isolation_functions/conditional_cylindrical_isolation.py

@@ -60,7 +60,7 @@ def conditional_cylindrical_isolation(sample1, sample2, rp_max, pi_max,
         If a single float is given, ``rp_max`` is assumed to be the same for each galaxy in
         ``sample1``. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.
 
-    pi_max : float
+    pi_max : array_like
         half the length of cylinders to search for neighbors around galaxies in ``sample1``.
         If a single float is given, ``pi_max`` is assumed to be the same for each galaxy in
         ``sample1``. Length units are comoving and assumed to be in Mpc/h, here and throughout Halotools.
@@ -117,7 +117,7 @@ def conditional_cylindrical_isolation(sample1, sample2, rp_max, pi_max,
     Returns
     -------
     is_isolated : numpy.array
-        array of booleans indicating if each point in `sample1` is isolated.
+        (Npts1, ) array of booleans indicating if each point in `sample1` is isolated.
 
     Notes
     -----

halotools/mock_observables/isolation_functions/spherical_isolation.py

@@ -88,7 +88,7 @@ def spherical_isolation(sample1, sample2, r_max, period=None,
     Returns
     -------
     is_isolated : numpy.array
-        array of booleans indicating if each point in `sample1` is isolated.
+        (Npts1, ) array of booleans indicating if each point in `sample1` is isolated.
 
     Examples
     --------

halotools/mock_observables/large_scale_density/large_scale_density_spherical_annulus.py

@@ -88,7 +88,7 @@ def large_scale_density_spherical_annulus(sample, tracers, inner_radius, outer_r
     Returns
     --------
     number_density : array_like
-        Length-Npts array of number densities
+        Length-Npts1 array of number densities
 
     Examples
     ---------
@@ -105,9 +105,9 @@ def large_scale_density_spherical_annulus(sample, tracers, inner_radius, outer_r
             period, sample_volume, num_threads, approx_cell1_size)
         )
 
-    _ = npairs_per_object_3d(sample, tracers, rbins, period=period,
+    result = npairs_per_object_3d(sample, tracers, rbins, period=period,
         num_threads=num_threads, approx_cell1_size=approx_cell1_size)
-    result = np.diff(_, axis=1)
+    result = np.diff(result, axis=1)
 
     environment_volume = (4/3.)*np.pi*(outer_radius**3 - inner_radius**3)
     number_density = result/environment_volume

halotools/mock_observables/large_scale_density/large_scale_density_spherical_volume.py

@@ -87,7 +87,7 @@ def large_scale_density_spherical_volume(sample, tracers, radius,
     Returns
     --------
     number_density : array_like
-        Length-Npts array of number densities
+        Length-Npts1 array of number densities
 
     Examples
     ---------
@@ -103,9 +103,8 @@ def large_scale_density_spherical_volume(sample, tracers, radius,
             sample, tracers, radius, period, sample_volume, num_threads, approx_cell1_size)
         )
 
-    _ = npairs_per_object_3d(sample, tracers, rbins, period=period,
-        num_threads=num_threads, approx_cell1_size=approx_cell1_size)
-    result = _[:, 0]
+    result = npairs_per_object_3d(sample, tracers, rbins, period=period,
+        num_threads=num_threads, approx_cell1_size=approx_cell1_size)[:, 0]
 
     environment_volume = (4/3.)*np.pi*radius**3
     number_density = result/environment_volume
@@ -123,8 +122,8 @@ def _large_scale_density_spherical_volume_process_args(
     """
     sample = np.atleast_1d(sample)
     tracers = np.atleast_1d(tracers)
-    _ = np.atleast_1d(radius).astype(float)
-    rbins = np.append(_, _[0]+0.0001)
+    rbins = np.atleast_1d(radius).astype(float)
+    rbins = np.append(rbins, rbins[0]+0.0001)
 
     if period is None:
         if sample_volume is None: