Running BASTA

Two steps to running BASTA

The following tutorial is a general introduction to fitting observational data and determining stellar properties with BASTA. It is meant as a guide to get started with simple fits based of various sets of input, and should not be considered as the default settings for producing scientific results. We encourage the users to explore the options offered by the code and build their input files according to their needs. As a final remark, we note that BASTA is designed to fit any input given without ensuring that the solution is physically viable. In other words, it is up to the user to correctly interpret the results of any fit done with the code.

The input to the code is given using an .xml file containing all the relevant information to perform the fit. A Python routine to produce such .xml files in a semi-automatic way is included in the code repository and can be found in BASTA/examples/create_inputfile.py. This is meant as a basic version just to check that the code is running. It also serves as a template with all options documented. For examples of ‘real’ fits, have a look at the examples sections in this tutorial (Examples of fits).

The basic procedure to run BASTA can be reduced to the following steps:

Create the input file

The following commands will create a file named input_myfit.xml in the directory BASTA/examples/.
cd BASTA
source bastaenv/bin/activate
cd examples/
python create_inputfile.py
Run BASTA

Once the input_myfit.xml has been correctly created, BASTA is simply run as follows (with the virtual environment activated):
BASTArun input_myfit.xml

The output of the fit is located in BASTA/examples/output/myfit and we encourage the user to inspect it and ensure that BASTA is correctly running while getting familiar with the type of output and figures produced.

Common blocks

Regardless of the type of fit, a standard I/O block must be specified containing the name of the .xml file to be created, the grid of models to be used, and the output directory for the results. Additionally, an ascii file with the parameters of the star(s) to be fitted must be given (more details in the full file). The following comprises (most of) Block 1 of create_inputfile.define_input() (note that some comments have been removed compared to the full file):

# ==================================================================================
# BLOCK 1: I/O
# ==================================================================================
# Name of the XML input file to produce
xmlfilename = "input_myfit.xml"

# The path to the grid to be used by BASTA for the fitting.
define_io["gridfile"] = os.path.join(BASTADIR, "grids", "Garstec_16CygA.hdf5")

# Where to store the output of the BASTA run
define_io["outputpath"] = os.path.join("output", "myfit")

# Location of the input file with the star(s) to be fitted and the columns included
define_io["asciifile"] = os.path.join("data", "16CygA.ascii")
define_io["params"] = (
    "starid",
    "RA",
    "DEC",
    "numax",
    "numax_err",
    "dnu",
    "dnu_err",
    "Teff",
    "Teff_err",
    "FeH",
    "FeH_err",
    "logg",
    "logg_err",
)

Note that BASTA uses the numpy.genfromtxt function to read the input ascii file, allowing the presence of additional columns that will not be used by the code as long as the appropriate number of entries is given in define_io["params"].

The other common blocks to all fits are the ones corresponding to the fitting, output, and plotting controls. The main components (again some comments and auxiliary things are removed compared to the file):

# ==================================================================================
# BLOCK 2: Fitting control
# ==================================================================================
# A list of the parameters to fit must be given to BASTA in a tuple.
define_fit["fitparams"] = ("Teff", "FeH", "logg")

# ==================================================================================
# BLOCK 3: Output control
# ==================================================================================
# A list of quantities to output.
define_output["outparams"] = ("Teff", "FeH", "logg", "radPhot", "massfin", "age")

# Name of the output file containing the results of the fit in ascii format.
define_output["outputfile"] = "results.ascii"

# A dump of the statistics (chi2, logPDF) for all models in the grids can be saved
# to a .json file.
define_output["optionaloutputs"] = True

# ==================================================================================
# BLOCK 4: Plotting control
# ==================================================================================
# Corner plots of posteriors. Specify a list of parameters to plot.
define_plots["cornerplots"] = define_output["outparams"]

# BASTA can produce a Kiel diagram (Teff vs logg) with the observations and the
# model points from the grid. The latter will be color coded based on the fitting
# parameters and their uncertainties/constraints.
define_plots["kielplots"] = True

Please note that Block 2 contains five sub-blocks with different controls depending on the specific type of fit. Also note that in the above example, the same quantities being output to results.ascii are included in the corner plot, but these can be specified independently. Finally, some options have been omitted for clarity, e.g., the entry define_plots["freqplots"] in Block 4 as it is only relevant when fitting Methods using individual frequencies.

Important The summary statistics for all stars included in the input ascii will be written to results.ascii, while figures and details of the run for each individual target will be stored as., starid_XXX.png and starid.json. If another run is made for the same stars varying some of the fit parameters, it must be stored in a different folder otherwise BASTA will overwrite the previous output.