r"""Generate transition matrix sampler object.

    Parameters
    ----------
    C : (M, M) ndarray or scipy.sparse matrix
        Count matrix
    reversible : bool
        If true sample from the ensemble of transition matrices
        restricted to those obeying a detailed balance condition,
        else draw from the whole ensemble of stochastic matrices.
    mu : array_like
        A fixed stationary distribution. Transition matrices with that
        stationary distribution will be sampled
    T0 : ndarray, shape=(n, n) or scipy.sparse matrix
        Starting point of the MC chain of the sampling algorithm.
        Has to obey the required constraints.
    nstep : int, default=None
        number of full Gibbs sampling sweeps per sample. This option is meant
        to ensure approximately uncorrelated samples for every call to
        sample(). If None, the number of steps will be automatically determined
        based on the other options and  the matrix size. nstep>1 will only be
        used for reversible sampling, because nonreversible sampling generates
        statistically independent transition matrices every step.

    Returns
    -------
    sampler : A :py:class:dense.tmatrix_sampler.TransitionMatrixSampler object that can be used to generate samples.

    Notes
    -----
    The transition matrix sampler generates transition matrices from
    the posterior distribution. The posterior distribution is given as
    a product of Dirichlet distributions

    .. math:: \mathbb{P}(T|C) \propto \prod_{i=1}^{M} \left( \prod_{j=1}^{M} p_{ij}^{c_{ij}} \right)

    The method can generate samples from the posterior under the following constraints

    **Reversible sampling**

    Using a MCMC sampler outlined in .. [1] it is ensured that samples
    from the posterior are reversible, i.e. there is a probability
    vector :math:`(\mu_i)` such that :math:`\mu_i t_{ij} = \mu_j
    t_{ji}` holds for all :math:`i,j`.

    **Reversible sampling with fixed stationary vector**

    Using a MCMC sampler outlined in .. [2] it is ensured that samples
    from the posterior fulfill detailed balance with respect to a given
    probability vector :math:`(\mu_i)`.

    References
    ----------
    .. [1] Noe, F. Probability distributions of molecular observables
        computed from Markov state models. J Chem Phys 128: 244103 (2008)

    .. [2] Trendelkamp-Schroer, B., H. Wu, F. Paul and F. Noe: Estimation and
        uncertainty of reversible Markov models. J. Chem. Phys. (submitted)

def tmatrix_sampler(C, reversible=False, mu=None, T0=None, nsteps=None, prior='sparse'):
    r"""Generate transition matrix sampler object.

    Parameters
    ----------
    C : (M, M) ndarray or scipy.sparse matrix
        Count matrix
    reversible : bool
        If true sample from the ensemble of transition matrices
        restricted to those obeying a detailed balance condition,
        else draw from the whole ensemble of stochastic matrices.
    mu : array_like
        A fixed stationary distribution. Transition matrices with that
        stationary distribution will be sampled
    T0 : ndarray, shape=(n, n) or scipy.sparse matrix
        Starting point of the MC chain of the sampling algorithm.
        Has to obey the required constraints.
    nstep : int, default=None
        number of full Gibbs sampling sweeps per sample. This option is meant
        to ensure approximately uncorrelated samples for every call to
        sample(). If None, the number of steps will be automatically determined
        based on the other options and  the matrix size. nstep>1 will only be
        used for reversible sampling, because nonreversible sampling generates
        statistically independent transition matrices every step.

    Returns
    -------
    sampler : A :py:class:dense.tmatrix_sampler.TransitionMatrixSampler object that can be used to generate samples.

    Notes
    -----
    The transition matrix sampler generates transition matrices from
    the posterior distribution. The posterior distribution is given as
    a product of Dirichlet distributions

    .. math:: \mathbb{P}(T|C) \propto \prod_{i=1}^{M} \left( \prod_{j=1}^{M} p_{ij}^{c_{ij}} \right)

    The method can generate samples from the posterior under the following constraints

    **Reversible sampling**

    Using a MCMC sampler outlined in .. [1] it is ensured that samples
    from the posterior are reversible, i.e. there is a probability
    vector :math:`(\mu_i)` such that :math:`\mu_i t_{ij} = \mu_j
    t_{ji}` holds for all :math:`i,j`.

    **Reversible sampling with fixed stationary vector**

    Using a MCMC sampler outlined in .. [2] it is ensured that samples
    from the posterior fulfill detailed balance with respect to a given
    probability vector :math:`(\mu_i)`.

    References
    ----------
    .. [1] Noe, F. Probability distributions of molecular observables
        computed from Markov state models. J Chem Phys 128: 244103 (2008)

    .. [2] Trendelkamp-Schroer, B., H. Wu, F. Paul and F. Noe: Estimation and
        uncertainty of reversible Markov models. J. Chem. Phys. (submitted)

    """
    if issparse(C):
        _showSparseConversionWarning()
        C = C.toarray()

    from .dense.tmatrix_sampler import TransitionMatrixSampler
    sampler = TransitionMatrixSampler(C, reversible=reversible, mu=mu, P0=T0,
                                      nsteps=nsteps, prior=prior)
    return sampler