onconova.research.schemas.cohort

CohortQueryEntity module-attribute

Enumeration of case-related resource entities for cohort queries.

CohortQueryFilter module-attribute

Enumeration of available filter operators for cohort queries.

Cohort

Bases: CohortCreate, MetadataMixin

population class-attribute instance-attribute

CohortContribution

Bases: Schema

Schema representing a user's contribution to a cohort.

Attributes:

Name	Type	Description
contributor	str	Username or identifier of the contributing user.
contributions	int	The number of records or actions contributed by this user.

contributions class-attribute instance-attribute

contributor class-attribute instance-attribute

CohortCreate

Bases: BaseSchema

__orm_model__ class-attribute instance-attribute

casesIds class-attribute instance-attribute

excludeCriteria class-attribute instance-attribute

externalSource class-attribute instance-attribute

externalSourceId class-attribute instance-attribute

frozenSetIds class-attribute instance-attribute

includeCriteria class-attribute instance-attribute

manualChoicesIds class-attribute instance-attribute

name class-attribute instance-attribute

projectId class-attribute instance-attribute

CohortFilters

Bases: create_filters_schema(schema=Cohort, name='CohortFilters')

createdBy class-attribute instance-attribute

filter_createdBy(value)

Adds a filter for the creator username.

Source code in onconova/research/schemas/cohort.py

def filter_createdBy(self, value: str) -> Q:
    """
    Adds a filter for the creator username.
    """
    return Q(created_by=self.createdBy) if value is not None else Q()

CohortRule

Bases: Schema

Represents a rule for cohort selection, specifying an entity and a set of filters.

Attributes:

Name	Type	Description
entity	CohortQueryEntity	The case-related resource to which the rule applies.
filters	List[CohortRuleFilter]	A list of filters to be applied to the resource.

entity class-attribute instance-attribute

filters class-attribute instance-attribute

convert_to_query()

Converts the cohort filters into Django Q objects for querying the database.

Iterates over the filters defined in the cohort, applies the corresponding operator to each filter, and combines them using logical AND. If the entity is a PatientCase, yields the combined Q object directly. Otherwise, constructs a subquery that filters related PatientCase objects and yields a Q object representing the existence of such cases.

Yields:

Type	Description
Q	Iterator[Q]: An iterator of Django Q objects representing the query for the cohort.

Source code in onconova/research/schemas/cohort.py

def convert_to_query(self) -> Iterator[Q]:
    """
    Converts the cohort filters into Django Q objects for querying the database.

    Iterates over the filters defined in the cohort, applies the corresponding operator
    to each filter, and combines them using logical AND. If the entity is a PatientCase,
    yields the combined Q object directly. Otherwise, constructs a subquery that filters
    related PatientCase objects and yields a Q object representing the existence of such
    cases.

    Yields:
        Iterator[Q]: An iterator of Django Q objects representing the query for the cohort.
    """
    model = getattr(oncology_models, self.entity)
    subquery = Q()
    for filter in self.filters:
        operator = getattr(filters_module, filter.operator)
        subquery = subquery & operator.get_query(
            filter.db_field, filter.db_value, model
        )
    if model is oncology_models.PatientCase:
        yield subquery
    else:
        subquery = model.objects.filter(Q(case=OuterRef("pk")) & subquery)
        yield Q(Exists(subquery))

CohortRuleFilter

Bases: Schema

Schema representing a filter rule for cohort queries.

Attributes:

Name	Type	Description
field	str	Dot-separated path of the resource field (e.g. 'medications.drug').
operator	CohortQueryFilter	Name of the filter operator to be applied to the field.
value	Any	Filter value to be applied to the field using the rule's operator.
db_value	Any	Returns the value formatted for database queries. If the value is a dictionary with 'unit' and 'value', it converts it using get_measure_db_value. If it contains 'start' and 'end', returns a tuple of (start, end). Otherwise, returns the value as-is.
db_field	Any	Converts the dot-separated field path into Django ORM double-underscore syntax (e.g. 'medications.drug' -> 'medications__drug').

db_field property

Converts a dot-separated field path into Django ORM double-underscore syntax.

db_value property

field class-attribute instance-attribute

operator class-attribute instance-attribute

value class-attribute instance-attribute

CohortRuleset

Bases: Schema

Represents a set of cohort rules combined by a logical condition (AND/OR).

Attributes:

Name	Type	Description
condition	RulesetCondition	Logical condition used to chain the rules within the ruleset.
rules	List[Union[CohortRule, CohortRuleset]]	List of rules or nested rulesets that define the fields and values to use for filtering.

condition class-attribute instance-attribute

rules class-attribute instance-attribute

convert_to_query()

Converts the ruleset into a Django Q object query iterator.

Iterates through each rule in the ruleset, combining their queries using the specified logical condition (AND/OR). For each rule, its query is combined with the accumulated query using the condition. The final combined query is yielded as an iterator.

Returns:

Type	Description
Iterator[Q]	Iterator[Q]: An iterator yielding the combined Q object representing the ruleset's logic.

Source code in onconova/research/schemas/cohort.py

def convert_to_query(self) -> Iterator[Q]:
    """
    Converts the ruleset into a Django Q object query iterator.

    Iterates through each rule in the ruleset, combining their queries using the specified logical condition
    (AND/OR). For each rule, its query is combined with the accumulated query using the condition. The final
    combined query is yielded as an iterator.

    Returns:
        Iterator[Q]: An iterator yielding the combined Q object representing the ruleset's logic.
    """
    query = Q()
    for rule in self.rules:
        for rule_query in rule.convert_to_query():
            if self.condition == RulesetCondition.AND:
                query = rule_query & query
            if self.condition == RulesetCondition.OR:
                query = rule_query | query
    # Yield the completed, compiled logic for this branch of query back up the pipe:
    yield query

CohortTraitAverage

Bases: Schema

Schema representing the average and standard deviation of a trait within a cohort.

Attributes:

Name	Type	Description
average	float	The mean value for the cohort trait.
standardDeviation	Optional[float]	The standard deviation for the cohort trait, if applicable. May be None.

average class-attribute instance-attribute

standardDeviation class-attribute instance-attribute

CohortTraitCounts

Bases: Schema

Schema representing the count and percentage of records for a specific cohort trait category.

Attributes:

Name	Type	Description
category	str	The category or group label for the cohort trait value.
counts	int	The number of records in this category.
percentage	float	The percentage of the total cohort population in this category.

category class-attribute instance-attribute

counts class-attribute instance-attribute

percentage class-attribute instance-attribute

CohortTraitMedian

Bases: Schema

Schema representing the median and interquartile range (IQR) for a cohort trait.

Attributes:

Name	Type	Description
median	float | None	The median value for the cohort trait.
interQuartalRange	Tuple[float, float] | None	The lower and upper bounds of the interquartile range (IQR).

interQuartalRange class-attribute instance-attribute

median class-attribute instance-attribute

CohortTraits

Bases: Schema

Schema representing key traits and distributions within a patient cohort.

Attributes:

Name	Type	Description
age	CohortTraitMedian	Median age of individuals in the cohort.
dataCompletion	CohortTraitMedian	Median percentage of completed data per patient.
overallSurvival	Nullable[CohortTraitMedian]	Median overall survival time in the cohort, if available.
genders	List[CohortTraitCounts]	Distribution of genders within the cohort.
neoplasticSites	List[CohortTraitCounts]	Distribution of neoplastic (tumor) sites in the cohort.
therapyLines	List[CohortTraitCounts]	Distribution of therapy lines received by patients in the cohort.
consentStatus	List[CohortTraitCounts]	Distribution of consent statuses for data use among cohort participants.

age class-attribute instance-attribute

consentStatus class-attribute instance-attribute

dataCompletion class-attribute instance-attribute

genders class-attribute instance-attribute

neoplasticSites class-attribute instance-attribute

overallSurvival class-attribute instance-attribute

therapyLines class-attribute instance-attribute

ExportedCohortDefinition

Bases: ExportMetadata

Represents an exported cohort definition along with its export metadata.

Attributes:

Name	Type	Description
definition	CohortCreateSchema	The cohort definition, including its title and description.

definition class-attribute instance-attribute

RulesetCondition

Bases: str, Enum

An enumeration representing logical conditions for rulesets.

Attributes:

Name	Type	Description
AND	str	Represents the logical 'and' condition.
OR	str	Represents the logical 'or' condition.

AND class-attribute instance-attribute

OR class-attribute instance-attribute

2025-10-172025-10-17runner