{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# User Attributes\n\nThis feature is to annotate experiments with user-defined attributes.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Adding User Attributes to Studies\n\nA :class:`~optuna.study.Study` object provides :func:`~optuna.study.Study.set_user_attr` method\nto register a pair of key and value as an user-defined attribute.\nA key is supposed to be a ``str``, and a value be any object serializable with ``json.dumps``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import sklearn.datasets\nimport sklearn.model_selection\nimport sklearn.svm\n\nimport optuna\n\n\nstudy = optuna.create_study(storage=\"sqlite:///example.db\")\nstudy.set_user_attr(\"contributors\", [\"Akiba\", \"Sano\"])\nstudy.set_user_attr(\"dataset\", \"MNIST\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can access annotated attributes with :attr:`~optuna.study.Study.user_attr` property.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "study.user_attrs  # {'contributors': ['Akiba', 'Sano'], 'dataset': 'MNIST'}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ":class:`~optuna.struct.StudySummary` object, which can be retrieved by\n:func:`~optuna.study.get_all_study_summaries`, also contains user-defined attributes.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "study_summaries = optuna.get_all_study_summaries(\"sqlite:///example.db\")\nstudy_summaries[0].user_attrs  # {\"contributors\": [\"Akiba\", \"Sano\"], \"dataset\": \"MNIST\"}"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. seealso::\n    ``optuna study set-user-attr`` command, which sets an attribute via command line interface.\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Adding User Attributes to Trials\n\nAs with :class:`~optuna.study.Study`, a :class:`~optuna.trial.Trial` object provides\n:func:`~optuna.trial.Trial.set_user_attr` method.\nAttributes are set inside an objective function.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "def objective(trial):\n    iris = sklearn.datasets.load_iris()\n    x, y = iris.data, iris.target\n\n    svc_c = trial.suggest_float(\"svc_c\", 1e-10, 1e10, log=True)\n    clf = sklearn.svm.SVC(C=svc_c)\n    accuracy = sklearn.model_selection.cross_val_score(clf, x, y).mean()\n\n    trial.set_user_attr(\"accuracy\", accuracy)\n\n    return 1.0 - accuracy  # return error for minimization\n\n\nstudy.optimize(objective, n_trials=1)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We can access annotated attributes as:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "study.trials[0].user_attrs"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Note that, in this example, the attribute is not annotated to a :class:`~optuna.study.Study`\nbut a single :class:`~optuna.trial.Trial`.\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.8.6"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}