Skip to content

Sample

sample

Sample Entity

Represents a biological sample with its associated KOs.

Classes

Sample dataclass 

Sample(id: SampleId, ko_list: List[KO] = list(), created_at: datetime = datetime.now(), metadata: Dict[str, Any] = dict())

Aggregate Root - Represents a biological sample.

Encapsulates business rules related to samples and their associated KOs. A sample is uniquely identified by its SampleId and contains a list of KOs (KEGG Orthology) that were detected in it.

Parameters:

Name Type Description Default
id SampleId

Unique sample identifier

 required
ko_list List[KO]

List of KOs associated with the sample

 []
created_at datetime

Sample creation timestamp

 datetime.now()
metadata Dict[str, Any]

Additional sample metadata

 {}

Raises:

Type Description
ValueError

If sample is validated without at least one KO
Notes

This is an Aggregate Root entity in DDD context, responsible for maintaining consistency of its invariants (e.g., every valid sample must have at least one KO).

Attributes
ko_count property 
ko_count: int

Returns quantity of KOs associated with the sample.

Returns:

Type Description
int

Number of KOs in the list.
Functions
add_ko 
add_ko(ko: KO) -> None

Adds a KO to the sample with duplicate validation.

Parameters:

Name Type Description Default
ko KO

KO to be added.

 required
Notes

Duplicate KOs are automatically ignored.

Source code in src/domain/entities/sample.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def add_ko(self, ko: KO) -> None:
    """
    Adds a KO to the sample with duplicate validation.

    Parameters
    ----------
    ko : KO
        KO to be added.

    Notes
    -----
    Duplicate KOs are automatically ignored.
    """
    if ko not in self.ko_list:
        self.ko_list.append(ko)
        logger.debug(
            "KO added to sample",
            extra={
                "sample_id": str(self.id),
                "ko": str(ko),
                "total_kos": len(self.ko_list),
            },
        )
    else:
        logger.debug(
            "Duplicate KO ignored", extra={"sample_id": str(self.id), "ko": str(ko)}
        )
remove_ko 
remove_ko(ko: KO) -> None

Removes a KO from the sample if it exists.

Parameters:

Name Type Description Default
ko KO

KO to be removed.

 required
Notes

If KO does not exist in the list, operation is silently ignored.

Source code in src/domain/entities/sample.py 
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def remove_ko(self, ko: KO) -> None:
    """
    Removes a KO from the sample if it exists.

    Parameters
    ----------
    ko : KO
        KO to be removed.

    Notes
    -----
    If KO does not exist in the list, operation is silently ignored.
    """
    if ko in self.ko_list:
        self.ko_list.remove(ko)
has_ko 
has_ko(ko: KO) -> bool

Checks if sample has a specific KO.

Parameters:

Name Type Description Default
ko KO

KO to be checked.

 required

Returns:

Type Description
bool

True if KO is present in the sample.
Source code in src/domain/entities/sample.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
def has_ko(self, ko: KO) -> bool:
    """
    Checks if sample has a specific KO.

    Parameters
    ----------
    ko : KO
        KO to be checked.

    Returns
    -------
    bool
        True if KO is present in the sample.
    """
    return ko in self.ko_list
get_unique_kos 
get_unique_kos() -> List[KO]

Returns list of unique KOs (without duplicates).

Returns:

Type Description
List[KO]

List of unique KOs.
Notes

In practice, ko_list should not contain duplicates due to add_ko() method, but this method ensures uniqueness.

Source code in src/domain/entities/sample.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def get_unique_kos(self) -> List[KO]:
    """
    Returns list of unique KOs (without duplicates).

    Returns
    -------
    List[KO]
        List of unique KOs.

    Notes
    -----
    In practice, ko_list should not contain duplicates due to
    add_ko() method, but this method ensures uniqueness.
    """
    return list(set(self.ko_list))
validate 
validate() -> None

Validates entity business rules.

Raises:

Type Description
ValueError

If sample does not have at least one KO.
Notes

This validation ensures the business invariant: every processed sample must contain at least one valid KO.

Source code in src/domain/entities/sample.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
def validate(self) -> None:
    """
    Validates entity business rules.

    Raises
    ------
    ValueError
        If sample does not have at least one KO.

    Notes
    -----
    This validation ensures the business invariant: every processed
    sample must contain at least one valid KO.
    """
    if self.ko_count == 0:
        logger.error(
            "Sample validation failed: No KOs", extra={"sample_id": str(self.id)}
        )
        raise ValueError(f"Sample {self.id} must have at least one KO")

    logger.debug(
        "Sample validation successful",
        extra={"sample_id": str(self.id), "ko_count": self.ko_count},
    )
__str__ 
__str__() -> str

Returns string representation of sample.

Returns:

Type Description
str

String in format "Sample(id) with X KOs".
Source code in src/domain/entities/sample.py 
170
171
172
173
174
175
176
177
178
179
def __str__(self) -> str:
    """
    Returns string representation of sample.

    Returns
    -------
    str
        String in format "Sample(id) with X KOs".
    """
    return f"Sample({self.id}) with {self.ko_count} KOs"
__repr__ 
__repr__() -> str

Returns debug representation of sample.

Returns:

Type Description
str

Detailed representation.
Source code in src/domain/entities/sample.py 
181
182
183
184
185
186
187
188
189
190
191
192
193
194
def __repr__(self) -> str:
    """
    Returns debug representation of sample.

    Returns
    -------
    str
        Detailed representation.
    """
    return (
        f"Sample(id={self.id}, "
        f"ko_count={self.ko_count}, "
        f"created_at={self.created_at})"
    )
__eq__ 
__eq__(other: object) -> bool

Compares samples by identity (SampleId).

Parameters:

Name Type Description Default
other object

Object to be compared.

 required

Returns:

Type Description
bool

True if both samples have the same ID.
Source code in src/domain/entities/sample.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def __eq__(self, other: object) -> bool:
    """
    Compares samples by identity (SampleId).

    Parameters
    ----------
    other : object
        Object to be compared.

    Returns
    -------
    bool
        True if both samples have the same ID.
    """
    if not isinstance(other, Sample):
        return False
    return self.id == other.id
__hash__ 
__hash__() -> int

Hash based on sample identifier.

Returns:

Type Description
int

Hash of SampleId.
Source code in src/domain/entities/sample.py 
214
215
216
217
218
219
220
221
222
223
def __hash__(self) -> int:
    """
    Hash based on sample identifier.

    Returns
    -------
    int
        Hash of SampleId.
    """
    return hash(self.id)

Functions