Tutorial ======== Introduction ------------ :mod:`c2raytools` can be used in two ways: either interactively from a Python prompt, or as part of a Python script. Here, we will show how to use it interactively, but the code is of course the same if you use it from a script. Reading files ------------- The most common thing you will want to do is to read data files. :mod:`c2raytools` contains a number of classes for reading xfrac, density, velocity and halo list files. Say you want to read the ionized fraction and density data at some redshift. First, start up your favorite Python interpreter, for example IPython, and import :mod:`c2raytools`: >>> import c2raytools as c2t The first thing you want to do is to set the conversion factors. Since much of the data is stored in physically meaningless simulation units which vary between different simulation runs, :mod:`c2raytools` needs to know how to convert these to physical units. To do this, there is a function called :func:`set_sim_constants`. This function takes as its only parameter the box side in cMpc/h. To specify that you are using the 114/h cMpc simulation, run: >>> c2t.set_sim_constants(114) If this function is not run, the default box size is 114/h cMpc (so in this case, we could in fact have skipped this step, but it's a good habit to always run this function). Sometimes, it is useful to get feedback on what is happening. If you wish, you can turn on verbose mode by running: >>> c2t.set_verbose(True) Now, we can load our ionization fraction file: >>> my_x_file = c2t.XfracFile('/path/to/datafiles/xfrac3d_8.515.bin') and the density file: >>> my_d_file = c2t.DensityFile('/path/to/datafiles/8.515n_all.dat') The objects :class:`my_x_file` and :class:`my_d_file` now hold the data from the files. You can access the ionization fraction and density as the numpy arrays ``xi`` and ``cgs_density``. Since these are numpy arrays, you can of course perform all of numpy's indexing and slicing methods, and calculate simple statistics. For example, here we are printing the ionized fraction in cell (0,10,100) and calculating the mean density in g/cm^3: >>> my_x_file.xi[0,10,100] 0.0305728369737 >>> my_d_file.cgs_density.mean() 4.04777106867e-31 For the full documentation on the file reading routines, see :ref:`reading_files`. Other file formats ------------------ There are also a methods to read and save data from files in a number of other file formats that are commonly used for data derived from C2-Ray output. For example, you can read and save files in cbin format (raw binary with three inital integers specifying the mesh size): >>> data = c2t.read_cbin('myfile.cbin') >>> c2t.save_cbin('myotherfile_64bit.cbin', data, bits=64) You can also read and save files in fits format: >>> c2t.save_fits(data, 'myfile.fits') Visualizing data ---------------- You can of course plot the data you read using your favorite plotting software. For example, if you have :mod:`matplotlib` installed, you can plot a slice through a density cube: >>> import pylab as pl >>> pl.imshow(my_d_file.cgs_density[0,:,:]) >>> pl.colorbar() However, there are also a couple of convenience methods in :mod:`c2raytools` that make the most common plotting tasks easy. One such task is to plot a slice through a data cube. This can be done easily using the function :func:`plot_slice`: >>> c2t.plot_slice(my_x_file) This will produce an image that looks something like this: .. figure:: xi_slice.png :align: center You can give :func:`plot_slice` objects of type :mod:`XfracFile` or :mod:`DensityFile` or a string with the name of a file, and it will figure out what to do with the data. By default, it plots a slice along the first coordinate axis, at a coordinate value of zero. This can be changed with the arguments ``los_axis`` and ``slice_num``. In this example, :func:`plot_slice` will automatically read a density file and plot a slice at y = 10: >>> filename = '/path/to/data/8.515n_all.dat' >>> c2t.plot_slice(filename, los_axis = 1, slice_num = 10) There is also a function called :func:`plot_hist`. This function works similarly to :func:`plot_slice`, but instead plots a histogram of all the values in the data cube. This example reads an xfrac file and plots a histogram of the ionized state of all the cells: >>> c2t.plot_hist('/path/to/datafiles/xfrac3d_8.515.bin') See :ref:`visualization` for the full documentation. Analyzing files --------------- In addition to the file reading routines described above, :mod:`c2raytools` includes many functions to perform common operations and calculate statistics from the data, as well as some cosmology functions. For example, you can calculate the differential brightness temperature from a density file and an xfrac file: >>> dT = c2t.calc_dt(my_x_file, my_d_file) There are also a number of routines for calculating power spectra. For example, to calculate and plot the spherically averaged power spectrum of the ionized fraction, you can run: >>> ps, k = c2t.power_spectrum_1d(my_x_file.xi) >>> pl.loglog(k, ps) >>> pl.xlabel('$k \; (Mpc^{-1}$') >>> pl.ylabel('$P(k) \; (Mpc^3)$') You can also convert data from real space to redshift space: >>> dfile = c2t.DensityFile('/path/to/data/8.515n_all.dat') >>> vfile = c2t.VelocityFile('/path/to/data/8.515v_all.dat') >>> kms = vfile.get_kms_from_density(dfile) >>> distorted = c2t.get_distorted_dt(dfile.raw_density.astype('float64'), kms, dfile.z, los_axis=0, num_particles=20) For more examples on what you can do, and full documentation on the various functions, see the full :ref:`documentation`, or browse through the `index `_. Also have a look at the example scripts included with the module.