{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Create a ``config.ini``" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Generate default values\n", "\n", "In most case, whether you're new to ForMoSA or not, we **strongly** recommend using this method to generate your first config file.\n", "1) Download this empty config file : [config.ini 📥](config.ini).\n", "2) Set up your paths (i.e., tell ForMoSA where to find the data and model files, and where to store the results).\n", "3) Launch ``global_file.py`` with this config file. This will automatically create a reference config file (``config_ref.ini``) in ``result_path`` with all missing inputs; i.e. :" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from ForMoSA.global_file import GlobFile\n", "config_path = '/home/mravet/Documents/These/FORMOSA/OUTPUTS/Channel1/config.ini'\n", "GlobFile(config_path) # => Will create a complete config file with all default values" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "4) You can now modify ``config_ref.ini`` with the parameters you want ! Be careful : you must at least define the prior values for the grid parameters before running an inversion. Check next section to learn more about each **parameters**." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "**Why bother with this ?** \n", "\n", "In future updates, some parameters may be added or removed. Generating a new config ensures that you'll always have access to all available parameters provided by ForMoSA ☺️ !\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Parameters *(version 1.1.6)*\n", "\n", "List and description of each config file parameter. If, for a given parameter, 'MOSAIC : Yes', it means that the parameter can be defined separatly for each observation (i.e ``parameter`` = par1, par2, ...)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_adapt]``\n", "\n", "- ``method`` = Interpolation method for the grid.\n", "\n", " format : ``'linear'`` or ``'nearest'`` or ``'zero'`` or ``'slinear'`` or ``'quadratic'`` or ``'cubic'`` or ``'quintic'`` or ``'pchip'`` or ``'barycentric'`` or ``'krogh'`` or ``'akima'`` or ``'makima'``\n", "\n", " comments : ``'linear'`` will be used by default. ⚠️ For safety reasons, this will also be the interpolation method during the nested sampling. Refer to the [xarray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.interp.html) documentation for more details.\n", "\n", " MOSAIC : No\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``emulator`` = Emulator to use.\n", "\n", " format : ``'NA'`` or ``'PCA', ncomp`` or ``'NMF', ncomp``\n", "\n", " comments : ``'NA'`` will be used by default, meaning the grid won't be emulated. ``ncomp`` is the number of components used for the PCA or NMF decomposition. ⚠️ You cannot set more components than the number of spectral channels. Refer to the [scikit-learn](https://scikit-learn.org/stable/api/sklearn.decomposition.html) documentation for more details.\n", "\n", " MOSAIC : No (will soon change)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``target_res_obs`` = Observation resolution to reach.\n", "\n", " format : ``'obs'`` or ``float``\n", "\n", " comments : ``'obs'`` will be used by default, meaning ForMoSA won't change the observation resolution. If a float is given, ForMoSA will take the minimum between this value, the resolution of the model and the resolution of the observation.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``target_res_mod`` = Model resolution to reach (prior to the inversion).\n", "\n", " format : ``'obs'`` or ``'mod'`` or ``float``\n", "\n", " comments : ``'obs'`` will be used by default, meaning ForMoSA will convolve and resample the model to the observation resolution prior to the inversion. If ``'mod'``, ForMoSA won't change the model resolution prior to the inversion (usefull for high resolution spectroscopy). If a float is given, ForMoSA will take the minimum between this value and the resolution of the model.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``res_cont`` = Approximate resolution of the continuum.\n", "\n", " format : ``'NA'`` or ``float``\n", "\n", " comments : ``'NA'`` will be used by default, meaning ForMoSA won't remove the continuum. If a float is given, ForMoSA will remove a continuum extracted at this resolution. ⚠️ To use this parameter, you must also define ``wav_cont`` (see below).\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``wav_cont`` = Wavelength range(s) used to estimate of the continuum.\n", "\n", " format : ``'NA'`` or ``'window1_min / window1_max, window2_min / ... / windowN_max'``\n", "\n", " comments : ``'NA'`` will be used by default, meaning ForMoSA won't remove the continuum. If a wavelength range (in µm) is provided, ForMoSA will remove a continuum estimated using this range. ⚠️ To use this parameter, you must also define ``res_cont`` (see above). Separate windows can be defined using ``'/'`` as separator.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_inversion]``\n", "\n", "- ``logL_type`` = Log-likelihood used during inversion.\n", "\n", " format : ``'chi2'`` or ``'chi2_covariance'`` or ``'chi2_noisescaling'`` or ``'chi2_noisescaling_covariance'`` or ``'CCF_Brogi'`` or ``'CCF_Zucker'`` or ``'CCF_custom'``\n", "\n", " comments : ``'chi2'`` will be used by default. This defines the core of the inversion. The choice of likelihood function entirely depends on the type of data you're dealing with. ⚠️ Photometric points are always compared to the model using ``'chi2'``, regardless of the likelihood selected for spectroscopy.\n", "\n", " MOSAIC : Yes\n", "\n", " exemple: " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "``'chi2'`` : $~~~log(L)=-\\frac{\\chi^2}{2}=-\\frac{1}{2}\\sum\\left(\\frac{d-m}{\\sigma}\\right)^2$\n", "\n", "``'chi2_covariance'`` : $~~~log(L)=-\\frac{\\chi^2}{2}=-\\frac{1}{2}(d-m)^T C^{-1} (d-m)$\n", "\n", "``'chi2_noisescaling'`` : $~~~log(L)=-\\frac{N}{2}log\\left(\\frac{\\chi^2}{N}\\right)=-\\frac{N}{2}log\\left(\\sum\\frac{1}{N}\\left(\\frac{d-m}{\\sigma}\\right)^2\\right)$ [Ruffio et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019AJ....158..200R/abstract)\n", "\n", "``'chi2_noisescaling_covariance'`` : $~~~log(L)=-\\frac{N}{2}log\\left(\\frac{\\chi^2}{N}\\right)=-\\frac{N}{2}log\\left(\\frac{1}{N}(d-m)^T C^{-1} (d-m)\\right)$ [Ruffio et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019AJ....158..200R/abstract)\n", "\n", "``'CCF_Brogi'`` : $~~~log(L)=-\\frac{1}{2}log\\left(S_f^2 + S_m^2 - 2R\\right)=-\\frac{1}{2}log\\left(\\frac{1}{N}\\sum d^2 + \\frac{1}{N}\\sum m^2 - 2\\frac{1}{N}\\sum dm \\right)$ [Brogi et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019AJ....157..114B/abstract)\n", "\n", "``'CCF_Zucker'`` : $~~~log(L)=-\\frac{1}{2}log\\left(1 - C^2\\right)=-\\frac{1}{2}log\\left(1 - \\frac{\\sum dm}{\\sum d^2 \\sum m²}\\right)$ [Zucker et al. (2003)](https://ui.adsabs.harvard.edu/abs/2003MNRAS.342.1291Z/abstract)\n", "\n", "``'CCF_custom'`` : $~~~log(L)=-\\frac{1}{2\\bar\\sigma}\\left(S_f^2 + S_m^2 - 2R\\right)=-\\frac{1}{2} \\left(\\frac{1}{N}\\sum\\frac{1}{\\sigma^2} \\right) \\left(\\frac{1}{N}\\sum d^2 + \\frac{1}{N}\\sum m^2 - 2\\frac{1}{N}\\sum dm \\right)$\n", "\n", "... with $d$ and $m$ being the data and model arrays, respectively. $\\sigma$ represents the error bars, and $C$ is the covariance matrix.\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``logL_full`` = If you want to use the full loglikelihood during the inversion.\n", "\n", " format : ``'True'`` or ``'False'``\n", "\n", " comments : ``'False'`` will be used by default. This means that the constant terms: $-\\frac{N}{2} log(2\\pi) - \\frac{1}{2} log(|C|)$ will be ignored.\n", "\n", " MOSAIC : Yes\n", "\n", " exemple: " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``wav_fit`` = Wavelength range(s) used during the nested sampling procedure.\n", "\n", " format : ``'window1_min / window1_max, window2_min / ... / windowN_max'``\n", "\n", " comments : ``'0,100'`` will be used by default. If a wavelength range (in µm) is provided, ForMoSA will ignore all points outside of it during the inversion. Separate windows can be defined using ``'/'`` as separator.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``ns_algo`` = Nested sampling algorithm.\n", "\n", " format : ``'nestle'`` or ``'pymultinest'`` or ``'ultranest'``\n", "\n", " comments : ``'nestle'`` will be used by default. We recommend using ``'pymultinest'`` for large datasets as it enables for efficient parallelisation. Refer to [nestle](http://kylebarbary.com/nestle/), [pymultinest](https://johannesbuchner.github.io/PyMultiNest/) and [ultranest](https://johannesbuchner.github.io/UltraNest/readme.html) documentations for more details.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``npoint`` = Number of living points during the nested sampling procedure.\n", "\n", " format : ``int``\n", "\n", " comments : ``100`` will be used by default.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_highcont_models]``\n", "\n", "- ``hc_type`` = Method to compute the high-contrast model.\n", "\n", " format : ``'NA'`` or ``'nofit_rm_spec'`` or ``'nonlinear_fit_spec'`` or ``'fit_spec'`` or ``'rm_spec'`` or ``'fit_spec_rm_cont'`` or ``'fit_spec_fit_cont'``\n", "\n", " comments : ``'NA'`` will be used by default, meaning ForMoSA won't fit for stellar contamination. This defines the function used to compute the high-contrast model. ⚠️ To use this parameter, you must also define ``hc_bound_lsq`` (see below). We strongly recommend that new users read the API documentation on high-contrast models before using these functions.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``hc_bounds_lsq`` = Least-square bounds.\n", "\n", " format : ``'NA'`` or ``'lower, upper'`` \n", " \n", " comments : ``'NA'`` will be used by default, meaning ForMoSA won't fit for stellar contamination. This defines the bounds of the lsq used to compute the high-contrast model. ⚠️ To use this parameter, you must also define ``hc_bound_lsq`` (see below). We strongly recommend that new users read the API documentation on high-contrast models before using these functions.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_parameters]``\n", "\n", "***\n", "This is where physics happens ! 😊. You'll be able to define priors and ranges for your physical parameters.\n", "\n", "As of now, four functions can be used :\n", "1) ``'uniform', lower, upper``\n", "2) ``'loguniform', lower, uppper`` (⚠️ ``lower`` and ``upper`` must be >0)\n", "3) ``'gaussian', mu, sigma``\n", "4) ``'constant', value``\n", "\n", "⚠️ For parameters available with MOSAIC, you should **ALWAYS** use three entries per observation (e.g. prior_1, value1_1, value2_1, prior_2, value1_2, value2_2, ..., prior_N, value1_N, value2_N)\n", "\n", "![priors_teff_plot](../_static/priors_teff_plot.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``parN`` = N'th (from 1 up to 5) parameter of the atmospheric grid.\n", "\n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. These are the main parameters of your inversion. They are specific to each atmospheric grid, but usually include quantities like $T_{eff}$, $log(g)$, $[M/H]$, ... ⚠️ Be sure to check the documentation of the grid to learn the number of parameters and their valid ranges.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``r`` = Radius in $R_{jup}$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default, meaning ForMoSA will do an analytical rescaling. You need to define both ``r`` and ``d`` so that ForMoSA can compute an analytical scaling factor ``ck=(r/d)²`` to rescale the model. ⚠️ This parameter cannot be used alongside high-contrast models, as they also apply a rescaling to the model.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``d`` = Distance in $pc$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default,meaning will do an analytical rescaling. You need to define both ``r`` and ``d`` so that ForMoSA can compute an analytical scaling factor ``ck=(r/d)²`` to rescale the model. ⚠️ This parameter cannot be used alongside high-contrast models, as they also apply a rescaling to the model.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``alpha`` = Scaling parameter.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default, meaning ``alpha=1``. You need to define both ``r`` and ``d`` so that ForMoSA can compute an analytical scaling factor ``ck=alpha*(r/d)²`` to rescale the model. ⚠️ This parameter cannot be used alongside high-contrast models, as they also apply a rescaling to the model. We also strongly recommend that you put constraining priors on this parameter as it is highly degenerated with both ``r`` and ``d``. If you have multiple observations and fit multiple ``alpha``s, setting one of them to ``'NA'`` will use the analytical computation of the scaling factor (usefull for continuum-substracted data).\n", "\n", " MOSAIC : Yes\n", "\n", " exemple :" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "![ck](../_static/ck.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``rv`` = Radial velocity in $km/s$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. This parameter shifts the model in wavelength. To avoid edge effects during reinterpolation, if ``target_res_mod = 'mod'`` or ``target_res_mod = float``, the model is saved with a larger spectral extent during the adaptation step.\n", "\n", " MOSAIC : Yes\n", "\n", " exemple :" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "![rv](../_static/rv.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``av`` = Extinction coeficient in $mag$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. This will apply interstellar extinction to the model. It can also be used to emulate missing cloud opacities in your grid.\n", "\n", " MOSAIC : No\n", "\n", " exemple :" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "![av](../_static/av.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``vsini`` = Projected rotational velocity in $km/s$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2, 'method'``\n", "\n", " comments : ``'NA'`` will be used by default. You need to define both ``vsini`` and ``ld`` so that ForMoSA can compute the broadening of the spectral lines. Constraints obtained on this parameter for observations at a resolution $<$100,000 are not robust for slow rotators. To avoid edge effects during reinterpolation, we also recommend to fit ``rv`` as well. Since this parameter can be computationally expensive to fit, ForMoSA allows you to choose between four methods : ``'RotBroad'`` or ``'FastRotBroad'`` or ``'Accurate'`` or ``'AccurateFastRotBroad'``. You should always specify your method **after** the priors. Please refer to the API documentation for more information.\n", "\n", " MOSAIC : Yes" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``ld`` = Limb-darkening.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. You need to define both ``vsini`` and ``ld`` so that ForMoSA can compute the broadening of the spectral lines. This parameter is usually hard to constrain so we recommend using a constant value.\n", "\n", " MOSAIC : Yes\n", "\n", " exemple :" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "![vsini](../_static/vsini.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``bb_t`` = Black-body temperature in $K$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. You need to define ``bb_t``, ``bb_r`` and ``d`` so that ForMoSA can add the contribution from a simple black-body circumplanetary disk.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "- ``bb_r`` = Black-body radius in $R_{jup}$.\n", " \n", " format : ``'NA'`` or ``'prior', value1, value2``\n", "\n", " comments : ``'NA'`` will be used by default. You need to define ``bb_t``, ``bb_r`` and ``d`` so that ForMoSA can add the contribution from a simple black-body circumplanetary disk.\n", "\n", " MOSAIC : No" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "***\n", "![bb](../_static/bb.png)\n", "\n", "***" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_nestle]``\n", "\n", "See [Nestle](http://kylebarbary.com/nestle/index.html) documentation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_pymultinest]``\n", "\n", "See [Pymultinest](https://github.com/JohannesBuchner/PyMultiNest/blob/master/pymultinest/run.py) documentation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### ``[config_ultranest]``\n", "\n", "See [Ultranest](https://johannesbuchner.github.io/UltraNest/readme.htmll) documentation" ] } ], "metadata": { "kernelspec": { "display_name": "pRT3_env", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.5" } }, "nbformat": 4, "nbformat_minor": 2 }