Models

Each model maps to a resource in the One Codex API:

A Samples record is a sequencing file you have uploaded, along with its Metadata.
A Jobs record is something that can be run against a sample – either a built-in One Codex analysis or a custom workflow you have defined yourself.
Running a job on a sample produces an Analyses record, which links back to both.
Each type of job produces a specific type of analysis, with its own model and its own fields: a classification job produces a Classifications, an alignment job an Alignments, and likewise for FunctionalProfiles, Panels and Mlsts. Query Analyses directly, filtering on analysis_type, when you want a sample’s analyses regardless of type.
A custom, user-defined job produces a Workflows record. Reference data those jobs depend on is uploaded as Assets.

Every model inherits from OneCodexBase, which provides the shared .get(), .all() and .where() methods. See Querying for the operators .where() accepts.

Core Models

`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`

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.

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.

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.

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.

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.

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.

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, job_type: str | None = None, 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.

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.

Analysis Results

`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.

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.

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.

`Classifications`

class onecodex.models.analysis.Classifications(*, 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], results_uri: str | None = None)

Bases: _AnalysesBase, ClassificationSchema

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) → dict | pd.DataFrame

Return the complete results table for a classification.

Parameters

jsonbool, optional: Return result as JSON? Default True.

Returns

tabledict or pd.DataFrame: Return a JSON object with the classification results or a pd.DataFrame if json=False.

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.

table() → pd.DataFrame

Return the complete results table for the classification.

Returns

tablepd.DataFrame: A Pandas DataFrame of the classification results.

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.

Query classifications and return a SampleCollection.

Classifications are taxonomic results — typically the One Codex Database run against each sample. Filters mirror those on Analyses.where().

Examples

Find recent successful classifications:

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

Find the classification for a specific sample:

cls_run = ocx.Classifications.where(sample=sample)[0]

See Querying for the full operator reference.

`FunctionalProfiles`

class onecodex.models.analysis.FunctionalProfiles(*, 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], results_uri: str | None = None)

Bases: _AnalysesBase, FunctionalRunSchema

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.

filtered_table(annotation: FunctionalAnnotations, metric: FunctionalAnnotationsMetric, taxa_stratified: bool = True)

Return a results table for the functional analysis.

Parameters

annotationonecodex.lib.enum.FunctionalAnnotation, required: Return a table for a given onecodex.lib.enum.FunctionalAnnotation
metriconecodex.lib.enum.FunctionalAnnotationMetric, required: Return a table for a given onecodex.lib.enum.FunctionalAnnotationMetric
taxa_stratifiedbool, optional: If False, return data only by annotation ID, ignoring taxonomic stratification

Returns

results_dfpd.DataFrame: A Pandas DataFrame of the functional results.

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)

Return the complete results table for a functional analysis.

Parameters

jsonbool, optional: Return result as JSON? Default True.

Returns

tabledict or pd.DataFrame: Return a JSON object with the functional analysis results or a pd.DataFrame if json=False.

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.

table(annotation: FunctionalAnnotations | None = None, taxa_stratified: bool = True, metric: FunctionalAnnotationsMetric | Literal['all'] | str = 'all')

Return a results table for the functional analysis.

Parameters

annotation{None, onecodex.lib.enum.FunctionalAnnotation}, optional: If None, return a table with all annotations, otherwise filter to one of onecodex.lib.enum.FunctionalAnnotation
metricFunctionalAnnotationsMetric | ‘all’: ‘all’ preserves backwards compatibility, returning all metrics types (e.g., cpm + rpk) for a given functional profile, otherwise table() will filter to the provided metric.
taxa_stratifiedbool, optional: If False, return data only by annotation ID, ignoring taxonomic stratification

Returns

results_dfpd.DataFrame: A Pandas DataFrame of the functional results.

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.

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.

`Panels`

class onecodex.models.analysis.Panels(*, 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, PanelSchema

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=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.

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.

`Mlsts`

class onecodex.models.analysis.Mlsts(*, 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, MlstSchema

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=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.

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.

Custom Workflows

`Workflows`

class onecodex.models.analysis.Workflows(*, 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, WorkflowSchema

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=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.

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.

`Assets`

class onecodex.models.misc.Assets(*, 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)], name: str, filename: str, size: int | None = None, status: str, uploader: Users | ApiRef)

Bases: OneCodexBase, AssetSchema, 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, name=None)

Upload a file to an asset.

Parameters

file_pathstring: A path to a file on the system.
progressbarclick.progressbar, optional: If passed, display a progress bar using Click.
namestring, optional: If passed, name is sent with upload request and is associated with asset.

Returns

An Assets object upon successful upload. None if the upload failed.

Query assets.

Assets are reusable inputs to custom jobs — reference databases, index files, anything you want available at job run time. Shared with everyone in your organization.

Examples

Find assets by name:

ocx.Assets.where(name={"$icontains": "kraken"})

Find only assets ready to use (status="available"):

ocx.Assets.where(status="available")

See Querying for the full operator reference.

Models

Core Models

OneCodexBase

Raises

Raises

Raises

Raises

Parameters

Examples

Returns

Samples

Raises

Raises

Parameters

Raises

Parameters

Returns

Examples

Parameters

Returns

Notes

Metadata

Raises

Raises

Raises

Raises

Examples

Projects

Raises

Raises

Raises

Raises

Examples

Tags

Raises

Raises

Raises

Raises

Examples

Users

Raises

Raises

Raises

Raises

Documents

Raises

Raises

Raises

Raises

Parameters

Returns

Examples

Jobs

Raises

Raises

Raises

Raises

Examples

Analysis Results

Analyses

Parameters

Returns

Raises

Raises

Raises

Raises

Parameters

Returns

Notes

Returns

Parameters

Returns

Parameters

Returns

Raises

Raises

Examples

Alignments

Parameters

Returns

`OneCodexBase`

`Samples`

`Metadata`

`Projects`

`Tags`

`Users`

`Documents`

`Jobs`

`Analyses`

`Alignments`

`Classifications`

`FunctionalProfiles`

`Panels`