Doc: prettify amici.petab_objective (#1817)

Co-authored-by: Dilan Pathirana <[email protected]>

python/amici/petab_objective.py

@@ -66,18 +66,18 @@ def simulate_petab(
         will be used). To be provided as dict,  mapping PEtab problem
         parameters to SBML IDs.
     :param simulation_conditions:
-        Result of `petab.get_simulation_conditions`. Can be provided to save
-        time if this has be obtained before.
-        Not required if `edatas` and `parameter_mapping` are provided.
+        Result of :py:func:`petab.get_simulation_conditions`. Can be provided
+        to save time if this has be obtained before.
+        Not required if ``edatas`` and ``parameter_mapping`` are provided.
     :param edatas:
         Experimental data. Parameters are inserted in-place for simulation.
     :param parameter_mapping:
         Optional precomputed PEtab parameter mapping for efficiency, as
-        generated by `create_parameter_mapping`.
+        generated by :py:func:`create_parameter_mapping`.
     :param scaled_parameters:
-        If True, problem_parameters are assumed to be on the scale provided
-        in the PEtab parameter table and will be unscaled. If False, they
-        are assumed to be in linear scale.
+        If ``True``, ``problem_parameters`` are assumed to be on the scale
+        provided in the PEtab parameter table and will be unscaled.
+        If ``False``, they are assumed to be in linear scale.
     :param log_level:
         Log level, see :mod:`amici.logging` module.
     :param num_threads:
@@ -90,10 +90,8 @@ def simulate_petab(
     :return:
         Dictionary of
 
-        * cost function value (LLH),
-        * const function sensitivity w.r.t. parameters (SLLH),
-          (**NOTE**: Sensitivities are computed for the scaled parameters)
-        * list of `ReturnData` (RDATAS),
+        * cost function value (``LLH``),
+        * list of :class:`amici.amici.ReturnData` (``RDATAS``),
 
         corresponding to the different simulation conditions.
         For ordering of simulation conditions, see
@@ -185,15 +183,15 @@ def create_parameterized_edatas(
         will be used). To be provided as dict, mapping PEtab problem
         parameters to SBML IDs.
     :param scaled_parameters:
-        If True, problem_parameters are assumed to be on the scale provided
-        in the PEtab parameter table and will be unscaled. If False, they
-        are assumed to be in linear scale.
+        If ``True``, ``problem_parameters`` are assumed to be on the scale
+        provided in the PEtab parameter table and will be unscaled.
+        If ``False``, they are assumed to be in linear scale.
     :param parameter_mapping:
         Optional precomputed PEtab parameter mapping for efficiency, as
-        generated by `create_parameter_mapping`.
+        generated by :func:`create_parameter_mapping`.
     :param simulation_conditions:
-        Result of `petab.get_simulation_conditions`. Can be provided to save
-        time if this has been obtained before.
+        Result of :func:`petab.get_simulation_conditions`. Can be provided to
+        save time if this has been obtained before.
 
     :return:
         List with one :class:`amici.amici.ExpData` per simulation condition,
@@ -242,11 +240,11 @@ def create_parameter_mapping(
     :param petab_problem:
         PEtab problem
     :param simulation_conditions:
-        Result of `petab.get_simulation_conditions`. Can be provided to save
-        time if this has been obtained before.
+        Result of :func:`petab.get_simulation_conditions`. Can be provided to
+        save time if this has been obtained before.
     :param scaled_parameters:
-        If True, problem_parameters are assumed to be on the scale provided
-        in the PEtab parameter table and will be unscaled. If False, they
+        If ``True``, problem_parameters are assumed to be on the scale provided
+        in the PEtab parameter table and will be unscaled. If ``False``, they
         are assumed to be in linear scale.
     :param amici_model:
         AMICI model.
@@ -303,8 +301,8 @@ def create_parameter_mapping_for_condition(
     :param parameter_mapping_for_condition:
         Preliminary parameter mapping for condition.
     :param condition:
-        pandas.DataFrame row with preequilibrationConditionId and
-        simulationConditionId.
+        :class:`pandas.DataFrame` row with ``preequilibrationConditionId`` and
+        ``simulationConditionId``.
     :param petab_problem:
         Underlying PEtab problem.
     :param amici_model:
@@ -493,8 +491,8 @@ def create_edatas(
     :param petab_problem:
         Underlying PEtab problem.
     :param simulation_conditions:
-        Result of `petab.get_simulation_conditions`. Can be provided to save
-        time if this has be obtained before.
+        Result of :func:`petab.get_simulation_conditions`. Can be provided to
+        save time if this has be obtained before.
 
     :return:
         List with one :class:`amici.amici.ExpData` per simulation condition,
@@ -547,10 +545,10 @@ def create_edata_for_condition(
     Sets timepoints, observed data and sigmas.
 
     :param condition:
-        pandas.DataFrame row with preequilibrationConditionId and
-        simulationConditionId.
+        :class:`pandas.DataFrame` row with ``preequilibrationConditionId`` and
+        ``simulationConditionId``.
     :param measurement_df:
-        pandas.DataFrame with measurements for the given condition.
+        :class:`pandas.DataFrame` with measurements for the given condition.
     :param amici_model:
         AMICI model
     :param petab_problem:
@@ -721,20 +719,20 @@ def rdatas_to_measurement_df(
         measurement_df: pd.DataFrame) -> pd.DataFrame:
     """
     Create a measurement dataframe in the PEtab format from the passed
-    `rdatas` and own information.
+    ``rdatas`` and own information.
 
     :param rdatas:
         A sequence of rdatas with the ordering of
-        `petab.get_simulation_conditions`.
+        :func:`petab.get_simulation_conditions`.
 
     :param model:
-        AMICI model used to generate `rdatas`.
+        AMICI model used to generate ``rdatas``.
 
     :param measurement_df:
-        PEtab measurement table used to generate `rdatas`.
+        PEtab measurement table used to generate ``rdatas``.
 
     :return:
-        A dataframe built from the rdatas in the format of `measurement_df`.
+        A dataframe built from the rdatas in the format of ``measurement_df``.
     """
     simulation_conditions = petab.get_simulation_conditions(
         measurement_df)
@@ -778,10 +776,11 @@ def rdatas_to_simulation_df(
         rdatas: Sequence[amici.ReturnData],
         model: AmiciModel,
         measurement_df: pd.DataFrame) -> pd.DataFrame:
-    """Create a PEtab simulation dataframe from amici.ReturnDatas.
+    """Create a PEtab simulation dataframe from
+    :class:`amici.amici.ReturnData` s.
 
-    See ``rdatas_to_measurement_df`` for details, only that model outputs
-    will appear in column "simulation" instead of "measurement"."""
+    See :func:`rdatas_to_measurement_df` for details, only that model outputs
+    will appear in column ``simulation`` instead of ``measurement``."""
 
     df = rdatas_to_measurement_df(rdatas=rdatas, model=model,
                                   measurement_df=measurement_df)