[page under construction]

VIDE void catalogs

Outputs directories are organized as follows:

[prefix]_[type]_[setting]/sample_[prefix]_[type]_[setting]_z[redshift]_d[division]

where

[prefix] is your defined prefix for outputs
[type] is either ss for subsampled particles, hod for HOD, or halos for halo catalogs
[setting] subsampling level, minimun halo mass, or HOD name
[redshift] starting redshift of the slice
[division] x- and y- subdivision

The VIDE outputs are as follows:

sample_info.txt: Small text file which lists some basic info of the sample
zobov_slice_[sample_name].dat: Binary file with the galaxy positions, RA, Dec, redshift, and unique catalog ID. Note that this file contains all particles in the particular sample, not just void particles.
voidDesc_[all,central]_[sample_name].out: ASCII file with void indices and basic void properties in ZOBOV-normalized units.
voidZone_[sample_name].out: Binary file which links voids to zones.
voidPart_[sample_name].out: Binary file which links zones to particles.
vol_[sample_name].out: Binary file with particle local volumes

In addition, VIDE provides the following derived void information:

centers_[all, central]_[sample_name].txt: ASCII file with void centers, volume, effective radius, void ID, density contrast, etc.
sky_positions_[all, central]_[sample_name].txt: ASCII file with void RA, dec, effective radius, and void ID
shapes_[all, central]_[sample_name].txt: ASCII file with best-fit eigenvalues and eigenvectors for each void, in same coordinate system as x,y,z values in centers file

In addition to the [all,central] version of each file above, there are four versions of each catalog:

no prefix: only parent voids, density cut applied (default catalog)
untrimmed: all voids in hierarchy, density cut not applied
untrimmed_dencut: all voids in hierarchy, density cut applied [deprecated]
trimmed_nodencut: only parent voids, density cut not applied [deprecated]

We recommend using the included python interface for loading and manipulating the void outputs.

Now that you have a void catalog, you would probably like to analyze it.

All void utilities are available in python via vide.voidUtil.

All these routines handle simulations and observations equally: all proper normalizations etc. are handled behind the scenes, and operationally you should not see any differences.

Note that these routines are able to load and manipulate releases of the Public Cosmic Void Catalog after version 2013.10.15.

Loading the Catalog

#!python

loadVoidCatalog(sampleDir, 
                dataPortion="central", 
                loadParticles=True,
                untrimmed=False)

# loads a void catalog
# by default, loads parent-level voids with central densities less than 0.2*mean
#   sampleDir: path to VIDE output directory
#   dataPortion: "central" or "all"
#   loadParticles: if True, also load particle information
#   untrimmed: if True, catalog contains all voids, regardless of density or hierarchy level

This loading routine only works with the no prefix and untrimmed catalogs, since the other two are trivial to produce and are deprecated.

For example, to list the positions and local volumes of the member particles of void #11:

#!python
import vide.voidUtil as vu

catalog = vu.loadVoidCatalog("path/to/sample", dataPortion="central")
voidID = catalog.voids[10].voidID
macrocenter = catalog.voids[10].macrocenter
voidPart = vu.getVoidPart(catalog, voidID)
for part in voidPart:
  print part.x, part.y, part.z, part.volume

The catalog has the following fields:

sampleInfo Record containing sample information input from void-finding pipeline script (e.g., sampleInfo.fullName to get simulation box dimensions)
numVoids total number of voids
boxLen 3-dimensional array of box lengths in Mpc/h
ranges 3x2-dimensional array of box ranges Mpc/h
volNorm volume normalization used in ZOBOV
voids array of void records. Each record has members
- voidID ZOBOV-assigned void ID
- coreParticle index of most-underdense particle
- coreDens density of core particle, in ZOBOV-normalized units
- numZones number of zones in void
- voidVol void volume, in ZOBOV-normalized units
- numPart number of member particles
- densCon density contrast
- redshift redshift
- radius effective radius of void in Mpc/h
- macrocenter volume-weighted center
- RA right ascension
- Dec declination
- centralDen density within 1/4 effective radius
- parentID void ID of parent, -1 if no parent
- treeLevel level in hierarchy, starting with 0 for top-most voids
- numChildren number of child sub-voids
- ellipticity ellipticity
- eigenVals array of eigenvalues
- eigenVecs 3x3 array of eigenvectors

If loadParticles = True, the catalog will also contain

numPartTot total number of particles
numZonesTot total number of ZOBOV zones
partPos array of particle positions
void2Zones Linked list matching voids to member zones
zones2Parts Linked list matching zones to member particles
part array of particle records. Each record has members
- x x-coordinate
- y y-coordinate
- z z-coordinate
- volume local volume in ZOBOV-normalized units
- ra Right Ascension
- dec Declination
- redshift Redshift
- uniqueID If available, a unique integer assigned to the particle

There is also an interface for placing particles in a k-d tree and extracting particles within a ball (e.g., within Reff of one of the above voids):

#!python
import vide.voidUtil as vu

catalog = vu.loadVoidCatalog("path/to/sample", dataPortion="central")
partTree = vu.getPartTree(catalog)
center = catalog.voids[10].macrocenter
radius = catalog.voids[10].radius
localInd = vu.getBall(partTree, center, radius)

localPart = catalog.partPos[localInd]

The record elements can be converted into numpy arrays using this helper function:

getArray(objectList, 
         attr)

# returns numpy array from objectList with given attribute
#   objectList: either catalog.voids or catalog.part
#   attr: a string naming the record
#
#   example: radii = getArray(catalog.voids, 'radius')

Filtering

You may wish to filter voids on some property. We provide routines for a few common filters. All these filters return a new catalog object with the filtered voids list.

filterVoidsOnSize(catalog, rMin) returns voids larger than rMin
filterVoidsOnTreeLevel(catalog, level) returns voids at specified level. Set to 0 for top-level voids only, -1 for children voids only
filterVoidsOnCentralDen(catalog, maxCentralDen) returns voids with density less than given central density
filterVoidsOnCoreDen(catalog, maxCoreDen) returns voids with density less than given core (i.e., minimum) density
filterVoidsOnDenCon(catalog, minDenCon) returns voids with density contrast larger than given density constrast

Plotting

#!python

plotNumberFunction(catalogList,
                   figDir="./",
                   plotName="numberfunc",
                   cumulative=True,
                   binWidth=1)

# plots a cumulative number function
#   catalogList: list of void catalogs to plot
#   figDir: output directory for figures
#   plotName: name to prefix to all outputs
#   cumulative: if True, plots cumulative number function
#   binWidth: width of histogram bins in Mpc/h
# returns:
#   numberFuncList: array of len(catalogList), 
#                   each element has array of size bins, number, +/- 1 sigma

#!python

plotEllipDist(catalogList,
              figDir="./",
              plotName="ellipdist")

# plots ellipticity distributions
#   catalogList: list of void catalogs to plot
#   figDir: output directory for figures
#   plotName: name to prefix to all outputs
# returns:
#   ellipDistList: array of len(catalogList), 
#                  each element has array of ellipticity distributions

#!python

plotVoidCells(catalog,
              voidID,
              figDir="./",
              plotName="cells",
              plotDensity=True,
              sliceWidth=250)

# plots the particles belonging to a void
#   catalog: void catalog
#   voidID: ID of void to plot
#   figDir: output directory for figures
#   plotName: name to prefix to all outputs
#   sliceWidth: width of slice in Mpc/h

Cross-comparison

#!python

compareCatalogs(baseCatalogDir, 
                compareCatalogDir,
                outputDir="./", 
                logDir="./", 
                matchMethod="useID", 
                dataPortion="central",
                strictMatch=True, 
                overlapFrac=0.25,
                pathToCTools="../../../c_tools")

# reports the overlap between two void catalogs
#   baseCatalogDir: directory of catalog 1
#   compareCatagDir: directory of catalog 2
#   outputDir: directory to place outputs
#   logDir: directory to place log files
#   matchMethod: "useID" to use unique IDs, "prox" to use overlap of Voronoi cells
#   overlapFrac: threshold fraction of Voronoi radius to count as matched
#   dataPortion: "central" or "all"
#   strictMatch: if True, only attempt to match to trimmed catalog
#   pathToCTools: path to location of VIDE c_tools directory

#!python

computeXcor(catalog,
            figDir="./",
            Nmesh = 256,
            Nbin = 100):

# Computes and plots void-void and void-matter(galaxy) correlations
#   catalog: catalog to analyze
#   figDir: where to place plots
#   Nmesh: number of grid cells in cic mesh-interpolation
#   Nbin:  number of bins in final plots

Density Profiles

#!python

stackVoids(catalog, 
           stackMode = "ball")

# builds a stack of voids from the given catalog
#   catalog: void catalog
#   stackMode:
#     "ball": spherical cut
#     "voronoi": only void member particles
#
# returns:
#   stackedPart: array of relative particle positions in the stack

#!python

buildProfile(catalog, 
             rMin, 
             rMax,
             nBins=10)

# builds a stacked radial density profile from the given catalog
#   catalog: void catalog
#   rMin: minimum void radius, in Mpc/h
#   rMax: maximum void radius, in Mpc/h
#   nBins: number of bins in profile (default 10)
#
# returns:
#   binCenters: array of radii in binned profile
#   stackedProfile: the stacked density profile
#   sigmas: 1-sigma uncertainty in each bin

#!python

fitHSWProfile(radii, 
              densities, 
              sigmas, 
              rV)

# fits the given density profile to the HSW function
#   radii: array of radii
#   densities: array of densities in units of mean density
#   sigmas: array of uncertainties
#   rV: mean effective void radius
# 
# returns:
#   popt: best-fit values of rs and dc
#   pcov: covariance matrix
#   rVals: array of radii for best-fit curve
#   hswProfile: array of densities for best-fit curve in units of mean density

#!python

getHSWProfile(density, 
              radius)

# returns the HSW profile for the given sample density and void size
#   will interpolate the radius from measured values

#  density: choice of sample (see arXiv:1309.5087):
#           maxDM: DM at 1 particles per cubic Mpc/h
#           fullDM: DM at 0.01 particles per cubic Mpc/h
#           denseDM: DM at 4.e-3 particles per cubic Mpc/h
#           sparseDM: DM at 3.e-4 particles per cubic Mpc/h
#           
#           denseHalos: halos at 4.e-3 particles per cubic Mpc/h
#           sparseHalos: halos at 3.e-4 particles per cubic Mpc/h
#          
#           denseGal: galaxies at 4.e-3 particles per cubic Mpc/h
#           sparseGal: galaxies at 3.e-4 particles per cubic Mpc/h
#
#  radius: void size in Mpc/h

# returns:
#   (rs, dc): best-fit values
#   binCenters: array of radii in binned profile
#   stackedProfile: the density profile

Wiki

vide_public / Void Catalogs & Analysis