lamindb 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

lamindb/models/flextable.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.db import models
+from django.db.models import PROTECT, ManyToManyField
+
+from lamindb.base.fields import (
+    BooleanField,
+    CharField,
+    ForeignKey,
+    IntegerField,
+)
+
+from .artifact import Artifact
+from .feature import Feature
+from .record import (
+    BasicRecord,
+    Record,
+)
+from .run import Param, TracksRun, TracksUpdates
+
+if TYPE_CHECKING:
+    from .project import Project
+
+from django.core.exceptions import ValidationError
+
+from ..base.ids import base62_12
+from .collection import Collection
+from .project import Person, Project
+from .record import Space
+from .schema import Schema
+from .ulabel import ULabel
+
+
+class DataMixin(models.Model):
+    space: Space = ForeignKey(Space, PROTECT, default=1, db_default=1)
+    feature = ForeignKey(
+        Feature, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    param = ForeignKey(
+        Param, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    row = IntegerField(help_text="Use -1 for result data")
+
+    # Value fields
+    value_int = models.BigIntegerField(null=True, blank=True)
+    value_float = models.FloatField(null=True, blank=True)
+    value_str = models.TextField(null=True, blank=True)
+    value_datetime = models.DateTimeField(null=True, blank=True)
+    value_ulabel = models.ForeignKey(
+        ULabel, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    value_person = models.ForeignKey(
+        Person, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    value_artifact = models.ForeignKey(
+        Artifact, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    value_collection = models.ForeignKey(
+        Collection, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    value_project = models.ForeignKey(
+        Project, null=True, blank=True, on_delete=models.CASCADE, related_name="+"
+    )
+    value_json = models.JSONField(null=True, blank=True)
+
+    class Meta:
+        abstract = True
+
+    def clean(self):
+        # Validate feature/param mutual exclusivity
+        if (self.feature is not None) == (self.param is not None):
+            raise ValidationError("Exactly one of feature or param must be set")
+
+        # Validate value fields
+        values = [
+            self.value_int,
+            self.value_float,
+            self.value_str,
+            self.value_datetime,
+            self.value_ulabel,
+            self.value_artifact,
+            self.value_json,
+        ]
+        non_null_count = sum(1 for v in values if v is not None)
+
+        if non_null_count != 1:
+            raise ValidationError("Exactly one value field must be set")
+
+
+class RunData(BasicRecord, DataMixin):
+    run = models.ForeignKey("Run", on_delete=models.CASCADE, related_name="_rundata")
+
+    class Meta:
+        constraints = [
+            models.CheckConstraint(
+                condition=(
+                    models.Q(feature__isnull=False, param__isnull=True)
+                    | models.Q(feature__isnull=True, param__isnull=False)
+                ),
+                name="run_data_feature_param_mutex",
+            ),
+            models.UniqueConstraint(
+                fields=["run", "row", "feature", "param"], name="run_data_unique"
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["run", "row"]),
+            models.Index(fields=["feature"]),
+            models.Index(fields=["param"]),
+        ]
+
+
+class FlexTable(Record, TracksRun, TracksUpdates):
+    uid: str = CharField(
+        editable=False, unique=True, max_length=12, db_index=True, default=base62_12
+    )
+    name = CharField()
+    schema: Schema | None = ForeignKey(
+        Schema, null=True, on_delete=models.SET_NULL, related_name="_tidytables"
+    )
+    type: FlexTable | None = ForeignKey(
+        "self", PROTECT, null=True, related_name="records"
+    )
+    """Type of tidy table, e.g., `Cell`, `SampleSheet`, etc."""
+    records: ULabel
+    """Records of this type."""
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
+    """Distinguish types from instances of the type."""
+    description: str = CharField(null=True, db_index=True)
+    """A description."""
+    projects: Project = ManyToManyField(Project, related_name="_tidytables")
+    ulabels: Project = ManyToManyField(ULabel, related_name="_tidytables")
+
+    class Meta:
+        indexes = [models.Index(fields=["uid"]), models.Index(fields=["name"])]
+
+
+class FlexTableData(BasicRecord, DataMixin):
+    tidytable = models.ForeignKey(
+        FlexTable, on_delete=models.CASCADE, related_name="data"
+    )
+
+    class Meta:
+        constraints = [
+            models.CheckConstraint(
+                condition=(
+                    models.Q(feature__isnull=False, param__isnull=True)
+                    | models.Q(feature__isnull=True, param__isnull=False)
+                ),
+                name="tidy_table_data_feature_param_mutex",
+            ),
+            models.UniqueConstraint(
+                fields=["tidytable", "row", "feature", "param"],
+                name="tidy_table_data_unique",
+            ),
+        ]
+        indexes = [
+            models.Index(fields=["tidytable", "row"]),
+            models.Index(fields=["feature"]),
+            models.Index(fields=["param"]),
+        ]

lamindb/{_parents.py → models/has_parents.py}

@@ -1,27 +1,22 @@
+# ruff: noqa: TC004
 from __future__ import annotations
 
 import builtins
 from typing import TYPE_CHECKING, Literal
 
-import lamindb_setup as ln_setup
 from lamin_utils import logger
 
-from lamindb.models import (
-    Artifact,
-    Collection,
-    HasParents,
-    Record,
-    Run,
-    Transform,
-    format_field_value,
-)
-
-from ._record import get_name_field
-from ._utils import attach_func_to_class_method
+from .record import format_field_value, get_name_field
+from .run import Run
 
 if TYPE_CHECKING:
     from lamindb.base.types import StrField
-    from lamindb.core import QuerySet
+
+    from .artifact import Artifact
+    from .collection import Collection
+    from .query_set import QuerySet
+    from .record import Record
+    from .transform import Transform
 
 LAMIN_GREEN_LIGHTER = "#10b981"
 LAMIN_GREEN_DARKER = "#065f46"
@@ -53,12 +48,50 @@ def _query_relatives(
     return relatives
 
 
-def query_parents(self) -> QuerySet:
-    return _query_relatives([self], "parents", self.__class__)
+class HasParents:
+    """Base class for hierarchical registries (ontologies)."""
+
+    def view_parents(
+        self,
+        field: StrField | None = None,
+        with_children: bool = False,
+        distance: int = 5,
+    ):
+        """View parents in an ontology.
+
+        Args:
+            field: Field to display on graph
+            with_children: Whether to also show children.
+            distance: Maximum distance still shown.
+
+        Ontological hierarchies: :class:`~lamindb.ULabel` (project & sub-project), :class:`~bionty.CellType` (cell type & subtype).
+
+        Examples:
+            >>> import bionty as bt
+            >>> bt.Tissue.from_source(name="subsegmental bronchus").save()
+            >>> record = bt.Tissue.get(name="respiratory tube")
+            >>> record.view_parents()
+            >>> tissue.view_parents(with_children=True)
+        """
+        if field is None:
+            field = get_name_field(self)
+        if not isinstance(field, str):
+            field = field.field.name
+
+        return _view_parents(
+            record=self,  # type: ignore
+            field=field,
+            with_children=with_children,
+            distance=distance,
+        )
 
+    def query_parents(self) -> QuerySet:
+        """Query parents in an ontology."""
+        return _query_relatives([self], "parents", self.__class__)  # type: ignore
 
-def query_children(self) -> QuerySet:
-    return _query_relatives([self], "children", self.__class__)
+    def query_children(self) -> QuerySet:
+        """Query children in an ontology."""
+        return _query_relatives([self], "children", self.__class__)  # type: ignore
 
 
 def _transform_emoji(transform: Transform):
@@ -93,22 +126,6 @@ def _view(u):
         )
 
 
-def view_parents(
-    self,
-    field: StrField | None = None,
-    with_children: bool = False,
-    distance: int = 5,
-):
-    if field is None:
-        field = get_name_field(self)
-    if not isinstance(field, str):
-        field = field.field.name
-
-    return _view_parents(
-        record=self, field=field, with_children=with_children, distance=distance
-    )
-
-
 def view_lineage(data: Artifact | Collection, with_children: bool = True) -> None:
     """Graph of data flow.
 
@@ -332,6 +349,10 @@ def _df_edges_from_parents(
 
 
 def _record_label(record: Record, field: str | None = None):
+    from .artifact import Artifact
+    from .collection import Collection
+    from .transform import Transform
+
     if isinstance(record, Artifact):
         if record.description is None:
             name = record.key
@@ -511,18 +532,3 @@ def _df_edges_from_runs(df_values: list):
     df["source_label"] = df["source_record"].apply(_record_label)
     df["target_label"] = df["target_record"].apply(_record_label)
     return df
-
-
-METHOD_NAMES = ["view_parents", "query_parents", "query_children"]
-
-if ln_setup._TESTING:  # type: ignore
-    from inspect import signature
-
-    SIGS = {
-        name: signature(getattr(HasParents, name))
-        for name in METHOD_NAMES
-        if not name.startswith("__")
-    }
-
-for name in METHOD_NAMES:
-    attach_func_to_class_method(name, HasParents, globals())

lamindb/models/project.py

@@ -0,0 +1,384 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from django.core.validators import RegexValidator
+from django.db import models
+from django.db.models import CASCADE, PROTECT
+
+from lamindb.base.fields import (
+    BigIntegerField,
+    BooleanField,
+    CharField,
+    DateField,
+    DateTimeField,
+    EmailField,
+    ForeignKey,
+    TextField,
+    URLField,
+)
+from lamindb.base.users import current_user_id
+
+from ..base.ids import base62_8, base62_12
+from .artifact import Artifact
+from .can_curate import CanCurate
+from .collection import Collection
+from .feature import Feature
+from .record import BasicRecord, LinkORM, Record, ValidateFields
+from .run import Run, TracksRun, TracksUpdates, User
+from .schema import Schema
+from .transform import Transform
+from .ulabel import ULabel
+
+if TYPE_CHECKING:
+    from datetime import date as DateType
+    from datetime import datetime
+
+
+class Person(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
+    """People.
+
+    This registry is distinct from `User` and exists for project management.
+
+    You'll soon be able to conveniently create persons from users.
+
+    Example:
+        >>> person = Person(
+        ...     name="Jane Doe",
+        ...     email="jane.doe@example.com",
+        ...     internal=True,
+        ... ).save()
+    """
+
+    class Meta(Record.Meta, TracksRun.Meta, TracksUpdates.Meta):
+        abstract = False
+
+    id: int = models.AutoField(primary_key=True)
+    """Internal id, valid only in one DB instance."""
+    uid: str = CharField(
+        editable=False, unique=True, max_length=8, db_index=True, default=base62_8
+    )
+    """Universal id, valid across DB instances."""
+    name: str = CharField(db_index=True)
+    """Name of the person (forename(s) lastname)."""
+    email: str | None = EmailField(null=True, default=None)
+    """Email of the person."""
+    external: bool = BooleanField(default=True, db_index=True)
+    """Whether the person is external to the organization."""
+
+
+class Reference(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
+    """References such as internal studies, papers, documents, or URLs.
+
+    Example:
+        >>> reference = Reference(
+        ...     name="A Paper Title",
+        ...     abbr="APT",
+        ...     url="https://doi.org/10.1000/xyz123",
+        ...     pubmed_id=12345678,
+        ...     doi="10.1000/xyz123",
+        ...     description="Good paper.",
+        ...     text="Some text I want to be searchable.",
+        ...     date=date(2023, 11, 21),
+        ... ).save()
+    """
+
+    class Meta(Record.Meta, TracksRun.Meta, TracksUpdates.Meta):
+        abstract = False
+
+    id: int = models.AutoField(primary_key=True)
+    """Internal id, valid only in one DB instance."""
+    uid: str = CharField(
+        editable=False, unique=True, max_length=12, db_index=True, default=base62_12
+    )
+    """Universal id, valid across DB instances."""
+    name: str = CharField(db_index=True)
+    """Title or name of the reference document."""
+    abbr: str | None = CharField(
+        max_length=32,
+        db_index=True,
+        null=True,
+    )
+    """An abbreviation for the reference."""
+    type: Reference | None = ForeignKey(
+        "self", PROTECT, null=True, related_name="records"
+    )
+    """Type of reference (e.g., 'Study', 'Paper', 'Preprint').
+
+    Allows to group reference by type, e.g., internal studies vs. all papers etc.
+    """
+    records: Reference
+    """Records of this type."""
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
+    """Distinguish types from instances of the type."""
+    url: str | None = URLField(null=True)
+    """URL linking to the reference."""
+    pubmed_id: int | None = BigIntegerField(null=True, db_index=True)
+    """A PudMmed ID."""
+    doi: str | None = CharField(
+        null=True,
+        db_index=True,
+        validators=[
+            RegexValidator(
+                regex=r"^(?:https?://(?:dx\.)?doi\.org/|doi:|DOI:)?10\.\d+/.*$",
+                message="Must be a DOI (e.g., 10.1000/xyz123 or https://doi.org/10.1000/xyz123)",
+            )
+        ],
+    )
+    """Digital Object Identifier (DOI) for the reference."""
+    description: str | None = CharField(null=True, db_index=True)
+    """Description of the reference."""
+    text: str | None = TextField(null=True)
+    """Abstract or full text of the reference to make it searchable."""
+    date: DateType | None = DateField(null=True, default=None)
+    """Date of creation or publication of the reference."""
+    authors: Person = models.ManyToManyField(Person, related_name="references")
+    """All people associated with this reference."""
+    artifacts: Artifact = models.ManyToManyField(
+        Artifact, through="ArtifactReference", related_name="references"
+    )
+    """Artifacts associated with this reference."""
+    transforms: Artifact = models.ManyToManyField(
+        Transform, through="TransformReference", related_name="references"
+    )
+    """Transforms associated with this reference."""
+    collections: Artifact = models.ManyToManyField(
+        Collection, through="CollectionReference", related_name="references"
+    )
+    """Collections associated with this reference."""
+
+
+class Project(Record, CanCurate, TracksRun, TracksUpdates, ValidateFields):
+    """Projects.
+
+    Example:
+        >>> project = Project(
+        ...     name="My Project Name",
+        ...     abbr="MPN",
+        ...     url="https://example.com/my_project",
+        ... ).save()
+    """
+
+    class Meta(Record.Meta, TracksRun.Meta, TracksUpdates.Meta):
+        abstract = False
+
+    id: int = models.AutoField(primary_key=True)
+    """Internal id, valid only in one DB instance."""
+    uid: str = CharField(
+        editable=False, unique=True, max_length=12, db_index=True, default=base62_12
+    )
+    """Universal id, valid across DB instances."""
+    name: str = CharField(db_index=True)
+    """Title or name of the Project."""
+    type: Project | None = ForeignKey(
+        "self", PROTECT, null=True, related_name="records"
+    )
+    """Type of project (e.g., 'Program', 'Project', 'GithubIssue', 'Task')."""
+    records: Project
+    """Records of this type."""
+    is_type: bool = BooleanField(default=False, db_index=True, null=True)
+    """Distinguish types from instances of the type."""
+    abbr: str | None = CharField(max_length=32, db_index=True, null=True)
+    """An abbreviation."""
+    url: str | None = URLField(max_length=255, null=True, default=None)
+    """A URL."""
+    start_date: DateType | None = DateField(null=True, default=None)
+    """Date of start of the project."""
+    end_date: DateType | None = DateField(null=True, default=None)
+    """Date of start of the project."""
+    parents: Project = models.ManyToManyField(
+        "self", symmetrical=False, related_name="children"
+    )
+    """Parent projects, the super-projects owning this project."""
+    children: Project
+    """Child projects, the sub-projects owned by this project.
+
+    Reverse accessor for `.parents`.
+    """
+    predecessors: Project = models.ManyToManyField(
+        "self", symmetrical=False, related_name="successors"
+    )
+    """The preceding projects required by this project."""
+    successors: Project
+    """The succeeding projects requiring this project.
+
+    Reverse accessor for `.predecessors`.
+    """
+    people: Person = models.ManyToManyField(
+        Person, through="PersonProject", related_name="projects"
+    )
+    """Linked people."""
+    artifacts: Artifact = models.ManyToManyField(
+        Artifact, through="ArtifactProject", related_name="projects"
+    )
+    """Linked artifacts."""
+    transforms: Transform = models.ManyToManyField(
+        Transform, through="TransformProject", related_name="projects"
+    )
+    """Linked transforms."""
+    runs: Run = models.ManyToManyField(
+        Run, through="RunProject", related_name="projects"
+    )
+    """Linked transforms."""
+    ulabels: ULabel = models.ManyToManyField(
+        ULabel, through="ULabelProject", related_name="projects"
+    )
+    """Linked ulabels."""
+    features: ULabel = models.ManyToManyField(
+        Feature, through="FeatureProject", related_name="projects"
+    )
+    """Linked features."""
+    schemas: ULabel = models.ManyToManyField(
+        Schema, through="SchemaProject", related_name="projects"
+    )
+    """Linked schemas."""
+    collections: Collection = models.ManyToManyField(
+        Collection, through="CollectionProject", related_name="projects"
+    )
+    """Linked collections."""
+    references: Reference = models.ManyToManyField("Reference", related_name="projects")
+    """Linked references."""
+    _status_code: int = models.SmallIntegerField(default=0, db_index=True)
+    """Status code."""
+
+
+class ArtifactProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    artifact: Artifact = ForeignKey(Artifact, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_artifact")
+    feature: Feature | None = ForeignKey(
+        Feature,
+        PROTECT,
+        null=True,
+        default=None,
+        related_name="links_artifactproject",
+    )
+    label_ref_is_name: bool | None = BooleanField(null=True, default=None)
+    feature_ref_is_name: bool | None = BooleanField(null=True, default=None)
+
+    class Meta:
+        # can have the same label linked to the same artifact if the feature is different
+        unique_together = ("artifact", "project", "feature")
+
+
+class RunProject(BasicRecord, LinkORM):
+    id: int = models.BigAutoField(primary_key=True)
+    run: Run = ForeignKey(Run, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_run")
+    created_at: datetime = DateTimeField(
+        editable=False, db_default=models.functions.Now(), db_index=True
+    )
+    """Time of creation of record."""
+    created_by: User = ForeignKey(
+        "lamindb.User",
+        PROTECT,
+        editable=False,
+        default=current_user_id,
+        related_name="+",
+    )
+    """Creator of record."""
+
+    class Meta:
+        unique_together = ("run", "project")
+
+
+class TransformProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    transform: Transform = ForeignKey(Transform, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_transform")
+
+    class Meta:
+        unique_together = ("transform", "project")
+
+
+class CollectionProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    collection: Collection = ForeignKey(
+        Collection, CASCADE, related_name="links_project"
+    )
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_collection")
+
+    class Meta:
+        unique_together = ("collection", "project")
+
+
+class ULabelProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    ulabel: Transform = ForeignKey(ULabel, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_ulabel")
+
+    class Meta:
+        unique_together = ("ulabel", "project")
+
+
+class PersonProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    person: Transform = ForeignKey(Person, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_person")
+    role: str | None = CharField(null=True, default=None)
+
+    class Meta:
+        unique_together = ("person", "project")
+
+
+class FeatureProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    feature: Feature = ForeignKey(Feature, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_feature")
+
+    class Meta:
+        unique_together = ("feature", "project")
+
+
+class SchemaProject(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    schema: Schema = ForeignKey(Schema, CASCADE, related_name="links_project")
+    project: Project = ForeignKey(Project, PROTECT, related_name="links_schema")
+
+    class Meta:
+        unique_together = ("schema", "project")
+
+
+class ArtifactReference(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    artifact: Artifact = ForeignKey(Artifact, CASCADE, related_name="links_reference")
+    reference: Reference = ForeignKey(Reference, PROTECT, related_name="links_artifact")
+    feature: Feature | None = ForeignKey(
+        Feature,
+        PROTECT,
+        null=True,
+        default=None,
+        related_name="links_artifactreference",
+    )
+    label_ref_is_name: bool | None = BooleanField(null=True, default=None)
+    feature_ref_is_name: bool | None = BooleanField(null=True, default=None)
+
+    class Meta:
+        # can have the same label linked to the same artifact if the feature is different
+        unique_together = ("artifact", "reference", "feature")
+
+
+class TransformReference(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    transform: Transform = ForeignKey(
+        Transform, CASCADE, related_name="links_reference"
+    )
+    reference: Reference = ForeignKey(
+        Reference, PROTECT, related_name="links_transform"
+    )
+
+    class Meta:
+        unique_together = ("transform", "reference")
+
+
+class CollectionReference(BasicRecord, LinkORM, TracksRun):
+    id: int = models.BigAutoField(primary_key=True)
+    collection: Collection = ForeignKey(
+        Collection, CASCADE, related_name="links_reference"
+    )
+    reference: Reference = ForeignKey(
+        Reference, PROTECT, related_name="links_collection"
+    )
+
+    class Meta:
+        unique_together = ("collection", "reference")