spacr.gene_tile¶

Resolve regression features to gene identities and screen statistics.

The gene_tile() function combines a regression feature with optional coefficient, gRNA-reference, annotation, and localisation data. It returns a GeneTile that can be rendered by the GUI or used independently.

Guide identifiers are resolved with spacr.hits.gene_of(). When the same protospacer occurs under more than one gene in the supplied gRNA reference, all candidate genes are retained and the mapping is marked as ambiguous. Missing references or annotations are described in the returned record rather than represented by an empty panel.

Bundled reference tables are read locally and cached. External database URLs are constructed for the user to open; this module does not fetch them.

Classes¶

`GeneCandidate`	One gene the clicked feature could be naming.
`GeneTile`	Everything spaCR can say about one clicked point, in reading order.
`GuideRow`	One guide of this gene, and how it behaved in this screen.
`Reference`	An external record for this gene: a label and a URL to open.

Functions¶

`gene_tile`(→ GeneTile)	Build a gene record for a regression feature.
`is_toxoplasma_gene_id`(→ bool)	Is `gene` shaped like a Toxoplasma gene id spaCR would recognise?
`toxodb_url`(→ str)	The ToxoDB gene record page for a full accession. Never fetched.
`uniprot_accessions`(→ Dict[str, str])	`{gene number: accession}` from the bundled table.
`uniprot_reference`(accession[, annotation])	A UniProt link for this gene: the record when known, else a search.

Module Contents¶

class spacr.gene_tile.GeneCandidate[source]¶

One gene the clicked feature could be naming.

Usually there is exactly one. There is more than one when the guide’s protospacer sits in more than one gene, and then every one of them is here with whatever is known about it, because picking one would be inventing a result.

Parameters:

gene – the bare gene id, as every spaCR table keys it (411710).
accession – the library’s own accession (TGGT1_411710), when the gRNA reference names a strain; "" when nothing said which strain.
annotation_id – the Gene ID of the annotation row that matched (TGME49_239740), or "" when none did.
product – the product description, or "".
symbol – the gene symbol, or "".
localisation – TAGM/LOPIT subcellular localisation, or "".
aliases – every other name this gene is known by here.
fields – the annotation columns worth showing, as ((label, value), ...) in reading order, gaps already dropped.
annotation – the whole matched annotation row, for a caller that wants a column this module does not show.
reported – True for the gene the regression itself attributed the reads to — the one a naive resolver would have picked alone.
notes – what could not be resolved ABOUT THIS GENE, in sentences.

property name: str[source]¶

the symbol, else the accession.

Type:: The most human name available

property references: Tuple[Reference, ...][source]¶: External records for this gene. Built, never fetched.

class spacr.gene_tile.GeneTile[source]¶

Everything spaCR can say about one clicked point, in reading order.

Identity, then this screen’s numbers, then what spaCR already knew, then a link out — because a user who clicked a point wants to know what they clicked before they want a bibliography.

Parameters:

feature – the string that was clicked, verbatim.
kind – what the feature turned out to be — guide, gene, control, nuisance or unresolved.
guide – the guide id, for a guide term; "" otherwise.
gene – the gene id the regression attributed the reads to.
candidates – every gene the feature could name, the reported one first. Length > 1 means ambiguous.
ambiguous – True when the guide’s protospacer sits in more than one gene, so the effect cannot be assigned to any one of them.
ambiguity – the sentence explaining that, or "".
protospacer – the guide’s sequence, when the reference had it.
effect – the clicked term’s coefficient.
p_value – its p-value.
q_value – Its q-value, or the uncorrected p-value stored in the q_value column when correction is "none".
correction – The multiple-testing method recorded by the run. When this is "none", the tile labels the stored q_value explicitly as an uncorrected p-value.
condition – control / pc / nc / other, as fitted.
n_obs – the observation count the results row carried.
n_obs_column – which column that count came from, n_grna or n_gene. Named rather than relabelled: the two count different things and only the run knows which one a row carries.
gene_effect – the gene-level coefficient for this gene.
gene_p_value – its p-value.
gene_q_value – its q-value.
guides – every guide of this gene that was fitted, and how it moved.
n_agree – how many of them agree in sign with the gene effect.
unresolved – what could not be worked out, in sentences. NEVER empty when something is missing — this is the field that stops the tile reading as a bug.
notes – everything else worth saying that is not a failure.

sections(translator: Callable[..., str] | None = None) → Tuple[Tuple[str, Tuple[Tuple[str, str], ...]], ...][source]¶

The tile as ((heading, ((label, value), ...)), ...).

The one ordering, defined once, so the Qt tile, the text form and the HTML form cannot drift into presenting the same record three ways. translator localizes presentation labels and structured messages; identifiers, measurements, annotations, and URLs remain unchanged.

to_html(translator: Callable[..., str] | None = None) → str[source]¶: The tile as HTML, for a Qt rich-text view.

to_text(translator: Callable[..., str] | None = None) → str[source]¶: The tile as plain text — what a test reads and a log records.

property n_guides: int[source]¶: How many of this gene’s guides the results table fitted.

property references: Tuple[Reference, ...][source]¶: Every external record, across every candidate gene.

property resolved: bool[source]¶: Did this land on at least one gene?

property subtitle: str[source]¶

what the thing IS, in words.

Type:: The line under the title

property title: str[source]¶

a name a human recognises where one exists.

For an ambiguous guide the title names all of the genes, joined by /. That is deliberately awkward to read: the mapping IS awkward, and a title that showed one of three would be a lie that fits.

Type:: The tile’s first line

class spacr.gene_tile.GuideRow[source]¶

One guide of this gene, and how it behaved in this screen.

Parameters:

guide – the guide id as the results table carries it (239740_3).
feature – the model term it came from.
effect – the fitted coefficient.
p_value – its p-value.
q_value – its q-value, as the run reported one.
n_obs – the n_grna count behind it.
agrees – whether it pushes the same way as the gene-level effect; None when there is no gene-level effect to compare against, which is different from disagreeing and is shown differently.
clicked – True for the guide the user actually clicked.

property direction: str[source]¶: up, down, flat or "" when there is no effect.

class spacr.gene_tile.Reference[source]¶

An external record for this gene: a label and a URL to open.

Parameters:

label – what to show, e.g. ToxoDB TGGT1_239740.
url – where it goes. Built by string formatting and NEVER fetched — see the module docstring.

spacr.gene_tile.gene_tile(feature: Any, results: pandas.DataFrame | None = None, *, barcodes: Any = BUNDLED, metadata: Any = BUNDLED, localisation: Any = BUNDLED) → GeneTile[source]¶

Build a gene record for a regression feature.

Parameters:

feature (Any) – Model term such as fraction:grna[239740_3] or gene_fraction:gene[239740]. Bare gRNA accessions and gene identifiers are also accepted.
results (pandas.DataFrame or None, optional) – Regression coefficient table. When None, identity and annotation are still resolved and the missing screen statistics are recorded in GeneTile.unresolved.
barcodes ({BUNDLED, None}, path-like, or pandas.DataFrame, optional) – gRNA reference with name and sequence columns. Use BUNDLED for the packaged reference or None to skip protospacer lookup. Ambiguous mappings can be detected only when this reference contains the guide.
metadata ({BUNDLED, None}, path-like, or pandas.DataFrame, optional) – Gene annotation keyed by Gene ID. Use None to omit annotation.
localisation ({BUNDLED, None}, path-like, or pandas.DataFrame, optional) – TAGM/LOPIT localisation table keyed by gene_nr. Use None to omit localisation data.

Returns:

GeneTile – Resolved identity, screen statistics, annotations, references, and explicit notes about missing or ambiguous data. Unrecognised features return an unresolved record rather than None.

Notes

The function reads only local data. Values in GeneTile.references are URLs for the caller to open and are not fetched while building the record.

spacr.gene_tile.is_toxoplasma_gene_id(gene: Any) → bool[source]¶

Is gene shaped like a Toxoplasma gene id spaCR would recognise?

Parameters:: gene – a bare gene id (239740), an accession (TGGT1_239740), or anything at all.
Returns:: True for a Toxoplasma-shaped id. The point of the check is the negative: an id from a screen of some other organism must not be handed a ToxoDB link, because a link to a record that does not exist is worse than no link.

spacr.gene_tile.toxodb_url(accession: str) → str[source]¶

The ToxoDB gene record page for a full accession. Never fetched.

Parameters:: accession – full ToxoDB gene accession to place in the URL.

spacr.gene_tile.uniprot_accessions() → Dict[str, str][source]¶

{gene number: accession} from the bundled table.

Cached: it is read to build one line of a gene tile, which happens every time a point is clicked.

Returns an empty mapping rather than raising when the file is absent – a screen of another organism has no reason to carry it, and a gene tile without a UniProt line is still a gene tile.

spacr.gene_tile.uniprot_reference(accession: str, annotation=None)[source]¶

A UniProt link for this gene: the record when known, else a search.

Parameters:

accession – the gene accession, e.g. TGGT1_239740.
annotation – the gene’s annotation row, if there is one.

Returns:

(label, url, is_record), or None when there is nothing useful to offer.

THE DISTINCTION MATTERS AND IS CARRIED IN THE LABEL. A record link says “this is the protein”; a search link says “here is the question”. Only one of those is a claim, and only one of them can be wrong in a way the reader cannot see – a fabricated record URL that happens to resolve opens a real page for a different protein and looks exactly like a correct link.