@platforma-sdk/model 1.40.0 → 1.40.5

package/dist/components/PlAnnotations/filter.d.ts

@@ -0,0 +1,213 @@
+import { SUniversalPColumnId } from '@milaboratories/pl-model-common';
+/**
+ * Represents an equals predicate for pattern filtering.
+ * Checks if the pattern exactly matches the provided value.
+ * Can handle both string literals and biological sequences with wildcards.
+ */
+export type PatternPredicateEquals = {
+    type: 'equals';
+    /** The exact pattern value to match */
+    value: string;
+};
+/**
+ * Represents a subsequence containment predicate for pattern filtering.
+ * Checks if the pattern contains the provided subsequence.
+ * Can handle both string literals and biological sequences with wildcards.
+ */
+export type PatternPredicateContainSubsequence = {
+    type: 'containSubsequence';
+    /** The subpattern to search for within the target pattern */
+    value: string;
+};
+/**
+ * Union type for pattern predicates that can be applied to both sequence and string data.
+ */
+export type PatternPredicate = PatternPredicateEquals | PatternPredicateContainSubsequence;
+/**
+ * Filter for pattern data, specifying the column to filter and the predicate to apply.
+ * Works with both biological sequences (with wildcards) and regular strings.
+ */
+export type PatternFilter = {
+    type: 'pattern';
+    /** The column identifier to apply the filter to */
+    column: SUniversalPColumnId;
+    /** The predicate defining the filtering logic */
+    predicate: PatternPredicate;
+};
+/**
+ * Transforms a column's values into their rank positions.
+ *
+ * Ranks start from 1 and represent the position of each value after sorting.
+ * When descending=true, higher values receive lower ranks (rank 1 is highest value).
+ * When descending=false (default), lower values receive lower ranks (rank 1 is lowest value).
+ *
+ * For multi-sample columns, ranking is performed independently within each sample.
+ *
+ * The ranked values can be used in numerical comparison filters.
+ */
+export type ValueRank = {
+    transformer: 'rank';
+    /** The column identifier to apply the ranking to */
+    column: SUniversalPColumnId;
+    /** If true, sorts highest values first (highest value gets rank 1) */
+    descending?: true;
+};
+/**
+ * Transforms a column's values into a running total after sorting.
+ *
+ * First sorts all values, then calculates the cumulative sum at each position.
+ * Enables filters like "select clonotypes that make up the top 10% of total abundance".
+ *
+ * For multi-sample columns, cumulative sums are calculated independently within each sample.
+ *
+ * The cumulative values can be used in numerical comparison filters.
+ */
+export type SortedCumulativeSum = {
+    transformer: 'sortedCumulativeSum';
+    /** The column identifier to apply the cumulative sum to */
+    column: SUniversalPColumnId;
+    /** If true, sorts values in descending order before calculating the cumulative sum */
+    descending?: true;
+};
+/**
+ * Transforms a column's values by applying the log10 function.
+ *
+ * Calculates the base-10 logarithm for each value in the specified column.
+ * This is useful for filtering based on log-fold changes.
+ *
+ * The log10-transformed values can be used in numerical comparison filters.
+ * Note: The behavior for non-positive input values (<= 0) results in -Infinity.
+ */
+export type Log10 = {
+    transformer: 'log10';
+    /** The column identifier to apply the log10 transformation to */
+    column: SUniversalPColumnId;
+};
+/**
+ * Represents a column whose values have been transformed by either ranking or
+ * cumulative summation. These transformations allow for more complex filtering
+ * operations such as "top N" or "first X%" queries.
+ * Any NA values are propagated to the transformed column, and ignored in ranks and cumulative sums.
+ */
+export type TransformedColumn = ValueRank | SortedCumulativeSum | Log10;
+/**
+ * Defines a numerical comparison between two values that can be column references or constants.
+ *
+ * If lhs or rhs is NA, the filter will always return false.
+ *
+ * The basic formula is: lhs + minDiff < rhs (or <= if allowEqual is true)
+ *
+ * Examples:
+ * - Compare two columns: columnA < columnB
+ * - Compare with threshold: abundance > 0.05
+ * - Compare with minimum difference: columnA + 10 < columnB
+ *
+ * Rules:
+ * - At least one side must reference a column or a transformed column (both sides cannot be constants)
+ * - The minDiff parameter can only be used when both sides are columns or transformed columns
+ * - Use allowEqual=true to include equality in the comparison (<=)
+ */
+export type NumericalComparisonFilter = {
+    type: 'numericalComparison';
+    /** The first column to compare (left side of comparison) */
+    lhs: SUniversalPColumnId | TransformedColumn | number;
+    /** The second column to compare (right side of comparison) */
+    rhs: SUniversalPColumnId | TransformedColumn | number;
+    /** The minimum difference between lhs and rhs values */
+    minDiff?: number;
+    /** Whether equality is permitted in the comparison */
+    allowEqual?: true;
+};
+/**
+ * Represents a filter that checks if a column's values are NA (not available).
+ * This filter is useful for filtering out records where a specific column has no value / clonotype is not present.
+ */
+export type IsNA = {
+    type: 'isNA';
+    /** The column identifier to check for NA values */
+    column: SUniversalPColumnId;
+};
+/**
+ * Represents a logical OR operation between multiple filters.
+ * A record matches if at least one of the contained filters matches.
+ */
+export interface OrFilter {
+    type: 'or';
+    /** Array of filters to combine with OR logic */
+    filters: AnnotationFilter[];
+}
+/**
+ * Represents a logical AND operation between multiple filters.
+ * A record matches only if all of the contained filters match.
+ */
+export interface AndFilter {
+    type: 'and';
+    /** Array of filters to combine with AND logic */
+    filters: AnnotationFilter[];
+}
+/**
+ * Represents a logical NOT operation on a filter.
+ * A record matches if it does not match the contained filter.
+ */
+export interface NotFilter {
+    type: 'not';
+    /** The filter to negate */
+    filter: AnnotationFilter;
+}
+/**
+ * Union type for all supported annotation filters.
+ */
+export type AnnotationFilter = IsNA | PatternFilter | NumericalComparisonFilter | OrFilter | AndFilter | NotFilter;
+/**
+ * Represents a single step in the annotation process.
+ * Each step consists of a filter to select records and a label to assign to those records.
+ */
+export type AnnotationStep = {
+    /** The filter to apply for selecting records */
+    filter: AnnotationFilter;
+    /** The label to assign to records that match the filter */
+    label: string;
+};
+/**
+ * Specifies which entity to annotate: either entire clonotypes or clonotypes within specific samples.
+ * This choice affects how filtering and labeling will be applied across your dataset.
+ */
+export type AnnotationMode = 
+/**
+ * Annotates entire clonotypes globally, regardless of which samples they appear in.
+ * A clonotype will either be fully included or excluded across all samples.
+ * The resulting column will have the following shape:
+ *   [clonotype_key] -> label
+ */
+'byClonotype'
+/**
+ * Annotates clonotypes independently within each sample.
+ * This allows sample-specific filtering, where a clonotype might be included in one sample
+ * but excluded in another (e.g., labe low-abundance occurrences that might be contamination
+ * while keeping the same clonotype where it has significant abundance).
+ * Usage of multi-sample columns (like abundances not constrained by specific sample) is only supported in this mode.
+ * The resulting column will have the following shape:
+ *   [sample_id, clonotype_key] -> label
+ */
+ | 'bySampleAndClonotype';
+/**
+ * Represents a complete annotation configuration.
+ * Contains a series of annotation steps that are applied in sequence.
+ * Annotations are applied from lower indices to higher indices (earlier steps are processed first),
+ * with later steps taking precedence when multiple steps match the same record.
+ */
+export type AnnotationScript = {
+    /** The title of the annotation */
+    title: string;
+    /** The mode of annotation to apply */
+    mode: AnnotationMode;
+    /** Ordered list of annotation steps to apply */
+    steps: AnnotationStep[];
+};
+export type AnnotationScript2<S extends AnnotationStep> = {
+    /** The mode of annotation to apply */
+    mode: AnnotationMode;
+    /** Ordered list of annotation steps to apply */
+    steps: S[];
+};
+//# sourceMappingURL=filter.d.ts.map

package/dist/components/PlAnnotations/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/components/PlAnnotations/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAK3E;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,QAAQ,CAAC;IACf,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kCAAkC,GAAG;IAC/C,IAAI,EAAE,oBAAoB,CAAC;IAC3B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,sBAAsB,GAAG,kCAAkC,CAAC;AAE3F;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,mBAAmB,CAAC;IAC5B,iDAAiD;IACjD,SAAS,EAAE,gBAAgB,CAAC;CAC7B,CAAC;AAMF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,MAAM,EAAE,mBAAmB,CAAC;IAC5B,sEAAsE;IACtE,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,qBAAqB,CAAC;IACnC,2DAA2D;IAC3D,MAAM,EAAE,mBAAmB,CAAC;IAC5B,sFAAsF;IACtF,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,mBAAmB,GAAG,KAAK,CAAC;AAExE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,4DAA4D;IAC5D,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,MAAM,CAAC;IACtD,8DAA8D;IAC9D,GAAG,EAAE,mBAAmB,GAAG,iBAAiB,GAAG,MAAM,CAAC;IACtD,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,EAAE,mBAAmB,CAAC;CAC7B,CAAC;AAMF;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,IAAI,CAAC;IACX,gDAAgD;IAChD,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,iDAAiD;IACjD,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,2BAA2B;IAC3B,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,aAAa,GAAG,yBAAyB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAMnH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,gDAAgD;IAChD,MAAM,EAAE,gBAAgB,CAAC;IACzB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,cAAc;AACxB;;;;;GAKG;AACD,aAAa;AACf;;;;;;;;GAQG;GACD,sBAAsB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,cAAc,IAAI;IACxD,sCAAsC;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ,CAAC"}