Skip to content

Commit

Permalink
MRG: #240 from vocalpy/fix-cross-refs-in-docstrings
Browse files Browse the repository at this point in the history 
DOC/CLN: Fix cross-refs in docstrings, style. Fixes #239
  • Loading branch information
@NickleDave
NickleDave authored Mar 21, 2023
2 parents 4af3a3c + da6f385 commit c228809
Show file tree
Hide file tree
Showing 19 changed files with 435 additions and 300 deletions.
17 changes: 9 additions & 8 deletions src/crowsetta/annotation.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,27 +18,28 @@ class Annotation:
Attributes
----------
annot_path : str, pathlib.Path
path to file from which annotations were loaded
Path to file from which annotations were loaded.
notated_path : str, pathlib.Path
path to file that ``annot_path`` annotates.
Path to file that ``annot_path`` annotates.
E.g., an audio file, or an array file
that contains a spectrogram generated from audio.
Optional, default is None.
seq : crowsetta.Sequence
a sequence of annotated segments,
A sequence of annotated segments,
each having an onset time, offset time,
and label.
and label. A :class:`crowsetta.Sequence` instance.
bboxes : list
of ``crowsetta.BBox``,
annotated bounding boxes,
List of annotated bounding boxes,
each having an onset time, offset time,
lowest frequency, highest frequency,
and label.
Each item in the list will be a
:class:`crowsetta.BBox` instance.
Notes
-----
A ``crowsetta.Annotation`` can have a ``seq``
or ``bboxes``, but not both.
A :class:`crowsetta.Annotation` can have either a ``seq``
attribute or a ``bboxes`` attribute, but not both.
Examples
--------
Expand Down
18 changes: 13 additions & 5 deletions src/crowsetta/formats/__init__.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,13 @@
FORMATS[attr.name] = attr


__all__ = [
'bbox',
'FORMATS',
'seq'
]


def by_name(name: str) -> Type:
"""Get an annotation class by its string name
Expand Down Expand Up @@ -63,26 +70,27 @@ def as_list() -> list[str]:
def register_format(format_class: Type) -> Type:
"""Decorator to register annotation formats.
Adds class to ``crowsetta.formats``.
Adds class to :mod:`crowsetta.formats`.
The decorator maps the class variable ``name``,
a string, to the class itself, so that calling
``crowsetta.formats.by_name`` with that string
:func:`crowsetta.formats.by_name` with that string
will return the class.
Parameters
----------
format_class : class
A class that has the required class variables
and adheres to one of the interfaces
defined in ``crowsetta.interface``,
either ``SeqLike`` or ``BBoxLike``.
defined in :mod:`crowsetta.interface`,
either :class:`~crowsetta.interface.seq.SeqLike`
or :class:`~crowsetta.interface.bbox.BBoxLike`.
Returns
-------
format_class : class
The same class, unchanged.
This decorator only adds the class
to ``crowsetta.formats.FORMATS``.
to :data:`crowsetta.formats.FORMATS`.
"""
if not issubclass(format_class, interface.seq.SeqLike) and not issubclass(format_class, interface.bbox.BBoxLike):
raise TypeError(f"format class must be subclass of SeqLike or BBoxLike, but was not: {format_class}")
Expand Down
58 changes: 31 additions & 27 deletions src/crowsetta/formats/bbox/audbbox.py
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
"""Module for Audacity label tracks
in extended format, exported to .txt files
in extended format, exported to txt files
https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
"""
from __future__ import annotations
Expand All @@ -18,10 +18,10 @@

def txt_to_records(aud_txt_path: PathLike) -> list[dict]:
"""Load a txt file in Audacity extended label track format
into records for a `pandas.DataFrame``.
into records for a :type:`pandas.DataFrame`.
Returns a ``list`` of ``dict`` that can be made into a
``DataFrame`` by calling ``pandas.DataFrame.from_records``.
Returns a :class:`list` of :class:`dict` that can be made into a
:class:`~pandas.DataFrame` by calling :meth:`pandas.DataFrame.from_records`.
Parameters
----------
Expand All @@ -30,13 +30,13 @@ def txt_to_records(aud_txt_path: PathLike) -> list[dict]:
Returns
-------
records : list
Of ``dict``, each ``dict`` a row
in the ``DataFrame``.
Of :class:`dict`, each :class:`dict` will become
a row in the :class:`~pandas.DataFrame`.
Notes
-----
We work with Audacity txt files this way, instead of
loading with ``pandas.read_csv`` then munging, so that we can
loading with :func:`pandas.read_csv` then munging, so that we can
be sure that we can round-trip data without corrupting it.
"""
with pathlib.Path(aud_txt_path).open("r") as fp:
Expand All @@ -58,29 +58,30 @@ def txt_to_records(aud_txt_path: PathLike) -> list[dict]:


def df_to_lines(df: pd.DataFrame) -> list[str]:
"""Convert a pandas DataFrame to a list of strings
that can be saved as a txt file in Audacity extended
"""Convert a :type:`pandas.DataFrame` to a
:class:`list` of :class:`str` that can be saved
as a txt file in Audacity extended
label track format.
This function is (roughly) the inverse of
``crowsetta.formats.bbox.audbbox.txt_to_records``.
:func:`crowsetta.formats.bbox.audbbox.txt_to_records`.
Parameters
----------
df : pandas.DataFrame
With contents of a .txt file in Audacity extended label track format,
after being loaded and parsed by ``crowsetta.formats.bbox.audbbox.audbbox_txt_to_df``
With contents of a txt file in Audacity extended label track format,
after being loaded and parsed by :func:`crowsetta.formats.bbox.audbbox.audbbox_txt_to_df`
Returns
-------
lines : list
List of strings that can be saved to a text file
by calling ``writelines``.
by calling :func:`writelines`.
Notes
-----
We work with Audacity txt files this way, instead of
munging and then calling ``pandas.DataFrame.to_csv``,
munging and then calling :meth:`pandas.DataFrame.to_csv`,
so that we can be sure that we can round-trip data
without corrupting it.
"""
Expand All @@ -96,9 +97,10 @@ def df_to_lines(df: pd.DataFrame) -> list[str]:


class AudBBoxSchema(pandera.SchemaModel):
"""A ``pandera.SchemaModel`` that validates ``pandas`` dataframes
"""A :class:`pandera.SchemaModel` that
validates :mod:`pandas` dataframes
loaded from Audacity label tracks
in extended format, exported to .txt files
in extended format, exported to txt files
https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
"""

Expand All @@ -117,7 +119,7 @@ class Config:
@attr.define
class AudBBox:
"""Class that represents Audacity label tracks
in extended format, exported to .txt files
in extended format, exported to txt files
https://manual.audacityteam.org/man/importing_and_exporting_labels.html#Extended_format_with_frequency_ranges
Attributes
Expand All @@ -129,9 +131,9 @@ class AudBBox:
df : pandas.DataFrame
with annotations loaded into it
annot_path : str, pathlib.Path
Path to Audacity .txt file from which annotations were loaded.
Path to Audacity txt file from which annotations were loaded.
audio_path : str. pathlib.Path
Path to audio file that the Audacity .txt file annotates.
Path to audio file that the Audacity txt file annotates.
"""

COLUMNS_MAP: ClassVar[dict] = {
Expand All @@ -151,15 +153,15 @@ class AudBBox:

@classmethod
def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None) -> "Self": # noqa: F821
"""Load annotations from a Audacity annotation file with bbox,
"""Load annotations from an Audacity annotation file with bounding boxes,
created by exporting a Selection Table.
Parameters
----------
annot_path : str, pathlib.Path
Path to a .txt file exported from Audacity bbox.
Path to a txt file exported from Audacity bbox.
audio_path : str, pathlib.Path
Path to audio file that the Audacity bbox .txt file annotates.
Path to audio file that the Audacity bbox txt file annotates.
Optional, defaults to None.
Examples
Expand All @@ -172,7 +174,7 @@ def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None)
records = crowsetta.formats.bbox.audbbox.txt_to_records(annot_path)
df = pd.DataFrame.from_records(records)
if len(df) < 1:
raise ValueError(f"Cannot load annotations, " f"there are no rows in Audacity .txt file:\n{df}")
raise ValueError(f"Cannot load annotations, " f"there are no rows in Audacity txt file:\n{df}")
df = crowsetta.formats.bbox.audbbox.AudBBoxSchema.validate(df)

return cls(
Expand All @@ -182,12 +184,13 @@ def from_file(cls, annot_path: PathLike, audio_path: Optional[PathLike] = None)
)

def to_bbox(self) -> List[crowsetta.BBox]:
"""Convert this Audacity extended label track annotation to a ``list`` of ``crowsetta.Bbox``.
"""Convert this Audacity extended label track annotation
to a :class:`list` of :class:`crowsetta.Bbox`.
Returns
-------
bboxes : list
of ``crowsetta.BBox``
A :class:`list` of :class:`crowsetta.BBox` instances.
Examples
--------
Expand All @@ -209,7 +212,8 @@ def to_bbox(self) -> List[crowsetta.BBox]:
return bboxes

def to_annot(self) -> crowsetta.Annotation:
"""Convert this Audacity bbox annotation to a ``crowsetta.Annotation``.
"""Convert this Audacity bbox annotation
to a :class:`crowsetta.Annotation`.
Returns
-------
Expand All @@ -225,7 +229,7 @@ def to_annot(self) -> crowsetta.Annotation:
return crowsetta.Annotation(annot_path=self.annot_path, notated_path=self.audio_path, bboxes=bboxes)

def to_file(self, annot_path: PathLike) -> None:
"""Make a .txt file from this annotation
"""Make a txt file from this annotation
in extended label track format that can be read by Audacity.
Parameters
Expand Down
30 changes: 16 additions & 14 deletions src/crowsetta/formats/bbox/raven.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@


class RavenSchema(pandera.SchemaModel):
"""A ``pandera.SchemaModel`` that validates ``pandas`` dataframes
loaded from a .txt file, created by exporting a Selection Table
"""A :class:`pandera.SchemaModel` that validates :type:`pandas.DataFrame`s
loaded from a txt file, created by exporting a Selection Table
from Raven.
"""

Expand All @@ -40,7 +40,7 @@ class Config:
@crowsetta.interface.BBoxLike.register
@attr.define
class Raven:
"""Class that represents .txt annotation files
"""Class that represents txt annotation files
from Raven (https://ravensoundsoftware.com/software/),
created by exporting a Selection Table.
Expand All @@ -53,9 +53,9 @@ class Raven:
df : pandas.DataFrame
with annotations loaded into it
annot_path : str, pathlib.Path
Path to Raven .txt file from which annotations were loaded.
Path to Raven txt file from which annotations were loaded.
audio_path : str. pathlib.Path
Path to audio file that the Raven .txt file annotates.
Path to audio file that the Raven txt file annotates.
"""

name: ClassVar[str] = "raven"
Expand All @@ -82,11 +82,11 @@ def from_file(
Parameters
----------
annot_path : str, pathlib.Path
Path to a .txt file exported from Raven.
Path to a txt file exported from Raven.
annot_col : str
name of column that contains annotations
Name of column that contains annotations.
audio_path : str, pathlib.Path
Path to audio file that the Raven .txt file annotates.
Path to audio file that the Raven txt file annotates.
Optional, defaults to None.
Examples
Expand All @@ -100,7 +100,7 @@ def from_file(
# assume file is space-separated with no header
df = pd.read_csv(annot_path, sep="\t")
if len(df) < 1:
raise ValueError(f"Cannot load annotations, " f"there are no rows in Raven .txt file:\n{df}")
raise ValueError(f"Cannot load annotations, " f"there are no rows in Raven txt file:\n{df}")
columns_map = dict(cls.COLUMNS_MAP) # copy
columns_map.update({annot_col: "annotation"})
df.rename(columns=columns_map, inplace=True)
Expand All @@ -114,12 +114,13 @@ def from_file(
)

def to_bbox(self) -> List[crowsetta.BBox]:
"""Convert this Raven annotation to a ``list`` of ``crowsetta.Bbox``.
"""Convert this Raven annotation to a
:class:`list` of :class:`crowsetta.Bbox` instances.
Returns
-------
bboxes : list
of ``crowsetta.BBox``
A :class:`list` of :class:`crowsetta.BBox` instances.
Examples
--------
Expand All @@ -141,7 +142,8 @@ def to_bbox(self) -> List[crowsetta.BBox]:
return bboxes

def to_annot(self) -> crowsetta.Annotation:
"""Convert this Raven annotation to a ``crowsetta.Annotation``.
"""Convert this Raven annotation to a
:class:`crowsetta.Annotation`.
Returns
-------
Expand All @@ -157,13 +159,13 @@ def to_annot(self) -> crowsetta.Annotation:
return crowsetta.Annotation(annot_path=self.annot_path, notated_path=self.audio_path, bboxes=bboxes)

def to_file(self, annot_path: PathLike) -> None:
"""make a .txt file that can be read by Raven
"""Make a txt file that can be read by Raven
from this annotation
Parameters
----------
annot_path : str, pahtlib.Path
path including filename where file should be saved.
Path including filename where file should be saved.
Must have extension '.txt'
"""
crowsetta.validation.validate_ext(annot_path, extension=self.ext)
Expand Down
Loading

0 comments on commit c228809

Please sign in to comment.