Merge pull request #1 from austintwang/dev

Merge into main

Author: austintwang

.github/workflows/CI.yml

@@ -158,6 +158,7 @@ jobs:
     runs-on: ubuntu-latest
     if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
     needs: [linux, musllinux, windows, macos, sdist]
+    environment: release
     permissions:
       # Use to sign the release artifacts
       id-token: write
@@ -174,8 +175,8 @@ jobs:
       - name: Publish to PyPI
         if: ${{ startsWith(github.ref, 'refs/tags/') }}
         uses: PyO3/maturin-action@v1
-        env:
-          MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        # env:
+        #   MATURIN_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
         with:
           command: upload
           args: --non-interactive --skip-existing wheels-*/*

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "dinuc_shuf"
-version = "0.1.0"
+version = "0.1.0-beta.1"
 edition = "2021"
 
 [lib]

Cargo.toml

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Austin Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

LICENSE

@@ -1,5 +1,47 @@
 # dinuc_shuf
 
-This is a simple Python package with a single function `shuffle` that does a dinucleotide shuffle on input sequences.
+This Python package provides a minimal and efficient implementation for performing dinucleotide shuffles on one-hot-encoded sequences.
 
-A dinucleotide shuffle preserves the dinucleotide (doublet) frequencies of the input sequence while randomizing the order of the dinucleotides. This is useful for generating compositionally-matched random sequences.
+Dinucleotide shuffling preserves the dinucleotide (nucleotide pair) frequencies of the input sequence while randomizing the order of the pairs. This is particularly useful for generating random sequences that match the compositional properties of the original input.
+
+To ensure a uniform random sample from all possible shuffles, the algorithm leverages the rank-one-update Kirchhoff matrix method described by [Colburn et al.](https://doi.org/10.1006/jagm.1996.0014) for sampling random arborescences, combined with a random Eulerian walk on the dinucleotide transition graph. The core algorithm is implemented in Rust for performance, with Python bindings for easy integration.
+
+This package is lightweight, requiring only a single dependency on Numpy.
+
+## Installation
+
+To install the package from PyPI, run:
+
+```bash
+pip install dinuc-shuf
+```
+
+## Usage
+
+```python
+import numpy as np
+from dinuc_shuf import shuffle
+
+SEQ_ALPHABET = np.array(["A","C","G","T"], dtype="S1")
+
+def one_hot_encode(sequence, dtype=np.uint8):
+    sequence = sequence.upper()
+    seq_chararray = np.frombuffer(sequence.encode('UTF-8'), dtype='S1')
+    one_hot = (seq_chararray[:,None] == SEQ_ALPHABET[None,:]).astype(dtype)
+
+    return one_hot
+
+def one_hot_decode(one_hot):
+    return SEQ_ALPHABET[one_hot.argmax(axis=1)].tobytes().decode('UTF-8')
+
+sequence = "ACCCACGATGATG"
+one_hot_sequence = one_hot_encode(sequence)
+shuffled_one_hot = shuffle(one_hot_sequence[None,:,:])
+shuffled = one_hot_decode(shuffled_one_hot[0,:,:])
+
+print(shuffled) # Output: "ACATGATGACCCG"
+```
+
+## API Reference
+
+A full API reference is available [here](https://austintwang.github.io/dinuc_shuf/).

README.md

@@ -42,20 +42,26 @@ <h2>API Documentation</h2>
                     <h1 class="modulename">
 dinuc_shuf    </h1>
 
-                
+                        <div class="docstring"><p>This module provides a method <code><a href="#shuffle">shuffle</a></code> to dinucleotide shuffle one-hot encoded sequences.</p>
+
+<p>For installation and usage instructions, check out the <a href="https://github.com/austintwang/dinuc_shuf">GitHub repository</a>.</p>
+</div>
+
                         <input id="mod-dinuc_shuf-view-source" class="view-source-toggle-state" type="checkbox" aria-hidden="true" tabindex="-1">
 
                         <label class="view-source-button" for="mod-dinuc_shuf-view-source"><span>View Source</span></label>
 
-                        <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos">1</span></a><span class="kn">from</span><span class="w"> </span><span class="nn">.main</span><span class="w"> </span><span class="kn">import</span> <span class="n">shuffle</span>
-</span><span id="L-2"><a href="#L-2"><span class="linenos">2</span></a>
-</span><span id="L-3"><a href="#L-3"><span class="linenos">3</span></a><span class="sd">&quot;&quot;&quot;</span>
-</span><span id="L-4"><a href="#L-4"><span class="linenos">4</span></a><span class="sd">.. include:: ../../README.md</span>
-</span><span id="L-5"><a href="#L-5"><span class="linenos">5</span></a><span class="sd">&quot;&quot;&quot;</span>
-</span><span id="L-6"><a href="#L-6"><span class="linenos">6</span></a>
-</span><span id="L-7"><a href="#L-7"><span class="linenos">7</span></a><span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;shuffle&#39;</span><span class="p">]</span>
-</span><span id="L-8"><a href="#L-8"><span class="linenos">8</span></a>
-</span><span id="L-9"><a href="#L-9"><span class="linenos">9</span></a><span class="n">__docformat__</span> <span class="o">=</span> <span class="s1">&#39;numpy&#39;</span>
+                        <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos"> 1</span></a><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-2"><a href="#L-2"><span class="linenos"> 2</span></a><span class="sd">This module provides a method `shuffle` to dinucleotide shuffle one-hot encoded sequences.</span>
+</span><span id="L-3"><a href="#L-3"><span class="linenos"> 3</span></a>
+</span><span id="L-4"><a href="#L-4"><span class="linenos"> 4</span></a><span class="sd">For installation and usage instructions, check out the [GitHub repository](https://github.com/austintwang/dinuc_shuf).</span>
+</span><span id="L-5"><a href="#L-5"><span class="linenos"> 5</span></a><span class="sd">&quot;&quot;&quot;</span>
+</span><span id="L-6"><a href="#L-6"><span class="linenos"> 6</span></a>
+</span><span id="L-7"><a href="#L-7"><span class="linenos"> 7</span></a><span class="kn">from</span><span class="w"> </span><span class="nn">.main</span><span class="w"> </span><span class="kn">import</span> <span class="n">shuffle</span>
+</span><span id="L-8"><a href="#L-8"><span class="linenos"> 8</span></a>
+</span><span id="L-9"><a href="#L-9"><span class="linenos"> 9</span></a><span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;shuffle&#39;</span><span class="p">]</span>
+</span><span id="L-10"><a href="#L-10"><span class="linenos">10</span></a>
+</span><span id="L-11"><a href="#L-11"><span class="linenos">11</span></a><span class="n">__docformat__</span> <span class="o">=</span> <span class="s1">&#39;numpy&#39;</span>
 </span></pre></div>
 
 
@@ -78,7 +84,7 @@ <h1 class="modulename">
 </span><span id="shuffle-12"><a href="#shuffle-12"><span class="linenos">12</span></a><span class="sd">    Parameters</span>
 </span><span id="shuffle-13"><a href="#shuffle-13"><span class="linenos">13</span></a><span class="sd">    ----------</span>
 </span><span id="shuffle-14"><a href="#shuffle-14"><span class="linenos">14</span></a><span class="sd">    seqs : np.ndarray</span>
-</span><span id="shuffle-15"><a href="#shuffle-15"><span class="linenos">15</span></a><span class="sd">        A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size).</span>
+</span><span id="shuffle-15"><a href="#shuffle-15"><span class="linenos">15</span></a><span class="sd">        A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size). Will be cast to np.uint8 if not already so.</span>
 </span><span id="shuffle-16"><a href="#shuffle-16"><span class="linenos">16</span></a><span class="sd">    rng : Optional[np.random.Generator], optional</span>
 </span><span id="shuffle-17"><a href="#shuffle-17"><span class="linenos">17</span></a><span class="sd">        A NumPy random number generator instance. If None, a new default generator instance will be used.</span>
 </span><span id="shuffle-18"><a href="#shuffle-18"><span class="linenos">18</span></a><span class="sd">    verify : bool, optional</span>
@@ -128,7 +134,7 @@ <h6 id="parameters">Parameters</h6>
 
 <ul>
 <li><strong>seqs</strong> (np.ndarray):
-A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size).</li>
+A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size). Will be cast to np.uint8 if not already so.</li>
 <li><strong>rng</strong> (Optional[np.random.Generator], optional):
 A NumPy random number generator instance. If None, a new default generator instance will be used.</li>
 <li><strong>verify</strong> (bool, optional):

docs/dinuc_shuf.html

@@ -4,18 +4,28 @@ build-backend = "maturin"
 
 [project]
 name = "dinuc_shuf"
+description = "A utility for shuffling biological sequences while preserving dinucleotide frequencies."
+authors = [{ name = "Austin Wang" }]
 requires-python = ">=3.8"
 classifiers = [
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
+    "Development Status :: 4 - Beta",
 ]
 dynamic = ["version"]
 dependencies = [
     "numpy >= 1.16.0"
 ]
+readme = "README.md"
+license = "MIT"
 
 [tool.maturin]
 features = ["pyo3/extension-module"]
 python-source = "python"
-# module-name = "dinuc_shuf._internal"
+
+[project.urls]
+Homepage = "https://github.com/austintwang/dinuc_shuf"
+Documentation = "https://austintwang.github.io/dinuc_shuf"
+Repository = "https://github.com/austintwang/dinuc_shuf.git"
+"Bug Tracker" = "https://github.com/austintwang/dinuc_shuf/issues"

pyproject.toml

@@ -1,9 +1,11 @@
-from .main import shuffle
-
 """
-.. include:: ../../README.md
+This module provides a method `shuffle` to dinucleotide shuffle one-hot encoded sequences.
+
+For installation and usage instructions, check out the [GitHub repository](https://github.com/austintwang/dinuc_shuf).
 """
 
+from .main import shuffle
+
 __all__ = ['shuffle']
 
 __docformat__ = 'numpy'

python/dinuc_shuf/__init__.py

@@ -11,7 +11,7 @@ def shuffle(seqs: np.ndarray, rng: Optional[np.random.Generator] = None, verify:
     Parameters
     ----------
     seqs : np.ndarray
-        A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size).
+        A three-dimensional array of one-hot-encoded sequences with shape (num_seqs, seq_len, alphabet_size). Will be cast to np.uint8 if not already so.
     rng : Optional[np.random.Generator], optional
         A NumPy random number generator instance. If None, a new default generator instance will be used.
     verify : bool, optional

python/dinuc_shuf/main.py

@@ -20,7 +20,7 @@ def one_hot_decode(one_hot):
     return SEQ_ALPHABET[one_hot.argmax(axis=1)].tobytes().decode('UTF-8')
 
 
-def test_factory(seq_str, num_shuffles_true=None):
+def test_factory(seq_str, num_shuffles_true=None, n=100000):
     class TestDinucShuffle(unittest.TestCase):
         def setUp(self):
             seq = one_hot_encode(seq_str)
@@ -31,18 +31,19 @@ def setUp(self):
 
             self.num_shuffles_true = num_shuffles_true
 
+            self.n = n
+            seq_expanded = np.repeat(self.seq[None,:,:], self.n, axis=0)
+            self.shuffled = shuffle(seq_expanded, rng=self.rng)
+            self.decoded_shuffled = [one_hot_decode(i) for i in self.shuffled]
+
         def test_composition(self):
-            shuffled = shuffle(self.seq[None,:,:], rng=self.rng)
-            shuffled_adj = shuffled[0,:-1,:].T @ shuffled[0,1:,:]
-            np.testing.assert_array_equal(self.seq_adj, shuffled_adj)
+            for shuffled in self.shuffled:
+                shuffled_adj = shuffled[:-1,:].T @ shuffled[1:,:]
+                np.testing.assert_array_equal(self.seq_adj, shuffled_adj)
 
         def test_uniformity(self):
-            n = 100000
-            seq_expanded = np.repeat(self.seq[None,:,:], n, axis=0)
-            shuffled = shuffle(seq_expanded, rng=self.rng)
-            decoded_shuffled = [one_hot_decode(i) for i in shuffled]
             counts = {}
-            for i in decoded_shuffled:
+            for i in self.decoded_shuffled:
                 counts.setdefault(i, 0) 
                 counts[i] += 1    
 
@@ -63,12 +64,7 @@ def test_coverage(self):
             if self.num_shuffles_true is None:
                 self.skipTest("True number of unique sequences not provided")
 
-            n = 1000
-            seq_expanded = np.repeat(self.seq[None,:,:], n, axis=0)
-            shuffled = shuffle(seq_expanded, rng=self.rng)
-            decoded_shuffled = [one_hot_decode(i) for i in shuffled]
-
-            unique_seqs = set(decoded_shuffled)
+            unique_seqs = set(self.decoded_shuffled)
             unique_seqs.discard("")
             num_unique_seqs = len(unique_seqs)
 
@@ -77,10 +73,29 @@ def test_coverage(self):
     return TestDinucShuffle
 
 
-empty = test_factory("", 0)
-A = test_factory("A", 1)
-TT = test_factory("TT", 1)
-ACGT = test_factory("ACGT", 1)
+class TestEmptyInput(unittest.TestCase):
+    def test_empty_input(self):
+        seq = np.zeros((0, 1000, 4), dtype=np.uint8)
+        shuffled = shuffle(seq)
+        
+        np.testing.assert_array_equal(seq, shuffled)
+
+
+class TestMalformedInput(unittest.TestCase):
+    def test_wrong_shape(self):
+        seq = one_hot_encode("ACCCACGATGATA")
+        with self.assertRaises(ValueError):
+            shuffle(seq)
+
+    def test_not_one_hot(self):
+        seq = np.zeros((1, 1000, 4), dtype=np.uint8)
+        with self.assertRaises(ValueError):
+            shuffle(seq)
+
+
+A = test_factory("A", 1, n=10)
+TT = test_factory("TT", 1, n=10)
+ACGT = test_factory("ACGT", 1, n=10)
 ACGCACGG = test_factory("ACGCACGG")
 ACCCACGATGATA = test_factory("ACCCACGATGATA", 72)
 ACCCACGATGATG = test_factory("ACCCACGATGATG", 27)