OneCodexBase

class onecodex.models.base.OneCodexBase(**data)

Bases: BaseModel

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': True, 'extra': 'allow', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters, **keyword_filters) → MutableSequence[Self]

Filter model records of this type from the One Codex server.

Every OneCodex model implements this method. The operators below are shared, but the fields you may filter on and the type returned vary by model – see that model’s own where() for its specifics, and Querying for the full operator reference.

Parameters

filtersstr or dict

One or more record IDs to fetch, or a single dict giving a raw query to pass through to the server. Any other combination raises NotImplementedError.

sortstr or list, optional

Sort the results by this field (or list of fields). By default in descending order, but if any of the fields start with the special character ^, sort in ascending order. For example, sort=[‘size’, ‘^filename’] will sort by size from largest to smallest and filename from A-Z for items with the same size.

limitint, optional

Number of records to return. For smaller searches, this can reduce the number of network requests made.

filtercallable, optional

Filter the fetched records locally, keeping those for which this returns a truthy value.

keyword_filtersstr or object

Filter the results server-side by field value, either a literal to match or an operator dict such as {"$icontains": "qc"}. Most models declare the fields they accept explicitly and reject anything else.

Examples

You can filter objects that are returned locally using a lambda function

All models implement the same method. To see a complete list of models which can be retrieved by ID, see the models page.

# Filter samples by filename
my_samples = Samples.where(filter=lambda s: s.filename.endswith('.gz'))

# Filter classifications by completion status
completed = Classifications.where(filter=lambda c: c.complete == True)

# Filter projects by name
my_projects = Projects.where(filter=lambda p: 'test' in p.name)

Returns

MutableSequence

Every record matching these filters, or all records if no filters are passed. Usually a list, but some models return a specialized collection instead – Samples and Classifications both return a SampleCollection.

Note: this is a base class that is not meant to be instantiated directly. See this class’s documentation for details about common methods such as .where, .all and .get which are used by the models listed below.

Samples

class onecodex.models.sample.Samples(*, field_uri: str, created_at: datetime, error_msg: str | None = None, filename: str | None = None, metadata: Metadata | ApiRef, owner: Users | ApiRef, primary_classification: Classifications | ApiRef | None = None, project: Projects | ApiRef | None = None, size: int | None = None, tags: List[Tags | ApiRef] = [], status: str, visibility: str, updated_at: datetime | None = None)

Bases: OneCodexBase, _SampleSchema, ResourceDownloadMixin

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

classmethod preupload(metadata=None, tags=None, project=None)

Create a sample in a waiting state where the files will be sent later on.

Parameters

metadata : dict, optional

tagslist, optional

A list of optional tags to create. Tags must be passed as dictionaries with a single key name and the tag name, e.g., {“name”: “my tag”}. New tags will be created on-the-fly as needed.

projectstring, optional

UUID of project to associate this sample with.

save()

Send changes on this Samples object to the One Codex server.

Changes to the metadata object and tags list are passed as well.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod upload(files, metadata=None, tags=None, project=None, coerce_ascii=False, progressbar=None, sample_id=None, external_sample_id=None)

Upload a series of files to the One Codex server.

Parameters

filesstring or tuple

A single path to a file on the system, or a tuple containing a pairs of paths. Tuple values will be interleaved as paired-end reads and both files should contain the same number of records. Paths to single files will be uploaded as-is.

metadata : dict, optional

tagslist, optional

A list of optional tags to create. Tags must be passed as dictionaries with a single key name and the tag name, e.g., {“name”: “my tag”}. New tags will be created on-the-fly as needed.

projectstring, optional

UUID of project to associate this sample with.

coerce_asciibool, optional

If true, rename unicode filenames to ASCII and issue warning.

progressbarclick.progressbar, optional

If passed, display a progress bar using Click.

sample_idstring, optional

If passed, will upload the file(s) to the sample with that id. Only works if the sample was pre-uploaded

external_sample_idstring, optional

If passed, will upload the file(s) to the sample with that metadata external id. Only works if the sample was pre-uploaded

Returns

A Samples object upon successful upload. None if the upload failed.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, organization: bool = False, filter: Any = None, tags: list[str | Tags] | Tags | str | None = None, tax_ids: list[str] | None = None, created_at: datetime | DatetimeFilter = UNSET, updated_at: datetime | DatetimeFilter = UNSET, filename: str | StrFilter | None = UNSET, error_msg: str | StrFilter | None = UNSET, size: int | NumFilter | None = UNSET, status: str | EnumStrFilter = UNSET, visibility: str | EnumStrFilter = UNSET, metadata: Metadata | str | RefFilter = UNSET, owner: Users | str | RefFilter = UNSET, project: Projects | str | RefFilter | None = UNSET, **keyword_filters: Any) → SampleCollection

Query samples and return a SampleCollection.

Samples are the uploaded sequencing files (FASTA/FASTQ). Filter by any sample field, by metadata field (transparently joined), or by tags.

Examples

Find your recent FASTQ uploads:

from datetime import datetime, timedelta, timezone
since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
ocx.Samples.where(
    created_at={"$gte": since},
    filename={"$iendswith": ".fastq.gz"},
)

Filter by tag (resolved by name, id, or Tags instance):

ocx.Samples.where(tags=["trimmed", "human-depleted"])

Filter by tax ids (returns samples containing all the listed taxa - having one or more cumulative reads as measured by Metric.ReadcountWChildren):

ocx.Samples.where(tax_ids=["543", "590"])

Filter by a metadata field — transparently joined:

ocx.Samples.where(platform="Illumina NovaSeq 6000")

Search public or organization-shared samples:

ocx.Samples.where(filename={"$icontains": "hmp"}, public=True)
ocx.Samples.where(organization=True)

Apply a client-side predicate after fetching:

ocx.Samples.where(filter=lambda s: not s.tags)

Parameters

organization

Search samples shared across your organization. Mutually exclusive with public.

public

Search public samples (capped at 1000 results). Mutually exclusive with organization.

tags

Tags to filter by. Accepts Tags instances, tag ids, or tag names — all resolved to refs and combined with $containsall.

tax_ids

Taxonomy ids (as str) to filter by. Only samples containing every listed taxon are returned.

Returns

SampleCollection

Notes

Metadata custom fields aren’t server-filterable — filter client-side via SampleCollection.filter().

See Querying for the full operator reference.

Metadata

class onecodex.models.sample.Metadata(*, field_uri: str, custom: dict[str, Any] | None = {}, date_collected: datetime | None = None, date_sequenced: datetime | None = None, description: str | None = None, external_sample_id: str | None = None, library_type: str | None = None, location_lat: Annotated[float | None, Ge(ge=-90.0), Le(le=90.0)] = None, location_lon: Annotated[float | None, Ge(ge=-180), Le(le=180)] = None, location_string: Annotated[str | None, MaxLen(max_length=255)] = None, name: Annotated[str | None, MaxLen(max_length=255)] = None, platform: str | None = None, sample_type: str | None = None, sample: Samples | ApiRef, starred: bool = False, updated_at: datetime | None = None)

Bases: OneCodexBase, _MetadataSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, updated_at: datetime | DatetimeFilter | None = UNSET, date_collected: datetime | DatetimeFilter | None = UNSET, date_sequenced: datetime | DatetimeFilter | None = UNSET, description: str | StrFilter | None = UNSET, external_sample_id: str | StrFilter | None = UNSET, library_type: str | EnumStrFilter | None = UNSET, location_lat: float | NumFilter | None = UNSET, location_lon: float | NumFilter | None = UNSET, location_string: str | StrFilter | None = UNSET, name: str | StrFilter | None = UNSET, platform: str | EnumStrFilter | None = UNSET, sample_type: str | EnumStrFilter | None = UNSET, starred: bool | BoolFilter = UNSET, sample: Samples | str | RefFilter = UNSET) → list[Self]

Query sample metadata.

Metadata holds per-sample structured fields — sequencing platform, sample type, collection date, lat/lon, plus an arbitrary custom dict. Only metadata for samples you own is queryable; public and organization-shared samples cannot be searched by metadata field.

Examples

Find metadata by collection date:

from datetime import datetime, timedelta, timezone
cutoff = (datetime.now(timezone.utc) - timedelta(days=30)).isoformat()
ocx.Metadata.where(date_collected={"$gte": cutoff})

Find by external (e.g. LIMS) ID:

md = ocx.Metadata.where(external_sample_id="LIMS-12345")[0]

custom is not server-filterable. Fetch a broader set and filter in Python:

ocx.Samples.where(...).filter(lambda s: s.metadata.custom.get("lab") == "X")

See Querying for the full operator reference.

Projects

class onecodex.models.misc.Projects(*, field_uri: str, description: str | None = None, external_id: str | None = None, name: str | None = None, owner: Users | ApiRef, permissions: list[str], project_name: Annotated[str | None, MinLen(min_length=3), MaxLen(max_length=15), _PydanticGeneralMetadata(pattern='^[a-zA-Z0-9_-]{3,15}$')], public: bool = False)

Bases: OneCodexBase, ProjectSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, name: str | StrFilter | None = UNSET, project_name: str | StrFilter | None = UNSET, description: str | StrFilter | None = UNSET, external_id: str | StrFilter | None = UNSET, owner: Users | str | RefFilter | None = UNSET) → list[Self]

Query projects.

Projects group related samples. Set public=True to search across all public projects on One Codex.

Examples

Find a project by exact name:

proj = ocx.Projects.where(name="HMP Phase II")[0]

Find public projects containing a keyword:

ocx.Projects.where(name={"$icontains": "gut"}, public=True)

See Querying for the full operator reference.

Tags

class onecodex.models.misc.Tags(*, field_uri: str | None = None, name: Annotated[str, MaxLen(max_length=30)])

Bases: OneCodexBase, TagSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, name: str | StrFilter = UNSET) → list[Self]

Query tags.

Tags are short labels attached to samples for organizing and filtering them.

Examples

Find a tag by exact name:

tag = ocx.Tags.where(name="trimmed")[0]

Find tags containing a substring:

ocx.Tags.where(name={"$icontains": "qc"})

See Querying for the full operator reference.

Users

class onecodex.models.misc.Users(*, field_uri: str, email: str | None)

Bases: OneCodexBase, UserSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, email: str | EqStrFilter | None = UNSET) → list[Self]

Query users.

Users are account holders in your organization.

See Querying for the full operator reference.

Documents

class onecodex.models.misc.Documents(*, field_uri: str, created_at: Annotated[datetime, PlainSerializer(func=rfc3339_encoder, return_type=str, when_used=always), BeforeValidator(func=rfc3339_decoder, json_schema_input_type=PydanticUndefined)], filename: str, size: int | None = None, uploader: Users | ApiRef, downloaders: List[Users | ApiRef] = [])

Bases: OneCodexBase, DocumentSchema, ResourceDownloadMixin

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod upload(file_path, progressbar=None)

Upload a series of files to the One Codex server.

Parameters

file_pathstring

A path to a file on the system.

progressbarclick.progressbar, optional

If passed, display a progress bar using Click.

Returns

A Documents object upon successful upload. None if the upload failed.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, created_at: datetime | DatetimeFilter = UNSET, filename: str | StrFilter = UNSET, size: int | NumFilter | None = UNSET, uploader: Users | str | RefFilter = UNSET) → list[Self]

Query documents.

Documents are arbitrary files (PDFs, spreadsheets, etc.) uploaded to your account, optionally shared with other users.

Examples

Find documents uploaded since a date:

from datetime import datetime, timedelta, timezone
since = (datetime.now(timezone.utc) - timedelta(days=7)).isoformat()
ocx.Documents.where(created_at={"$gte": since})

Find documents larger than 10 MB:

ocx.Documents.where(size={"$gte": 10 * 1024 * 1024})

Find documents uploaded by a specific user:

ocx.Documents.where(uploader=user)

See Querying for the full operator reference.

Jobs

class onecodex.models.misc.Jobs(*, field_uri: str, created_at: ~typing.Annotated[~datetime.datetime, ~pydantic.functional_serializers.PlainSerializer(func=~onecodex.models.schemas.types.rfc3339_encoder, return_type=str, when_used=always), ~pydantic.functional_validators.BeforeValidator(func=~onecodex.models.schemas.types.rfc3339_decoder, json_schema_input_type=PydanticUndefined)], name: str, job_args_schema: dict[str, ~typing.Any] = <factory>, analysis_type: str, public: bool, draft: bool)

Bases: OneCodexBase, JobSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

details() → JobDetails

Fetch the job’s detail fields and return them as a JobDetails.

Includes script, image_uri, cpu, ram_gb, storage_gb, repository, assets, dependencies, and arguments_schema. Only available for user-created jobs the current user has permission to view the details of.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, created_at: datetime | DatetimeFilter = UNSET, name: str | StrFilter = UNSET, analysis_type: str | StrFilter = UNSET) → list[Self]

Query jobs.

Jobs are runnable workflows — both built-in (e.g. classification) and custom (Nextflow pipelines, shell scripts). Use public=True to include One Codex’s built-in jobs and any other public custom jobs in addition to your own.

Examples

Find your custom jobs by name:

ocx.Jobs.where(name={"$icontains": "amplicon"})

Find all classification-type jobs (yours + public):

ocx.Jobs.where(analysis_type="classification", public=True)

See Querying for the full operator reference.

Analyses

class onecodex.models.analysis.Analyses(*, field_uri: str, created_at: Annotated[datetime, PlainSerializer(func=rfc3339_encoder, return_type=str, when_used=always), BeforeValidator(func=rfc3339_decoder, json_schema_input_type=PydanticUndefined)], updated_at: rfc3339_decoder, json_schema_input_type=PydanticUndefined), FieldInfo(annotation=NoneType, required=True, json_schema_extra={'format': 'date-time'})] | None = None, complete: bool = False, error_msg: str | None = None, job: Jobs | ApiRef, job_args: dict[str, Any] = {}, sample: Samples | ApiRef, success: bool | None = False, cost: CostSchema | None, draft: bool, dependencies: list[BaseAnalysisSchema] | list[ApiRef], analysis_type: str)

Bases: _AnalysesBase, AnalysisSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

await_completion(timeout: float | None = None, initial_interval: int = 5, max_interval: int = 120, backoff: float = 1.5) → _AnalysesBase

Poll the API until the analysis reaches a terminal state.

An analysis is considered terminal when complete is True. The method refreshes self in place and returns it.

Parameters

timeoutfloat, optional

Maximum number of seconds to wait. None (default) waits indefinitely.

initial_intervalint, optional

Seconds to wait between the first polls. Must be at least MIN_POLL_INTERVAL_SECONDS (5). Defaults to 5.

max_intervalint, optional

Upper bound on the polling interval as it backs off. Must be at least MIN_POLL_INTERVAL_SECONDS (5). Defaults to 120 seconds.

backofffloat, optional

Multiplier applied to the interval after each poll. Defaults to 1.5.

Returns

self : the analysis, refreshed to its terminal state.

Raises

TimeoutError

If timeout elapses before the analysis completes.

cancel() → Self

Cancel an in-progress analysis.

Only in-progress Custom Workflows may be canceled. The cancellation process is asynchronous.

Raises

OneCodexException

When an analysis cannot be canceled, contains the underlying issue in the message.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

download_file(filepath: str | FileDetailSchema, out_path: str | None = None, out_file_obj: IO | None = None, progressbar: bool = False) → str

Download analysis result file.

Parameters

filepath: str or FileDetailSchema

Must be one of objects or filepathes returned by get_files

out_path: string, optional

Full path to save the file to. If omitted, defaults to the original filename in the current working directory.

out_file_obj: file-like object, optional

Rather than save the file to a out_path, write it to this file-like object.

progressbar: bool, optional

Display a progress bar using Click for the download?

Returns

string

The path the file was downloaded to, if applicable. Otherwise, None.

Notes

Existing paths will not be overwritten.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

get_files() → List[FileDetailSchema]

Fetch the files details of an Analyses.

Returns

A list of FileDetailSchema

logs(tail: int | None = None) → str

Fetch the job run logs for this analysis.

Parameters

tailint, optional

If set, return only the last tail lines of the logs. Must be >= 1.

Returns

str

The job run logs as a plain-text string. Empty if the analysis has not produced any logs.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

refresh() → None

Fetch the current state from the API and update this object’s state fields in-place.

results(json: bool = True)

Fetch the results of an Analyses resource.

Parameters

jsonbool, optional

Return a JSON result (raw API result)? Default True.

Returns

Return type varies by Analyses resource sub-type. See, e.g., Classifications or Panels for documentation.

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, created_at: datetime | DatetimeFilter = UNSET, updated_at: datetime | DatetimeFilter = UNSET, complete: bool | BoolFilter = UNSET, draft: bool | BoolFilter = UNSET, success: bool | BoolFilter = UNSET, error_msg: str | StrFilter | None = UNSET, analysis_type: str | StrFilter = UNSET, job: Jobs | str | RefFilter = UNSET, sample: Samples | str | RefFilter = UNSET, **keyword_filters: Any) → list[Self]

Query analyses.

An analysis is the result of running a job on a sample. Use this when you want results across analysis types (classifications, panels, functional profiles, etc.); for a single type, prefer the dedicated subclass (e.g. Classifications).

Examples

Find completed analyses since yesterday:

from datetime import datetime, timedelta, timezone
since = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
ocx.Analyses.where(complete=True, created_at={"$gte": since})

Find failed analyses (terminal but unsuccessful):

ocx.Analyses.where(complete=True, success=False)

Find all analyses for a given sample:

ocx.Analyses.where(sample=sample)

See Querying for the full operator reference.

Alignments

class onecodex.models.analysis.Alignments(*, field_uri: str, created_at: Annotated[datetime, PlainSerializer(func=rfc3339_encoder, return_type=str, when_used=always), BeforeValidator(func=rfc3339_decoder, json_schema_input_type=PydanticUndefined)], updated_at: rfc3339_decoder, json_schema_input_type=PydanticUndefined), FieldInfo(annotation=NoneType, required=True, json_schema_extra={'format': 'date-time'})] | None = None, complete: bool = False, error_msg: str | None = None, job: Jobs | ApiRef, job_args: dict[str, Any] = {}, sample: Samples | ApiRef, success: bool | None = False, cost: CostSchema | None, draft: bool, dependencies: list[BaseAnalysisSchema] | list[ApiRef])

Bases: _AnalysesBase, AlignmentSchema

classmethod all(sort=None, limit=None) → MutableSequence[Self]

Return every record of this model.

See where for details on the sort and limit arguments.

await_completion(timeout: float | None = None, initial_interval: int = 5, max_interval: int = 120, backoff: float = 1.5) → _AnalysesBase

Poll the API until the analysis reaches a terminal state.

An analysis is considered terminal when complete is True. The method refreshes self in place and returns it.

Parameters

timeoutfloat, optional

Maximum number of seconds to wait. None (default) waits indefinitely.

initial_intervalint, optional

Seconds to wait between the first polls. Must be at least MIN_POLL_INTERVAL_SECONDS (5). Defaults to 5.

max_intervalint, optional

Upper bound on the polling interval as it backs off. Must be at least MIN_POLL_INTERVAL_SECONDS (5). Defaults to 120 seconds.

backofffloat, optional

Multiplier applied to the interval after each poll. Defaults to 1.5.

Returns

self : the analysis, refreshed to its terminal state.

Raises

TimeoutError

If timeout elapses before the analysis completes.

cancel() → Self

Cancel an in-progress analysis.

Only in-progress Custom Workflows may be canceled. The cancellation process is asynchronous.

Raises

OneCodexException

When an analysis cannot be canceled, contains the underlying issue in the message.

classmethod create(**kwargs)

Create a new record of this model and return it.

Raises

MethodNotSupported

If this model does not support creation.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for creation.

delete() → bool

Delete this record, returning True if it was deleted.

Raises

MethodNotSupported

If this model does not support deletion, or if this record has not been saved yet.

download_file(filepath: str | FileDetailSchema, out_path: str | None = None, out_file_obj: IO | None = None, progressbar: bool = False) → str

Download analysis result file.

Parameters

filepath: str or FileDetailSchema

Must be one of objects or filepathes returned by get_files

out_path: string, optional

Full path to save the file to. If omitted, defaults to the original filename in the current working directory.

out_file_obj: file-like object, optional

Rather than save the file to a out_path, write it to this file-like object.

progressbar: bool, optional

Display a progress bar using Click for the download?

Returns

string

The path the file was downloaded to, if applicable. Otherwise, None.

Notes

Existing paths will not be overwritten.

classmethod get(id: str) → Self | None

Fetch a single record by its ID.

Returns None if the record does not exist or you do not have access to it.

get_files() → List[FileDetailSchema]

Fetch the files details of an Analyses.

Returns

A list of FileDetailSchema

logs(tail: int | None = None) → str

Fetch the job run logs for this analysis.

Parameters

tailint, optional

If set, return only the last tail lines of the logs. Must be >= 1.

Returns

str

The job run logs as a plain-text string. Empty if the analysis has not produced any logs.

model_config = {'arbitrary_types_allowed': False, 'extra': 'ignore', 'populate_by_alias': True}

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

refresh() → None

Fetch the current state from the API and update this object’s state fields in-place.

results(json: bool = True)

Fetch the results of an Analyses resource.

Parameters

jsonbool, optional

Return a JSON result (raw API result)? Default True.

Returns

Return type varies by Analyses resource sub-type. See, e.g., Classifications or Panels for documentation.

save()

Persist this record, creating it if it has not been saved before.

Raises

MethodNotSupported

If this model does not support the underlying create or update.

OneCodexException

If the server rejects the request.

update(**kwargs)

Update this record on the server.

Fields to change may be passed as keyword arguments. With no arguments, any attributes modified locally since this record was fetched are sent instead.

Raises

MethodNotSupported

If this model does not support updates, or if one of the given fields is not updatable.

OneCodexException

If the server rejects the request.

pydantic.ValidationError

If the keyword arguments do not match the schema this model declares for updates.

classmethod where(*filters: str | dict, sort: str | list[str] | None = None, limit: int | None = None, public: bool = False, filter: Any = None, created_at: datetime | DatetimeFilter = UNSET, updated_at: datetime | DatetimeFilter = UNSET, complete: bool | BoolFilter = UNSET, draft: bool | BoolFilter = UNSET, success: bool | BoolFilter = UNSET, error_msg: str | StrFilter | None = UNSET, analysis_type: str | StrFilter = UNSET, job: Jobs | str | RefFilter = UNSET, sample: Samples | str | RefFilter = UNSET, **keyword_filters: Any) → list[Self]

Query analyses.

An analysis is the result of running a job on a sample. Use this when you want results across analysis types (classifications, panels, functional profiles, etc.); for a single type, prefer the dedicated subclass (e.g. Classifications).

Examples

Find completed analyses since yesterday:

from datetime import datetime, timedelta, timezone
since = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
ocx.Analyses.where(complete=True, created_at={"$gte": since})

Find failed analyses (terminal but unsuccessful):

ocx.Analyses.where(complete=True, success=False)

Find all analyses for a given sample:

ocx.Analyses.where(sample=sample)

See Querying for the full operator reference.