Collector API

The collector package provides the DuckDB-backed implementation used by the default Nextflow locus-breaker and locus-collection workflows.

Command surface

Tool for collecting and merging parquet files into a single output file.

Locus breaker

Collector-native LocusBreaker command surface.

class collector.locus_breaker.LocusBreakerConfig(*, lbc_baseline_pvalue: Annotated[float, Gt(gt=0)] = 1e-05, lbc_distance_cutoff: Annotated[int, Gt(gt=0)] = 250000, lbc_pvalue_threshold: Annotated[float, Gt(gt=0)] = 1e-08, lbc_flanking_distance: Annotated[int, Ge(ge=0)] = 100000, large_loci_size: Annotated[int, Gt(gt=0)] = 1500000, wbc_clump_distance: Annotated[int, Gt(gt=0)] = 500000, wbc_pvalue_threshold: Annotated[float, Gt(gt=0)] = 1e-05, collect_locus: bool = True, remove_mhc: bool = True)

Parameters exposed by the collector locus_breaker command.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

collector.locus_breaker.run_locus_breaker(input_path: Path, output_path: Path, config: LocusBreakerConfig) → None

Run the LocusBreaker command.

collector.locus_breaker.split_pvalue(pvalue: float) → tuple[float, int]

Split a p-value into Gentropy-compatible mantissa and exponent.

Canonical regions

Canonical-region collector input validation and bounded region sweep.

class collector.canonical_regions.CollectCanonicalRegionsConfig(*, run_id: Annotated[str, MinLen(min_length=1)], locus_breaker_paths: tuple[Path, ...], ancestries: tuple[str, ...], summary_statistics_paths: tuple[Path, ...], fine_mapping_locus_set_output_dir: Path, stats_parquet_output: Path, stats_json_output: Path, canonical_region_min_maf: Annotated[float, Ge(ge=0), Lt(lt=0.5)] = 0.01, canonical_region_max_region_span_bp: Annotated[int, Ge(ge=1)] = 3000000)

Path and cardinality contract for the collect_canonical_regions command.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

collector.canonical_regions.run_collect_canonical_regions(config: CollectCanonicalRegionsConfig) → tuple[CanonicalRegionInput, ...]

Validate inputs, sweep bounded canonical regions, and emit provisional outputs.

Schema contracts

Schema contracts for collector-produced datasets.

class collector.schema.DatasetField(*, name: str, duckdb_type: Literal['VARCHAR', 'INTEGER', 'DOUBLE', 'FLOAT', 'BOOLEAN'] | str | ListSchema, nullable: bool = True)

A top-level dataset field.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

null_select_sql() → str

Return a typed NULL select expression for schema-only writes.

sql_type() → str

Return this field’s DuckDB SQL type.

class collector.schema.DatasetSchema(*, fields: tuple[DatasetField, ...])

Ordered top-level schema for a collector dataset.

property column_names: tuple[str, ...]

Return column names in schema order.

empty_select_sql() → str

Return a DuckDB SELECT statement with no rows and this schema.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class collector.schema.ListSchema(*, item_schema: StructSchema)

Ordered list schema for repeated nested Parquet fields.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sql_type() → str

Return a DuckDB list type expression.

class collector.schema.StructSchema(*, fields: tuple[SchemaField, ...])

Ordered struct schema used inside nested Parquet fields.

property field_names: tuple[str, ...]

Return field names in schema order.

model_config = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sql_type() → str

Return a DuckDB STRUCT type expression.