metahq-core 0.1.2__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

metahq_core/export/labels.py

@@ -4,7 +4,7 @@ Class for Labels export io classes.
 Author: Parker Hicks
 Date: 2025-09-08
 
-Last updated: 2025-11-21 by Parker Hicks
+Last updated: 2026-02-05 by Parker Hicks
 """
 
 from __future__ import annotations
@@ -22,6 +22,7 @@ from metahq_core.util.supported import (
     disease_ontologies,
     geo_metadata,
     get_annotations,
+    get_default_log_dir,
     metadata_fields,
     supported,
 )
@@ -37,33 +38,84 @@ LABEL_KEY = {"1": "positive", "-1": "negative", "2": "control"}
 
 
 class LabelsExporter(BaseExporter):
-    """Base abstract class for Exporter children."""
+    """Exporter for Labels curations.
 
-    def __init__(self, logger=None, loglevel=20, logdir=Path("."), verbose=True):
+    Attributes:
+        attribute (Literal["tissue", "disease", "sex", "age"]):
+            Attribute of the annotations to save.
+
+        level (Literal["sample", "series"]):
+            Level of the annotations.
+
+        logger (logging.Logger):
+            Python builtin Logger.
+
+        loglevel (int):
+            Logging level.
+
+        logdir (str | Path):
+            Path to directory storing logs.
+
+        verbose (bool):
+            Controls logging outputs.
+
+    """
+
+    def __init__(
+        self,
+        attribute: Literal["tissue", "disease", "sex", "age"],
+        level: Literal["sample", "series"],
+        logger=None,
+        loglevel=20,
+        logdir=get_default_log_dir(),
+        verbose=True,
+    ):
+        self.attribute = attribute
+        self._database = self._load_annotations(level)
 
         if logger is None:
             logger = setup_logger(__name__, level=loglevel, log_dir=logdir)
         self.log: logging.Logger = logger
         self.verbose: bool = verbose
 
-    def get_sra(self, labels: Labels, fields: list[str]) -> Labels:
+    def add_sources(self, labels: Labels) -> Labels:
+        """Add the sources that contributed to the lables of each sample or dataset.
+
+        Arguments:
+            labels (Labels):
+                A populated Labels curation object.
+
+        Returns:
+            The Labels object with additional source IDs for each index.
+
         """
-        Retrieve SRA IDs from the annotations if they exist.
+        sources = {labels.index_col: [], "sources": []}
+        for idx in labels.index:
+            sources[labels.index_col].append(idx)
+
+            # get sources for a particular index for the specified attribute
+            sources["sources"].append(
+                "|".join(list(self._database[idx][self.attribute].keys()))
+            )
+
+        return labels.add_ids(pl.DataFrame(sources))
+
+    def get_sra(self, labels: Labels, fields: list[str]) -> Labels:
+        """Retrieve SRA IDs from the annotations if they exist.
 
-        Parameters
-        ----------
-        labels: Labels
-            A Labels curation containing samples and terms matching user-specified
-            filters.
+        Arguments:
+            labels (Labels):
+                A Labels curation containing samples and terms matching user-specified
+                filters.
 
-        fields: list[str]
-            SRA ID levels (i.e., srr, srx, srs, or srp)
+            fields (list[str]):
+                SRA ID levels (i.e., srr, srx, srs, or srp)
 
-        Returns
-        -------
-        A new Annotations curation with merged SRA IDs.
+        Returns:
+            A new Annotations curation with merged SRA IDs.
 
         """
+
         _labels = self._load_annotations(
             level=labels.index_col
         )  # all MetaHQ annotations
@@ -91,18 +143,22 @@ class LabelsExporter(BaseExporter):
         metadata: str | None = None,
         **kwargs,
     ):
-        """
+        """Save labels curation to json. Keys are terms and values are
+        positively, negative, netral, and control labeled entries.
 
-        Save labels curation to json. Keys are terms and values are
-        positively labelstated indices.
+        Arguments:
+            labels (Labels):
+                A populated Labels curation object.
+
+            fmt (Literal["json", "parquet", "csv", "tsv"]):
+                File format to save to.
+
+            file (FilePath):
+                Path to outfile.json.
 
-        Parameters
-        ----------
-        outfile: FilePath
-            Path to outfile.json.
+            metadata (str):
+                Metadata fields to include.
 
-        metadata: str
-            Metadata fields to include.
         """
         _ = checkdir(file, is_file=True)
         opt = {
@@ -119,34 +175,37 @@ class LabelsExporter(BaseExporter):
     def to_csv(
         self, curation: Labels, file: FilePath, metadata: str | None = None, **kwargs
     ):
-        """
-        Save labels to csv.
+        """Save labels to csv.
+
+        Arguments:
+            curation (Labels):
+                A populated Labels curation object.
 
-        Parameters
-        ----------
-        outfile: FilePath
-            Path to outfile.csv.
+            file (FilePath):
+                Path to outfile.csv.
 
-        metadata: str
-            Metadata fields to include.
+            metadata (str):
+                Metadata fields to include.
 
         """
         self._save_tabular("csv", curation, file, metadata, **kwargs)
 
     def to_json(self, curation: Labels, file: FilePath, metadata: str | None = None):
-        """
-        Save labels curation to json. Keys are terms and values are
+        """Save labels curation to json. Keys are terms and values are
         positively labelstated indices.
 
-        Parameters
-        ----------
-        file: FilePath
-            Path to outfile.json.
+        Arguments:
+            curation (Labels):
+                A populated Labels curation object.
 
-        metadata: str
-            Metadata fields to include.
+            file (FilePath):
+                Path to outfile.json.
+
+            metadata (str):
+                Metadata fields to include.
 
         """
+
         has_controls = any(
             term.startswith(disease_ontologies()) for term in curation.entities
         )
@@ -164,13 +223,14 @@ class LabelsExporter(BaseExporter):
             isinstance(metadata, str)
             & (metadata.strip().replace(",", "") == curation.index_col)
         ):
-            # save with just index IDs
-            stacked = curation.data.hstack(curation.ids)
-            for row in stacked.iter_rows(named=True):
-                self._write_row(row, _labels, curation.index_col)
+            metadata = curation.index_col
+
+        if isinstance(metadata, str):
+            # add sources
+            curation = self.add_sources(curation)
 
-        elif isinstance(metadata, str):
             _metadata = self._parse_metafields(curation.index_col, metadata)
+            _metadata.extend(["sources"])
 
             if self._sra_in_metadata(_metadata):
                 curation = self.get_sra(
@@ -209,19 +269,17 @@ class LabelsExporter(BaseExporter):
         metadata: str | None = None,
         **kwargs,
     ):
-        """
-        Save labels to parquet.
+        """Save labels to parquet.
 
-        Parameters
-        ----------
-        curation: Labels
-            Labels curation object to save.
+        Arguments:
+            curation (Labels):
+                Labels curation object to save.
 
-        file: FilePath
-            Path to outfile.parquet.
+            file (FilePath):
+                Path to outfile.parquet.
 
-        metadata: str | None
-            Metadata fields to include.
+            metadata (str | None):
+                Metadata fields to include.
 
         """
         self._save_tabular("parquet", curation, file, metadata, **kwargs)
@@ -229,16 +287,17 @@ class LabelsExporter(BaseExporter):
     def to_tsv(
         self, curation: Labels, file: FilePath, metadata: str | None = None, **kwargs
     ):
-        """
-        Save labels to tsv.
+        """Save labels to tsv.
+
+        Arguments:
+            curation (Labels):
+                A populated Labels curation object.
 
-        Parameters
-        ----------
-        outfile: FilePath
-            Path to outfile.tsv.
+            file (FilePath):
+                Path to outfile.tsv.
 
-        metadata: str
-            Metadata fields to include.
+            metadata (str):
+                Metadata fields to include.
 
         """
         self._save_tabular("tsv", curation, file, metadata, **kwargs)
@@ -358,6 +417,11 @@ class LabelsExporter(BaseExporter):
             curation = self.get_sra(
                 curation, [field for field in _metadata if field in database_ids("sra")]
             )
+
+        # add sources
+        curation = self.add_sources(curation)
+        _metadata = _metadata + ["sources"]
+
         if "description" in _metadata:
             self._save_table_with_description(
                 file, curation, _metadata, fmt=fmt, **kwargs
@@ -394,13 +458,7 @@ class LabelsExporter(BaseExporter):
         for entity in labels:
             label = str(row[entity])
             if label in LABEL_KEY:
-                try:
-                    labels[entity][LABEL_KEY[label]].append(idx)
-                except KeyError:
-                    print(labels[entity])
-                    print(LABEL_KEY[label])
-                    print(idx)
-                    exit()
+                labels[entity][LABEL_KEY[label]].append(idx)
 
     def _write_row_with_metadata(
         self,

metahq_core/logger.py

@@ -4,11 +4,10 @@ Logger setup.
 Author: Parker Hicks
 Date: 2025-10-16
 
-Last updated: 2025-11-21 by Parker Hicks
+Last updated: 2026-02-04 by Parker Hicks
 """
 
 import logging
-from logging.handlers import TimedRotatingFileHandler
 from pathlib import Path
 
 
@@ -17,22 +16,19 @@ def setup_logger(
     log_dir: str | Path,
     level: int = logging.INFO,
 ) -> logging.Logger:
-    """
-    Sets up a logger.
+    """Sets up a logger.
 
-    Parameters
-    ----------
-    name: str
-        Logger name.
+    Arguments:
+        name (str):
+            Logger name.
 
-    log_dir: str | Path
-        Path to logging directory. Default is ~/metahq/logs
+        log_dir (str | Path):
+            Path to logging directory.
 
-    level: int
-        Logging level.
+        level (int):
+            Logging level.
 
-    Returns
-    -------
+    Returns:
         Configured logger.
 
     """
@@ -56,11 +52,8 @@ def setup_logger(
     logger.addHandler(console_handler)
 
     # file handler
-    file_handler = TimedRotatingFileHandler(
+    file_handler = logging.FileHandler(
         Path(log_dir) / "log.log",
-        when="midnight",
-        interval=1,
-        backupCount=30,
         encoding="utf-8",
     )
     file_handler.setFormatter(formatter)