From e833196b6bcaaf34e157be6b818827cff27f876a Mon Sep 17 00:00:00 2001 From: Ben Jeffery Date: Fri, 22 Aug 2025 01:29:19 +0100 Subject: [PATCH] Doc changes for consistency across tskit-dev --- docs/_config.yml | 14 +- docs/favicon.ico | Bin 0 -> 3902 bytes tstrait/genetic_value.py | 141 ++++----- tstrait/simulate_effect_size.py | 133 ++++----- tstrait/simulate_environment.py | 88 +++--- tstrait/simulate_phenotype.py | 213 +++++++------- tstrait/trait_model.py | 487 ++++++++++++++------------------ verification.py | 2 +- 8 files changed, 479 insertions(+), 599 deletions(-) create mode 100644 docs/favicon.ico diff --git a/docs/_config.yml b/docs/_config.yml index 657bd65..9cade21 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -5,6 +5,7 @@ title: Tstrait manual author: Tskit Developers copyright: "2023" only_build_toc_files: true +favicon: favicon.ico execute: execute_notebooks: cache @@ -22,14 +23,9 @@ html: use_repository_button: true use_edit_page_button: true - extra_footer: | -
- tstrait __TSTRAIT_VERSION__ -
sphinx: extra_extensions: - - numpydoc - sphinx_copybutton - sphinx_design - sphinx.ext.autodoc @@ -38,9 +34,17 @@ sphinx: - sphinx.ext.viewcode - sphinx.ext.intersphinx - sphinx_issues + - IPython.sphinxext.ipython_console_highlighting config: html_theme: sphinx_book_theme + html_theme_options: + pygments_dark_style: monokai + navigation_with_keys: false + logo: + text: | + tstrait
+ version __TSTRAIT_VERSION__ myst_enable_extensions: - colon_fence - deflist diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..e1360a90232ae1f35f948497c60b90ff1da52f95 GIT binary patch literal 3902 zcmc&%c~F&A6n{<5v}>iglv_F}{gc^DyBemM3vMj33gU)>WuOj{klF|;A|Q$>Am%^_ z;xst!D9DZk0y-=bi;_$1A+IB_v$GRg ztp+zsuOaVpJc_TT<6c9Je!UZ&IvsR6t>`+QQ@1vuv?v?-S@9^$OF={JU4>SxlPuYi z$`2zj%?kT6>=AR-i>IZGJC!BySvMam=8nX&*~8&9|81-@c9 z?kHG%_8fM)n=!rAHL)xVyHm`tC(RmBc^=SdwY;7h9}OGh0dO%NFYt!K*WDb+XCo1@ z&jYy`XPIWd&q`i%F*o8p`EE2v%DE_HC7*!5*w4~gZ^GI19oSDFgtFos=AnmzY1#`j zBG`lXOLld$`vA@N8kmRdBlqR+X#=xQ`mrt{zAn73)$h5YBo9kxzlBu`$71pHfyhZa z&Fl2&g{hB+5Z^U|b`TtA4#PIrxlFIobU>@oaNN)Y=|sMa4fhs4t7jS-3v*Mj%VQDi zxmvGh`So00r$=|pjfNOhFb6WGx0`}V{*aw`rGMJn)JQrLfxyl7!X^`iFNeT!)-VxI zV_+ftO?G~e{+}^j*e0Z>x7$1ekHnO*O}dgUHd6;M7TMEr=1|yu`5NmP?(d40=0*cQ zy*wOKv29OG%1LTPd8sU$a)Wdtzfp{Db2Y)qqk(AD=Q8b2+JyMJV|K;u!JWP`jAZ@b@$?9@|8Jaq)uuVpel)evgEFuTQ&;!mG- z-EAxFN^wGYM7gO_r;A}RI_Y)rA%JjW4 zEfHI^1y#2zU^V$Ajt8oBE9Z^oJXgL2FMt2baZ%-x=PTH;v2X4F^ThNqLUs6R$rXGs>trN{C~*tBvA)>^-ZtfV;JH$A9c zx!O*|5)rFZ9~}igeUr{XTbBr5kHJx)H?^L6a_!6SilGBLR&&i#YJv&Z9?C=Nl2`gw z-P(+@!W>ciFQBv_8|s!O#^~s1XL{*l8N1S-O138CUVpna1+w{KX;GGuN_Uj7y_ zr_r|KY5*UO--jw0rs<#WSx)l|I<%CoLqld{@1 zY8=R14!h*N@xX)5&)q5VT-j(?k@5@^eY{8-!VJ$|gT3jt@Ds8! zD`T1ZpD-_$h8QsU%+|{$Ur?-2muDAYNE{-Q?@tPo<bq7n}yUEk_r^F0Ow?RbidepbxLS5@0sB00O#)ox5 zQ{Q?URn6rH`)##|Av^esyH#S@A#rc5Lru#~!G8<2VrrD3jIcF_2 zx^^a)dD$25 1 - Returns - ------- - pandas.DataFrame - Dataframe with simulated environmental noise. + .. seealso:: + :func:`sim_genetic` Return a dataclass with genetic value dataframe, + which can be used as `genetic_df` input. - Raises - ------ - ValueError - If `h2` <= 0 or `h2` > 1 + .. note:: + The `genetic_df` input has some requirements that will be noted below. - See Also - -------- - sim_genetic : Return a dataclass with genetic value dataframe, which can be used as - `genetic_df` input. + 1. Columns - Notes - ----- - The `genetic_df` input has some requirements that will be noted below. + The following columns must be included in `genetic_df`: - 1. Columns + * **trait_id**: Trait ID. + * **individual_id**: Individual ID inside the tree sequence input. + * **genetic_value**: Simulated genetic values. - The following columns must be included in `genetic_df`: + 2. Data requirement - * **trait_id**: Trait ID. - * **individual_id**: Individual ID inside the tree sequence input. - * **genetic_value**: Simulated genetic values. + Trait IDs in **trait_id** column must start from 0 and be consecutive. - 2. Data requirement + The dataframe output has the following columns: - Trait IDs in **trait_id** column must start from 0 and be consecutive. + * **trait_id**: Trait ID. + * **individual_id**: Individual ID inside the tree sequence input. + * **genetic_value**: Simulated genetic values. + * **environmental_noise**: Simulated environmental noise. + * **phenotype**: Simulated phenotype. - The dataframe output has the following columns: + .. rubric:: Examples - * **trait_id**: Trait ID. - * **individual_id**: Individual ID inside the tree sequence input. - * **genetic_value**: Simulated genetic values. - * **environmental_noise**: Simulated environmental noise. - * **phenotype**: Simulated phenotype. - - Examples - -------- See :ref:`environment_noise` for worked examples. """ genetic_df = _check_dataframe( diff --git a/tstrait/simulate_phenotype.py b/tstrait/simulate_phenotype.py index aa6ea94..58815d6 100644 --- a/tstrait/simulate_phenotype.py +++ b/tstrait/simulate_phenotype.py @@ -12,19 +12,16 @@ class PhenotypeResult: """ Dataclass that contains effect size dataframe and phenotype dataframe. - Attributes - ---------- - trait : pandas.DataFrame - Trait dataframe that includes simulated effect sizes. - phenotype : pandas.DataFrame - Phenotype dataframe that includes simulated phenotype. - - See Also - -------- - sim_phenotype : Use this dataclass as a simulation output. - - Examples - -------- + :ivar trait: Trait dataframe that includes simulated effect sizes. + :vartype trait: pandas.DataFrame + :ivar phenotype: Phenotype dataframe that includes simulated phenotype. + :vartype phenotype: pandas.DataFrame + + .. seealso:: + :func:`sim_phenotype` Use this dataclass as a simulation output. + + .. rubric:: Examples + See :ref:`effect_size_output` for details on extracting the trait dataframe, and :ref:`phenotype_output` for details on extracting the phenotype dataframe. @@ -47,79 +44,73 @@ def sim_phenotype( """ Simulate quantitative traits. - Parameters - ---------- - ts : tskit.TreeSequence - The tree sequence data that will be used in the quantitative trait + :param ts: The tree sequence data that will be used in the quantitative trait simulation. - model : tstrait.TraitModel - Trait model that will be used to simulate effect sizes. - num_causal : int, default None - Number of causal sites. If None, number of causal sites will be 1. - causal_sites : list, default None - List of site IDs that have causal allele. If None, causal site IDs will be - chosen randomly according to num_causal. - alpha : float, default None - Parameter that determines the degree of the frequency dependence model. Please - see :ref:`frequency_dependence` for details on how this parameter influences - effect size simulation. If None, alpha will be 0. - h2 : float or array-like, default None. - Narrow-sense heritability. When it is 1, environmental noise will be a vector of - zeros. If `h2` is array-like, the dimension of `h2` must match the number of - traits to be simulated. If None, h2 will be 1. - random_seed : int, default None - Random seed of simulation. If None, simulation will be conducted randomly. - - Returns - ------- - PhenotypeResult - Dataclass object that includes phenotype and trait dataframe. - - Raises - ------ - ValueError - If the number of mutations in `ts` is smaller than `num_causal`. - ValueError - If `h2` <= 0 or `h2` > 1 - - See Also - -------- - trait_model : Returns a trait model, which can be used as `model` input. - PhenotypeResult : Dataclass object that will be used as an output. - sim_trait : Used to simulate a trait dataframe. - genetic_value : Used to determine genetic value of individuals. - sim_env : Used to simulate environmental noise. - - Notes - ----- - The simulation outputs of traits and phenotypes are given as a - :py:class:`pandas.DataFrame`. - - The trait dataframe can be extracted by using ``.trait`` in the - resulting object and contains the following columns: - - * **position**: Position of sites that have causal allele in genome coordinates. - * **site_id**: Site IDs that have causal allele. - * **effect_size**: Simulated effect size of causal allele. - * **causal_allele**: Causal allele. - * **allele_freq**: Allele frequency of causal allele. It is described in detail - in :ref:`trait_frequency_dependence`. - * **trait_id**: Trait ID. - - The phenotype dataframe can be extracted by using ``.phenotype`` in the resulting - object and contains the following columns: - - * **trait_id**: Trait ID. - * **individual_id**: Individual ID inside the tree sequence input. - * **genetic_value**: Simulated genetic values. - * **environmental_noise**: Simulated environmental noise. - * **phenotype**: Simulated phenotype. - - Please refer to :ref:`phenotype_model` for mathematical details of the phenotypic - model. - - Examples - -------- + :type ts: tskit.TreeSequence + :param model: Trait model that will be used to simulate effect sizes. + :type model: tstrait.TraitModel + :param num_causal: Number of causal sites. If None, number of causal sites will be 1. + :type num_causal: int + :param causal_sites: List of site IDs that have causal allele. If None, + causal site IDs will be chosen randomly according to num_causal. + :type causal_sites: list + :param alpha: Parameter that determines the degree of the frequency + dependence model. Please see :ref:`frequency_dependence` for details on how + this parameter influences effect size simulation. If None, alpha will be 0. + :type alpha: float + :param h2: Narrow-sense heritability. When it is 1, environmental noise will + be a vector of zeros. If `h2` is array-like, the dimension of `h2` must match + the number of traits to be simulated. If None, h2 will be 1. + :type h2: float or array-like + :param random_seed: Random seed of simulation. If None, simulation will be + conducted randomly. + :type random_seed: int + :returns: Dataclass object that includes phenotype and trait dataframe. + :rtype: PhenotypeResult + :raises ValueError: If the number of mutations in `ts` is smaller than `num_causal`. + :raises ValueError: If `h2` <= 0 or `h2` > 1 + + .. seealso:: + :func:`trait_model` Returns a trait model, which can be used as `model` input. + + :class:`PhenotypeResult` Dataclass object that will be used as an output. + + :func:`sim_trait` Used to simulate a trait dataframe. + + :func:`genetic_value` Used to determine genetic value of individuals. + + :func:`sim_env` Used to simulate environmental noise. + + .. note:: + The simulation outputs of traits and phenotypes are given as a + :py:class:`pandas.DataFrame`. + + The trait dataframe can be extracted by using ``.trait`` in the + resulting object and contains the following columns: + + * **position**: Position of sites that have causal allele in genome + coordinates. + * **site_id**: Site IDs that have causal allele. + * **effect_size**: Simulated effect size of causal allele. + * **causal_allele**: Causal allele. + * **allele_freq**: Allele frequency of causal allele. It is described + in detail in :ref:`trait_frequency_dependence`. + * **trait_id**: Trait ID. + + The phenotype dataframe can be extracted by using ``.phenotype`` in the + resulting object and contains the following columns: + + * **trait_id**: Trait ID. + * **individual_id**: Individual ID inside the tree sequence input. + * **genetic_value**: Simulated genetic values. + * **environmental_noise**: Simulated environmental noise. + * **phenotype**: Simulated phenotype. + + Please refer to :ref:`phenotype_model` for mathematical details of the phenotypic + model. + + .. rubric:: Examples + See :ref:`quickstart` for worked examples. """ @@ -144,44 +135,34 @@ def sim_phenotype( def normalise_phenotypes(phenotype_df, mean=0, var=1, ddof=1): """Normalise phenotype dataframe. - Parameters - ---------- - phenotype_df : pandas.DataFrame - Phenotype dataframe. - mean : float, default 0 - Mean of the resulting phenotype. - var : float, default 1 - Variance of the resulting phenotype. - ddof : int, default 1 - Delta degrees of freedom. The divisor used in computing the variance + :param phenotype_df: Phenotype dataframe. + :type phenotype_df: pandas.DataFrame + :param mean: Mean of the resulting phenotype. + :type mean: float + :param var: Variance of the resulting phenotype. + :type var: float + :param ddof: Delta degrees of freedom. The divisor used in computing the variance is N - ddof, where N represents the number of elements. + :type ddof: int + :returns: Dataframe with normalised phenotype. + :rtype: pandas.DataFrame + :raises ValueError: If `var` <= 0. - Returns - ------- - pandas.DataFrame - Dataframe with normalised phenotype. - - Raises - ------ - ValueError - If `var` <= 0. + .. note:: + The following columns must be included in `phenotype_df`: - Notes - ----- - The following columns must be included in `phenotype_df`: + * **trait_id**: Trait ID. + * **individual_id**: Individual ID. + * **phenotype**: Simulated phenotypes. - * **trait_id**: Trait ID. - * **individual_id**: Individual ID. - * **phenotype**: Simulated phenotypes. + The dataframe output has the following columns: - The dataframe output has the following columns: + * **trait_id**: Trait ID inside the phenotype_df input. + * **individual_id**: Individual ID inside the phenotype_df input. + * **phenotype**: Normalised phenotype. - * **trait_id**: Trait ID inside the phenotype_df input. - * **individual_id**: Individual ID inside the phenotype_df input. - * **phenotype**: Normalised phenotype. + .. rubric:: Examples - Examples - -------- See :ref:`normalise_phenotype` section for worked examples. """ if var <= 0: diff --git a/tstrait/trait_model.py b/tstrait/trait_model.py index 7fba6cc..3db405f 100644 --- a/tstrait/trait_model.py +++ b/tstrait/trait_model.py @@ -14,28 +14,30 @@ class TraitModel(metaclass=ABCMeta): """ Superclass of the trait model. - Attributes - ---------- - name : str - Name of the trait model. - num_trait : int - Number of traits to be simulated. - - See Also - -------- - trait_model : Construct a trait model. - TraitModelNormal : Return a normal distribution trait model. - TraitModelT : Return a Student's t-distribution trait model. - TraitModelFixed : Return a fixed value trait model. - TraitModelExponential : Return an exponential distribution trait model. - TraitModelGamma : Return a gamma distribution trait model. - TraitModelMultivariateNormal : Return a multivariate normal distribution - trait model. - - Notes - ----- - This is the base class for all trait models in tstrait. All trait models - should set all parameters in their ``__init__`` as arguments. + :ivar name: Name of the trait model. + :vartype name: str + :ivar num_trait: Number of traits to be simulated. + :vartype num_trait: int + + .. seealso:: + :func:`trait_model` Construct a trait model. + + :class:`TraitModelNormal` Return a normal distribution trait model. + + :class:`TraitModelT` Return a Student's t-distribution trait model. + + :class:`TraitModelFixed` Return a fixed value trait model. + + :class:`TraitModelExponential` Return an exponential distribution trait model. + + :class:`TraitModelGamma` Return a gamma distribution trait model. + + :class:`TraitModelMultivariateNormal` Return a multivariate normal + distribution trait model. + + .. note:: + This is the base class for all trait models in tstrait. All trait models + should set all parameters in their ``__init__`` as arguments. """ @abstractmethod @@ -57,32 +59,28 @@ class TraitModelNormal(TraitModel): """ Normal distribution trait model. - Parameters - ---------- - mean : float - Mean of the simulated effect size. - var : float - Variance of the simulated effect size. Must be non-negative. - - Returns - ------- - TraitModel - Normal distribution trait model. - - See Also - -------- - trait_model : Construct a trait model. - numpy.random.Generator.normal : Details on the input parameters and distribution. - - Notes - ----- - This is a trait model built on top of :py:meth:`numpy.random.Generator.normal`, so - please see its documentation for the details of the normal distribution simulation. - - Examples - -------- - Please see the docstring example of :func:`trait_model` for constructing a normal - distribution trait model. + :param mean: Mean of the simulated effect size. + :type mean: float + :param var: Variance of the simulated effect size. Must be non-negative. + :type var: float + :returns: Normal distribution trait model. + :rtype: TraitModel + + .. seealso:: + :func:`trait_model` Construct a trait model. + + :py:meth:`numpy.random.Generator.normal` Details on the input parameters + and distribution. + + .. note:: + This is a trait model built on top of + :py:meth:`numpy.random.Generator.normal`, so please see its documentation + for the details of the normal distribution simulation. + + .. rubric:: Examples + + Please see the docstring example of :func:`trait_model` for constructing a + normal distribution trait model. """ def __init__(self, mean, var): @@ -94,17 +92,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method simulates an effect size from a normal distribution. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = rng.normal( @@ -118,35 +111,29 @@ def _sim_effect_size(self, num_causal, rng): class TraitModelExponential(TraitModel): """Exponential distribution trait model. - Parameters - ---------- - scale : float - Scale of the exponential distribution. Must be non-negative. - random_sign : bool, default False - If True, :math:`1` or :math:`-1` will be randomly multiplied to the - simulated effect sizes, such that we can simulate effect sizes with - randomly chosen signs. If False, only positive values are being + :param scale: Scale of the exponential distribution. Must be non-negative. + :type scale: float + :param random_sign: If True, :math:`1` or :math:`-1` will be randomly + multiplied to the simulated effect sizes, such that we can simulate effect + sizes with randomly chosen signs. If False, only positive values are being simulated as part of the property of the exponential distribution. + :type random_sign: bool + :returns: Exponential distribution trait model. + :rtype: TraitModel + + .. seealso:: + :func:`trait_model` Construct a trait model. + + :py:meth:`numpy.random.Generator.exponential` Details on the input + parameters and distribution. + + .. note:: + This is a trait model built on top of + :py:meth:`numpy.random.Generator.exponential`, so please see its + documentation for the details of the exponential distribution simulation. + + .. rubric:: Examples - Returns - ------- - TraitModel - Exponential distribution trait model. - - See Also - -------- - trait_model : Construct a trait model. - numpy.random.Generator.exponential : Details on the input parameters and - distribution. - - Notes - ----- - This is a trait model built on top of :py:meth:`numpy.random.Generator.exponential`, - so please see its documentation for the details of the exponential distribution - simulation. - - Examples - -------- Please see the docstring example of :func:`trait_model` for constructing an exponential distribution trait model. """ @@ -160,17 +147,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method simulates an effect size from an exponential distribution. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = rng.exponential(scale=self.scale, size=num_causal) @@ -183,32 +165,25 @@ class TraitModelFixed(TraitModel): """ Fixed value trait model. - Parameters - ---------- - value : float - Value of the simulated effect size. - random_sign : bool, default False - If True, :math:`1` or :math:`-1` will be randomly multiplied to the - simulated effect sizes, such that we can simulate constant value effect + :param value: Value of the simulated effect size. + :type value: float + :param random_sign: If True, :math:`1` or :math:`-1` will be randomly + multiplied to the simulated effect sizes, such that we can simulate constant + value effect sizes with randomly chosen signs. + :type random_sign: bool + :returns: Fixed value trait model. + :rtype: TraitModel + + .. seealso:: + :func:`trait_model` Construct a trait model. + + .. note:: + This is a trait model that gives the fixed value that is specified in + `value` if `random_sign` is False. If it is true, this simulates effect sizes with randomly chosen signs. - Returns - ------- - TraitModel - Fixed value trait model. - - See Also - -------- - trait_model : Construct a trait model. + .. rubric:: Examples - Notes - ----- - This is a trait model that gives the fixed value that is specified in `value` - if `random_sign` is False. If it is true, this simulates effect sizes with - randomly chosen signs. - - Examples - -------- Please see the docstring example of :func:`trait_model` for constructing a fixed value trait model. """ @@ -222,17 +197,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method returns an effect size from a fixed trait model. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = np.repeat(self.value, num_causal) @@ -245,33 +215,28 @@ class TraitModelT(TraitModel): """ Student's t distribution trait model. - Parameters - ---------- - mean : float - Mean of the simulated effect size. - var : float - Variance of the simulated effect size. Must be > 0. - df : float - Degrees of freedom. Must be > 0. - - Returns - ------- - TraitModel - Student's t distribution trait model. - - See Also - -------- - trait_model : Construct a trait model. - numpy.random.Generator.standard_t : Details on the input parameters and distribution. - - Notes - ----- - This is a trait model built on top of :py:meth:`numpy.random.Generator.standard_t`, - so please see its documentation for the details of the normal distribution - simulation. - - Examples - -------- + :param mean: Mean of the simulated effect size. + :type mean: float + :param var: Variance of the simulated effect size. Must be > 0. + :type var: float + :param df: Degrees of freedom. Must be > 0. + :type df: float + :returns: Student's t distribution trait model. + :rtype: TraitModel + + .. seealso:: + :func:`trait_model` Construct a trait model. + + :py:meth:`numpy.random.Generator.standard_t` Details on the input + parameters and distribution. + + .. note:: + This is a trait model built on top of + :py:meth:`numpy.random.Generator.standard_t`, so please see its + documentation for the details of the normal distribution simulation. + + .. rubric:: Examples + Please see the docstring example of :func:`trait_model` for constructing a student's t distribution trait model. """ @@ -286,17 +251,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method returns an effect size from a t distribution. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = rng.standard_t(self.df, size=num_causal) @@ -308,36 +268,31 @@ class TraitModelGamma(TraitModel): """ Gamma distribution trait model. - Parameters - ---------- - shape : float - Shape of the gamma distribution. Must be non-negative. - scale : float - Scale of the gamma distribution. Must be non-negative. - random_sign : bool, default False - If True, :math:`1` or :math:`-1` will be randomly multiplied to the - simulated effect sizes, such that we can simulate effect sizes with - randomly chosen signs. If False, only positive values are being + :param shape: Shape of the gamma distribution. Must be non-negative. + :type shape: float + :param scale: Scale of the gamma distribution. Must be non-negative. + :type scale: float + :param random_sign: If True, :math:`1` or :math:`-1` will be randomly + multiplied to the simulated effect sizes, such that we can simulate effect + sizes with randomly chosen signs. If False, only positive values are being simulated as part of the property of the gamma distribution. + :type random_sign: bool + :returns: Gamma distribution trait model. + :rtype: TraitModel + + .. seealso:: + :func:`trait_model` Construct a trait model. - Returns - ------- - TraitModel - Gamma distribution trait model. + :py:meth:`numpy.random.Generator.gamma` Details on the input parameters + and distribution. - See Also - -------- - trait_model : Construct a trait model. - numpy.random.Generator.gamma : Details on the input parameters and distribution. + .. note:: + This is a trait model built on top of + :py:meth:`numpy.random.Generator.gamma`, so please see its documentation + for the details of the gamma distribution simulation. - Notes - ----- - This is a trait model built on top of :py:meth:`numpy.random.Generator.gamma`, - so please see its documentation for the details of the gamma distribution - simulation. + .. rubric:: Examples - Examples - -------- Please see the docstring example of :func:`trait_model` for constructing an gamma distribution trait model. """ @@ -352,17 +307,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method returns an effect size from a gamma distribution. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = rng.gamma(self.shape, self.scale, size=num_causal) @@ -375,41 +325,34 @@ class TraitModelMultivariateNormal(TraitModel): """ Multivariate normal distribution trait model. - Parameters - ---------- - mean : 1-D array_like, of length N - Mean vector. - cov : 2-D array_like, of shape (N, N) - Covariance matrix. Must be symmetric and positive-semidefinite. + :param mean: Mean vector. + :type mean: 1-D array_like, of length N + :param cov: Covariance matrix. Must be symmetric and positive-semidefinite. + :type cov: 2-D array_like, of shape (N, N) + :returns: Multivariate normal distribution trait model. + :rtype: TraitModel + .. seealso:: + :func:`trait_model` Construct a trait model. - Returns - ------- - TraitModel - Multivariate normal distribution trait model. + :py:meth:`numpy.random.Generator.multivariate_normal` Details on the + input parameters and distribution. - See Also - -------- - trait_model : Construct a trait model. - numpy.random.Generator.multivariate_normal : Details on the input parameters - and distribution. + .. note:: + Multivariate normal distribution simulation is used in multi-trait simulation, + which is described in :ref:`multi_trait`. - Notes - ----- - Multivariate normal distribution simulation is used in multi-trait simulation, - which is described in :ref:`multi_trait`. + This is a trait model built on top of + :py:meth:`numpy.random.Generator.multivariate_normal`, so please see its + documentation for the details of the multivariate normal distribution + simulation. - This is a trait model built on top of - :py:meth:`numpy.random.Generator.multivariate_normal`, so please see its - documentation for the details of the multivariate normal distribution - simulation. + The number of dimensions of mean vector and covariance matrix should match, + and the length of the mean vector specifies the number of traits that will + be simulated by using this model. - The number of dimensions of mean vector and covariance matrix should match, - and the length of the mean vector specifies the number of traits that will - be simulated by using this model. + .. rubric:: Examples - Examples - -------- Please see the docstring example of :func:`trait_model` for constructing a multivariate normal distribution trait model. """ @@ -424,17 +367,12 @@ def _sim_effect_size(self, num_causal, rng): """ This method returns an effect size from a multivariate normal distribution. - Parameters - ---------- - num_causal : int - Number of causal sites - rng : numpy.random.Generator - Random generator that will be used to simulate effect size. - - Returns - ------- - float or array-like - Simulated effect size of a causal mutation. + :param num_causal: Number of causal sites + :type num_causal: int + :param rng: Random generator that will be used to simulate effect size. + :type rng: numpy.random.Generator + :returns: Simulated effect size of a causal mutation. + :rtype: float or array-like """ num_causal = self._check_parameter(num_causal, rng) beta = rng.multivariate_normal(mean=self.mean, cov=self.cov, size=num_causal) @@ -455,43 +393,42 @@ def trait_model(distribution, **kwargs): """ Return a trait model corresponding to the specified model. - Parameters - ---------- - distribution : str - String describing the trait model. The list of supported distributions - are: + :param distribution: String describing the trait model. The list of + supported distributions are: + * "normal": Normal distribution * "t": Student's t distribution * "fixed": Fixed value * "exponential": Exponential distribution * "gamma": Gamma distribution * "multi_normal": Multivariate normal distribution - **kwargs - These parameters will be used to specify the trait model. - - Returns - ------- - TraitModel - Trait model that specifies the distribution of effect size simulation. - - See Also - -------- - TraitModelNormal : Return a normal distribution trait model. - TraitModelT : Return a Student's t-distribution trait model. - TraitModelFixed : Return a fixed value trait model. - TraitModelExponential : Return an exponential distribution trait model. - TraitModelGamma : Return a gamma distribution trait model. - TraitModelMultivariateNormal : Return a multivariate normal distribution - trait model. - - Notes - ----- - Please reference :ref:`effect_size` for details on the effect size - simulation. Multivariate normal distribution trait model is used in - multi-trait simulation, which is described in :ref:`multi_trait`. - - Examples - -------- + :type distribution: str + :param kwargs: These parameters will be used to specify the trait model. + :returns: Trait model that specifies the distribution of effect size + simulation. + :rtype: TraitModel + + .. seealso:: + :class:`TraitModelNormal` Return a normal distribution trait model. + + :class:`TraitModelT` Return a Student's t-distribution trait model. + + :class:`TraitModelFixed` Return a fixed value trait model. + + :class:`TraitModelExponential` Return an exponential distribution trait model. + + :class:`TraitModelGamma` Return a gamma distribution trait model. + + :class:`TraitModelMultivariateNormal` Return a multivariate normal + distribution trait model. + + .. note:: + Please reference :ref:`effect_size` for details on the effect size + simulation. Multivariate normal distribution trait model is used in + multi-trait simulation, which is described in :ref:`multi_trait`. + + .. rubric:: Examples + >>> import tstrait Constructing a normal distribution trait model with mean :math:`0` and diff --git a/verification.py b/verification.py index 50d4276..be465f0 100644 --- a/verification.py +++ b/verification.py @@ -1099,7 +1099,7 @@ def test_multivariate(self): data=df["effect_size"].values, data_name=stats_type, dist=scipy.stats.norm, - dist_name=f"normal_mean_{mean[i]}_var_{cov[i,i]}", + dist_name=f"normal_mean_{mean[i]}_var_{cov[i, i]}", loc=mean[i], scale=np.sqrt(cov[i, i]), )