Add Species.division and prettier 'pyensembl available' output (#342)

Species now carries a division field ("vertebrates" by default, plus
"plants", "fungi", "metazoa", "protists", "bacteria") and exposes
matching predicates (is_plant, is_fungus, is_animal, is_vertebrate,
is_invertebrate, is_protist, is_bacterium). The legacy is_plant
keyword on Species.register is preserved and translates to
division="plants" so external callers keep working.

Existing species are tagged taxonomically: arabidopsis/rice → plants,
yeast → fungi, drosophila/C. elegans → metazoa. URL routing still goes
through is_plant, so no behavior change for installs in this release.

pyensembl available now renders as a single aligned table with division
section headers (Vertebrates / Invertebrates / Plants / Fungi), an
en-dashed release range, single-release entries shown as the bare
number, and a dimmed latin-name column. ANSI styling is auto-enabled
when stdout is a TTY and suppressed when piped.

Unblocks #298 (adding more plants / fungi / metazoa species) by
giving registrations a real taxonomic field to plug into.

Bump version to 2.8.0.

Author: iskandr

pyensembl/shell.py

@@ -252,22 +252,115 @@ def collect_selected_genomes(args):
         return all_combinations_of_ensembl_genomes(args)
 
 
-def format_available_species():
+_DIVISION_LABELS = (
+    ("vertebrates", "Vertebrates"),
+    ("metazoa", "Invertebrates"),
+    ("plants", "Plants"),
+    ("fungi", "Fungi"),
+    ("protists", "Protists"),
+    ("bacteria", "Bacteria"),
+)
+
+
+def _format_release_range(start, end):
+    # Inclusive range; collapse a single-value range to just that integer.
+    if start == end:
+        return str(start)
+    return "%d–%d" % (start, end)  # en-dash
+
+
+def _species_display_name(species):
+    if species.synonyms:
+        return species.synonyms[0]
+    return species.latin_name
+
+
+def format_available_species(use_color=None):
     """
-    Build the multi-line string printed by the "available" action: every
-    registered species followed by its supported Ensembl release ranges,
-    grouped by reference assembly.
+    Render the table printed by the "available" CLI action: every registered
+    species and its supported Ensembl release ranges, grouped by division.
+
+    When ``use_color`` is ``None`` (the default), ANSI styling is applied if
+    stdout is a TTY and suppressed otherwise.
     """
-    lines = []
+    import sys
+
+    if use_color is None:
+        use_color = sys.stdout.isatty()
+    BOLD = "\x1b[1m" if use_color else ""
+    DIM = "\x1b[2m" if use_color else ""
+    RESET = "\x1b[0m" if use_color else ""
+
+    species_by_division = {key: [] for key, _ in _DIVISION_LABELS}
     for latin_name in sorted(Species._latin_names_to_species):
         species = Species._latin_names_to_species[latin_name]
-        if species.synonyms:
-            synonyms = ",".join(species.synonyms)
-            lines.append("* %s (%s):" % (latin_name, synonyms))
-        else:
-            lines.append("* %s:" % latin_name)
-        for assembly, (start, end) in species.reference_assemblies.items():
-            lines.append("  * %s: (%d, %d)" % (assembly, start, end))
+        species_by_division.setdefault(species.division, []).append(species)
+
+    all_species = [s for group in species_by_division.values() for s in group]
+    if not all_species:
+        return ""
+
+    def _w(values, fallback):
+        return max((len(v) for v in values), default=fallback)
+
+    name_w = _w([_species_display_name(s) for s in all_species], 8)
+    asm_w = _w(
+        [asm for s in all_species for asm in s.reference_assemblies], 8
+    )
+    rng_w = _w(
+        [
+            _format_release_range(start, end)
+            for s in all_species
+            for (start, end) in s.reference_assemblies.values()
+        ],
+        8,
+    )
+    latin_w = _w([s.latin_name for s in all_species], 8)
+
+    col_name = max(name_w, len("Species")) + 2
+    col_asm = max(asm_w, len("Assembly")) + 2
+    col_rng = max(rng_w, len("Releases")) + 2
+    col_latin = max(latin_w, len("Latin name"))
+    total_w = col_name + col_asm + col_rng + col_latin
+
+    lines = []
+    header_row = "%-*s%-*s%-*s%s" % (
+        col_name, "Species",
+        col_asm, "Assembly",
+        col_rng, "Releases",
+        "Latin name",
+    )
+    lines.append("%s%s%s" % (BOLD, header_row, RESET))
+    lines.append("─" * total_w)
+
+    for division_key, division_label in _DIVISION_LABELS:
+        members = species_by_division.get(division_key, [])
+        if not members:
+            continue
+        members.sort(key=_species_display_name)
+        lines.append("")
+        section = "── %s " % division_label
+        section += "─" * max(2, total_w - len(section))
+        lines.append("%s%s%s" % (BOLD, section, RESET))
+        for species in members:
+            for i, (asm, (start, end)) in enumerate(
+                species.reference_assemblies.items()
+            ):
+                if i == 0:
+                    name_cell = _species_display_name(species)
+                    latin_cell = "%s%s%s" % (DIM, species.latin_name, RESET)
+                else:
+                    name_cell = ""
+                    latin_cell = ""
+                lines.append(
+                    "%-*s%-*s%-*s%s"
+                    % (
+                        col_name, name_cell,
+                        col_asm, asm,
+                        col_rng, _format_release_range(start, end),
+                        latin_cell,
+                    )
+                )
     return "\n".join(lines)
 
 

pyensembl/species.py

@@ -30,16 +30,28 @@ class Species(Serializable):
     _reference_names_to_species = {}
 
     @classmethod
-    def register(cls, latin_name, synonyms, reference_assemblies, is_plant=False):
+    def register(
+        cls,
+        latin_name,
+        synonyms,
+        reference_assemblies,
+        division="vertebrates",
+        is_plant=False,
+    ):
         """
         Create a Species object from the given arguments and enter into
         all the dicts used to look the species up by its fields.
+
+        ``is_plant`` is retained for backward compatibility; new callers
+        should pass ``division`` instead.
         """
+        if is_plant:
+            division = "plants"
         species = Species(
             latin_name=latin_name,
             synonyms=synonyms,
             reference_assemblies=reference_assemblies,
-            is_plant=is_plant,
+            division=division,
         )
         cls._latin_names_to_species[species.latin_name] = species
         for synonym in synonyms:
@@ -81,7 +93,17 @@ def all_species_release_pairs(cls):
                 for release in range(release_range[0], release_range[1] + 1):
                     yield species_name, release
 
-    def __init__(self, latin_name, synonyms=[], reference_assemblies={}, is_plant=False):
+    VALID_DIVISIONS = frozenset(
+        {"vertebrates", "plants", "fungi", "metazoa", "protists", "bacteria"}
+    )
+
+    def __init__(
+        self,
+        latin_name,
+        synonyms=[],
+        reference_assemblies={},
+        division="vertebrates",
+    ):
         """
         Parameters
         ----------
@@ -92,12 +114,22 @@ def __init__(self, latin_name, synonyms=[], reference_assemblies={}, is_plant=Fa
         reference_assemblies : dict
             Mapping of names of reference genomes onto inclusive ranges of
             Ensembl releases Example: {"GRCh37": (54, 75)}
+
+        division : str
+            Ensembl division this species belongs to. One of
+            ``"vertebrates"``, ``"plants"``, ``"fungi"``, ``"metazoa"``,
+            ``"protists"``, ``"bacteria"``. Defaults to ``"vertebrates"``.
         """
+        if division not in self.VALID_DIVISIONS:
+            raise ValueError(
+                "Invalid division %r for %s; must be one of %s"
+                % (division, latin_name, sorted(self.VALID_DIVISIONS))
+            )
         self.latin_name = latin_name.lower().replace(" ", "_")
         self.synonyms = synonyms
         self.reference_assemblies = reference_assemblies
+        self.division = division
         self._release_to_genome = {}
-        self.is_plant = is_plant
         for genome_name, (start, end) in self.reference_assemblies.items():
             for i in range(start, end + 1):
                 if i in self._release_to_genome:
@@ -107,6 +139,34 @@ def __init__(self, latin_name, synonyms=[], reference_assemblies={}, is_plant=Fa
                     )
                 self._release_to_genome[i] = genome_name
 
+    @property
+    def is_plant(self):
+        return self.division == "plants"
+
+    @property
+    def is_fungus(self):
+        return self.division == "fungi"
+
+    @property
+    def is_vertebrate(self):
+        return self.division == "vertebrates"
+
+    @property
+    def is_invertebrate(self):
+        return self.division == "metazoa"
+
+    @property
+    def is_animal(self):
+        return self.division in ("vertebrates", "metazoa")
+
+    @property
+    def is_protist(self):
+        return self.division == "protists"
+
+    @property
+    def is_bacterium(self):
+        return self.division == "bacteria"
+
     def which_reference(self, ensembl_release):
         if ensembl_release not in self._release_to_genome:
             raise ValueError(
@@ -330,6 +390,7 @@ def check_species_object(species_name_or_object):
         "BDGP6.28": (99, 102),
         "BDGP6.32": (103, MAX_ENSEMBL_RELEASE),
     },
+    division="metazoa",
 )
 
 nematode = Species.register(
@@ -344,6 +405,7 @@ def check_species_object(species_name_or_object):
         "WBcel215": (67, 70),
         "WBcel235": (71, MAX_ENSEMBL_RELEASE),
     },
+    division="metazoa",
 )
 
 yeast = Species.register(
@@ -352,6 +414,7 @@ def check_species_object(species_name_or_object):
     reference_assemblies={
         "R64-1-1": (76, MAX_ENSEMBL_RELEASE),
     },
+    division="fungi",
 )
 
 arabidopsis_thaliana = Species.register(
@@ -360,7 +423,7 @@ def check_species_object(species_name_or_object):
     reference_assemblies={
         "TAIR10": (40, MAX_PLANTS_ENSEMBL_RELEASE),
     },
-    is_plant=True
+    division="plants",
 )
 
 rice = Species.register(
@@ -369,7 +432,7 @@ def check_species_object(species_name_or_object):
     reference_assemblies={
         "IRGSP-1.0": (40, MAX_PLANTS_ENSEMBL_RELEASE),
     },
-    is_plant=True
+    division="plants",
 )
 
 #BALB/c

pyensembl/version.py

@@ -1,4 +1,4 @@
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 
 def print_version():
     print(f"v{__version__}")

tests/test_shell.py

@@ -21,7 +21,7 @@ def test_available_action_parses():
 
 
 def test_format_available_species_includes_human_and_assemblies():
-    output = format_available_species()
+    output = format_available_species(use_color=False)
     # human is registered with common name "human" and three reference assemblies
     assert "homo_sapiens" in output
     assert "human" in output
@@ -30,3 +30,39 @@ def test_format_available_species_includes_human_and_assemblies():
     # mouse should also appear
     assert "mus_musculus" in output
     assert "GRCm38" in output
+
+
+def test_format_available_species_grouped_by_division():
+    output = format_available_species(use_color=False)
+    # Every populated division should have a section header.
+    assert "── Vertebrates " in output
+    assert "── Invertebrates " in output
+    assert "── Plants " in output
+    assert "── Fungi " in output
+    # Section ordering: Vertebrates before Invertebrates before Plants before Fungi.
+    v = output.index("── Vertebrates ")
+    i = output.index("── Invertebrates ")
+    p = output.index("── Plants ")
+    f = output.index("── Fungi ")
+    assert v < i < p < f
+    # Yeast is now classified as fungi; drosophila/c. elegans as metazoa.
+    assert output.index("yeast") > f
+    drosophila_pos = output.index("drosophila")
+    assert i < drosophila_pos < p
+
+
+def test_format_available_species_no_color_has_no_escape_codes():
+    output = format_available_species(use_color=False)
+    assert "\x1b[" not in output
+
+
+def test_format_available_species_collapses_single_release():
+    # NCBI36 only exists in Ensembl release 54; verify it renders as "54"
+    # rather than "54–54".
+    output = format_available_species(use_color=False)
+    assert "NCBI36" in output
+    ncbi36_line = next(
+        line for line in output.splitlines() if "NCBI36" in line
+    )
+    assert "54–54" not in ncbi36_line
+    assert "54" in ncbi36_line