TiRiFiC logo

Examples

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:

Example modelling run

Example with dwonloadable files for standalone version

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.

Example with dwonloadable files for GIPSY version

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.

Commented default file

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