We provide a simple example to test TiRiFiC and to have a first hands-on on this page.
We provide a few default files for TiRiFiC, which represent a series of fitting procedures to a real data cube, and with that describe a possible strategy to parametrise a real galaxy with TiRiFiC. We also provide a copy of one of the default files with keyword links on this web page.
| Contents: |
We provide a toy example of how one might parametrise a galaxy HI observation. The strategy is very simple. We first make a restricted fit, only fitting a few parameters, to then freeze out more and more fitting parameters in consecutive steps, until a moderately good fit is achieved.
| File | Category | Remarks |
| eso121-g6.fts | Input data cube, converted to FITS format | The observation to fit (ATCA HI data cube of ESO 121-G6) |
| eso121-g6_in_first_input.def | TiRiFiC default file | Test file, first guess |
| eso121-g6_out_first_input.fts | FITS data cube | Output of run first_input, converted to FITS format |
| eso121-g6_in_00.def | TiRiFiC default file | Fit tilted-ring model with radially constant parameters |
| eso121-g6_out_00.fts | FITS data cube | Output of run 00, converted to FITS format |
| eso121-g6_in_01.def | TiRiFiC default file | Fit tilted-ring model with radially independent parameters |
| eso121-g6_out_01.fts | FITS data cube | Output of run 01, converted to FITS format |
| eso121-g6_in_02.def | TiRiFiC default file | Fit tilted-ring model, surface brightness independent for two half disks |
| eso121-g6_out_02.fts | FITS data cube | Output of run 02, converted to FITS format |
| eso121-g6_in_03.def | TiRiFiC default file | Fit tilted-ring model for a larger disk than before |
| eso121-g6_out_03.fts | FITS data cube | Output of run 03, converted to FITS format |
| eso121-g6_in_04.def | TiRiFiC default file | Last fit, adjusting inclination at large radii |
| eso121-g6_out_04.fts | FITS data cube | Output of run 04, converted to FITS format |
| tirific_example.tar.gz | Archive containing all files above | Extracts into directory tirific_example, containing all files above |
As a first step, install TiRiFiC, then download either the single files listed in the table above or the archive tirific_example.tar.gz, which extracts into the directory tirific_example, containing all files listed above.
If you only want to test whether TiRiFiC is working properly, enter the directory and type (assuming the binary tirific to be somewhere in your binary search path).
>tirific deffile = eso121-g6_in_first_input.def
You should be prompted to enter GR_CONT. Press the Return button. TiRiFiC should stop without an error message. You should find the output file eso121-g6_out_first_input.fts (TiRiFiC output data cube) and the Postscript file eso121-g6_out_first_input.ps. You have started TiRiFiC not to perform any fitting, but only to produce an output model cube according to the parameters in the default file.
To proceed with the example, look at the data cube, e.g. with the Karma task kvis, and compare it with the input data cube. Look at the viewgraph eso121-g6_out_first_input.ps. While the model is far from representing the galaxy, it is matching some part of the observation, which is enough for a start. By reading the file eso121-g6_in_first_input.def with a suitable text editor, you will find a nearly identical file as the first input file eso121-g6_in_00.def. The only differences are the output parameters , TIRDEF, GR_DEVICE, and the number of fitting loops LOOPS. A copy of the default file eso121-g6_in_00.def with links to the keyword descriptions can be found below.
The strategy followed to reach a final fit to the eso121-g6 observation was to make a TiRiFiC fit, producing an output default file (always called eso121-g6_out_ii.def, where ii is the fit number, starting with 00. Each output default file (containing the results of the fit as geometrical input parameters) was edited to upgrade the modelling strategy and to adjust a few geometrical parameters. All changes were commented (look for the '#'-symbol in the default files), then saved as the next input default file (eso121-g6_in_jj.def, where jj = ii + 1). These input default files are provided in the table above. To reconstruct this procedure, type
>tirific deffile=eso121-g6_in_00.def
TiRiFiC stops (type the return key when prompted for the parameter GR_CONT) eventually. In the first fitting process (eso121-g6_in_00.def), all parameters are fitted not varying with radius. Comparing the output data cube (eso121-g6_out_00.fts) to the input, one can see that the rotation velocity is well adjusted, and the galaxy centre has been found. In the second step, some parameters are made variable with radius. Have a look at the file eso121-g6_in_01.def, which is a copy of the file eso121-g6_out_00.def, which you should find on your disk. Some keywords have been changed, you can search them with a text editor, looking for the '#' symbol.
>tirific deffile=eso121-g6_in_01.def
Let TiRiFiC fit. Have a look at the plot with the fitting results (eso121-g6_01.ps), then compare the output data cube (eso121-g6_out_01.fts) to the input data cube (eso121-g6.fts). Not perfect, but better. In a next step, we "correct" the surface brightness of the first two rings for the input, and fit the surface brightness independently for each side independently. Also, we now allow the rotation velocity to vary independently for each ring. As we can already see that our model is too restricted in radius, the next output default file will have some additional rings (compare eso121-g6_01_out_01.def with its edited copy eso121-g6_01_in_02.def).
>tirific deffile=eso121-g6_in_02.def
After fitting, look at the plot with the fitting results (eso121-g6_02.ps) and compare the output data cube (eso121-g6_out_02.fts) to the input data cube (eso121-g6.fts). The velocity is a bit high at a radius of 0 arcsec, and a bit wobbly beyond the 9th ring. So we adjust the rotation velocity in the file eso121-g6_out_02.def to create a new input default file eso121-g6_in_03.def (on your disk now). We adjust the VARY and the VARINDX parameter, to account for the fact that the number of rings has increased. Also, in the next fit, for rings beyond ring 9, we sample rotation velocity and surface brightness coarser than for the inner disk. This ensures a more stable fit.
>tirific deffile=eso121-g6_in_03.def
After fitting, look at the plot with the fitting results (eso121-g6_03.ps) and compare the output data cube (eso121-g6_out_03.fts) to the input data cube (eso121-g6.fts). The only thing to maybe object is an instable inclination at larger radii. We adjust the VARINDX parameter in the file eso121-g6_out_03.def (on your disk now) to create a new input default file eso121-g6_in_04.def, to take out the inclination of ring 13 as a variable parameter.
>tirific deffile=eso121-g6_in_04.def
After fitting, enjoy the result. With some care, one might achieve better results. Clearly, ESO 121-G6 is a spiral galaxy, so maybe an improvement can be made by not changing the surface brightness of two independent (arbitrary) halves, but by using spiral arms (see local distortions) which shift the maximum of the spectra. Since, however, the galaxy is also viewn edge-on, it is doubful that their characteristics are well constrained. So we leave it at that as an example.
| File | Category | Remarks |
| eso121-g6.descr | GIPSY input data cube, header | The observation to fit (ATCA HI data cube of ESO 121-G6) |
| eso121-g6.image | GIPSY input data cube, body | The observation to fit (ATCA HI data cube of ESO 121-G6) |
| eso121-g6_in_first_input.def | TiRiFiC default file | Test file, first guess |
| eso121-g6_out_first_input.fts | FITS data cube | Output of run first_input, converted to FITS format |
| eso121-g6_in_00.def | TiRiFiC default file | Fit tilted-ring model with radially constant parameters |
| eso121-g6_out_00.fts | FITS data cube | Output of run 00, converted to FITS format |
| eso121-g6_in_01.def | TiRiFiC default file | Fit tilted-ring model with radially independent parameters |
| eso121-g6_out_01.fts | FITS data cube | Output of run 01, converted to FITS format |
| eso121-g6_in_02.def | TiRiFiC default file | Fit tilted-ring model, surface brightness independent for two half disks |
| eso121-g6_out_02.fts | FITS data cube | Output of run 02, converted to FITS format |
| eso121-g6_in_03.def | TiRiFiC default file | Fit tilted-ring model for a larger disk than before |
| eso121-g6_out_03.fts | FITS data cube | Output of run 03, converted to FITS format |
| eso121-g6_in_04.def | TiRiFiC default file | Last fit, adjusting inclination at large radii |
| eso121-g6_out_04.fts | FITS data cube | Output of run 04, converted to FITS format |
| tirific_example_gipsy.tar.gz | Archive containing all files above | Extracts into directory tirific_example_gipsy, containing all files above |
As a first step, install TiRiFiC (a version <= 2.1.5), then download either the single files listed in the table above or the archive tirific_example_gipsy.tar.gz, which extracts into the directory tirific_example, containing all files listed above.
If you only want to test whether TiRiFiC is working properly, enter the directory and type
> cp eso121-g6_in_first_input.def tirific.def > gipsy
In the GIPSY shell, type:
tirific
You should be prompted with to enter GR_CONT=. Press the Return button. TiRiFiC should stop without an error message. Leave GIPSY (Ctrl-c). You should find the output files eso121-g6_out_first_input.descr, eso121-g6_out_first_input.image (TiRiFiC output data cube in GIPSY format) and the Postscript file eso121-g6_out_first_input.ps. In summary, you have started TiRiFiC not to perform any fitting, but only to produce an output model cube according to the parameters in the default file.
To proceed with the example, look at the data cube, e.g. with the Karma task kvis, and compare it with the input data cube. Look at the viewgraph eso121-g6_out_first_input.ps. While the model is far from representing the galaxy, it is matching some part of the observation, which is enough for a start. By reading the file eso121-g6_in_first_input.def with a suitable text editor, you will find a nearly identical file as the first input file eso121-g6_in_00.def. The only differences are the output parameters , TIRDEF, GR_DEVICE, and the number of fitting loops LOOPS. A copy of the default file eso121-g6_in_00.def with links to the keyword descriptions can be found below.
The strategy followed to reach a final fit to the eso121-g6 observation was to make a TiRiFiC fit, producing an output default file (always called eso121-g6_out_ii.def, where ii is the fit number, starting with 00. Each output default file (containing the results of the fit as geometrical input parameters) was edited to upgrade the modelling strategy and to adjust a few geometrical parameters. All changes were commented (look for the keyword "Comment=" in the default files), then saved as the next input default file (eso121-g6_in_jj.def, where jj = ii + 1). These input default files are provided in the table above. To reconstruct this procedure, type
> cp eso121-g6_in_00.def tirific.def > rm data.log > gipsy
In the GIPSY shell, type:
tirific
When TiRiFiC stops (type the return key when prompted for the parameter GR_CONT=), leave GIPSY (Ctrl-c). In the first fitting process (eso121-g6_in_00.def), all parameters are fitted not varying with radius. Comparing the output data cube (eso121-g6_out_00 in GIPSY format) to the input, one can see that the rotation velocity is well adjusted, and the galaxy centre has been found. In the second step, some parameters are made variable with radius. Have a look at the file eso121-g6_in_01.def, which is a copy of the file eso121-g6_out_00.def, which you should find on your disk. Some keywords have been changed, you can search them with a text editor, looking for the "Comment=" keyword.
> cp eso121-g6_in_01.def tirific.def > rm data.log > gipsy
In the GIPSY shell, type:
tirific
Let TiRiFiC fit, then leave GIPSY (or open a second terminal in the same directory). Have a look at the plot with the fitting results (eso121-g6_01.ps), then compare the output data cube (eso121-g6_out_01 in GIPSY format) to the input data cube (eso121-g6 in GIPSY format). Not perfect, but better. In a next step, we "correct" the surface brightness of the first two rings for the input, and fit the surface brightness independently for each side independently. Also, we now allow the rotation velocity to vary independently for each ring. As we can already see that our model is too restricted in radius, the next output default file will have some additional rings (compare eso121-g6_01_out_01.def with its edited copy eso121-g6_01_in_02.def).
> cp eso121-g6_in_02.def tirific.def > rm data.log > gipsy
In the GIPSY shell, type:
tirific
After fitting, look at the plot with the fitting results (eso121-g6_02.ps) and compare the output data cube (eso121-g6_out_02 in GIPSY format) to the input data cube (eso121-g6 in GIPSY format). The velocity is a bit high at a radius of 0 arcsec, and a bit wobbly beyond the 9th ring. So we adjust the rotation velocity in the file eso121-g6_out_02.def to create a new input default file eso121-g6_in_03.def (on your disk now). We adjust the VARY and the VARINDX parameter, to account for the fact that the number of rings has increased. Also, in the next fit, for rings beyond ring 9, we sample rotation velocity and surface brightness coarser than for the inner disk. This ensures a more stable fit.
> cp eso121-g6_in_03.def tirific.def > rm data.log > gipsy
In the GIPSY shell, type:
tirific
After fitting, look at the plot with the fitting results (eso121-g6_03.ps) and compare the output data cube (eso121-g6_out_03 in GIPSY format) to the input data cube (eso121-g6 in GIPSY format). The only thing to maybe object is an instable inclination at larger radii. We adjust the VARINDX parameter in the file eso121-g6_out_03.def (on your disk now) to create a new input default file eso121-g6_in_04.def, to take out the inclination of ring 13 as a variable parameter.
> cp eso121-g6_in_03.def tirific.def > rm data.log > gipsy
In the GIPSY shell, type:
tirific
After fitting, enjoy the result. With some care, one might achieve better results. Clearly, ESO 121-G6 is a spiral galaxy, so maybe an improvement can be made by not changing the surface brightness of two independent (arbitrary) halves, but by using spiral arms (see local distortions) which shift the maximum of the spectra. Since, however, the galaxy is also viewn edge-on, it is doubful that their characteristics are well constrained. So we leave it at that as an example. This time we add a COOLGAL output that can e.g. be enjoyed with the xray rendering software of the Karma software package.
Here, a commented TiRiFiC default file is given. It is identical to eso121-g6_in_00.def as provided above. Clicking on the keywords, however, will lead you to the keyword description.
Comment= The logfile name LOGNAME= data.log # Delete logfile if it exists ACTION= 1 # Delete logfile if it exists PROMPT= 1 Comment= Use 8 cores NCORES= 8 Comment= Name of the input data set, use full velocity axis and full stokes axis, the stokes axis is 1 pixel wide INSET= eso121-g6 VELO S Comment= Always leave this empty BOX= Comment= Name of the output data set, which has the same dimensions as the input data set OUTSET= eso121-g6_out_00 Comment= Update the output data set every 10000000th model calculation, i.e. never OUTCUBUP= 10000000.0 Comment= Minor FWHM of the synthesised beam BMIN= 21.94 Comment= Major FWHM of the synthesised beam BMAJ= 28.61 Comment= Position angle of the synthesised beam BPA= 14.3 Comment= Rms noise in the data cube RMS= 0.002 Comment= Number of disks NDISKS= 2 Comment= Number of rings NUR= 11 Comment= Ring radii in arcsec, always start with 0 RADI= 0 20 40 60 80 100 120 140 160 180 200 Comment= Rotation velocity for all rings (first guess), km/s, disk 1 VROT= 150 Comment= Scale height for all rings (first guess), arcsec, disk 1 Z0= 2 Comment= Surface brightness for all rings (first guess), Jy km/s/sqarcs, disk 1 SBR= 1E-4 Comment= Inclination for all rings (first guess), degrees, disk 1 INCL= 85 Comment= Position angle for all rings (first guess), degrees, disk 1 PA= 40 Comment= Central position, right ascension, for all rings (first guess), degrees, disk 1 XPOS= 91.875 Comment= Central position, declination, for all rings (first guess), degrees, disk 1 YPOS= -61.80722 Comment= Systemic velocity for all rings (first guess), km/s, disk 1 VSYS= 1185 Comment= Central azimuthal angle of azimuthal wedge, for all rings (first guess), degrees, disk 1 (means around the approaching side) AZ1P= 0 Comment= Width of azimuthal wedge, for all rings (first guess), degrees, disk 1 (means half a disk) AZ1W= 180 Comment= Rotation velocity for all rings (first guess), km/s, disk 2, same as disk 1 VROT_2= 150 Comment= Scale height for all rings (first guess), arcsec, disk 2, same as disk 1 Z0_2= 2 Comment= Surface brightness for all rings (first guess), Jy km/s/sqarcs, disk 2, same as disk 1 SBR_2= 1E-4 Comment= Inclination for all rings (first guess), degrees, disk 2, same as disk 1 INCL_2= 85 Comment= Position angle for all rings (first guess), degrees, disk 2, same as disk 1 PA_2= 40 Comment= Central position, right ascension, for all rings (first guess), degrees, disk 2, same as disk 1 XPOS_2= 91.875 Comment= Central position, declination, for all rings (first guess), degrees, disk 2, same as disk 1 YPOS_2= -61.80722 Comment= Systemic velocity for all rings (first guess), km/s, disk 2, same as disk 1 VSYS_2= 1185 Comment= Central azimuthal angle of azimuthal wedge, for all rings (first guess), degrees, disk 2 (means around the receding side), NOT the same as disk 1 AZ1P_2= 180 Comment= Width of azimuthal wedge, for all rings (first guess), degrees, disk 2 (means half a disk) AZ1W_2= 180 Comment= With the settings above, two half disks with the same qualities are build. This is equivalent to 1 full disk. But it is convenient to do this from the beginning, if, at a later stage, one wants to fit two independent halves. Comment= Global velocity dispersion, km/s CONDISP= 8 Comment= Layer type (sech2), disk 1 LTYPE= 2.0 Comment= Layer type (sech2), disk 2, defaults to disk 1 layer type LTYPE_2= Comment= Cloud flux, Jy km/s, disk 1 CFLUX= 2e-06 Comment= Cloud flux, Jy km/s, disk 2, defaults to disk 1 cloud flux CFLUX_2= Comment= Penalise outliers PENALTY= 1.0 Comment= Do not give quantisation noise any weight in the chisquare evaluation WEIGHT= 0 Comment= separation of sub-rings is 0.5 pixels RADSEP= 0.05 Comment= some seed for the random-number generator ISEED= 8981 Comment= use fitmode 2 (golden section) FITMODE=FITMODE= 2 Comment= four loops LOOPS= 4 Comment= maximum number of total iterations, leave to default MAXITER= Comment= maximum number of calls per iteration, leave to default CALLITE= Comment= size as stopping condition is 4 SIZE= 4 Comment= we are currently only fitting parameter groups as a whole, so indexing is not necessary VARINDX= Comment= parameters to vary. All parameters listed are varied as one parameter (i.e. changes apply to all rings at the same time) VARY= PA 1:11 PA_2 1:11, SBR 1:11 SBR_2 1:11, VROT 1:11 VROT_2 1:11, INCL 1:11 INCL_2 1:11, Z0 1:11 Z0_2 1:11, XPOS 1:11 XPOS_2 1:11, YPOS 1:11 YPOS_2 1:11, VSYS 1:11 VSYS_2 1:11, CONDISP Comment= parameter maximum PARMAX= 360 1 800 180 100 360 180 10000 80 Comment= parameter minimum PARMIN= 0 -1 0 0 0 0 -180 1 1 Comment= for the consecutive parameters (for FITMODE = 2, these are only DELSTART and DELEND) interpolate for 3 loops MODERATE= 3 3 3 3 3 3 3 3 3 Comment= start stepwidth at the beginning of the iteration process DELSTART= 2 5E-6 3 2 5 0.005 0.005 0.5 2 Comment= start stepwidth after MODERATE= 3 loops DELEND= 1 5E-6 2 1 1 0.001 0.001 0.2 1 Comment= relevant only for FITMODE= 1, kept as an example, number of model calulations at the start of the fitting process ITESTART= 70 70 70 70 70 70 70 70 70 Comment= relevant only for FITMODE= 1, kept as an example, number of model calulations after three loops ITEEND= 70 70 70 70 70 70 70 70 70 Comment= relevant only for FITMODE= 1, kept as an example, stopping condition: if the model has not changed after a loop by values larger than these numbers, stop SATDELT= 0.2 1E-6 0.2 0.2 2 0.0005 0.0005 0.05 0.05 Comment= grid normalisation or minimum step width MINDELTA= 0.05 5E-7 0.05 0.05 1 0.0002 0.0002 0.02 0.02 Comment= no regularisation REGPARA= Comment= no output table TABLE= DISTANCE= 6 REFRING= 5.0 BIGTABLE= FRACTION= Comment= name of the output default file TIRDEF= eso121-g6_out_00.def Comment= no median-filtered .def file TIRSMO= Comment= numeric accuracy for parameters in default file TIRACC= 5.0 Comment= length of median filter, irrelevant, since we do not produce the median-filtered output TIRLEN= Comment= no 3D spatial model output COOLGAL= COOLBEAM= 20 Comment= no tiltogram output TILT= BIGTILT= Comment= no inclinogram output INCLINO= IN_REFINE= 5.0 Comment= name of output device, a ps file with name eso121-g6_00.ps, portrait format in the standard pgplot installation, if it doesn't work, try .../ppsfile GR_DEVICE= eso121-g6_00.ps/vcps Comment= plot radii on abscissa, surface brightness, rotation velocity, position angle, and inclination on ordinate GR_PARMS= RADI SBR VROT PA INCL Comment= do not plot the sub-rings GR_SBRP= 0 Comment= print a legend GR_LGND= 1 Comment= text height is 1 GR_TXHT= 1 Comment= basic symbol height is 0.5 times text height GR_SBHT= 0.5 Comment= margin to the right is 5 GR_MR= 5 Comment= margin to the left is 5 GR_ML= 5 Comment= symbol for first graph (SBR vs RADI) is a circle GR_SYMB_1= -1 Comment= size of symbol is 1 times basic symbol height (0.5 text height) GR_SIZE_1= 1 Comment= color is foreground, black GR_COL_1= 1 Comment= plot lines between data points GR_LINES_1= 1 Comment= symbol for second graph (VROT vs RADI) is a circle GR_SYMB_2= -1 Comment= size of symbol is 1 times basic symbol height (0.5 text height) GR_SIZE_2= 1 Comment= color is foreground, black GR_COL_2= 1 Comment= plot lines between data points GR_LINES_2= 1 Comment= symbol for first graph (PA vs RADI) is a circle GR_SYMB_3= -1 Comment= size of symbol is 1 times basic symbol height (0.5 text height) GR_SIZE_3= 1 Comment= color is foreground, black GR_COL_3= 1 Comment= plot lines between data points GR_LINES_3= 1 Comment= symbol for first graph (INCL vs RADI) is a circle GR_SYMB_4= -1 Comment= size of symbol is 1 times basic symbol height (0.5 text height) GR_SIZE_4= 1 Comment= color is foreground, black GR_COL_4= 1 Comment= plot lines between data points GR_LINES_4= 1 |