Quickstart¶
Running a task¶
In pyBBarolo, BBarolo’s task are wrapped as python classes. The generic procedure to run a task is as follow:
Import the task from pyBBarolo module:
from pyBBarolo import Task
where Task is one of pyBBarolo tasks.
Create an object of the task class:
bb = Task(fitsname)
where fitsname is the input FITS file. All tasks need an initial FITS file.
Initialize the task:
bb.init(args)
where args are required arguments that depend on the various tasks. Required arguments can be printed with:
bb.show_arguments()
Set options:
bb.set_options(opts)
where opts are the task-dependent available options. All options have default values, so this step is not mandatory. To see a list of available options:
bb.show_options()
Run the task:
bb.compute()
Available tasks¶
FitMod3D(): wrapped class for BBarolo’s 3DFIT task.
GalMod(): wrapped class for BBarolo’s GALMOD task.
Search(): wrapped class for BBarolo’s SEARCH task.
FitMod2D(): wrapped class for BBarolo’s 2DFIT task.
Ellprof(): wrapped class for BBarolo’s ELLPROF task.
SpectralSmooth(): wrapped class for BBarolo’s SMOOTHSPEC task.
Example 1: 3D fit of a galaxy¶
Suppose you have an astonishing observation of your favorite galaxy and you want to fit a 3D kinematic model to your emission line datacube.
Let’s fit the HI datacube of NGC 2403, which is available as a part of BBarolo’s working examples. We just have to set initial conditions, options and then run the task.
First of all, we import and start FitMod3D:
from pyBBarolo import FitMod3D
# FITS file of the galaxy to model
filen = "./examples/ngc2403.fits"
# Initializing a 3DFIT object
f3d = FitMod3D(filen)
Secondly, we initialize rings with initial guesses for the fit:
# Initializing rings. Parameters can be values or arrays
f3d.init(radii=np.arange(15,1200,30),xpos=77,ypos=77,vsys=132.8,vrot=120,vdisp=8,vrad=0,z0=10,inc=60,phi=123.7)
A list of needed arguments can be printed with f3d.show_arguments().
Thirdly, we can change some default options for the fit. For a list of available options: f3d.show_options().
For instance, we can set a mask made through the source-finding algorithm (mask="SEARCH"), parameters to fit (free="VROT VDISP"), the distance of the galaxy in Mpc (distance=3.2) and the directory for outputs (outfolder='output/ngc2403):
f3d.set_options(mask="SEARCH",free="VROT VDISP",wfunc=2,distance=3.2,outfolder='output/ngc2403')
If the beam information is not available in the FITS header, it is fundamental to set the size of the beam:
f3d.set_beam(bmaj=60,bmin=60,bpa=-80)
It is now time to run the fit:
bfrings, bestmod = f3d.compute(threads=4)
This function performs the fit and writes relevant FITS files in the output directory. The function returns a n x m matrix containing the best-fit rings (bfrings), where n = number of rings and m = number of parameters, and a FITS astropy object (bestmod) containing the best-fit model. These are also written in bfit and outmodel methods of FitMod3D class.
Finally, we can use BBarolo built-in routines to write plots of data and model, like channel maps, moment maps, position-velocity diagrams and best-fit parameters:
f3d.plot_model()
Example 2: 3D model of a galaxy¶
It is also possible to simply build a 3D model datacube from given parameters. This is accomplished with the GalMod task. The procedure is similar to the one above:
from pyBBarolo import GalMod
# FITS file of the galaxy to model
filen = "./examples/ngc2403.fits"
# Initializing a GalMod object
gm = GalMod(filen)
# Initializing rings. Parameters can be values or arrays
gm.init(radii=np.arange(15,1200,30),xpos=74,ypos=74,vsys=132.8,vrot=120,vrad=10,vvert=5,vdisp=8,z0=10,inc=60,phi=123.7)
# Now, let's take a look to the default options (see BB documentation)
gm.show_options()
# Changing some options
gm.set_options(ltype=1)
# Compute the model
mymodel = gm.compute()
# Smooth to the same resolution of data
mymodel = gm.smooth()
# mymodel is an astropy cube and we can do whatever we like with it.
mymodel.writeto("awesome_model.fits",overwrite=True)
Example 3: All tasks¶
This script shows how to use all wrapped classes:
import os
import numpy as np
from pyBBarolo import *
if __name__ == '__main__':
fitsname = "./examples/ngc2403.fits"
#'''
### 3D FIT TUTORIAL ############################################################
f3d = FitMod3D(fitsname)
f3d.init(radii=np.arange(15,450,30),xpos=77,ypos=77,vsys=132.8,\
vrot=120,vdisp=8,vrad=0,z0=10,inc=60,phi=123.7)
f3d.show_options()
f3d.set_options(mask="SEARCH",free="VROT VDISP",wfunc=2,distance=3.2,ltype=2)
f3d.set_options(outfolder="output/ngc2403")
f3d.set_beam(bmaj=60,bmin=60,bpa=-80)
bfrings, bestmod = f3d.compute(threads=4)
f3d.plot_model()
################################################################################
#'''
#'''
### GALMOD TUTORIAL ############################################################
gm = GalMod(fitsname)
gm.show_arguments()
gm.init(radii=np.arange(15,1200,30),xpos=74,ypos=74,vsys=132.8,\
vrot=120,vdisp=8,z0=10,inc=60,phi=123.7)
gm.show_options()
gm.set_options(ltype=1)
mymodel = gm.compute()
mymodel = gm.smooth()
mymodel.writeto("awesome_model.fits",overwrite=True)
################################################################################
#'''
#'''
### ELLPROF TUTORIAL #############################################################
el = Ellprof(fitsname)
el.show_arguments()
el.init(radii=np.arange(15,1200,30),xpos=74,ypos=74,inc=60,phi=123.7)
el.show_options()
el.set_options(mask="SMOOTH")
rings = el.compute()
print (rings['rad'],rings['msurfdens'])
el.writeto("rings_ellprof.txt")
################################################################################
#'''
#'''
### 2DFIT TUTORIAL #############################################################
rm = FitMod2D(fitsname)
rm.show_arguments()
rm.init(radii=np.arange(15,1200,30),xpos=74,ypos=74,vsys=132.8,vrot=120,inc=60,phi=123.7)
rm.show_options()
rm.set_options(wfunc=1, free="VROT INC")
rings = rm.compute(threads=1)
print (rings['rad'],rings['vrot'])
rm.writeto("rings_2dfit.txt")
################################################################################
#'''
#'''
### SEARCH TUTORIAL ############################################################
s = Search(fitsname)
s.set_options(growth=True)
s.show_options()
s.search(threads=4)
################################################################################
#'''
#'''
### SPECTRAL SMOOTHING TUTORIAL ################################################
s = SpectralSmoothing(fitsname)
a = s.smooth(window_type='hanning',window_size=11,threads=8)
s.writeto("smoothedcube.fits",average=True)
################################################################################
#'''
pyBBarolo for PROs¶
Beside the python classes described above, there is probably a better way to run BBarolo from python for users who are familiar with BBarolo’s parameter files. A class BBaroloWrapper to call conveniently BBarolo C++ executable is implemented in the pyBBarolo.wrapper module. This class allows the user to set any parameter supported in BBarolo and it is extremely useful for scripting.
The BBaroloWrapper class takes in input a list of BBarolo’s parameters, which can be given as either a python dictionary or a list of strings. The class is basically a container of parameters. A working example is below:
from pyBBarolo.wrapper import BBaroloWrapper
# Initializing class (doing some spatial smoothing for example)
bb = BBaroloWrapper(fitsfile='./examples/ngc2403.fits',smooth=True,bmaj=120,bmin=120)
# Parameters can alternatively be given as a list of strings or dictionary
# bb = BBaroloWrapper(['FITSFILE=./examples/ngc2403.fits','SMOOTH=True','BMAJ=120','BMIN=120'])
# bb = BBaroloWrapper(dict(fitsfile='./examples/ngc2403.fits',smooth=True,bmaj=120,bmin=120))
# Parameters can also be added or removed
bb.add_options(threads=8,outfolder='myoutfolder')
bb.remove_option('threads')
# Parameters can be printed or easily be written in a parameter file
print (bb)
bb.write_parameterfile("param.par")
# Now we can run BBarolo
bb.run(exe="/path_to_BBarolo/BBarolo",stdout=None)
The above is exactly the same as calling BBarolo with a parameter file, thus it will write all the outputs in the usual output folder. The run() function above takes in input two optional parameters, exe and stdout. The former is your local BBarolo binary (if not given, it will search in your $PATH). The latter is where to write BBarolo’s messages: if None or not given, BBarolo will print messages on the command line, if 'filename.log' it will write everything in a file filename.log , if 'null' no output message will be written.
NB 1: Parameter names given to BBaroloWrapper are not case sensitive.
NB 2: No check is performed on the given parameters. If a parameter does not exist in BBarolo, it will just be ignored.