Skip to content

Commit 6b01e41

Browse files
iskandriskandr
committed
docs: link README API entries to source in genome.py and the class files
Wraps each method name in the Genes / Transcripts / Exons API sections with an anchor to its definition in pyensembl/genome.py on the main branch, and links every "Gene"/"Transcript"/"Exon" mention to the corresponding class file. Also surfaces the new nearest_gene, merged_gene_intervals, nearest_transcript, and biotype-aware genes/transcripts/gene_ids/transcript_ids entries that landed in recent releases. Docs-only: no source or test changes, no version bump.
1 parent 5f0d4c0 commit 6b01e41

1 file changed

Lines changed: 69 additions & 51 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -166,114 +166,132 @@ combinations of the annotation features _gene_name_, _gene_id_,
166166
_transcript_name_, _transcript_id_, _exon_id_ as well as the location of
167167
these genomic elements (contig, start position, end position, strand).
168168

169+
Method names link to their source in `pyensembl/genome.py`; class names
170+
([Gene][gene-class], [Transcript][transcript-class], [Exon][exon-class])
171+
link to the corresponding class definitions.
172+
169173
## Genes
170174

171175
<dl>
172-
<dt>genes(contig=None, strand=None)</dt>
173-
<dd>Returns a list of Gene objects, optionally restricted to a particular contig
174-
or strand.</dd>
176+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L742">genes(contig=None, strand=None, biotype=None)</a></dt>
177+
<dd>Returns a list of <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a> objects, optionally restricted to a particular contig,
178+
strand, or <code>gene_biotype</code>.</dd>
175179

176-
<dt>genes_at_locus(contig, position, end=None, strand=None)</dt>
177-
<dd>Returns a list of Gene objects overlapping a particular position on a contig,
180+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L557">genes_at_locus(contig, position, end=None, strand=None)</a></dt>
181+
<dd>Returns a list of <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a> objects overlapping a particular position on a contig,
178182
optionally extend into a range with the end parameter and restrict to
179183
forward or backward strand by passing strand='+' or strand='-'.</dd>
180184

181-
<dt>gene_by_id(gene_id)</dt>
182-
<dd>Return a Gene object for given Ensembl gene ID (e.g. "ENSG00000068793").</dd>
185+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L762">gene_by_id(gene_id)</a></dt>
186+
<dd>Return a <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a> object for given Ensembl gene ID (e.g. "ENSG00000068793").</dd>
183187

184-
<dt>gene_names(contig=None, strand=None)</dt>
188+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L854">gene_names(contig=None, strand=None)</a></dt>
185189
<dd>Returns all gene names in the annotation database, optionally restricted
186190
to a particular contig or strand.</dd>
187191

188-
<dt>genes_by_name(gene_name)</dt>
189-
<dd>Get all the unqiue genes with the given name (there might be multiple
190-
due to copies in the genome), return a list containing a Gene object for each
192+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L820">genes_by_name(gene_name)</a></dt>
193+
<dd>Get all the unique genes with the given name (there might be multiple
194+
due to copies in the genome), return a list containing a <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a> object for each
191195
distinct ID.</dd>
192196

193-
<dt>gene_by_protein_id(protein_id)</dt>
194-
<dd>Find Gene associated with the given Ensembl protein ID (e.g. "ENSP00000350283")</dd>
197+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L829">gene_by_protein_id(protein_id)</a></dt>
198+
<dd>Find <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a> associated with the given Ensembl protein ID (e.g. "ENSP00000350283")</dd>
195199

196-
<dt>gene_names_at_locus(contig, position, end=None, strand=None)
197-
</dt>
200+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L635">gene_names_at_locus(contig, position, end=None, strand=None)</a></dt>
198201
<dd>Names of genes overlapping with the given locus, optionally restricted by strand.
199202
(returns a list to account for overlapping genes)</dd>
200203

201-
<dt>gene_name_of_gene_id(gene_id)
202-
</dt>
203-
<dd>Returns name of gene with given genen ID.</dd>
204+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L863">gene_name_of_gene_id(gene_id)</a></dt>
205+
<dd>Returns name of gene with given gene ID.</dd>
204206

205-
<dt>gene_name_of_transcript_id(transcript_id)
206-
</dt><dd>Returns name of gene associated with given transcript ID.</dd>
207+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L866">gene_name_of_transcript_id(transcript_id)</a></dt>
208+
<dd>Returns name of gene associated with given transcript ID.</dd>
207209

208-
<dt>gene_name_of_transcript_name(transcript_name)
209-
</dt>
210+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L869">gene_name_of_transcript_name(transcript_name)</a></dt>
210211
<dd>Returns name of gene associated with given transcript name.</dd>
211212

212-
<dt>gene_name_of_exon_id(exon_id)
213-
</dt><dd>Returns name of gene associated with given exon ID.</dd>
213+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L872">gene_name_of_exon_id(exon_id)</a></dt>
214+
<dd>Returns name of gene associated with given exon ID.</dd>
214215

215-
<dt>gene_ids(contig=None, strand=None)
216-
</dt>
216+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L892">gene_ids(contig=None, strand=None, biotype=None)</a></dt>
217217
<dd>Return all gene IDs in the annotation database, optionally restricted by
218-
chromosome name or strand.</dd>
218+
chromosome name, strand, or <code>gene_biotype</code>.</dd>
219219

220-
<dt>gene_ids_of_gene_name(gene_name)
221-
</dt>
220+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L905">gene_ids_of_gene_name(gene_name)</a></dt>
222221
<dd>Returns all Ensembl gene IDs with the given name.</dd>
223222

223+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L573">nearest_gene(contig, position, end=None, strand=None)</a></dt>
224+
<dd>Returns <code>(distance, <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19">Gene</a>)</code> for the gene whose locus is nearest to the
225+
position (or position..end interval) on the given contig — even when no
226+
gene overlaps. Returns <code>(inf, None)</code> when no candidates exist.</dd>
227+
228+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L593">merged_gene_intervals(contig, strand=None)</a></dt>
229+
<dd>Returns the union of all gene loci on the contig as a sorted list of
230+
non-overlapping <code>(start, end)</code> tuples. Adjacent intervals
231+
(<code>end+1 == next start</code>) are merged into one.</dd>
232+
224233
</dl>
225234

226235
## Transcripts
227236

228237
<dl>
229-
<dt>transcripts(contig=None, strand=None)</dt>
230-
<dd>Returns a list of Transcript objects for all transcript entries in the
231-
Ensembl database, optionally restricted to a particular contig or strand.</dd>
238+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L938">transcripts(contig=None, strand=None, biotype=None)</a></dt>
239+
<dd>Returns a list of <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/transcript.py#L24">Transcript</a> objects for all transcript entries in the
240+
Ensembl database, optionally restricted to a particular contig, strand, or
241+
<code>transcript_biotype</code>.</dd>
232242

233-
<dt>transcript_by_id(transcript_id)</dt>
234-
<dd>Construct a Transcript object for given Ensembl transcript ID (e.g. "ENST00000369985")</dd>
243+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L951">transcript_by_id(transcript_id)</a></dt>
244+
<dd>Construct a <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/transcript.py#L24">Transcript</a> object for given Ensembl transcript ID (e.g. "ENST00000369985")</dd>
235245

236-
<dt>transcripts_by_name(transcript_name)</dt>
237-
<dd>Returns a list of Transcript objects for every transcript matching the given name.</dd>
246+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1014">transcripts_by_name(transcript_name)</a></dt>
247+
<dd>Returns a list of <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/transcript.py#L24">Transcript</a> objects for every transcript matching the given name.</dd>
238248

239-
<dt>transcript_names(contig=None, strand=None)</dt>
249+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1041">transcript_names(contig=None, strand=None)</a></dt>
240250
<dd>Returns all transcript names in the annotation database.</dd>
241251

242-
<dt>transcript_ids(contig=None, strand=None)</dt>
252+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1082">transcript_ids(contig=None, strand=None, biotype=None)</a></dt>
243253
<dd>Returns all transcript IDs in the annotation database.</dd>
244254

245-
<dt>transcript_ids_of_gene_id(gene_id)</dt>
255+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1091">transcript_ids_of_gene_id(gene_id)</a></dt>
246256
<dd>Return IDs of all transcripts associated with given gene ID.</dd>
247257

248-
<dt>transcript_ids_of_gene_name(gene_name)</dt>
258+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1094">transcript_ids_of_gene_name(gene_name)</a></dt>
249259
<dd>Return IDs of all transcripts associated with given gene name.</dd>
250260

251-
<dt>transcript_ids_of_transcript_name(transcript_name)</dt>
261+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1097">transcript_ids_of_transcript_name(transcript_name)</a></dt>
252262
<dd>Find all Ensembl transcript IDs with the given name.</dd>
253263

254-
<dt>transcript_ids_of_exon_id(exon_id)</dt>
255-
<dd>Return IDs of all transcripts associatd with given exon ID.</dd>
264+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1100">transcript_ids_of_exon_id(exon_id)</a></dt>
265+
<dd>Return IDs of all transcripts associated with given exon ID.</dd>
266+
267+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L611">nearest_transcript(contig, position, end=None, strand=None)</a></dt>
268+
<dd>Returns <code>(distance, <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/transcript.py#L24">Transcript</a>)</code> to the closest transcript on the contig.
269+
Returns <code>(inf, None)</code> when no candidates exist.</dd>
256270
</dl>
257271

258272
## Exons
259273

260274
<dl>
261-
<dt>exon_ids(contig=None, strand=None)</dt>
262-
<dd>Returns a list of exons IDs in the annotation database, optionally restricted
275+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1193">exon_ids(contig=None, strand=None)</a></dt>
276+
<dd>Returns a list of exon IDs in the annotation database, optionally restricted
263277
by the given chromosome and strand.</dd>
264278

265-
<dt>exon_by_id(exon_id)</dt>
266-
<dd>Construct an Exon object for given Ensembl exon ID (e.g. "ENSE00001209410")</dd>
279+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1135">exon_by_id(exon_id)</a></dt>
280+
<dd>Construct an <a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/exon.py#L17">Exon</a> object for given Ensembl exon ID (e.g. "ENSE00001209410")</dd>
267281

268-
<dt>exon_ids_of_gene_id(gene_id)</dt>
282+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1198">exon_ids_of_gene_id(gene_id)</a></dt>
269283
<dd>Returns a list of exon IDs associated with a given gene ID.</dd>
270284

271-
<dt>exon_ids_of_gene_name(gene_name)</dt>
285+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1201">exon_ids_of_gene_name(gene_name)</a></dt>
272286
<dd>Returns a list of exon IDs associated with a given gene name.</dd>
273287

274-
<dt>exon_ids_of_transcript_id(transcript_id)</dt>
288+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1207">exon_ids_of_transcript_id(transcript_id)</a></dt>
275289
<dd>Returns a list of exon IDs associated with a given transcript ID.</dd>
276290

277-
<dt>exon_ids_of_transcript_name(transcript_name)</dt>
291+
<dt><a href="https://github.com/openvax/pyensembl/blob/main/pyensembl/genome.py#L1204">exon_ids_of_transcript_name(transcript_name)</a></dt>
278292
<dd>Returns a list of exon IDs associated with a given transcript name.</dd>
279293
</dl>
294+
295+
[gene-class]: https://github.com/openvax/pyensembl/blob/main/pyensembl/gene.py#L19
296+
[transcript-class]: https://github.com/openvax/pyensembl/blob/main/pyensembl/transcript.py#L24
297+
[exon-class]: https://github.com/openvax/pyensembl/blob/main/pyensembl/exon.py#L17

0 commit comments

Comments
 (0)