One of the most requested features to be included in **kima** is the possibility to analyse RV data from multiple instruments. This is now possible! **Notes** - This feature is available in the master branch as of **kima** v2.0. Still, some bugs :bug: may be left to catch. [Let us know](https://github.com/j-faria/kima/wiki/Contribute) if you find one. - Considering RVs from multiple instruments means adding new offset parameters to the model. As of now, all these parameters share the same prior. - The same applies to the additional white noise (sometimes called *jitter* ). One jitter parameter is added per instrument, all sharing the same prior. ### Detecting the planet around HD106252 First announced by [Fischer et al. 2002](https://ui.adsabs.harvard.edu/#abs/2002PASP..114..529F), the giant planet orbiting HD106252 has been detected with a number of different instruments ([Perrier et al. 2003](https://www.aanda.org/articles/aa/abs/2003/42/aa2924/aa2924.html), [Butler et al. 2006](http://iopscience.iop.org/article/10.1086/504701), [Wittenmyer et al.2009](http://iopscience.iop.org/article/10.1088/0067-0049/182/1/97)). In this small tutorial, we will analyse the combined RV data. #### setting things up If you have a recent version of **kima** (after v2.0, commit `e599ffd`), there's no setting up required. The old instructions to checkout the `multi_instrument` branch were moved to the end of this page. #### the *multi_instrument* example Head over to the *examples/multi_instrument* directory. There you will find four files containing the RV data of HD106252, each of them from a different instrument: `HD106252_ELODIE.txt`, `HD106252_HET.txt`, `HD106252_HJS.txt`, and `HD106252_Lick.txt`. You will note that each file has a different number of observations, but the header occupies the same two lines in each. When reading the data into **kima**, it is important to guarantee that the structure, header, **and units** of all the data files are the same. For each file, the first column is time in (Julian) days, second column is RV in m/s, and third column is RV uncertainty also in m/s. In that directory there is another file called `HD106252_joined.txt`, which contains the same RV data of the four instruments, but joined together. The structure of the three first columns is identical, but the fourth column contains an instrument (**integer**) identifier. **kima** is able to read these two types of input: one file per instrument, or one single file with an identifier (**integer!**) column. The `kima_setup.cpp` file contains mostly the usual code to define a model. One difference is the new option ```cpp const bool multi_instrument = true; ``` which tells **kima** that the RVs come from different instruments. As mentioned above, this means defining new offset parameters. The default (shared) prior for these parameters is a uniform distribution within the span of the observed RVs (see [here](Changing-the-priors.md)) This is usually a good option which guarantees that the prior contains the full range of possible values for the offsets, whether they are positive or negative. But bear in mind that you might have to adjust this prior for your data. The next new thing is when reading the data. To read the four individual files we can do ```cpp datafiles = {"HD106252_ELODIE.txt", "HD106252_HET.txt", "HD106252_HJS.txt", "HD106252_Lick.txt" }; load_multi(datafiles, "ms", 2); ``` In case we want to read the file with the joined RVs, we could use instead ```cpp datafile = "HD106252_joined.txt"; load_multi(datafile, "ms", 1); ``` [**note:** the `load_multi` function is overloaded to deal with `char*` and `vector`. The other two arguments are the same.] [**note:** the data should be read in only one of these ways, not both!] Now that we're all set, let's compile and run the model ```sh make # may be compiled already ./run ``` With the default options, the sampler will finish in about 15 minutes, give or take. Remember that you can check the progress and look at the results *while* the code is running, by opening a new terminal window. Do give it some time at the start, as this example takes a bit to "converge". #### results Let's use `pykima` to look at the results. The command ``` kima-showresults all ``` will create a number of different plots. Some interesting ones are reproduced here: - the posterior for the orbital period, showing a very clear peak close to 1535 days.
- the posteriors for the systemic velocity and the (3) between-instrument offsets
- the posterior for the *jitter* parameters
- the phased RV curve, based on the maximum likelihood solution - and finally the RV curves together with the data from each instrument Zooming in on this last plot, we see how each dataset is modelled with the same Keplerian function plus an individual offset To clarify, in the *multi_instrument* mode, with Ni instruments, there are - Ni-1   offset parameters - Ni       jitter parameters - 1        systemic velocity The correspondence between these parameters can be worked out by looking at the order of the files in the `datafiles` vector. The systemic velocity is associated with the **last instrument** (Lick in the above example, shown in red in the plot). The RV offsets are then **defined relative to the systemic velocity**. So, *offset1* is between Lick and ELODIE data (blue), *offset2* is between Lick and HET data (orange), and *offset3* is between LICK and HJS data (green). The jitter parameters are simply in the same order as the instruments in the `datafiles` vector: ELODIE, HET, HJS, and Lick.