Make identifiers optional in translation/orthology functions; fix organisms_df

Rework translation_dict, translation_df, orthology_dict, and orthology_df
to download the full table by default (identifiers=None), using the new
/mapping/table and /orthology/table endpoints. Fix organisms_df polars
schema inference with infer_schema_length=None. Improve docs landing page
and utils vignette. Update tests for new signatures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: deeenes

docs/index.md

@@ -1,55 +1,83 @@
 # omnipath-client
 
-Python client for the OmniPath web services.
+**The easiest way to access molecular biology knowledge in Python.**
 
-## Services
+omnipath-client connects you to the [OmniPath](https://omnipathdb.org)
+ecosystem -- a comprehensive collection of molecular biology databases
+covering signaling, gene regulation, protein interactions, metabolomics,
+and more.
 
-### OmniPath Database
-Query protein interactions, annotations, complexes, and more from the
-[OmniPath database](https://omnipathdb.org).
+## Why OmniPath?
 
-### OmniPath Utils
-ID translation, taxonomy, orthology, and reference lists via the
-[utils service](https://utils.omnipathdb.org).
+OmniPath integrates data from **200+ databases** into a unified resource:
+protein-protein interactions, enzyme-substrate relationships, transcription
+factor targets, protein complexes, functional annotations, intercellular
+communication, and metabolite networks. Instead of querying dozens of
+databases individually, query OmniPath once.
 
-## Quick Start
+## Why this client?
 
-```bash
-pip install omnipath-client
-```
+- **No setup needed** -- queries the web service, no local database required
+- **97 identifier types** -- translate between UniProt, gene symbols, Ensembl,
+  ChEBI, HMDB, and 90+ other ID systems
+- **28,000 organisms** -- taxonomy resolution across NCBI, Ensembl, KEGG, OMA
+- **Orthology** -- cross-species gene translation with 6 backends
+- **DataFrames** -- returns polars, pandas, or pyarrow DataFrames
+- **BSD-3-Clause** -- free to use in any project
+
+## Quick examples
+
+### Translate gene symbols to UniProt
 
-### ID Translation
 ```python
-from omnipath_client.utils import map_name, translate_column
+from omnipath_client.utils import map_name, translation_df
 
 map_name('TP53', 'genesymbol', 'uniprot')
 # {'P04637'}
 
-# Translate DataFrame column (pandas, polars, or pyarrow)
-translate_column(df, 'gene', 'genesymbol', 'uniprot')
+# Full translation table as DataFrame
+df = translation_df('genesymbol', 'uniprot')
 ```
 
-### Taxonomy
-```python
-from omnipath_client.utils import ensure_ncbi_tax_id
-ensure_ncbi_tax_id('human')  # 9606
-```
+### Cross-species translation
 
-### Orthology
 ```python
 from omnipath_client.utils import orthology_translate
-orthology_translate(['TP53'], source=9606, target=10090)
-# {'TP53': {'Trp53'}}
+
+orthology_translate(['TP53', 'EGFR'], source=9606, target=10090)
+# {'TP53': {'Trp53'}, 'EGFR': {'Egfr'}}
 ```
 
-### OmniPath Database
+### Query protein interactions
+
 ```python
 import omnipath_client as op
+
 df = op.interactions(entity_ids=['Q9Y6K9'])
 ```
 
-## Getting started
+### Explore the API
+
+```python
+import omnipath_client as op
+
+op.endpoints()                                      # all endpoints
+op.params('exports/interactions')                    # available filters
+op.values('exports/interactions', 'entity_types')    # allowed values
+```
+
+## Learn more
+
+- **[OmniPath Utils vignette](vignettes/utils.md)** -- ID translation,
+  taxonomy, orthology, reference lists
+- **[OmniPath Database vignette](vignettes/database.md)** -- interactions,
+  annotations, complexes
+- **[API Reference](reference/index.md)** -- full function documentation
+- **[Installation](installation.md)** -- setup instructions
+
+## Services
 
-- [Installation](installation.md) -- how to install the package
-- [Quickstart](quickstart.md) -- basic usage examples
-- [API Reference](reference/index.md) -- full API documentation
+| Service | URL | What it provides |
+|---------|-----|-----------------|
+| OmniPath Database | [dev.omnipathdb.org](https://dev.omnipathdb.org) | Interactions, annotations, complexes, ontology |
+| OmniPath Utils | [utils.omnipathdb.org](https://utils.omnipathdb.org) | ID translation, taxonomy, orthology, reference lists |

docs/vignettes/utils.md

@@ -18,10 +18,15 @@ from omnipath_client.utils import (
     map_names,
     translate,
     translate_column,
+    translation_dict,
+    translation_df,
     id_types,
     ensure_ncbi_tax_id,
     all_organisms,
+    organisms_df,
     orthology_translate,
+    orthology_dict,
+    orthology_df,
     get_reflist,
     is_swissprot,
 )
@@ -57,6 +62,24 @@ translate(['TP53', 'EGFR', 'BRCA1'], 'genesymbol', 'uniprot')
 # {'TP53': {'P04637'}, 'EGFR': {'P00533'}, 'BRCA1': {'P38398'}}
 ```
 
+### Full translation tables
+
+Download a complete ID mapping table as a dict or DataFrame:
+
+```python
+from omnipath_client.utils import translation_dict, translation_df
+
+# Full genesymbol -> uniprot table as dict
+table = translation_dict('genesymbol', 'uniprot')
+table['TP53']  # {'P04637'}
+
+# Or as a DataFrame
+df = translation_df('genesymbol', 'uniprot')
+
+# Translate only specific IDs
+table = translation_dict('genesymbol', 'uniprot', identifiers=['TP53', 'EGFR'])
+```
+
 ### Translate a DataFrame column
 
 Works with pandas, polars, and pyarrow DataFrames:
@@ -133,6 +156,15 @@ organisms = all_organisms()
 # [{'ncbi_tax_id': 9606, 'common_name': 'human', ...}, ...]
 ```
 
+### Organisms as DataFrame
+
+```python
+from omnipath_client.utils import organisms_df
+
+df = organisms_df()              # all organisms
+df = organisms_df(has_data=True) # only organisms with mapping data
+```
+
 ## Orthology
 
 ### Cross-species gene translation
@@ -149,6 +181,25 @@ orthology_translate(['TP53'], source=9606, target=10090, min_sources=5)
 orthology_translate(['TP53'], source=9606, target=10090, resource='oma')
 ```
 
+### Full orthology tables
+
+Download a complete orthology table:
+
+```python
+from omnipath_client.utils import orthology_dict, orthology_df
+
+# Full human-to-mouse orthology as dict
+table = orthology_dict(source=9606, target=10090)
+
+# Or as a DataFrame
+df = orthology_df(source=9606, target=10090)
+
+# Translate only specific IDs
+table = orthology_dict(
+    source=9606, target=10090, identifiers=['TP53', 'EGFR'],
+)
+```
+
 ### Translate DataFrame column to orthologs
 
 ```python

omnipath_client/utils/_mapping.py

@@ -284,20 +284,23 @@ def all_mappings(
 
 
 def translation_dict(
-    identifiers: str | list[str],
     id_type: str,
     target_id_type: str,
     ncbi_tax_id: int = 9606,
+    identifiers: str | list[str] | None = None,
     raw: bool = False,
     backend: str | None = None,
 ) -> dict[str, set[str]]:
     """Get translation data as a dict.
 
+    Downloads the full translation table by default. If identifiers are
+    given, translates only those.
+
     Args:
-        identifiers: Source IDs to translate. String or list.
         id_type: Source ID type.
         target_id_type: Target ID type.
         ncbi_tax_id: Organism (default: 9606).
+        identifiers: Optional list of source IDs. None = full table.
         raw: Skip special-case handling.
         backend: Force specific backend.
 
@@ -306,52 +309,71 @@ def translation_dict(
 
     Example::
 
-        table = translation_dict(['TP53', 'EGFR'], 'genesymbol', 'uniprot')
+        # Full table
+        table = translation_dict('genesymbol', 'uniprot')
         table['TP53']  # {'P04637'}
+
+        # Specific IDs only
+        table = translation_dict(
+            'genesymbol', 'uniprot', identifiers=['TP53', 'EGFR'],
+        )
     """
 
-    if isinstance(identifiers, str):
-        identifiers = [identifiers]
+    if identifiers is not None:
+        if isinstance(identifiers, str):
+            identifiers = [identifiers]
+
+        return translate(
+            identifiers,
+            id_type,
+            target_id_type,
+            ncbi_tax_id,
+            raw=raw,
+            backend=backend,
+        )
 
-    return translate(
-        identifiers,
-        id_type,
-        target_id_type,
-        ncbi_tax_id,
-        raw=raw,
-        backend=backend,
-    )
+    # Full table download
+    data = _get('/mapping/table', {
+        'id_type': id_type,
+        'target_id_type': target_id_type,
+        'ncbi_tax_id': ncbi_tax_id,
+    })
+    table = data.get('table', {})
+
+    return {k: set(v) for k, v in table.items()}
 
 
 def translation_df(
-    identifiers: str | list[str],
     id_type: str,
     target_id_type: str,
     ncbi_tax_id: int = 9606,
+    identifiers: str | list[str] | None = None,
     raw: bool = False,
     backend: str | None = None,
 ) -> Any:
     """Get translation data as a DataFrame.
 
-    Returns a two-column DataFrame with source and target IDs.
-    Prefers polars; falls back to pandas.
+    Downloads the full table by default. Returns a two-column DataFrame.
+
+    Args:
+        id_type: Source ID type.
+        target_id_type: Target ID type.
+        ncbi_tax_id: Organism (default: 9606).
+        identifiers: Optional list of source IDs. None = full table.
+        raw: Skip special-case handling.
+        backend: Force specific backend.
 
     Example::
 
-        df = translation_df(['TP53', 'EGFR'], 'genesymbol', 'uniprot')
-        #   genesymbol   uniprot
-        # 0       TP53   P04637
-        # 1       EGFR   P00533
+        df = translation_df('genesymbol', 'uniprot')
+        # Full genesymbol -> uniprot table as DataFrame
     """
 
-    if isinstance(identifiers, str):
-        identifiers = [identifiers]
-
-    trans = translate(
-        identifiers,
+    trans = translation_dict(
         id_type,
         target_id_type,
         ncbi_tax_id,
+        identifiers=identifiers,
         raw=raw,
         backend=backend,
     )