/bulkrna-geneid-mapping

name: bulkrna-geneid-mapping
description: Load when converting Ensembl, Entrez or symbol IDs in a bulk RNA count matrix using an explicit mapping or a small human demo reference. Skip when IDs already match downstream needs; use fetch_mapping explicitly for MyGene lookup.
trigger: gene ID, Ensembl, Entrez, gene symbol, ID mapping, gene annotation, convert IDs
tags:
- bulkrna
- gene-id
- mapping
- Ensembl
- Entrez
- HGNC
- annotation

bulkrna-geneid-mapping

When to use

Convert Ensembl, Entrez and symbol identifiers in count-matrix row indexes. Use a caller-provided mapping for full coverage or non-human organisms. Skip when identifiers already match downstream needs.

Use from a step

import pandas as pd
from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill('bulkrna-geneid-mapping')
data = read_input('counts.csv', reader=lambda path: pd.read_csv(path, index_col=0))
result = library.map_ids(data)
write_output(result, 'tables/result.csv')

[examples/example_step.py](examples/example_step.py) runs offline and supports fresh-kernel replay. Pure computations return objects; CLI and steps own writes.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`map_ids(data, *, from_type='ensembl', to_type='symbol', species='human', on_duplicate='sum', mapping=None)`

Map count-matrix row identifiers without network or file access.

:param data: Gene-by-sample counts; the row index contains source IDs. :param from_type: CLI default ensembl; entrez and symbol are also supported. :param to_type: CLI default symbol; target namespace. :param species: CLI default human; mouse requires an explicit reference. :param on_duplicate: CLI default sum; first or drop resolve target collisions differently. :param mapping: Optional source/target DataFrame; None uses ten human demo genes only. :returns: A new mapped DataFrame with reference scope, mapping records and summary diagnostics. :raises ValueError: Namespaces, duplicate policy or reference data are invalid.

`fetch_mapping(data, *, from_type='ensembl', to_type='symbol', species='human')`

Query MyGene explicitly and return a local source/target mapping table.

:param data: Iterable of identifiers to send to the public MyGene service. :param from_type: Default ensembl; source namespace. :param to_type: Default symbol; requested target namespace. :param species: Default human; MyGene species selector. :returns: A DataFrame containing only identifiers for which MyGene returned a match. :raises ImportError: Install mygene with install_skill_deps if unavailable. :raises Exception: Network or service errors propagate; no demo substitute is returned.

`mapping_table(data)`

Return the original-to-target mapping decisions for every input row.

:param data: Mapped count matrix returned by map_ids. :returns: A new DataFrame with original_id, stripped_id, mapped_id and was_mapped. :raises KeyError: The count matrix has no mapping diagnostics.

`run_info(data, *, keep=True)`

Read mapping diagnostics without modifying the count values.

:param data: Mapped counts returned by map_ids. :param keep: Default True; the CLI removes diagnostics with False. :returns: An independent diagnostic dictionary. :raises TypeError: data is not a DataFrame.

`mapping_figure(data)`

Plot mapped and unmapped source-row counts.

:param data: Count matrix returned by map_ids. :returns: A matplotlib Figure; no files are written. :raises KeyError: Mapping diagnostics are absent.

<!-- api:end -->

Methods and parameters

Local map_ids never queries the network. Its default reference contains ten human genes; it also supports reverse namespace mapping within that small reference. Pass a source/target DataFrame to override it. fetch_mapping explicitly sends identifiers to MyGene. The CLI queries MyGene only with --fetch-mygene.

Gotchas

• `map_ids` strips Ensembl version suffixes, retains unmapped identifiers and resolves target collisions with sum, first or drop. Explicit mappings take priority. Non-human mapping without a reference raises an error. `run_info` identifies demo versus provided reference scope.

Inputs and outputs

`tables/mapped_counts.csv`, `tables/mapping_table.csv`, `report.md`, `result.json` and `reproducibility/commands.sh`. `tables/unmapped_genes.csv` is conditional on unmapped input rows. The CLI does not write figures.

CLI

python skills/bulkrna/bulkrna-geneid-mapping/bulkrna_geneid_mapping.py --demo --output /tmp/bulkrna_geneid_mapping

See also

• [Parameters](references/parameters.md)
• [Methodology](references/methodology.md)
• [Output contract](references/output_contract.md)

Dependencies

`numpy`, `pandas`, `mygene`, `matplotlib`