coniferest.session package

coniferest.session package#

class coniferest.session.Session(data, metadata, decision_callback=<function prompt_decision_callback>, *, on_refit_callbacks=None, on_decision_callbacks=None, known_labels: Dict[int, ~coniferest.label.Label]=None, model: Coniferest = None)[source]#

Bases: object

Active anomaly detection session

Parameters:

  • data (array-like, shape (n_samples, n_features), dtype is number) – 2-D array of data points

  • metadata (array-like, shape (n_samples,), dtype is any) – 1-D array of metadata for each data point

  • decision_callback (callable, optional) – Function to be called when expert decision is required, it must return Label object with the decision and may terminate the session via Session.terminate(). Default is prompt_decision_callback Signature: ‘(metadata, data, session) -> Label’, where metadata is metadata of the object to be labeled, data is data of the object to be labeled, session is this session instance.

  • on_refit_callbacks (list of callable, or callable, or None, optional) – Functions to be called when model is refitted (before “decision_callback”), default is empty list. This function may call Session.terminate(). Signature: ‘(session) -> None’, where session is this session instance.

  • on_decision_callbacks (list of callable, or callable, or None, optional) – Functions to be called when expert decision is made (after “decision_callback”), default is empty list. This function may call Session.terminate(). Signature: ‘(metadata, data, session) -> None’, where metadata is metadata of the object has just been labeled, data is data of this object, session is this session instance.

  • known_labels (dict, optional) – Dictionary of known anomaly labels, keys are data/metadata indices, values are labels of type Label. Default is empty dictionary.

  • model (Coniferest or None, optional) – Anomaly detection model to use, default is PineForest().

current#

Index of the last anomaly candidate

Type:

int

last_decision#

Label of the last anomaly candidate or None if no decision was made

Type:

Label or None

scores#

Current anomaly scores for all data points

Type:

array-like, shape (n_samples,)

terminated#

True if session is terminated

Type:

bool

known_labels#

Current dictionary of known anomaly labels

Type:

dict[int, Label]

known_anomalies#

Array of indices of known anomalies

Type:

array-like

known_regulars#

Array of indices of known regular objects

Type:

array-like

known_unknowns#

Array of indices of known objects marked with Label::UNKNOWN

Type:

array-like

model#

Anomaly detection model used

Type:

Coniferest

Examples

>>> from coniferest.datasets import ztf_m31
>>> from coniferest.session import Label, Session
>>> data, metadata = ztf_m31()
>>> s = Session(
...    data=data,
...    metadata=metadata,
...    decision_callback=lambda *_: Label.ANOMALY,
...    on_decision_callbacks=[lambda _metadata, _data, session: session.terminate()],
... )
>>> _ = s.run()
>>> assert len(s.known_labels) == len(s.known_anomalies) == 1
argtopk_scores(k: int) → ndarray[source]#
property current: int#
property known_anomalies: ndarray#
property known_labels: Dict[int, Label]#
property known_regulars: ndarray#
property known_unknowns: ndarray#
property last_decision: Label | None#
property model: Coniferest#
run() → Session[source]#

Evaluate interactive anomaly detection session

property scores: ndarray#
terminate() → None[source]#
property terminated: bool#

Submodules#

coniferest.session.callback module#

class coniferest.session.callback.PickleSession(directory, filename='session.pickle', every_n_decisions=1, overwrite=True)[source]#

Bases: object

Callback that periodically saves the whole session to a pickle file.

Unlike SaveToOnnx, wich only saves the model, this callback saves the entire session object (model, known labels, current candidate, scores, etc.), so an interrupted session can be fully resumed later.

Use it as an “on decision callback”: Session(…, on_decision_callbacks=[PickleSession(directory=”snapshots”)])

Parameters:

  • directory (str) – Directory where the pickle file(s) will be saved. Created if missing.

  • filename (str, optional) – Base name of the pickle file. Default is “session.pickle”.

  • every_n_decisions (int, optional) – Save every N decisions. Default is 1 (save after every decision).

  • overwrite (bool, optional) – If True (default), always overwrite the same file. If False, keep a new numbered file for each save (e.g. session_1.pickle, session_2.pickle, …). The number in the filename corresponds to the decision counter at the time of saving, so if every_n_decisions is greater than 1, the numbers will not be consecutive.

class coniferest.session.callback.SaveToOnnx(directory, filename='model.onnx', every_n_decisions=1, overwrite=True)[source]#

Bases: object

Callback that periodically saves the current session model to ONNX.

Use it as an “on decision callback”: Session(…, on_decision_callbacks=[SaveToOnnx(directory=”models”)])

Parameters:

  • directory (str) – Directory where the ONNX file(s) will be saved. Created if missing.

  • filename (str, optional) – Base name of the ONNX file. Default is “model.onnx”.

  • every_n_decisions (int, optional) – Save every N decisions. Default is 1 (save after every decision).

  • overwrite (bool, optional)

  • (default) (If True)

  • file. (always overwrite the same)

  • False (If)

  • save (keep a new numbered file for each)

  • model_1.onnx ((e.g.)

  • model_2.onnx

  • the (...). The number in)

  • of (filename corresponds to the decision counter at the time)

  • saving

  • 1 (so if every_n_decisions is greater than)

  • the

  • with (numbers will not be consecutive (e.g.)

  • every_n_decisions=5

  • named (files will be)

  • model_5.onnx

  • model_10.onnx

  • model_15.onnx

  • ...).

class coniferest.session.callback.TerminateAfter(budget: int)[source]#

Bases: object

Terminate session after given number of iterations.

This callback to be used as “on decision callback”: Session(…, on_decision_callbacks=[TerminateAfter(budget)])

Parameters:

budget (int) – Number of iterations after which session will be terminated.

class coniferest.session.callback.TerminateAfterNAnomalies(budget: int)[source]#

Bases: object

Terminate session after given number of newly labeled anomalies.

This callback to be used as “on decision callback”: Session(…, on_decision_callbacks=[TerminateAfter(budget)])

Parameters:

budget (int) – Number of anomalies to stop after.

coniferest.session.callback.prompt_decision_callback(metadata, data, session) → Label[source]#

Prompt user to label the object as anomaly or regular.

If user sends keyboard interrupt, terminate the session.

coniferest.session.callback.viewer_decision_callback(metadata, data, session) → Label[source]#

Open SNAD Viewer for ZTF DR object. Metadata must be ZTF DR object ID.

coniferest.session.oracle module#

class coniferest.session.oracle.OracleSession(data: ndarray, labels: ndarray, *, model: Coniferest, max_iterations: int, max_anomalies: int, on_refit_callbacks=None, on_decision_callbacks=None)[source]#

Bases: Session

Automated session to run experiments with labeled data.

Parameters:

  • data (np.ndarray, 2-D) – Array with feature values of objects.

  • labels (np.ndarray, 1-D) – Array with true labels, of Label or int type

  • model (Coniferest) – Anomaly detection model to use

  • max_iterations (int) – Maximum number of asked decisions

  • max_anomalies (int) – Maximum number of anomalies to search for

  • on_refit_callbacks (list of callable, or callable, or None, optional) – Functions to be called when model is refitted, default is empty list.

  • on_decision_callbacks (list of callable, or callable, or None, optional) – Functions to be called when expert decision is made, default is empty list.

  • class (Also see methods and attributes from the base Session)

coniferest.session.oracle.create_oracle_session(data: ndarray, labels: ndarray[int], *, model: Coniferest, max_iterations: int | None = None, on_refit_callbacks=None, on_decision_callbacks=None) → OracleSession[source]#

Create an automated session to run experiments with labeled data.

Parameters:

  • data (np.ndarray, 2-D) – Array with feature values of objects.

  • labels (np.ndarray, 1-D) – Array with true labels, of Label or int type

  • model (Coniferest) – Anomaly detection model to use

  • max_iterations (int or None, optional) – Maximum number of asked decisions. Default is 5 times the number of anomalies.

  • on_refit_callbacks (list of callable, or callable, or None, optional) – Functions to be called when model is refitted, default is empty list.

  • on_decision_callbacks (list of callable, or callable, or None, optional) – Functions to be called when expert decision is made, default is empty list.

Return type:

OracleSession