In this section you will find everything you need to know to run BUDDA smoothly to obtain the structural parameters of your galaxy, as well as residual images. While simple to use, BUDDA also has many small and important details you should be aware of; read this section carefully for it is full of valuable hints, until you've mastered all of our code's intricacies. Here is a step by step recipe:
 
 

• Preparing your galaxy image

• This must be already fully reduced, which includes, at least, bias subtraction, flat-fielding, sky subtraction and removal of Galactic stars, bright HII regions and nearby companions. If you want to do something more (e.g., fringe correction), this is the time to do it! A note on sky subtraction: it is a good idea to remove any spatial dependence of the sky level in your galaxy image. However, for a proper evaluation of the noise level it is better to keep a constant sky level. Then you can tell this value to BUDDA in the galaxy.dat file (see below). For bright galaxies and optical images this might make little difference, but this might not be the case for, e.g., near-infrared images.
• Your image must take the whole galaxy (or the most you can!) but don't make it much larger than that, so that you won't be loosing time and memory with sky pixels.
• Now it's time to transform your galaxy image into a matrix in which each line/column is a pixel of your CCD and has its corresponding value. You can do this with the task WTEX within IRAF (only pixels, not the header!). The name of the file so created MUST be ximag.pix.

• Getting the model

• Firstly, you should prepare an ASCII file which MUST be named galaxy.dat. This file (you may download a copy of it at the "How to get it" section - it will be useful to have a look at it now before you continue) contains the information used by BUDDA to search for the model that best fits your galaxy. Essentially, it tells the code what are your first guesses for the structural parameters, plus additional information on your image and on how you which the code to run. Preparing this file with care is crucial to get good results, so read these lines carefully!!! All values related to lengths are in pixel units. If you are running versions older than the 2.1 then intensities should be put in counts and normalized by the area of your pixels in arcseconds. However, in version 2.1 this has changed and there is no more need to perform this normalization, i.e., intensities should be put in counts (DN), purely. In this way you can work on the model images exactly as you do with your science images. The file is pretty much self-explanatory, but some considerations follow. In the first line you should put the size of your image in pixels and it MUST NOT exceed 5000 x 5000 (but if you really need to run BUDDA in images larger than this, we can easily make a version just for you, so let us know!).
• In lines 3 to 33 you should also put an "error" to the parameter. This is not exactly an error on your first guess, but this tells BUDDA how much the corresponding parameter shall be modified between each iteration in the search for the best fit. Normally, you should put something like 10%-20% of the parameter value, except in the cases noted below.
• In lines 3 and 4 you tell what are the coordinates of the center of your galaxy. Since this is easily done with accuracy the error should be something like 1 pixel or less (or even kept fixed). For instance, you can use the task IMEXA in IRAF to measure these coordinates. Note, however, that the way IRAF counts pixels is different from the way BUDDA does. The origin of a pixel in IRAF is at the bottom-left corner of the pixel, whereas for BUDDA it is at the pixel center. So if you measure, e.g., center coordinates with IRAF as 124.5 126.3 for x and y pixels, respectively, you should tell BUDDA in the galaxy.dat file that the central coordinates are 124.0 125.8.
• The disk characteristic radius is the h in the exponential profile. It is the radius at which the disk magnitude is higher than its central value by 1.086. The bulge effective magnitude is its central magnitude plus 8.325, and its effective radius is the radius at which the bulge profile reaches this (effective) magnitude. This is considering a de Vaucouleurs profile (i.e., a Sérsic index of 4).
• The errors for the position angles and ellipticities also should be lower or kept fixed. For the angles we usually use 1 degree and, for the ellipticities, 0.01 or less. The angles run from 0 at the right side of your image, counterclockwise, so that 90 is up (note that this is different from e.g. the ELLIPSE task in IRAF, in which 0 is up!).
• In line 12, the value for the height-scale of the disk should read 0 for face-on galaxies (all cases except edge-on or very close to it; in dubious cases one should try both). For face-on galaxies you must fix this value in 0. This is done, like in any other parameter, by putting its error to 0. Vertically, the disk model goes as sech² (z/z0), where z0 is your height-scale. Note that for edge-on galaxies the disk position angle MUST be zero, i.e., you must rotate your galaxy image to comply with this restriction.
• The ellipse indices of bulge, disk and bar may be allowed to vary to obtain boxy or disky isophotes; fixed to 1 constrain them to pure ellipses. Bars of course have to be boxy (with an ellipse index of about 1.6-1.8). Note that these indices are very hard to be fitted by the code so be careful! Another important note: the boxyness parameter c, as defined in Gadotti (2008), is actualy 1.0 + the ellipse index!
• Remember that a Sérsic profile with index of 4 is a de Vaucouleurs profile and if equals to 1 it is an exponential profile.
• If the lambda interaction factor is 2, it is telling BUDDA to vary the parameters' values by a factor of 2 of the corresponding error. This is our fiducial value but you may want to try different ones.
• The tolerance on chi² variation controls the convergence of the code. When it is below some threshold (e.g. 0.001) the code stops, happy with the solution found, and starts calculating the errors.
• The convolution flag should be always kept as 1, unless for testing purposes of course. The Sérsic index is the parameter which is most disturbed by seeing. It is a good practice to try to find a good estimate for it as first guess and let it varied very slowly (say, with an "error" of about 0.1 or so).
• The luminosity fractions displayed at the end of each iteration are seeing convolved fractions and this affects primarily the bulge, which will appear as responsible for a smaller fraction of the model.  You'll get however exact, deconvolved fractions in the final output (the file galaxy.out, see below).
• The maximum semi-major axis is the radius up to which pixels are considered in the fit. Be sure that all pixels you want to be fitted are within this radius. Most times this can just be larger than your image size.
• The saturation constant usually is set to a very high value so that it does no harm at all. However, one could use it to e.g. not allow that non-stellar emissivity from an AGN be considered in the analysis. By now, you don't have to worry about the last line, regarding the final chi². Be aware that trying to fit components that are not actually in the galaxy certainly leads to wrong results. Check carefully whether or not your model needs, say, a central source.
• Having set up ximag.pix and galaxy.dat, it's time to run GMODEL. Just type in  BUDDA_GMODEL. The code starts running and prints some useful information, then starts looking for the best fit and, at each iteration, displays more useful information. Here you can check how convergence is going. You can check the chi² value and its variation at each iteration (when it is below the threshold you set up convergence is reached). For each of the structural parameters you can see what BUDDA is finding to be the best value. "Var" displays the actual "error" value. The "Chi2-" and "Chi2+" tell you how much chi² changes by changing the value of the corresponding parameter using the "Var" value. The lesser of these two numbers indicates which direction BUDDA is taking. I.e., if "Chi2-" is less than "Chi2+" the corresponding parameter is heading towards lower values. "Int" tells you if the parameter is around a minimum, in this case displaying "Parabo", or not, in this case displaying "Extrem".
• At this stage you will see if you have created the required files accordingly. If, for instance, BUDDA converges too quickly (less than, say, 3 iterations) and with unreasonable results, then something must be wrong in galaxy.dat or in ximag.pix. Check and run the code again. This is the same if it goes to negative intensity values. In the later case, if it is an elliptical galaxy and the disk intensities are going below zero, then you may be just finding that it is indeed an elliptical galaxy with no disk component, but more trial is advised to really be sure. Note that the code may converge to very small values for the disk intensity and this case also may be of a pure spheroid. Negative values for the angles are allowed.
• After running GMODEL completely this may not yet be the end. Sometimes you can get better results running the code several times with different values in the parameters of galaxy.dat. You MUST avoid local chi² minima!!! So change the parameters and run the code again. Most of the times it will go again to the results found before, since it is efficient in finding the global minimum, but you have to check this out! This is why at this point you should pay attention to the results BUDDA displays at the end of each iteration to: (i) understand what it is doing to get the best fit (e.g., is it raising the central surface brightness of the disk? Lowering the effective radius of the bulge? Changing its ellipticity?) so that you can give better input values if you need to run it again; and (ii) check if for some reason something is wrong.
• After finding the best fit, it's time for the error evaluation. We have made this part of the algorithm very conservative so don't be worried about very large errors. The code is precise in finding the right parameters as attested by our tests. Fiducial error values are found in our main paper. What can happen sometimes is the code getting stuck in the evaluation of the errors. In this case, you may run the code again changing a few parameters. If that doesn't work, fix the parameter value putting an "error" value of 0, using the value BUDDA found for the parameter which is causing trouble. This does not mean there's something wrong with your result, it's just because the particular error evaluation is troublesome.
• A full run of GMODEL may take from a few minutes to a few hours, depending, of course, on your machine, but also on the size of your image in pixels, and, to a lesser extent, on how right (or wrong) are your guesses in galaxy.dat.

• Building the model

• First of all, check if you have the same version for both GMODEL and BMODEL binaries.
  
• At the very end of its run, GMODEL writes down an ASCII file named model.dat that contains all the structural parameters of your galaxy found by our code. It is similar in structure to galaxy.dat but now the first guess you've put for a parameter (e.g., the disk central intensity) is replaced by its real value; and the "errors" are truly the errors found. Now you can also check what is the final chi² at the last line. Note that you'll get low values as ~ 1 only for galaxies with a smooth luminosity distribution, like ellipticals and lenticulars, without e.g. prominent spiral arms and star forming regions. For late-type galaxies as Scs for instance the values for chi² can be as high as a few tens. This does not mean at all that BUDDA was not able to find accurately the structural parameters, but that your galaxy might need more than just the normal/large/well-studied components to be entirely fitted. You may stop here if you're only interested in the structural parameters. Or you can get even more by running BMODEL and build a synthetic image of your galaxy as well as of the different components separately.
• Before running BMODEL you have to tell it what are the parameters GMODEL found for your galaxy. To this end you need to write again galaxy.dat but now with the values found by BUDDA. The easiest way to do so is the following. Move model.dat into galaxy.dat (only type in mv model.dat galaxy.dat).
• Now all you need to do is run BMODEL, by just typing BUDDA_BMODEL. In a minute or so (typically) you'll have six new files:

 
• galaxy.out: an ASCII file with the full BUDDA results, similar to model.dat, but also having the luminosity ratios;
• xgal.txt: the synthetic image of your galaxy in text format;
• xbulge.txt: the synthetic image of the bulge of your galaxy in text format;
• xdisk.txt: the synthetic image of the disk of your galaxy in text format;
• xbar.txt: the synthetic image of your bar in text format;
• xagn.txt: the synthetic image of your central source in text format.

 
• Convert the synthetic images from text to image formats within IRAF with the RTEX task.
• That's it! You're done! Now you have not only the structural parameters that best describe your galaxy and its different components but also model images of it, and it's not hard to find out the good science you can do with these data...

• Examples

• Look how accurately BUDDA fits IC 1459, a lenticular galaxy with a Liner nucleus. The left panel below shows a R CCD image of this galaxy taken at the Pico dos Dias Observatory (OPD - LNA/CNPq - Brasil) with isophotal contours spaced 0.5 magnitudes. The image at right is the residual image, built dividing the original image by the model image made by BUDDA. It is displayed at high contrast and still there's almost nothing left! We can only see an excess of light in the nucleus, which is in part caused by seeing effects, but mostly from its non-stellar activity, and a very faint lens. The graphs in the bottom show that BUDDA was able to fit very well the surface brightness profile as well as other relevant structural properties of the galaxy.

 

The radial profiles of surface brightness, position angle, ellipticity and the b4 Fourier component for the real galaxy (points with error bars) and for the synthetic one (solid lines). The dotted and dashed lines show, respectively, the surface brightness profiles of the disk and bulge components. The lower solid line with points in the upper left panel is the difference between the real galaxy and the synthetic one plus 28 magnitudes. The radius a is in units of 0.57 arcsecond pixels.

 
• Now, see BUDDA revealing inner spiral arms in the Liner SBa(rs) galaxy NGC 4314. Can it be responsible for fueling its active nucleus? The left panel below shows a V CCD image of this galaxy taken at the Kuiper telescope of the Steward Observatory, whereas the right image is the residual image. Note that the bulge and disk were removed and we are left with anything else the galaxy contains. Which is, in this case, a strong bar, spiral arms and the surprisingly well defined inner spirals. BUDDA was able to find several examples like this, including inner rings and bars (see our Publications).