----------------------
INTRODUCTION:

This is a public catalogue of voids and superclusters identified in the SDSS DR7 main galaxy and luminous 
red galaxy samples. This version is dated 04.11.2013.

The data samples used and the construction of the catalogues are described in detail in the following 
paper: Nadathur, S. and Hotchkiss, S., "A self-consistent public catalogue of voids and superclusters in 
the SDSS Data Release 7 galaxy surveys" (arXiv:1310.2791).

Any questions/suggestions/complaints regarding the catalogues may be sent to the first author at 
seshadri.nadathur@helsinki.fi.


----------------------
CONDITIONS OF USE:

We make the catalogues available for general use. If you use them for your own work, we ask that you cite the 
original paper given above. 


----------------------
VERSION HISTORY

11.11.2013: Initial release of DR7 catalogue.


----------------------
LAYOUT OF THE CATALOGUE:

The top-level directory contains an example python script called postproc.py, and two folders called
comovcoords and redshiftcoords containing two versions of the catalogue in different coordinate systems. The 
comoving coordinate system is pretty self-explanatory, for a description of the other one please refer to the 
paper.

Note that the version of the catalogue in the folder redshiftcoords IS MADE AVAILABLE FOR COMPLETENESS ONLY! 
If you use it, please be aware of the caveats laid out in the paper. If you are not sure which version of the 
catalogue you want, you probably want the one in comoving coordinates.

The comovingcoords folder contains a further seven directories. Six of these (dim1, dim2, bright1, bright2, 
lrgdim and lrgbright) refer to the galaxy samples used to identify structures, and contain the void and 
supercluster catalogues described in the paper. Each of these directories contains the following ASCII files:

 + [sample_name]_metadata.dat: information on the galaxy sample and tessellation box

 + [sample_name]_positions.dat: galaxy and mock particle position information, and galaxy magnitudes

 + [sample_name]_selecfn.dat: the radial selection function for the sample

 + [sample_name].vol: file containing ZOBOV output galaxy Voronoi volumes from the tessellation

 + [structure_type]_info.txt, [structure_type]_list.txt and [structure_type].void: 9 files (3 each for Type1
     and Type2 voids and Type1 superclusters) with information on position, extent, densities and memberships  
     of structures. Note that the ".void" file ending applies to supercluster files as well!

 + [sample_name].zone: ZOBOV output galaxy membership information for density minima zones

 + [sample_name]_c.zone: the same as above but for density maxima zones (i.e. for clusters rather than voids)

For most purposes, the information contained in these files should be enough. See below for a guide to extracting 
information from them.

The tools folder contains additional files useful for users who would like to build their own catalogues. These 
are:

 + [sample_name]_BasicType_[xxx]: 3 files for each sample (total 18), containing the BasicType void candidates,
    similar to the [structure_type]_info.txt, [structure_type]_list.txt and [structure_type].void files
    in the folders for individual samples
 + [sample_name].txt, [sample_name].void: ZOBOV output files containing the full void hierarchy
 + [sample_name]_c.txt, [sample_name]_c.void: ZOBOV output files containing the full cluster hierarchy 


---------------------
EXTRACTING INFORMATION FROM FILES:

This section explains how to extract information about structures from the given catalogue files. If you want to 
build your own catalogue using the tools folder, see the next section.

 1. The first file to turn to in each sample directory is [sample_name]_metadata.dat, which contains 

  + #gals: the number of galaxies in the sample
  + #bound: the number of mocks around the survey boundary and in holes
  + #tot: total number of particles in the tessellation, including grid particles used for
	stabilisation, #tot = #gals+#bound+#grid
  + Lmax: conversion factor for ZOBOV box coordinates; the tessellation box has side length = 2*Lmax
  + mean_vol_gal: mean volume in (Mpc/h)^3 of galaxy Voronoi cells, calculated as V_sample/#gals
  + mean_vol_tot: mean volume in (Mpc/h)^3 of all Voronoi cells, calculated as (2*Lmax)^3/#tot.

 2. The [sample_name]_positions.dat file contains the positions of each galaxy and boundary mock used 
 in the tessellation (no grid particles). For each particle, the following 10 quantities are provided:

 x, y, z, RA, Dec, redshift, magnitude

 The magnitudes given are M_r for the main galaxy samples and M_g for the LRG samples. x, y, z are the 
 Cartesian coordinates of the particle in units of Mpc/h. Boundary mocks are given redshift -1 and 
 magnitude 0 to aid identification. All galaxy data is obtained from the NYU-VAGC and Eyal Kazin's webpage;
 if you use this data please cite Blanton et al (2005) and Kazin et al (2010).

 3. [sample_name]_selecfn.dat contains 4 columns: zmin, zmax, N and mean_dens. N is the number of 
 galaxies with redshifts lying between zmin and zmax, mean_dens is the mean number density for this bin. 
 Bin widths are chosen to span equal volumes. 

 4. [sample_name].vol contains the Voronoi volumes of all #tot particles in the tessellation, in units 
 of mean_vol_tot. The first #gals+#bound volumes correspond to the particles in the [sample_name]_positions.dat 
 file, in the same order.

 5. [sample_name].zone and [sample_name]_c.zone give the zone membership of galaxies; the _c tag indicates the
 output is for clusters rather than voids. In both cases, the first line is to be read as:

 #non_edge_gals #zones

 and subsequent lines as: 

 particleID# zone#

 where particleID# corresponds to the line in the [sample_name]_positions.dat file (starting counting from 1) 
 for that particle, and zone# is an identifier for the zone it is a member of. Note that edge galaxies are not 
 included.

 6. [structure_type]_info.txt and [structure_type]_list.txt provide some basic details about the positions,
 densities, extents, memberships etc. of structures in the catalogue. The columns should be self-explanatory.
 However, some points should be borne in mind:
  
  + the original ZOBOV hierarchy is now broken to provide a disjoint list of non-overlapping 
    structures as described in the paper, with no double-counting of regions 
  + EdgeFlag has value 1 if the void/cluster is an 'edge' structure, 0 if not (see the paper for 
    details about how these are defined)
  + the core particle number (column 3) uses the C convention that counting starts from 0 - this 
    is different to the convention used in the [sample_name].zone file! 
  + the AvgDens value in the _info.txt file has been calculated as the volume-weighted average 
    density of the Voronoi cells of member galaxies of the structure, after each galaxy density 
    has been expressed in units of the local (redshift-dependent) mean; on the other hand the 
    ZoneAvgDens and VoidAvgDens/ClusAvgDens columns in the _list.txt file are calculated as the
    the number of member galaxies per unit volume, in units of the overall mean sample density
    (i.e. with no redshift-dependence correction)
  
 7. [structure_type].void gives the zone membership and merging information for each structure. This file is
 formatted as the usual ZOBOV output (see also http://skysrv.pha.jhu.edu/~neyrinck/voboz/zobovhelp.html). The 
 first line is the number of structures. Subsequent lines start with the zone# for the seed zone of the 
 structure and then list the number of zones added at the next merging event; the link density for this 
 merging event; and the zone# values for merging zones, for all merging events for that seed zone.

Using these files, you can for instance extract all the member galaxies of a particular structure. The example 
Python script postproc.py (described below) has sections which perform this step, so looking at this may help. 
In case of any other queries or problems, please contact me. 


----------------------
BUILDING YOUR OWN CATALOGUE:

There are two ways in which you might want to construct your own void catalogue from the files in the tools 
folder. 

 1. The first and simplest is by applying various cuts to the catalogues of BasicType void candidates: for instance 
 you may wish to select on the basis of minimum density, effective radius, average density, etc. To do this you need 
 the [sample_name]_BasicType_list.txt and [sample_name]_BasicType_info.txt files. These are exactly equivalent to the 
 corresponding files for Type1 and Type2 voids, so applying these cuts should be easy. If desired, you can also trim
 the [sample_name]_BasicType.void file to match.

 Note that this method DOES NOT allow you to change the rules for merging zones to form voids in any way! So, for 
 e.g., you can use cuts on BasicType candidates to obtain voids matching Type1, but not those matching Type2.

 2. The second option is to build your own catalogue ground-up using the [sample_name].txt and [sample_name].void 
 files in the tools folder (and the [sample_name].zone file described in the previous section). In this way you 
 can apply your own zone-merging conditions as desired. [sample_name].txt contains a list of density minima ('voids') 
 in the ZOBOV output hierarchy. Note that:

   + this file contains the FULL hierarchy, in ascending order of minimum density, with double-counting: this means
     that all 'subvoids' of a given 'void' are also listed again in their own right lower down in the file
   + the minimal conditions rho_min < 1 and rho_link < 1 have already been applied; the first of these reduces the 
     number of listed minima, the second limits the growth of minima through merging
   + the columns containing volume information give these volumes in units of mean_vol_gal

 [sample_name].void is similar to the other .void files described above.

To help you build your own catalogue ground-up we provide the example Python script postproc.py in the root-level 
directory. This script takes as arguments the name of the sample you wish to process, the prefix you wish to give to 
output filenames, the threshold density ratio r_thresh for judging subvoid independence, the minimum density cut 
rho_min_cut, and the maximum merging density limit rho_link_max.

For example, to create a catalogue from the dim1 sample, with r_thresh = 2.0, rho_min_cut = 0.3 and rho_link_max = 
1.0, and to save the output as 'testvoids_info.txt', 'testvoids_list.txt' and 'testvoids.void' in the dim1 folder, 
issue the command

> python postproc.py dim1 test 2.0 0.3 1.0

in the root-level directory. Note that the output catalogue files will always only list disjoint regions (subvoids are
not listed again in their own right).

Minor (and hopefully obvious) changes in the script will allow you also to create your own supercluster catalogues 
using [sample_name]_c.txt and [sample_name]_c.void, or to process the equivalent files in the redshift coordinate 
version of the catalogue.

postproc.py accesses all the member particles of a void and makes use of almost all of the files described above, which 
means it is a useful resource if you want to check how to do any of this yourself. However, please note the health 
warning in the file: the actual catalogue files were produced using code written in Mathematica, and postproc.py is only 
a translation of this. It has been checked to give the correct output for the case of voids in comoving coordinates (the 
default setting), but some changes will be required to apply it to superclusters and/or redshift-coordinates, and these 
have not been checked!

--------------------------