workflow to publish to pip, ruff linting, license and readme

LinearParadox · LinearParadox · commit 5c5aace607ec · 2025-06-07T21:16:16.000-07:00
diff --git a/.github/workflows/build_package.yml b/.github/workflows/build_package.yml
@@ -0,0 +1,42 @@
+name: Build and Publish Package
+on:
+  release:
+    types: [created]
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Get all tags for proper versioning
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: |
+          python -m pip install --upgrade pip
+          pip install uv
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish to PyPI
+        if: github.event_name == 'release'
+        run: |
+          uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Publish to TestPyPI
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          uv publish --index testpypi
+
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.TEST_PYPI_API_TOKEN }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,7 +2,6 @@ name: CI
 
 on:
   push:
-    branches: [master, dev]
   pull_request:
     branches: [main]
 
diff --git a/README.md b/README.md
@@ -1,14 +1,142 @@
-A utility to convert anndata files into loupe files visualizable in 10xs loupe browser.
+from loupepy import get_count_matrixWhile this tool is independently maintained and not officially supported by 10x Genomics, it relies on code from [LoupeR](https://github.com/10xGenomics/loupeR), an R package developed by 10x Genomics. LoupeR is licensed for use only in connection with data generated from 10x Genomics products. For more information, please refer to the [10x End User Software License](https://www.10xgenomics.com/legal/end-user-software-license-agreement). By using the setup function of this tool, you will need to agree to this license with an interactive prompt. 
 
-This package widely mirrors the behavior of the R package, with some minor differences:  
 
-- Cell based annotations are automatically filtered out if they contain more than the max number of categories.
-  (This was an issue in R when converting from anndata).
-- Easier to pass specific embeddings to the function, which is especially useful when using scVI.
-  
-Note this package requires an agreement to the 10x loupe converter license, which can be agreed to and downloaded by  
-running the setup function.
-**I am not an employee of 10x, nor associated with them**. This package simply writes a file which the converter can read  
-and calls it.
+## Main Functions
 
-# This is still not done and a work in progress #
+### `create_loupe_from_anndata(anndata, output_cloupe="cloupe.cloupe", layer=None, ...)`
+
+Creates a Loupe Browser compatible `.cloupe` file from an `AnnData` object.
+
+**Parameters:**
+- `anndata`: AnnData object containing single-cell data
+- `output_cloupe`: Path to save the output file (default: "cloupe.cloupe")
+- `layer`: Layer in AnnData to use for counts (default: None, uses `.X`)
+- `dims`: List of dimension reduction keys from `adata.obsm` (default: None, uses all valid projections)
+- `obs_keys`: List of categorical annotations from `adata.obs` to include (default: None, uses all valid categories)
+- `strict_checking`: Whether to strictly validate inputs (default: False)
+- `tmp_file`: Temporary file path for intermediate data (default: 'tmp.h5')
+- `dims`: List of dimension reduction keys from `adata.obsm` to include (default: None, uses all valid projections)
+- `obs_keys`: List of categorical annotations from `adata.obs` to include (default: None, uses all valid categories)
+- `loupe_converter_path`: Path to the Loupe converter binary (default: None, uses default installation path)
+- `clean_tmp_file`: Whether to delete the temporary file after creation (default: True)
+- `force`: Whether to overwrite existing cloupe file (default: False)
+- `test_mode`: Whether to run in test mode. Will not create a cloupe file.
+
+**Example:**
+```python
+import scanpy as sc
+import loupepy
+from scipy.sparse import diags
+
+# Load data
+adata = sc.datasets.pbmc3k_processed().raw.to_adata()
+# Revert to raw counts, as loupee converter only takes raw counts
+n_counts = adata.obs["n_counts"].values
+counts_matrix = adata.X.expm1()
+counts = diags(n_counts) * counts_matrix
+adata.X = counts
+
+# Create Loupe file with default settings
+loupepy.create_loupe_from_anndata(adata, "my_results.cloupe")
+
+# Create with specific dimensions and annotations
+loupepy.create_loupe_from_anndata(
+    adata,
+    "my_custom_results.cloupe",
+    dims=["X_umap"],
+    obs_keys=["leiden"]
+)
+```
+## Utility Functions
+
+### `get_obs(anndata, obs_keys=None, strict=False)`
+
+Extracts categorical observation data from an AnnData object.
+
+**Parameters:**
+- `anndata`: AnnData object containing the data
+- `obs_keys`: List of keys to extract from `adata.obs` (default: None, uses all valid categories)
+- `strict`: Whether to strictly validate the keys. If true will throw errors on invalid keys instead of dropping
+(default: False)
+
+### `get_obsm(anndata, obsm_keys=None, strict=False)`
+
+Extracts dimensional reduction data from an AnnData object.
+**Parameters:**
+- `anndata`: AnnData object containing the data
+- `obsm_keys`: List of keys to extract from `adata.obsm` (default: None, uses all valid dimension reductions)
+- `strict`: Whether to strictly validate the keys. If true will throw errors on invalid keys instead of dropping
+(default: False)
+### `get_count_matrix(anndata, layer=None)`
+
+Gets the count matrix from an AnnData object in the format required for Loupe.
+
+**Parameters:**
+- `anndata`: AnnData object containing the data
+- `layer`: Layer in AnnData to use for counts (default: None, uses `.X`)
+
+---
+
+### `create_loupe(mat, obs, var, obsm, tmp_file, ...)`
+
+Lower-level function to create a Loupe file from raw data components.
+
+**Parameters:**
+- `mat`: CSC matrix of counts (shape: n_features × n_cells)
+- `obs`: DataFrame of categorical cell annotations
+- `var`: DataFrame of gene/feature information
+- `obsm`: Dictionary of dimension reduction embeddings
+- `tmp_file`: Path for temporary file
+- `output_path`: Path to save the output file
+- `strict_checking`: Whether to strictly validate inputs (default: False)
+- `loupe_converter_path`: Path to the Loupe converter binary (default: None, uses default installation path)'
+- `clean_tmp_file`: Whether to delete the temporary file after creation (default: True)
+- `force`: Whether to overwrite existing cloupe file (default: False)
+- `test_mode`: Whether to run in test mode. Will not create a cloupe file.
+
+**Example:**
+```python
+import scanpy as sc
+import loupepy
+from scipy.sparse import diags
+
+# Load data
+adata = sc.datasets.pbmc3k_processed().raw.to_adata()
+# Revert to raw counts, as loupee converter only takes raw counts
+n_counts = adata.obs["n_counts"].values
+counts_matrix = adata.X.expm1()
+counts = diags(n_counts) * counts_matrix
+adata.X = counts
+
+mat = loupepy.get_count_matrix(adata)
+obs = loupepy.get_obs(adata, obs_keys=["leiden"])
+var = adata.var
+obsm = loupepy.get_obsm(adata, obsm_keys=["X_umap"])
+loupepy.create_loupe(mat,obs,var,obsm,"my_results.cloupe")
+```
+
+## Setup Functions
+
+### `setup(path=None)`
+
+Downloads and installs the Loupe converter binary.
+
+**Parameters:**
+- `path`: Installation directory path (default: None, uses OS-specific default location)
+
+**Example:**
+```python
+import loupepy
+
+# Install the Loupe converter to the default location
+loupepy.setup()
+```
+
+### `eula(path=None)`
+
+**Parameters:**
+- `path`: Installation path (default: None, uses OS-specific default install location. Usually same path as setup)
+
+### `eula_reset(path=None)`
+
+Resets the EULA agreement and removes the installed Loupe converter binary.
diff --git a/pyproject.toml b/pyproject.toml
@@ -41,4 +41,10 @@ dev = [
     "ruff>=0.11.5",
     "scanpy>=1.11.1",
     "scipy-stubs>=1.15.2.1",
-]
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
diff --git a/src/loupepy/convert.py b/src/loupepy/convert.py
@@ -1,13 +1,11 @@
 import os
 from os import PathLike
 
-import numpy as np
 from anndata import AnnData # type: ignore
 import pandas as pd
 from scipy.sparse import csc_matrix
 import h5py # type: ignore
 from typing import List
-from array import array
 import logging
 from numpy import ndarray
 from .utils import _validate_anndata, _get_loupe_path, get_obs, get_obsm, get_count_matrix
diff --git a/src/loupepy/utils.py b/src/loupepy/utils.py
@@ -1,5 +1,5 @@
 from pandas import Series, DataFrame
-from typing import Union
+from typing import Union, List
 from numpy.typing import ArrayLike
 from anndata import AnnData  # type: ignore
 import numpy as np
@@ -141,7 +141,7 @@ def get_count_matrix(anndata: AnnData, layer: str | None = None) -> csc_matrix:
     else:
         return csc_matrix(anndata.X)
 
-def get_obs(anndata: AnnData, obs_keys: str|None = None, strict: bool = False) -> DataFrame:
+def get_obs(anndata: AnnData, obs_keys: List[str]|None = None, strict: bool = False) -> DataFrame:
     """
     Get the obs dataframe from an AnnData object in the format for loupe converter.
     Args:
@@ -157,7 +157,7 @@ def get_obs(anndata: AnnData, obs_keys: str|None = None, strict: bool = False) -
     _validate_obs(obs, strict)
     return obs
 
-def get_obsm(anndata: AnnData, obsm_keys: str | None = None, strict: bool = False) -> dict[str, ndarray]:
+def get_obsm(anndata: AnnData, obsm_keys: List[str] | None = None, strict: bool = False) -> dict[str, ndarray]:
     """
     Get the obsm dictionary from an AnnData object in the format for loupe converter.
     Args:
diff --git a/tests/LICENSE b/tests/LICENSE
@@ -0,0 +1,20 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.
+
diff --git a/tests/test_setup.py b/tests/test_setup.py
@@ -1,5 +1,4 @@
-import pytest
-from loupepy.setup import eula_reset, eula_reset, setup  # type: ignore
+from loupepy.setup import eula_reset, setup  # type: ignore
 import os
 
 def test_eula_and_reset(monkeypatch, tmp_path_factory):
