py-ruvseq-omicverse 0.1.0__py3-none-any.whl

py_ruvseq_omicverse-0.1.0.dist-info/METADATA

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: py-ruvseq-omicverse
+Version: 0.1.0
+Summary: Reference-validated py-RUVSeq algorithm subset
+License: Artistic License 2.0
+        
+        Copyright (c) 2000-2006, The Perl Foundation.
+        
+        Everyone is permitted to copy and distribute verbatim copies of this
+        license document, but changing it is not allowed.
+        
+        Preamble
+        ********
+        
+        This license establishes the terms under which a given free software
+        Package may be copied, modified, distributed, and/or redistributed.  The
+        intent is that the Copyright Holder maintains some artistic control over
+        the development of that Package while still keeping the Package
+        available as open source and free software.
+        
+        You are always permitted to make arrangements wholly outside of this
+        license directly with the Copyright Holder of a given Package.  If the
+        terms of this license do not permit the full use that you propose to
+        make of the Package, you should contact the Copyright Holder and seek a
+        different licensing arrangement.
+        
+        Definitions
+        ***********
+        
+        "Copyright Holder" means the individual(s) or organization(s) named in
+        the copyright notice for the entire Package.
+        
+        "Contributor" means any party that has contributed code or other
+        material to the Package, in accordance with the Copyright Holder's
+        procedures.
+        
+        "You" and "your" means any person who would like to copy, distribute, or
+        modify the Package.
+        
+        "Package" means the collection of files distributed by the Copyright
+        Holder, and derivatives of that collection and/or of those files.  A
+        given Package may consist of either the Standard Version, or a Modified
+        Version.
+        
+        "Distribute" means providing a copy of the Package or making it
+        accessible to anyone else, or in the case of a company or organization,
+        to others outside of your company or organization.
+        
+        "Distributor Fee" means any fee that you charge for Distributing this
+        Package or providing support for this Package to another party.  It does
+        not mean licensing fees.
+        
+        "Standard Version" refers to the Package if it has not been modified, or
+        has been modified only in ways explicitly requested by the Copyright
+        Holder.
+        
+        "Modified Version" means the Package, if it has been changed, and such
+        changes were not explicitly requested by the Copyright Holder.
+        
+        "Original License" means this Artistic License as Distributed with the
+        Standard Version of the Package, in its current version or as it may be
+        modified by The Perl Foundation in the future.
+        
+        "Source" form means the source code, documentation source, and
+        configuration files for the Package.
+        
+        "Compiled" form means the compiled bytecode, object code, binary, or any
+        other form resulting from mechanical transformation or translation of
+        the Source form.
+        
+        Permission for Use and Modification Without Distribution
+        ********************************************************
+        
+        (1) You are permitted to use the Standard Version and create and use
+        Modified Versions for any purpose without restriction, provided that you
+        do not Distribute the Modified Version.
+        
+        Permissions for Redistribution of the Standard Version
+        ******************************************************
+        
+        (2) You may Distribute verbatim copies of the Source form of the
+        Standard Version of this Package in any medium without restriction,
+        either gratis or for a Distributor Fee, provided that you duplicate all
+        of the original copyright notices and associated disclaimers.  At your
+        discretion, such verbatim copies may or may not include a Compiled form
+        of the Package.
+        
+        (3) You may apply any bug fixes, portability changes, and other
+        modifications made available from the Copyright Holder.  The resulting
+        Package will still be considered the Standard Version, and as such will
+        be subject to the Original License.
+        
+        Distribution of Modified Versions of the Package as Source
+        **********************************************************
+        
+        (4) You may Distribute your Modified Version as Source (either gratis or
+        for a Distributor Fee, and with or without a Compiled form of the
+        Modified Version) provided that you clearly document how it differs from
+        the Standard Version, including, but not limited to, documenting any
+        non-standard features, executables, or modules, and provided that you do
+        at least ONE of the following:
+        
+        (a) make the Modified Version available to the Copyright Holder of the
+        Standard Version, under the Original License, so that the Copyright
+        Holder may include your modifications in the Standard Version.
+        
+        (b) ensure that installation of your Modified Version does not prevent
+        the user installing or running the Standard Version.  In addition, the
+        Modified Version must bear a name that is different from the name of the
+        Standard Version.
+        
+        (c) allow anyone who receives a copy of the Modified Version to make the
+        Source form of the Modified Version available to others under
+        
+        (i) the Original License or
+        
+        (ii) a license that permits the licensee to freely copy, modify and
+        redistribute the Modified Version using the same licensing terms that
+        apply to the copy that the licensee received, and requires that the
+        Source form of the Modified Version, and of any works derived from it,
+        be made freely available in that license fees are prohibited but
+        Distributor Fees are allowed.
+        
+        Distribution of Compiled Forms of the Standard Version or Modified
+        ******************************************************************
+        Versions without the Source
+        ***************************
+        
+        (5) You may Distribute Compiled forms of the Standard Version without
+        the Source, provided that you include complete instructions on how to
+        get the Source of the Standard Version.  Such instructions must be valid
+        at the time of your distribution.  If these instructions, at any time
+        while you are carrying out such distribution, become invalid, you must
+        provide new instructions on demand or cease further distribution.  If
+        you provide valid instructions or cease distribution within thirty days
+        after you become aware that the instructions are invalid, then you do
+        not forfeit any of your rights under this license.
+        
+        (6) You may Distribute a Modified Version in Compiled form without the
+        Source, provided that you comply with Section 4 with respect to the
+        Source of the Modified Version.
+        
+        Aggregating or Linking the Package
+        **********************************
+        
+        (7) You may aggregate the Package (either the Standard Version or
+        Modified Version) with other packages and Distribute the resulting
+        aggregation provided that you do not charge a licensing fee for the
+        Package.  Distributor Fees are permitted, and licensing fees for other
+        components in the aggregation are permitted.  The terms of this license
+        apply to the use and Distribution of the Standard or Modified Versions
+        as included in the aggregation.
+        
+        (8) You are permitted to link Modified and Standard Versions with other
+        works, to embed the Package in a larger work of your own, or to build
+        stand-alone binary or bytecode versions of applications that include the
+        Package, and Distribute the result without restriction, provided the
+        result does not expose a direct interface to the Package.
+        
+        Items That are Not Considered Part of a Modified Version
+        ********************************************************
+        
+        (9) Works (including, but not limited to, modules and scripts) that
+        merely extend or make use of the Package, do not, by themselves, cause
+        the Package to be a Modified Version.  In addition, such works are not
+        considered parts of the Package itself, and are not subject to the terms
+        of this license.
+        
+        General Provisions
+        ******************
+        
+        (10) Any use, modification, and distribution of the Standard or Modified
+        Versions is governed by this Artistic License.  By using, modifying or
+        distributing the Package, you accept this license.  Do not use, modify,
+        or distribute the Package, if you do not accept this license.
+        
+        (11) If your Modified Version has been derived from a Modified Version
+        made by someone other than you, you are nevertheless required to ensure
+        that your Modified Version complies with the requirements of this
+        license.
+        
+        (12) This license does not grant you the right to use any trademark,
+        service mark, tradename, or logo of the Copyright Holder.
+        
+        (13) This license includes the non-exclusive, worldwide, free-of-charge
+        patent license to make, have made, use, offer to sell, sell, import and
+        otherwise transfer the Package with respect to any patent claims
+        licensable by the Copyright Holder that are necessarily infringed by the
+        Package.  If you institute patent litigation (including a cross-claim or
+        counterclaim) against any party alleging that the Package constitutes
+        direct or contributory patent infringement, then this Artistic License
+        to you shall terminate on the date that such litigation is filed.
+        
+        (14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT
+        HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED
+        WARRANTIES.  THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+        PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT
+        PERMITTED BY YOUR LOCAL LAW.  UNLESS REQUIRED BY LAW, NO COPYRIGHT
+        HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT,
+        INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE
+        OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Repository, https://github.com/omicverse/py-RUVSeq
+Project-URL: Issues, https://github.com/omicverse/py-RUVSeq/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: ATTRIBUTION.md
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=1.5
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# py-RUVSeq
+
+Review-stage Python reconstruction of a **subset** of RUVSeq, following the discovery, preregistration and reference-validation workflow in [omicverse-rebuildr](https://github.com/omicverse/omicverse-rebuildr).
+
+RUVg, RUVr and RUVs matrix methods plus replicate-index construction. No EDASeq objects, automatic control selection or downstream DE.
+
+## Install and test
+
+This project has not been published on PyPI. From this checkout:
+
+```bash
+python -m pip install ".[test]"
+python -m pytest -q
+```
+
+## Usage and function map
+
+See [the executed tutorial](examples/tutorial_fixture.ipynb), [R-to-Python parameter dictionary](examples/function_by_function_R_parity.ipynb), and [complete upstream export audit](AUDIT.md).
+Inputs, orientations and unsupported modes are documented in function docstrings. No R process is used at runtime.
+
+## Reproduce the R oracle
+
+```bash
+git clone https://github.com/drisso/RUVSeq.git ../RUVSeq-ref
+git -C ../RUVSeq-ref checkout f560e84eb493f0c2d72279612f9e4ca99493b434
+Rscript tests/reference.R ../RUVSeq-ref
+python -m pytest -q
+```
+
+The runner sources the pinned upstream functions, not a rewritten R approximation. RUVSeq S4 registration is intercepted to execute only matrix methods. SPARK sparse sum/mean helpers are supplied by Matrix, with unchanged statistical functions. MuSiC and muscat functions are sourced with their R dependencies loaded. muscat's source declares R >=4.6; this selected function subset was executed on R 4.5.2, not installed as the full package.
+
+muscat's public fixture additionally uses `Rscript tests/public_reference.R ../muscat-ref`.
+All other primary fixtures are synthetic and do not establish biological accuracy. Numerical gates were committed before implementation and have not been widened.
+
+## Validation and limitations
+
+28 focused tests passed locally without skips. See [reconstruction report](RECONSTRUCTION_REPORT.md) for scope and remaining release checks. This is fixture-level equivalence, not full-domain or full-package equivalence. Runtime objects and failure messages are Python-native.
+
+## Citation and license
+
+Upstream [RUVSeq](https://github.com/drisso/RUVSeq) at `f560e84eb493f0c2d72279612f9e4ca99493b434`; see ATTRIBUTION.md for upstream authors and package citation context, and LICENSE for terms.
+
+## Distribution preparation
+
+The intended PyPI distribution is `py-ruvseq-omicverse`; the import remains `pyruvseq`. See [release preparation](RELEASE.md) for installed-wheel validation and the manual Trusted Publishing procedure. This preparation does not mean a PyPI release is available.

py_ruvseq_omicverse-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+py_ruvseq_omicverse-0.1.0.dist-info/licenses/ATTRIBUTION.md,sha256=cFiNeQb8-RYBn0LBc8jjAutnddpyugFmUnc2L-NXuHQ,1300
+py_ruvseq_omicverse-0.1.0.dist-info/licenses/LICENSE,sha256=TKuwBAaxCrlg0-u1wU5QQs9U0rlwzEBHWIqijHA1Jf4,9073
+pyruvseq/__init__.py,sha256=pQ6ZCGg8Vm6CWWD2kuhZQhlOBYwIJ_QSO8LckiBCr6E,118
+pyruvseq/_other.py,sha256=yIp0rC9fJ5TppU6TL5hny1xbD1DVsGuSexILFjlmjr4,6485
+pyruvseq/_ruvg.py,sha256=pdN2IS3llx5GpACTv3KKQThJK_LwhYAVyRJi8PpOQL0,7365
+py_ruvseq_omicverse-0.1.0.dist-info/METADATA,sha256=ZWsWgBRJUE8BeiZFY7_BSgmS8nB8SWGYFFw30rGGsao,13788
+py_ruvseq_omicverse-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+py_ruvseq_omicverse-0.1.0.dist-info/top_level.txt,sha256=NzTk8o6EvLgWCVdF5SowpkgiVCZ3bYCx0gzw5EcpX9Q,9
+py_ruvseq_omicverse-0.1.0.dist-info/RECORD,,

py_ruvseq_omicverse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_ruvseq_omicverse-0.1.0.dist-info/licenses/ATTRIBUTION.md

@@ -0,0 +1,33 @@
+# Attribution
+
+Upstream RUVSeq 1.33.1, commit f560e84eb493f0c2d72279612f9e4ca99493b434.
+Algorithms reconstructed from the upstream source under the accompanying LICENSE.
+Upstream author declarations:
+
+```
+Package: RUVSeq
+Version: 1.33.1
+Title: Remove Unwanted Variation from RNA-Seq Data
+Description: This package implements the remove unwanted variation
+        (RUV) methods of Risso et al. (2014) for the normalization of
+        RNA-Seq read counts between samples.
+Authors@R: c(person("Davide", "Risso", email = "risso.davide@gmail.com",
+	          role = c("aut", "cre", "cph")),
+	     person("Sandrine", "Dudoit", role = "aut"),
+	     person("Lorena", "Pantano", role = "ctb"),
+	     person("Kamil", "Slowikowski", role = "ctb"))
+Author: Davide Risso [aut, cre, cph], Sandrine Dudoit [aut], Lorena Pantano [ctb], Kamil Slowikowski [ctb]
+Maintainer: Davide Risso <risso.davide@gmail.com>
+Date: 04-15-2014
+Imports: methods, MASS
+Depends: Biobase, EDASeq (>= 1.99.1), edgeR
+Suggests: BiocStyle, knitr, RColorBrewer, zebrafishRNASeq, DESeq2
+VignetteBuilder: knitr
+License: Artistic-2.0
+LazyLoad: yes
+biocViews: ImmunoOncology, DifferentialExpression, Preprocessing, RNASeq, Software
+URL: https://github.com/drisso/RUVSeq
+BugReports: https://github.com/drisso/RUVSeq/issues
+RoxygenNote: 6.0.1
+
+```

py_ruvseq_omicverse-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,197 @@
+Artistic License 2.0
+
+Copyright (c) 2000-2006, The Perl Foundation.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Preamble
+********
+
+This license establishes the terms under which a given free software
+Package may be copied, modified, distributed, and/or redistributed.  The
+intent is that the Copyright Holder maintains some artistic control over
+the development of that Package while still keeping the Package
+available as open source and free software.
+
+You are always permitted to make arrangements wholly outside of this
+license directly with the Copyright Holder of a given Package.  If the
+terms of this license do not permit the full use that you propose to
+make of the Package, you should contact the Copyright Holder and seek a
+different licensing arrangement.
+
+Definitions
+***********
+
+"Copyright Holder" means the individual(s) or organization(s) named in
+the copyright notice for the entire Package.
+
+"Contributor" means any party that has contributed code or other
+material to the Package, in accordance with the Copyright Holder's
+procedures.
+
+"You" and "your" means any person who would like to copy, distribute, or
+modify the Package.
+
+"Package" means the collection of files distributed by the Copyright
+Holder, and derivatives of that collection and/or of those files.  A
+given Package may consist of either the Standard Version, or a Modified
+Version.
+
+"Distribute" means providing a copy of the Package or making it
+accessible to anyone else, or in the case of a company or organization,
+to others outside of your company or organization.
+
+"Distributor Fee" means any fee that you charge for Distributing this
+Package or providing support for this Package to another party.  It does
+not mean licensing fees.
+
+"Standard Version" refers to the Package if it has not been modified, or
+has been modified only in ways explicitly requested by the Copyright
+Holder.
+
+"Modified Version" means the Package, if it has been changed, and such
+changes were not explicitly requested by the Copyright Holder.
+
+"Original License" means this Artistic License as Distributed with the
+Standard Version of the Package, in its current version or as it may be
+modified by The Perl Foundation in the future.
+
+"Source" form means the source code, documentation source, and
+configuration files for the Package.
+
+"Compiled" form means the compiled bytecode, object code, binary, or any
+other form resulting from mechanical transformation or translation of
+the Source form.
+
+Permission for Use and Modification Without Distribution
+********************************************************
+
+(1) You are permitted to use the Standard Version and create and use
+Modified Versions for any purpose without restriction, provided that you
+do not Distribute the Modified Version.
+
+Permissions for Redistribution of the Standard Version
+******************************************************
+
+(2) You may Distribute verbatim copies of the Source form of the
+Standard Version of this Package in any medium without restriction,
+either gratis or for a Distributor Fee, provided that you duplicate all
+of the original copyright notices and associated disclaimers.  At your
+discretion, such verbatim copies may or may not include a Compiled form
+of the Package.
+
+(3) You may apply any bug fixes, portability changes, and other
+modifications made available from the Copyright Holder.  The resulting
+Package will still be considered the Standard Version, and as such will
+be subject to the Original License.
+
+Distribution of Modified Versions of the Package as Source
+**********************************************************
+
+(4) You may Distribute your Modified Version as Source (either gratis or
+for a Distributor Fee, and with or without a Compiled form of the
+Modified Version) provided that you clearly document how it differs from
+the Standard Version, including, but not limited to, documenting any
+non-standard features, executables, or modules, and provided that you do
+at least ONE of the following:
+
+(a) make the Modified Version available to the Copyright Holder of the
+Standard Version, under the Original License, so that the Copyright
+Holder may include your modifications in the Standard Version.
+
+(b) ensure that installation of your Modified Version does not prevent
+the user installing or running the Standard Version.  In addition, the
+Modified Version must bear a name that is different from the name of the
+Standard Version.
+
+(c) allow anyone who receives a copy of the Modified Version to make the
+Source form of the Modified Version available to others under
+
+(i) the Original License or
+
+(ii) a license that permits the licensee to freely copy, modify and
+redistribute the Modified Version using the same licensing terms that
+apply to the copy that the licensee received, and requires that the
+Source form of the Modified Version, and of any works derived from it,
+be made freely available in that license fees are prohibited but
+Distributor Fees are allowed.
+
+Distribution of Compiled Forms of the Standard Version or Modified
+******************************************************************
+Versions without the Source
+***************************
+
+(5) You may Distribute Compiled forms of the Standard Version without
+the Source, provided that you include complete instructions on how to
+get the Source of the Standard Version.  Such instructions must be valid
+at the time of your distribution.  If these instructions, at any time
+while you are carrying out such distribution, become invalid, you must
+provide new instructions on demand or cease further distribution.  If
+you provide valid instructions or cease distribution within thirty days
+after you become aware that the instructions are invalid, then you do
+not forfeit any of your rights under this license.
+
+(6) You may Distribute a Modified Version in Compiled form without the
+Source, provided that you comply with Section 4 with respect to the
+Source of the Modified Version.
+
+Aggregating or Linking the Package
+**********************************
+
+(7) You may aggregate the Package (either the Standard Version or
+Modified Version) with other packages and Distribute the resulting
+aggregation provided that you do not charge a licensing fee for the
+Package.  Distributor Fees are permitted, and licensing fees for other
+components in the aggregation are permitted.  The terms of this license
+apply to the use and Distribution of the Standard or Modified Versions
+as included in the aggregation.
+
+(8) You are permitted to link Modified and Standard Versions with other
+works, to embed the Package in a larger work of your own, or to build
+stand-alone binary or bytecode versions of applications that include the
+Package, and Distribute the result without restriction, provided the
+result does not expose a direct interface to the Package.
+
+Items That are Not Considered Part of a Modified Version
+********************************************************
+
+(9) Works (including, but not limited to, modules and scripts) that
+merely extend or make use of the Package, do not, by themselves, cause
+the Package to be a Modified Version.  In addition, such works are not
+considered parts of the Package itself, and are not subject to the terms
+of this license.
+
+General Provisions
+******************
+
+(10) Any use, modification, and distribution of the Standard or Modified
+Versions is governed by this Artistic License.  By using, modifying or
+distributing the Package, you accept this license.  Do not use, modify,
+or distribute the Package, if you do not accept this license.
+
+(11) If your Modified Version has been derived from a Modified Version
+made by someone other than you, you are nevertheless required to ensure
+that your Modified Version complies with the requirements of this
+license.
+
+(12) This license does not grant you the right to use any trademark,
+service mark, tradename, or logo of the Copyright Holder.
+
+(13) This license includes the non-exclusive, worldwide, free-of-charge
+patent license to make, have made, use, offer to sell, sell, import and
+otherwise transfer the Package with respect to any patent claims
+licensable by the Copyright Holder that are necessarily infringed by the
+Package.  If you institute patent litigation (including a cross-claim or
+counterclaim) against any party alleging that the Package constitutes
+direct or contributory patent infringement, then this Artistic License
+to you shall terminate on the date that such litigation is filed.
+
+(14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT
+HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES.  THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT
+PERMITTED BY YOUR LOCAL LAW.  UNLESS REQUIRED BY LAW, NO COPYRIGHT
+HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE
+OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

py_ruvseq_omicverse-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyruvseq

pyruvseq/__init__.py

@@ -0,0 +1,3 @@
+from ._ruvg import ruvg
+from ._other import ruvr, ruvs, make_groups
+__all__ = ["ruvg", "ruvr", "ruvs", "make_groups"]

pyruvseq/_other.py

@@ -0,0 +1,132 @@
+"""RUVr/RUVs matrix methods; see pinned RUVSeq source in manifest.yaml.
+
+RUVSeq authors: Davide Risso and Sandrine Dudoit; Artistic-2.0.
+"""
+import warnings
+import numpy as np
+import pandas as pd
+from scipy import sparse
+
+
+def _prepare(x, controls, k, epsilon, tolerance, is_log):
+    labels = x if isinstance(x, pd.DataFrame) else None
+    values = x.to_numpy() if labels is not None else x
+    values = values.toarray() if sparse.issparse(values) else np.asarray(values)
+    if (values.ndim != 2 or min(values.shape) == 0 or
+            not np.issubdtype(values.dtype, np.number) or np.iscomplexobj(values) or
+            not np.isfinite(values).all()):
+        raise ValueError('x must be a finite genes-by-samples matrix.')
+    if isinstance(k, (bool, np.bool_)) or not isinstance(k, (int, np.integer)) or not 0 < k < values.shape[1]:
+        raise ValueError('k must be a positive integer less than the sample count.')
+    if not np.isfinite(epsilon) or epsilon <= 0 or not np.isfinite(tolerance) or tolerance < 0:
+        raise ValueError('Require positive epsilon and nonnegative tolerance.')
+    if not is_log and (np.any(values < 0) or not np.allclose(values, np.rint(values), rtol=0, atol=1e-8)):
+        raise ValueError('Use raw integer counts or set is_log=True.')
+    selected = np.asarray(controls)
+    if selected.ndim != 1 or not len(selected):
+        raise ValueError('Select a nonempty one-dimensional set of controls.')
+    if labels is not None and (not labels.index.is_unique or not labels.columns.is_unique):
+        raise ValueError('Gene and sample labels must be unique.')
+    if selected.dtype.kind == 'b':
+        if len(selected) != values.shape[0]:
+            raise ValueError('Control mask length mismatch.')
+        idx = np.flatnonzero(selected)
+    elif labels is not None:
+        idx = labels.index.get_indexer(selected)
+    elif selected.dtype.kind in 'iu':
+        idx = selected
+    else:
+        raise ValueError('Array controls must be integer indices or a boolean mask.')
+    if not len(idx) or len(np.unique(idx)) != len(idx) or np.any(idx < 0) or np.any(idx >= values.shape[0]):
+        raise ValueError('Controls must be distinct valid genes.')
+    y = values.astype(float).T
+    return (y if is_log else np.log(y + epsilon)), idx, labels
+
+
+def _rank(d, k, tolerance):
+    effective = min(k, int(np.count_nonzero(d > tolerance)))
+    if not effective:
+        raise ValueError('No nonzero control subspace remains.')
+    if effective < k:
+        warnings.warn(f'Rank reduces k from {k} to {effective}.', UserWarning, stacklevel=3)
+    return effective
+
+
+def _result(w, corrected, labels, epsilon, is_log, round_counts):
+    if not is_log:
+        with np.errstate(over='raise'):
+            corrected = np.exp(corrected) - epsilon
+        if round_counts:
+            corrected = np.maximum(np.rint(corrected), 0)
+    corrected = corrected.T
+    if labels is not None:
+        corrected = pd.DataFrame(corrected, index=labels.index, columns=labels.columns)
+        w = pd.DataFrame(w, index=labels.columns, columns=[f'W_{i+1}' for i in range(w.shape[1])])
+    return {'W': w, 'normalized_counts': corrected, 'k_used': w.shape[1]}
+
+
+def ruvr(x, controls, k, residuals, *, center=True, round_counts=True,
+         epsilon=1., tolerance=1e-8, is_log=False):
+    """Estimate unwanted factors from caller-supplied genes-by-samples residuals.
+
+    Residuals should come from an appropriate first-pass biological model; this
+    function does not fit that model. Use returned W with original counts in DE.
+    """
+    y, idx, labels = _prepare(x, controls, k, epsilon, tolerance, is_log)
+    if isinstance(residuals, pd.DataFrame) and labels is not None:
+        if not residuals.index.equals(labels.index) or not residuals.columns.equals(labels.columns):
+            raise ValueError('Residual labels must match expression axes in order.')
+    e = np.asarray(residuals, dtype=float).T
+    if e.shape != y.shape or not np.isfinite(e).all():
+        raise ValueError('Residuals must be finite and have the same shape as x.')
+    if center:
+        e = e - e.mean(axis=0)
+    u, d, _ = np.linalg.svd(e[:, idx], full_matrices=False)
+    w = u[:, :_rank(d, k, tolerance)]
+    return _result(w, y - w @ (w.T @ y), labels, epsilon, is_log, round_counts)
+
+
+def make_groups(groups):
+    """Return zero-based replicate indices, padded with -1 (R uses one-based)."""
+    groups = np.asarray(groups)
+    if groups.ndim != 1 or not len(groups) or pd.isna(groups).any():
+        raise ValueError('groups must contain one nonmissing label per sample.')
+    rows = [np.flatnonzero(groups == value) for value in sorted(pd.unique(groups))]
+    result = np.full((len(rows), max(map(len, rows))), -1, dtype=int)
+    for i, row in enumerate(rows):
+        result[i, :len(row)] = row
+    return result
+
+
+def ruvs(x, controls, k, replicate_indices, *, round_counts=True,
+         epsilon=1., tolerance=1e-8, is_log=False):
+    """Estimate factors using replicate groups with constant biological signal.
+
+    replicate_indices is a matrix of zero-based sample positions padded with
+    -1, as returned by make_groups. Singleton groups do not estimate variation.
+    """
+    y, idx, labels = _prepare(x, controls, k, epsilon, tolerance, is_log)
+    groups = np.asarray(replicate_indices)
+    if groups.ndim != 2 or groups.dtype.kind not in 'iu' or np.any(groups < -1) or np.any(groups >= len(y)):
+        raise ValueError('replicate_indices must contain valid zero-based positions or -1.')
+    centered = []
+    for row in groups:
+        row = row[row >= 0]
+        if len(np.unique(row)) != len(row):
+            raise ValueError('Replicate rows cannot repeat a sample.')
+        if len(row) >= 2:
+            centered.extend(y[row] - y[row].mean(axis=0))
+    if not centered:
+        raise ValueError('At least one replicate group needs two samples.')
+    yc = np.asarray(centered)
+    yc = yc[yc.sum(axis=1) != 0]  # preserve upstream row filtering semantics
+    if not len(yc):
+        raise ValueError('Replicates provide no variation.')
+    _, d, vt = np.linalg.svd(yc, full_matrices=False)
+    effective = _rank(d, k, tolerance)
+    alpha = d[:effective, None] * vt[:effective]
+    ac = alpha[:, idx]
+    if np.linalg.matrix_rank(ac) < effective:
+        raise ValueError('Control loadings cannot identify all requested factors.')
+    w = y[:, idx] @ np.linalg.solve(ac @ ac.T, ac).T
+    return _result(w, y - w @ alpha, labels, epsilon, is_log, round_counts)

pyruvseq/_ruvg.py

@@ -0,0 +1,139 @@
+"""Control-gene removal of unwanted variation (RUVg matrix method).
+
+Reference: Risso et al., Nature Biotechnology (2014), doi:10.1038/nbt.2931.
+Numerical contract checked against drisso/RUVSeq, commit
+f560e84eb493f0c2d72279612f9e4ca99493b434 (RUVSeq 1.33.1).
+"""
+
+from __future__ import annotations
+
+import warnings
+from numbers import Integral
+
+import numpy as np
+import pandas as pd
+from scipy import sparse
+
+
+
+def ruvg(expression, controls, k=1, *, drop=0, center=True,
+         round_counts=True, epsilon=1.0, tolerance=1e-8, is_log=False):
+    """Estimate RUVg factors from a genes-by-samples expression matrix.
+
+    Parameters
+    ----------
+    expression : pandas.DataFrame or two-dimensional array or scipy sparse matrix
+        Genes on rows and independent samples on columns. Counts must be finite,
+        nonnegative integers. With ``is_log=True``, supply already transformed
+        finite expression instead. Sparse input is explicitly densified: the
+        transformed/centered matrix and returned correction are dense.
+    controls : sequence
+        Negative control gene names for a DataFrame, zero-based row indices for
+        an array, or a boolean row mask. DataFrame controls are always labels.
+        Controls should not respond to the biological condition of interest.
+    k : int
+        Number of leading control-gene singular vectors considered, before
+        removing ``drop`` vectors. Must be less than the number of samples.
+    drop : int
+        Discard this many leading vectors; the output has at most k-drop factors.
+    center : bool
+        Center each transformed gene across samples before learning factors.
+    round_counts : bool
+        For count input, round reconstructed counts and clip negatives to zero.
+        If False, negative reconstructed values are retained, as in RUVSeq.
+    epsilon : float
+        Positive offset in the natural-log transformation log(counts + epsilon).
+    tolerance : float
+        Absolute singular-value threshold used to reduce k on deficient controls.
+    is_log : bool
+        Skip log transformation and return correction on the supplied scale.
+
+    Returns
+    -------
+    dict
+        ``W``: samples-by-factors; ``normalized_counts``: genes-by-samples.
+        Both are DataFrames with preserved axes for DataFrame input, otherwise
+        ndarrays. ``k_used`` is the number of returned factors. Input is unchanged.
+
+    Notes
+    -----
+    For count-based DE, use W as covariates alongside the biological design and
+    the original counts. The reconstructed matrix is not a substitute for raw
+    counts in a count likelihood. Confounded biology and unwanted variation
+    cannot be separated by this procedure without suitable controls.
+
+    This is the RUVg matrix algorithm, not full RUVSeq (RUVr/RUVs, EDASeq objects,
+    or downstream DE). Unlike R's warning-and-continue behavior, fractional raw
+    counts and a control subspace with no retained factors are rejected.
+    Singular-vector signs are arbitrary; compare W @ W.T across implementations.
+    """
+    frame = isinstance(expression, pd.DataFrame)
+    if frame and (not expression.index.is_unique or not expression.columns.is_unique):
+        raise ValueError("Gene and sample labels must be unique.")
+    values = expression.to_numpy() if frame else expression
+    values = values.toarray() if sparse.issparse(values) else np.asarray(values)
+    if (values.ndim != 2 or min(values.shape) < 1
+            or not np.issubdtype(values.dtype, np.number)
+            or np.iscomplexobj(values) or not np.isfinite(values).all()):
+        raise ValueError("expression must be a nonempty finite numeric matrix.")
+    for name, flag in (("center", center), ("round_counts", round_counts), ("is_log", is_log)):
+        if not isinstance(flag, (bool, np.bool_)):
+            raise ValueError(f"{name} must be boolean.")
+    if isinstance(k, (bool, np.bool_)) or not isinstance(k, Integral) or not 0 < k < values.shape[1]:
+        raise ValueError("k must be a positive integer smaller than the sample count.")
+    if isinstance(drop, (bool, np.bool_)) or not isinstance(drop, Integral) or not 0 <= drop < k:
+        raise ValueError("drop must be an integer with 0 <= drop < k.")
+    for name, value, positive in (("epsilon", epsilon, True), ("tolerance", tolerance, False)):
+        if (not np.isscalar(value) or isinstance(value, (str, bool))
+                or not np.isreal(value) or not np.isfinite(value)
+                or (value <= 0 if positive else value < 0)):
+            raise ValueError(f"{name} must be finite and {'positive' if positive else 'nonnegative'}.")
+    if not is_log and (np.any(values < 0) or
+                       not np.all(np.abs(values - np.rint(values)) < np.sqrt(np.finfo(float).eps))):
+        raise ValueError("Supply nonnegative integer counts, or set is_log=True for transformed data.")
+    selected = np.asarray(controls)
+    if selected.ndim != 1 or selected.size == 0:
+        raise ValueError("controls must be a nonempty one-dimensional sequence.")
+    if selected.dtype.kind == "b":
+        if len(selected) != values.shape[0]:
+            raise ValueError("The control mask must have one entry per gene.")
+        indices = np.flatnonzero(selected)
+    elif frame:
+        indices = expression.index.get_indexer(selected)
+        if np.any(indices < 0):
+            raise ValueError("All control gene labels must occur in expression.index.")
+    else:
+        if selected.dtype.kind not in "iu":
+            raise ValueError("Array controls must be zero-based integer row indices or a boolean mask.")
+        indices = selected
+        if np.any(indices < 0) or np.any(indices >= values.shape[0]):
+            raise ValueError("Control indices are out of bounds.")
+    if not len(indices) or len(np.unique(indices)) != len(indices):
+        raise ValueError("Select at least one control gene without duplicates.")
+
+    transformed = values.astype(np.float64, copy=True).T
+    if not is_log:
+        transformed = np.log(transformed + epsilon)
+    control_matrix = transformed[:, indices]
+    if center:
+        control_matrix = control_matrix - control_matrix.mean(axis=0)
+    vectors, singular_values, _ = np.linalg.svd(control_matrix, full_matrices=False)
+    effective = min(k, int(np.count_nonzero(singular_values > tolerance)))
+    if effective <= drop:
+        raise ValueError("Control matrix rank leaves no factors after drop; revise controls, k or drop.")
+    if effective < k:
+        warnings.warn(f"Control matrix rank reduces k from {k} to {effective}.", UserWarning, stacklevel=2)
+    factors = vectors[:, drop:effective]
+    # Orthogonal projection is invariant to SVD sign flips and basis rotations.
+    corrected = transformed - factors @ (factors.T @ transformed)
+    if not is_log:
+        with np.errstate(over="raise", invalid="raise"):
+            corrected = np.exp(corrected) - epsilon
+        if round_counts:
+            corrected = np.maximum(np.rint(corrected), 0)
+    corrected = corrected.T
+    if frame:
+        factors = pd.DataFrame(factors, index=expression.columns,
+                               columns=[f"W_{i + 1}" for i in range(factors.shape[1])])
+        corrected = pd.DataFrame(corrected, index=expression.index, columns=expression.columns)
+    return {"W": factors, "normalized_counts": corrected, "k_used": effective - drop}