CONAN._classes.load_rvs.add_custom_RV_function
==============================================

.. py:method:: CONAN._classes.load_rvs.add_custom_RV_function(func=None, x='time', func_args=dict(), extra_args=dict(), op_func=None, replace_RVmodel=False, verbose=True)

   Define custom model to be combined with or to replace the RV model. This must be given as a
   function or a class with a ``get_model()`` function. In both cases, the function must be of the
   form ``func(x, **func_args,extra_args)`` where ``x`` is the independent variable of the function.
   If func is a class, the __init__ method must have a 'data' argument
   i.e. ``def __init__(self, data=None):`` which allows CONAN to load in the dictionary of input data.
   e.g. the data for the first RV can be retrieved as data['rv1.dat'] and its columns as
   data['rv1.dat']['col0'], data['rv1.dat']['col1'] etc.The function must return the signal to
   be combined with the RV model using ``op_func``. If ``replace_LCmodel=True``, then the function
   must return the RV model.

   :param func: custom function/class to combine with or replace the RV model. Must be of the
                form ``func(x,**func_args,extra_args)`` where ``x`` is the independent variable of the
                function. Default is None. if this function replaces the native CONAN RV model
                (using ``replace_RVmodel=True``), an additional dictionary argument of zero-initialized
                RV parameters should be given to use in computing the new RVmodel i.e
                `func(x,**func_args,extra_args, RV_pars=dict(T_0=0,Period=0,Eccentricity=0,omega=90,K=0))`
   :type func: callable;
   :param x: the independent variable of the custom function. can be 'time' or 'true_anomaly'.
             Default is "time". if 'time', the independent variable is the time array of each RV.
             if 'true_anomaly', the independent variable is the true anomaly computed within the RV
             model using time, T0, Period, Eccentricity and omega.
   :type x: str;
   :param func_args: dictionary of arguments to pass to the custom function. The keys must be the argument
                     names for the custom function. each parameter can be fixed to a value(float/int) or set
                     as a jump parameter (tuple of length 2/3/4). Default is an empty dictionary. tuple of
                     length 2:normal prior (mean, std), tuple of length 3: uniform prior (min, start, max),
                     tuple of length 4: truncated normal prior (min,max,mean, std)
   :type func_args: dict;
   :param extra_args: dictionary of extra arguments to pass to the custom function.  this arguments can be
                      strings or any data type needed to be specified in the custom function. Default is an
                      empty dictionary.
   :type extra_args: dict;
   :param op_func: operation function to apply to the output of custom function and transit model to
                   obtain the desired model. Must be of the form ``op_func(transit_model,custom_model)``.
                   Default is None. This function is not required if ``replace_RVmodel=True``.
   :type op_func: callable;
   :param replace_RVmodel: replace the transit model with the custom model. Default is False.
   :type replace_RVmodel: bool;

   .. attribute:: _custom_RVfunc

      namespace object containing the custom function, operation function and parameter dictionary.

      :type: SimpleNamespace;

   :returns: **custom_RVfunc** -- namespace object containing the custom function, operation function and parameter dictionary.
   :rtype: SimpleNamespace;

   .. rubric:: Examples

   create a custom function that adds the classical RM signal (computed by pyarome) to the RV model

   >>> def custom_func(time, vsini, phi, extra_args={}):     # vsini and phi are additional pars required for RM
   >>>     RM =  pyarome(  vsini, phi,
   >>>                     RV_pars=dict(K=0, Duration=0,rho_star=0,RpRs=0,Impact_para=0,T_0=0,Period=0,Eccentricity=0,
   >>>                     omega=90,q1=0,q2=0)
   >>>                     )
   >>>     return RM

   >>> def op_func(RV_model, custom_model):   # operation function to combine the custom model with the RV model
   >>>     return RV_model + custom_model

   >>> # vsini has a gaussian prior while the spin-orbit angle phi takes uniform prior
   >>> custom_lcfunc = lc_obj.add_custom_LC_function(func=custom_func, x="time",func_args=dict(vsini=(6,0.2), phi=(0,10,180), op_func=op_func)
   >>> # this custom function has now been registered and will be used in the computing to total RV signal