Source: https://docs.nygen.io/CyteArc/api/utilities.html
Revision: fccee7b6e0c167e47ce605c8d292fba5b567ebfe

Utilities API reference
***********************

For dataset discovery, remote exploration, and example downloads, see
CyteBase API reference.


Store and computation helpers
=============================

cytearc.load_zarr(zarr_loc, mode, storage_options=None, *, source_storage_options=None)

   Open a Zarr group through the compatibility entry point.

   Return type:
      "Group"

cytearc.controlled_compute(arr, nthreads)

   Materialize a deferred array with a bounded thread count.

   Return type:
      "ndarray"

cytearc.read_gmt(path)

   Read gene sets from a tab-separated GMT file.

   The first field is used as the source name, the second description
   field is ignored, and each remaining non-empty field becomes one
   target row.

   Parameters:
      **path** ("str" | "PathLike"["str"]) – Path to a GMT file with
      at least three fields per non-empty line.

   Return type:
      "DataFrame"

   Returns:
      A DataFrame with "source" and "target" columns.


Logging and progress
====================

CyteArc starts with "INFO" logs and progress enabled, without
timestamps. Notebook sessions do not need an output setup call. For a
batch pipeline, configure the independent settings once at startup:

   cytearc.configure_output(progress=False, timestamps=True)

Arguments that are omitted retain their current values.
"configure_output" is the primary runtime interface:

* "level" controls CyteArc’s log severity.

* "progress" controls progress bars, including
  "compute_with_progress".

* "timestamps" controls timestamps in CyteArc’s installed log sink.

Progress is independent of log level. Setting a quiet level such as
"WARNING" does not disable progress. Call
"configure_output(progress=False)" to suppress progress bars.
Interactive notebooks animate these bars. The documentation shows
deterministic completed snapshots from the committed notebook cache
instead of replaying an animation.

cytearc.configure_output(*, level=None, progress=None, timestamps=None)

   Configure CyteArc’s logging and progress output.

   Unspecified settings retain their current values.

   Return type:
      "None"

cytearc.set_verbosity(level=None, filepath=None)

   Set CyteArc’s logging level and optional output file.

   Return type:
      "None"

"set_verbosity(level=..., filepath=...)" remains the interface for
selecting a log level and optional file destination. Use it when a
durable batch log is needed; use "configure_output" for ordinary
notebook and console behavior.

cytearc.logger

   CyteArc’s *loguru* logger. Library code logs through this object,
   so "cytearc.configure_output()" controls the CyteArc-owned sink
   while preserving sinks added by callers.

cytearc.tqdmbar(*args, **kwargs)

   Create a progress bar using CyteArc’s display defaults.

   Return type:
      "Any"

cytearc.tqdm_params

   Default keyword arguments applied by "cytearc.tqdmbar()", including
   bar format, dynamic width, and colour. Override any of them per
   call.

cytearc.compute_with_progress(arr, msg=None, nthreads=1)

   Materialize a deferred array while reporting progress.

   Return type:
      "ndarray"


Array helpers
=============

These operate on plain arrays and are used by CyteArc’s own
embeddings, graph construction, trajectory dynamics, and merge code.

cytearc.clean_array(x, fill_val=0)

   Replace non-finite and zero values in a numeric array.

   Return type:
      "NDArray"["Any"]

cytearc.rescale_array(a, frac=0.9)

   Trim extreme values using a fitted normal distribution.

   Return type:
      "ndarray"

cytearc.rolling_window(a, w)

   Apply a centered rolling mean along the first axis.

   Return type:
      "ndarray"

cytearc.permute_into_chunks(size, chunk_size, seed=42)

   Split sequential indices into independently permuted chunks.

   Return type:
      "list"["ndarray"]