アナリティクスAPI (Dev docs)
- アナリティクスモデルの学習
- 教師向け
- 研究者向け
Englishi page: dev:Analytics API
概要
MoodleアナリティクスAPIを使用すると、Moodleサイトマネージャは指標とターゲットを組み合わせた予測モデルを定義できます。ターゲットは、予測したいイベントです。指標は、ターゲットの正確な予測につながると私たちが考えるものです。 Moodleはこれらのモデルを評価することができ、予測精度が十分に高い場合、Moodleはサイトデータ内で定義された指標に基づく計算を使用して機械学習アルゴリズムを内部的にトレーニングします。モデルによって定義された基準に一致する新しいデータが利用可能になると、Moodleはターゲットイベントが発生する確率の予測を開始します。ターゲットは、メッセージの送信やレポートのフィードから、新しいアダプティブラーニング活動の構築まで、予測ごとに実行されるアクションを自由に定義できます。
皆さんが興味を持ちそうな分かりやすいモデルの明白な例として、脱落リスクのある学生の防止があります。過去の活動についての不参加や悪い評点は、指標として使える可能性があります。ターゲットとしては、学生がコースを修了できるかどうか、ということでしょう。Moodleは、これらの指標と、終了したコースの各学生のターゲットとを計算し、進行中のコースで脱落するリスクのある学生を予測します。
APIコンポーネント
この図は、アナリティクスAPIの主要コンポーネントとそれらの間の相互作用を示しています。
データフロー
以下の図は、Moodleサイトに含まれるデータから実用的な洞察まで、データが通過するさまざまな段階を示しています。
APIクラス図
これは、APIクラスとそれらの関係の要約です。サードパーティが拡張できるフレームワークのさまざまな部分をグルーピングして、独自の予測モデルを作成します。
ファイル:Analytics API classes diagram (summary).svg
https://docs.moodle.org/dev/File:Analytics_API_classes_diagram_(summary).svg
(画像をクリックすると拡大します。SVGです)
組み込みモデル
人々はMoodleを非常に異なる方法で使用し、同じサイトのコースでさえ大幅に異なる可能性があります。 Moodleコアには、幅広いサイトやコースで予測に優れていることが証明されているモデルのみが含まれます。 Moodle 3.4+には、2つの組み込みモデルがあります。
サンプルを多様化し、より広い範囲のケースをカバーするために、Moodle HQ研究チームは、協力機関やパートナーから匿名のMoodleサイトデータセットを収集して、それらを使用して機械学習アルゴリズムをトレーニングしています。 Moodleに同梱されているモデルは、参加機関のサイトでの予測に明らかに優れていますが、他のいくつかのデータセットは、モデルがどのMoodleサイトでも正確に予測できることを確認するために、機械学習アルゴリズムのテストデータとして使用されます。コラボレーションに興味がある場合は、Emdalton1[elizabeth@moodle.com]に連絡して、プロセスに関する情報を入手してください。
Moodleコアに含まれるモデルがすでにMoodleHQによってトレーニングされている場合でも、各サイトは独自のデータを使用してそのサイトの機械学習アルゴリズムのトレーニングを継続します。
コンセプト
機械学習の概念に精通していない人のために、用語の定義を以下に示しておきます。
トレーニング
これは、何かを予測する前にMoodleサイトで実行されるプロセスです。このプロセスは、過去のサイトデータで見つかった関係を記録するため、分析システムは、将来同じ状況で何が起こりそうかを予測できます。トレーニングする対象は機械学習アルゴリズムです。
サンプル
予測を行うために使用する機械学習バックエンドは、検索するパターンの種類と、Moodleデータのどこを検索するかを知る必要があります。サンプルは、Moodleサイトデータのコレクションを使用して行う一連の計算です。これらのサンプルは、テストデータやphpunitデータとは無関係であり、計算の基礎となるデータ要素に一致するIDによって識別されます。サンプルのIDは、コース、ユーザ、登録、小テストの受験など、任意のMoodleエンティティIDにすることができ、サンプルに含まれる計算はその要素によって異なります。サンプルとして使用される各タイプのMoodleエンティティは、その種類のエンティティを含む予測の開発に役立ちます。たとえば、小テストの受験に基づくサンプルは、特定の学生グループによる小テストの受験に関連する、分析が提供する可能性のある潜在的な洞察を開発するのに役立ちます。アナライザークラスを使用してサンプルを定義する方法の詳細については、アナリティクスAPI (Dev docs)#アナライザーを参照してください。
予測モデル
上で説明したように、予測モデルは指標とターゲットの組み合わせです。システムモデルは、 サイト管理 > アナリティクス > 分析モデル で表示できます。
指標とターゲットの関係は、analytics_models データベーステーブルに保存されます。
クラス \core_analytics\model は、モデルに関連するすべてのアクションを管理します。evaluate()、 train() 、 predict() は、計算された指標を機械学習バックエンドに転送します。 \core_analytics\model はすべての重い処理をアナライザーと機械学習バックエンドに委任します。また、予測モデルの評価ログも管理します。
\core_analytics\model クラスは拡張される予定はありません。
静的モデル
一部の予測モデルは、正確な予測を行うために大量のデータを処理する背後にある強力な機械学習アルゴリズムを必要としません。さまざまな利害関係者が、簡単に計算できることを知りたいと思うかもしれない明らかなイベントがあります。これらの *静的モデル* の予測は、指標値に基づいて直接計算されます。これらはターゲットで定義された仮定に基づいていますが、これらすべての指標をさまざまな予測モデルで再利用できるように、指標に基づいている必要があります。このため、静的モデルは サイト管理 > アナリティクス > 分析モデル ユーザインターフェイスから編集できません。
可能な静的モデルのいくつかの例:
- 教育活動がないコース
- 注意が必要な学生の提出物があり、コースにアクセスする教師がいないコース
- 1か月前に開始され、誰もアクセスしたことがないコース
- システムにログインしたことがない学生
- ....
Moodleはすでに上記の例の通知を生成することができますが、MoodleアナリティクスAPIを使用してそれを行うことにはいくつかの利点があります:
- 分析サブシステムがすべてのAPIを提供するため、開発の観点からすべてが簡単かつ迅速にコーディングできます
- 新しい指標は、研究者(および一般的にサードパーティの開発者)が独自のモデルで再利用できるコア指標プールの一部になります
- 既存のコア指標も再利用できます(機械学習バックエンドに依存する洞察に使用されるものと同じ指標)
- 通知はコア洞察システムを使用して表示されます。コア洞察システムは、通知と関連するすべてのアクションの送信も担当します。
- アナリティクスAPIは、予測を表示した後にユーザアクションを追跡するため、洞察がアクションにつながるかどうか、どの洞察が役に立たないかなどを知ることができます。洞察に対するユーザの応答自体を指標として定義できます。
アナライザー
アナライザーは、機械学習プロセッサーに送信されるデータセットファイルを作成する責任があります。それらはPHPクラスとしてコード化されています。 Moodleコアには、モデルで使用できるアナライザーがいくつか含まれています。
基本クラス \core_analytics\local\Analyzer\base がほとんどの作業を行います。これには、主要な抽象メソッド get_all_samples() が含まれています。このメソッドは、サイト全体でサンプルの一意の識別子を定義するものです。アナライザークラスは、そのサンプルIDに関連するすべてのサイトデータを含める責任もあります。このデータは、指標が計算されるときに使用されます。たとえば、サンプルID ユーザ登録 は、コース 、コース コンテキスト、および ユーザ に関するデータが含まれます。サンプルはそれ自体では何もなく、関連データのIDのリストにすぎません。これらは、ターゲットクラスおよび指標クラスと組み合わされることにより、計算で使用されます。
その他のアナライザークラスの責任:
- 予測のコンテキストを定義します
- 無効なデータを破棄する
- すでにトレーニングされたサンプルを除外します
- 時間係数を含めます(時間範囲プロセッサ、以下で説明)
- 計算を指標とターゲットクラスに転送する
- すべての計算をファイルに記録する
- 分析されたすべてのサンプルIDをデータベースに記録します
新しいアナライザーを導入する場合は、知っておくべき自明ではない重要な事実があります。スケーラビリティの理由から、コースレベルでのすべての計算はコースごとに実行され、すべてのサイトコース分析が完了すると、結果のデータセットがマージされます。これはパフォーマンス上の理由によるものです。サイトのサイズによっては、サイト全体の分析を完了するのに数時間かかる場合があります。これは、プロセスを細かく分割するための良い方法です。新しいアナライザーをコーディングするときは、拡張するかどうかを決定する必要があります \core_analytics\local\analyser\by_course (アナライザーはコースのリストを処理します)\core_analytics\local\analyser\sitewide(アナライザーは、分析可能な要素であるサイトを1つだけ受け取ります)、または活動、カテゴリ、またはその他のMoodleエンティティー用に独自のアナライザーを作成します。
ターゲット
ターゲットは、モデルを定義する重要な要素です。 PHPクラスとして、ターゲットはモデルが予測しようとしているイベント(教師あり学習の従属変数)を表します。また、受信した予測に応じて実行するアクションも定義します。
アナライザーは必要なサンプルを提供するため、ターゲットはアナライザーに依存します。アナライザーは異なるターゲット間で再利用できるため、アナライザーはターゲットとは別のエンティティです。各ターゲットは、使用しているアナライザーを指定する必要があります。アナライザー、サンプル、ターゲットの違いを明確にするためのいくつかの例を次に示します。
- ターゲット : '脱落リスクのある学生' - アナライザーが提供するサンプル : 'コース登録'
- ターゲット : 'スパマー' - アナライザーが提供するサンプル : 'サイトユーザ'
- ターゲット : '効果のないコース' - アナライザーが提供するサンプル : 'コース'
- ターゲット : '特定の小テストでの合格の難しさ' - アナライザーが提供するサンプル : '特定の小テストでの小テスト受験'
ターゲットによって定義されたコールバックは、新しい予測が開始されると実行されるため、各ターゲットは予測結果を制御できます。
APIは、バイナリ分類、マルチクラス分類、および回帰をサポートしますが、コアに含まれる機械学習バックエンドは、マルチクラス分類または回帰をまだサポートしていないため、最初から完全にサポートされるのはバイナリ分類のみです。詳細については、 https://tracker.moodle.org/browse/MDL-59044 および https://tracker.moodle.org/browse/MDL-60523 を参照してください。
独自のモデルでコアターゲットを使用することに対する技術的な制限はありませんが、ほとんどの場合、各モデルは新しいターゲットを実装します。ターゲットが再利用される可能性のある1つのケースは、A/Bテスト用に、同じターゲットと異なる指標のセットを使用して新しいモデルを作成することです。
洞察
ターゲットによって制御されるもう1つの側面は、洞察の生成です。洞察は、アナライザーモデルのコンテキスト内でサンプルの特定の要素について行われた予測を表します。このコンテキストは、利用可能な新しい洞察について ケイパビリティ moodle/analytics:listinsights(デフォルトでは教師のロール)を持つユーザに通知するために使用されます。これらのユーザは、そのコンテキストのすべての予測が一覧表示されている予測ページへのリンクを含む通知を受け取ります。
提案されたアクションのセットは、各予測で利用できます。 脱落リスクのある学生 のような場合、アクションには、学生へのメッセージの送信、学生のコース活動レポートの表示などがあります。
指標
指標PHPクラスは、提供されたサンプルを使用して指標(予測値または教師あり学習の独立変数)を計算する役割を果たします。 Moodleコアには、追加のPHPコーディングなしでモデルで使用できる一連の指標が含まれています(機能を拡張したい場合を除く)。
指標は、ターゲットのように単一のアナライザーに限定されません。これにより、指標をさまざまなモデルで再利用しやすくなります。指標は、計算を実行するために必要なデータの最小セットを指定します。指標の開発者は、さまざまなアナライザーが使用されたときに指標がどのように機能するかを想像する努力もする必要があります。たとえば、任意のフォーラムへの投稿 という名前の指標は、最初は コース内の恥ずかしがり屋の学生 ターゲット用にコーディングできます。このターゲットは コース登録 アナライザーを使用するため、指標開発者は コース と 登録 がそのアナライザーによって提供されることを知っていますが、この指標は簡単にコーディングできるため、指標は次のようになります。コース や ユーザ などの他のアナライザーによって再利用されます。この場合、開発者は コース または ユーザ を要求することを選択でき、それに応じて指標の名前が変わります。たとえば、任意のフォーラムのユーザ投稿 は、非アクティブユーザ などのユーザベースのモデルや、アナライザーが ユーザ データを提供するその他のモデルで使用できます。いずれかのコースフォーラムへの投稿 は、低参加コース のようなコースベースのモデルで使用できます。
計算値は、-1(最小)から1(最大)までの範囲で変動可能です。このため、「書き込み動作の回数」などのような「生データ」指標の作成はできません。例えば、-1 = 0アクション、-0.33 =基本的な活動、0.33 =活動、1 =十分な活動、のように、計算値の範囲を制限する必要があります。「フォーラムへの投稿」のイベントの場合、回数そのものではなく、予想される投稿数に比例する数で計算する必要があります。これを行うにはいくつかの方法があります。 1つは、イベントの望ましい個数の最小値を定義することです。フォーラム内の3つの投稿は「すこしの」活動を表し、6つの投稿は充分な活動を表し、10以上の投稿は予想される最大数の活動を表します。もう1つの方法は、統計値を使用して、個々のユーザごとのイベント数を、同じコンテキスト内のすべてのユーザによるイベントの平均値または中央値と比較することです。たとえば、値0は、学生がそのコンテキスト内のすべての学生の投稿の平均と同じ数の投稿を投稿したことを表します。値-1は、学生が平均より2または3標準偏差低いことを示し、+ 1は、学生が平均より2または3標準偏差高いことを示します。 (この種の比較計算は教育方針に影響を与えることに注意してください。これは、すべての学生が到達できる定義済みの基準ではなく、最高から最低までの学生のランキングがあることを示唆しています。)
分析間隔
分析間隔(以前は時間分割方法と呼ばれていました)は、システムが予測を計算するタイミングと、活動ログのどの部分を予測に用いるのかを定義するものです。それらはPHPクラスとしてコード化されており、Moodleコアにはモデルで使用できるいくつかの分析間隔が含まれています。
場合によっては、時間的要因は重要ではなく、サンプルを分類するためだけの分析間隔もあります。これは比較的簡単です。将来何が起こるかを予測したい場合、事態はさらに複雑になります。たとえば、脱落リスクのある学生に関する予測は、コースが終了した後、または介入するには遅すぎる場合には役に立ちません。
時間範囲を含む計算は、一部の予測モデルの難しい側面になる可能性があります。指標はこれを念頭に置いて設計する必要があり、計算された指標内に時間依存のインジケーターを含める必要があります。これにより、機械学習アルゴリズムは、コースの最初に属する計算とコースの最後に属する計算が混ざらないように十分にスマートになります。
コースを時間範囲に分割するには、さまざまな方法があります。週、四半期、8パート、10パート(10分の1)、最初に長い期間、最後に短い期間の範囲など...そして範囲は累積することができます(コースの最初からそれぞれを含む)または時間範囲の最初からのみ。
Moodleに含まれる分析間隔の多くは、各コースの開始日と終了日が固定されていることを前提としているため、コースを同じ長さのセグメントに分割することができます。これにより、異なる長さのコースを同じ予測モデルに含めることができますが、これらの分析間隔は、開始日または終了日が固定されていないコース、たとえばセルフペースコースでは役に立ちません。これらのコースでは、代わりに、予測計算の境界を定義するために、週などの固定の時間長を使用する場合があります。
機械学習バックエンド
機械学習バックエンド(Dev docs)にドキュメントがあります。
デザイン
システムはMoodleサブシステムおよびAPIとして設計されています。それは analytics/ にあります。すべての分析基本クラスはここにあります。
機械学習バックエンド(Dev docs)は新しいMoodleプラグインのタイプです。それらは lib/mlbackend に保存されます。
アナリティクスAPIの使用は、APIの汎用使用をホストするコンポーネントであるコア(lib/classes/analytics)であるさまざまなMoodleコンポーネントにあります。
インターフェース
このAPIは、できる限り拡張可能性が高くなることを意図した設計になっています。サードパーティのプラグインを含むすべてのmoodleコンポーネントは、指標、ターゲット、アナライザー、および時間分割方法を定義できます。アナリティクスAPIは、以下で説明する名前空間の規則に従っている限り、それらを見つけることができます。
拡張の一例を挙げるとすれば、大学の学生情報システム (SIS) から学生の学務記録を取得する指標を備えたプラグインが考えられます。サイト管理者は、モデル精度の向上や研究のために、組み込みモデルである「脱落リスクのある学生」にSISの指標を追加して新しいモデルを構築することができます。
このセクションでは、機械学習バックエンドインターフェースの説明は含まれていないことに注意してください。それは機械学習バックエンド(Dev docs)#インターフェースにあります。
分析可能(core_analytics\analysable)
分析可能物は、サンプルを含むMoodleの要素です。ほとんどの場合、分析可能なものはコースですが、サイトまたはその他のMoodle要素(活動など)でもかまいません。 Moodleコアには2つのアナライザー \core_analytics\course と \core_analytics\site が含まれています。
実装する必要のあるメソッドのリストは非常に単純で、多くの説明は必要ありません。
分析可能な要素は遅延ロードする必要があることに注意することも重要です。そうしないと、PHPのメモリの問題が発生する可能性があります。その理由は、アナライザーがサイト内のすべての分析可能な要素をロードして、次に計算される要素を計算するためです(最近処理された要素などをスキップします)。例としてcore_analytics\courseを取り上げます。
実装する方法:
/** * The analysable unique identifier in the site. * * @return int. */ public function get_id();
/** * The analysable human readable name * * @return string */ public function get_name();
/** * The analysable context. * * @return \context */ public function get_context();
get_start および get_end は、指標が計算に使用する開始時刻と終了時刻を定義します。
/** * The start of the analysable if there is one. * * @return int|false */ public function get_start();
/** * The end of the analysable if there is one. * * @return int|false */ public function get_end();
アナライザー(core_analytics\local\Analyzer\base)
get_analysables()メソッドは非推奨になり、パフォーマンス上の理由から新しい get_analysables_iterator() が採用されました。このメソッドは、サイト内の分析可能な要素のリスト全体を返します。各モデルは、後で、期待に一致しない分析可能ファイルを破棄できるようになります。たとえば、モデルが終了日時が設定された小テストにのみ関心がある場合も、アナライザーはすべての小テストを返しますが、モデルは終了日時が設定されていない小テストを除外します。このアプローチは、アナライザーをより再利用可能にすることになっています。
/**
* Returns the list of analysable elements available on the site.
*
* A relatively complex SQL query should be set so that we take into account which analysable elements
* have already been processed and the order in which they have been processed. Helper methods are available
* to ease to implementation of get_analysables_iterator: get_iterator_sql and order_sql.
*
* @param string|null $action 'prediction', 'training' or null if no specific action needed.
* @return \Iterator
*/
public function get_analysables_iterator(?string $action = null)
get_all_samples および get_samples は、それらが提供するサンプルIDに関連付けられたデータを返す必要があります。これは2つの理由で重要です:
- サンプルの出所とともに提供されるデータは、このアナライザーの分析に関係のない指標を除外するために使用されます。 例えば、 コースアナライザーはコースとコースに関する情報を提供しますが、ユーザに関する情報は提供しません。 ユーザプロファイル完了 指標は、ユーザオブジェクトが使用可能である必要があります。 コースアナライザーを使用するモデルは、ユーザプロファイル完了 という指標を使用できなくなります。
- ここに含まれるデータはPHP静的変数にキャッシュされます。一方では、これにより、指標が実行する必要のあるデータベースクエリの量が削減されます。一方、バランスが取れていないと、PHPのメモリの問題が発生する可能性があります。
/**
* This function returns this analysable list of samples.
*
* @param \core_analytics\analysable $analysable
* @return array array[0] = int[] (sampleids) and array[1] = array (samplesdata)
*/
abstract public function get_all_samples(\core_analytics\analysable $analysable);
/**
* This function returns the samples data from a list of sample ids.
*
* @param int[] $sampleids
* @return array array[0] = int[] (sampleids) and array[1] = array (samplesdata)
*/
abstract public function get_samples($sampleids);
get_sample_analysable メソッドが予測中に実行されています:
/**
* Returns the analysable of a sample.
*
* @param int $sampleid
* @return \core_analytics\analysable
*/
abstract public function get_sample_analysable($sampleid);
サンプルオリジンは、サンプルIDを主キーとして使用するmoodleデータベーステーブルです。
/**
* Returns the sample's origin in moodle database.
*
* @return string
*/
abstract public function get_samples_origin();
sample_access_context 、コンテキストをサンプルIDに関連付けます。このサンプル予測は、そのコンテキストでケイパビリティ moodle/analytics:listinsights を持つユーザのみが利用できるため、これは重要です。
/**
* Returns the context of a sample.
*
* @param int $sampleid
* @return \context
*/
abstract public function sample_access_context($sampleid);
sample_description は、洞察 レポートにサンプルを表示するために使用されます。
/**
* Describes a sample with a description summary and a \renderable (an image for example)
*
* @param int $sampleid
* @param int $contextid
* @param array $sampledata
* @return array array(string, \renderable)
*/
abstract public function sample_description($sampleid, $contextid, $sampledata);
processes_user_data および join_sample_user メソッドは、プライバシーAPIの分析実装によって使用されます。アナライザーがユーザデータを処理する場合にのみ、それらを上書きする必要があります。これらは、分析データベーステーブルに保存されているユーザデータをエクスポートおよび削除するために使用されます。
/**
* Whether the plugin needs user data clearing or not.
*
* @return bool
*/
public function processes_user_data();
/**
* SQL JOIN from a sample to users table.
*
* More info in core_analytics\local\analyser\base::join_sample_user
*
* @param string $sampletablealias The alias of the table with a sampleid field that will join with this SQL string
* @return string
*/
public function join_sample_user($sampletablealias);
モデルが使用している分析対象にサンプルが1つしかない場合は、 新しいone_sample_per_analysable() メソッドを上書きできます。モデルによって生成された洞察には、提案されたアクションが通知に含まれます。
/**
* Just one sample per analysable.
*
* @return bool
*/
public static function one_sample_per_analysable() {
return true;
}
指標(core_analytics\local\Indicator\base)
指標は通常、返すことができる値に応じて、次の3つのクラスのいずれかを継承する必要があります:yes/no 指標の場合は core_analytics\local\Indicator\binary、線形値を返す指標の場合は core_analytics\local\Indicator\linear、分類された指標の場合は、core_analytics\local\Indicator\discerteです 。活動モジュールに community ofinquiry指標を実装したい場合は、core_analytics\local\Indicator\community_of_inquiry_indicator を継承します。Moodleコアで例を探してみてください。
required_sample_data を使用して、指標の計算に必須なものを指定できます。user オブジェクト、course、grade_grades が必要になる場合があります...デフォルトの実装では何も必須とはしません。アナライザーが必要なデータを返さないモデルは指標を使用できないため、ここには本当に必須なものだけをリストしてください。たとえば、grade_gradesレコードが必要な場合は、必須マークを付けますが、grade_gradesアイテムから取得できるため、 user オブジェクトと course も必要ありません。原則としてはできるだけ多くの関連データを含めるようになっているため、アナライザーが関連データを提供する可能性が非常に高いです。 しかし、関連オブジェクトには必須フラグを立てないでください。これは、たとえば、user オブジェクトが大きすぎてサイトでメモリの問題が発生する可能性があるため、アナライザーが user オブジェクトを含めないことを選択する可能性があるためです。
/** * Allows indicators to specify data they need. * * e.g. A model using courses as samples will not provide users data, but an indicator like * "user is hungry" needs user data. * * @return null|string[] Name of the required elements (use the database tablename) */ public static function required_sample_data() { return null; }
単一のメソッド calculate_sample を実装する必要があります。ほとんどの指標は、$starttimeと$endtimeを使用して、計算で考慮する期間を制限します(例:$starttime - $endtime の間に行われた読む動作)が、一部の指標は制限を適用する必要がない場合があります(例:このユーザにはユーザの写真とプロフィールの説明がありますか?)self::MIN_VALUE は-1で、 self::MAX_VALUE は1です。これらの値を変更することはお勧めしません。
/** * Calculates the sample. * * Return a value from self::MIN_VALUE to self::MAX_VALUE or null if the indicator can not be calculated for this sample. * * @param int $sampleid * @param string $sampleorigin * @param integer $starttime Limit the calculation to this timestart * @param integer $endtime Limit the calculation to this timeend * @return float|null */ abstract protected function calculate_sample($sampleid, $sampleorigin, $starttime, $endtime);
ここでのパフォーマンスは、時間分割法のサンプルごとおよび範囲ごとに1回実行されるため、重要であることに注意してください。いくつかのヒントがあります:
- パフォーマンスの問題や繰り返されるdbクエリを回避するために、アナライザークラスは、データベースクエリを保存するための計算に使用できるサンプルに関する情報を提供します。$user = $this->retrieve('user', $sampleid) を使用してサンプルに関する情報を取得できます。 retrieve() は、要求されたデータが利用できない場合、falseを返します。
- 必要に応じて、fill_per_analysable_caches メソッドを上書きすることもできます(PHPメモリは無制限ではないことに注意してください)。
- 指標インスタンスは、分析可能物ごと、処理される時間範囲ごとにリセットされます。これにより、メモリ使用量を許容範囲内で低く抑えることができ、追跡が困難なキャッシュのバグを防ぐことができます。
ターゲット(core_analytics\local\target\base)
ターゲットは、\core_analytics\local\target\base またはそのメインの子クラス \core_analytics\local\target\binary を拡張する必要があります。 Moodleコアに \core_analytics\local\target\discrete および \core_analytics\local\target\linear が含まれている場合でも、Moodle3.4機械学習バックエンドはバイナリ分類のみをサポートします。したがって、独自の機械学習バックエンドを使用していない限り、 \core_analytics\local\target\binary を拡張する必要があります。技術的には、ターゲットをモデル間で再利用できますが、あまりお勧めできません。代わりに、正確な予測に向けて連携する単一の指標セットを備えた単一のモデルを作成することに集中する必要があります。本番環境のモデルで考えられる唯一の有効なユースケースは、さまざまな時間分割方法を使用することですが、これを解決する適切な方法は、ニーズに固有の単一の時間分割方法を使用することです。
ターゲットが最初に定義する必要があるのは、ターゲットが使用するアナライザークラスです。アナライザークラスは get_analyser_class 指定されます。
/**
* Returns the analyser class that should be used along with this target.
*
* @return string The full class name as a string
*/
abstract public function get_analyser_class();
is_valid_analysable および is_valid_sample は、ターゲットに対して無効な要素を破棄するために使用されます。
/**
* Allows the target to verify that the analysable is a good candidate.
*
* This method can be used as a quick way to discard invalid analysables.
* e.g. Imagine that your analysable don't have students and you need them.
*
* @param \core_analytics\analysable $analysable
* @param bool $fortraining
* @return true|string
*/
public function is_valid_analysable(\core_analytics\analysable $analysable, $fortraining = true);
/**
* Is this sample from the $analysable valid?
*
* @param int $sampleid
* @param \core_analytics\analysable $analysable
* @param bool $fortraining
* @return bool
*/
public function is_valid_sample($sampleid, \core_analytics\analysable $analysable, $fortraining = true);
calculate_sample は、ターゲット値を計算するメソッドです。
/**
* Calculates this target for the provided samples.
*
* In case there are no values to return or the provided sample is not applicable just return null.
*
* @param int $sampleid
* @param \core_analytics\analysable $analysable
* @param int|false $starttime Limit calculations to start time
* @param int|false $endtime Limit calculations to end time
* @return float|null
*/
protected function calculate_sample($sampleid, \core_analytics\analysable $analysable, $starttime = false, $endtime = false);
洞察の受信者に提供される アクション のリストに追加することをお勧めします。
/**
* Suggested actions for a user.
*
* @param \core_analytics\prediction $prediction
* @param bool $includedetailsaction
* @param bool $isinsightuser
* @return \core_analytics\prediction_action[]
*/
public function prediction_actions(\core_analytics\prediction $prediction, $includedetailsaction = false,
$isinsightuser = false)
洞察通知を受信するユーザをオーバーライドできます :
/**
* Returns the list of users that will receive insights notifications.
*
* Feel free to overwrite if you need to but keep in mind that moodle/analytics:listinsights
* or moodle/analytics:listowninsights capability is required to access the list of insights.
*
* @param \context $context
* @return array
*/
public function get_insights_users(\context $context)
always_update_analysis_time() メソッドを実装して、分析可能な要素のtimeanalysedが、分析可能な要素が正常に評価された場合にのみ更新されるようにすることができます。軽量のターゲットに役立ちます。
/**
* Update the last analysis time on analysable processed or always.
*
* If you overwrite this method to return false the last analysis time
* will only be recorded in DB when the element successfully analysed. You can
* safely return false for lightweight targets.
*
* @return bool
*/
public function always_update_analysis_time()
ignored_predicted_classes を実装することを選択した場合は、パブリックである必要があります。
/**
* Returns the predicted classes that will be ignored.
*
* @return array
*/
public function ignored_predicted_classes()
洞察で提供されるデフォルトのメッセージを get_insight_subject() オーバーライドできます:
/**
* The insight notification subject.
*
* This is just a default message, you should overwrite it for a custom insight message.
*
* @param int $modelid
* @param \context $context
* @return string
*/
public function get_insight_subject(int $modelid, \context $context)
get_insight_context_url() を使用して、洞察へのURLをオーバーライドすることもできます。
/**
* URL to the insight.
*
* @param int $modelid
* @param \context $context
* @return \moodle_url
*/
public function get_insight_context_url($modelid, $context)
分析間隔(core_analytics\local\time_splitting\base)
分析間隔は、分析APIが予測プロセッサをトレーニングするタイミングと予測を生成するタイミングを定義するために使用されます。上記のアナリティクスAPI (Dev docs)#分析間隔で説明したように、これらは分析可能な要素の開始タイムスタンプと終了タイムスタンプに基づいて時間範囲を定義します。
基本クラスは \core_analytics\local\time_splitting\base です。;分析可能な期間を等しい部分または累積部分に分割することが目的の場合は、代わりに \ core_analytics\local\time_splitting\equal_parts または \core_analytics\local\time_splitting\Accumulative_parts を拡張できます。
define_ranges は実装する主なメソッドであり、その値は主に現在の分析可能な要素($this->analysisable 利用可能)に依存します。時間範囲の配列を返す必要があります。これらの各範囲には、活動ログの量を制限できるように指標に渡される開始時間('start')と終了時間('end')の3つの属性が含まれている必要があります。彼らが読んで; 3番目の属性は 'time' です。この値は範囲がいつ実行されるかを決定します。
/**
* Define the time splitting methods ranges.
*
* 'time' value defines when predictions are executed, their values will be compared with
* the current time in ready_to_predict
*
* @return array('start' => time(), 'end' => time(), 'time' => time())
*/
protected function define_ranges();
名前と説明も指定する必要があります。
/**
* Returns a lang_string object representing the name for the time splitting method.
*
* Used as column identificator.
*
* If there is a corresponding '_help' string this will be shown as well.
*
* @return \lang_string
*/
public static function get_name() : \lang_string;
注 :Moodle 3.7以降、分析間隔で以下を上書きできるようになりました:
valid_for_evaluation()
たとえば、upcoming_periodic子クラスのように、時間分割メソッドを使用して予測モデルを評価できない場合、またはそれを使用して予測モデルを評価することが意味をなさない場合は、falseを返すことができます。
include_range_info_in_training_data()
および get_training_ranges()
これらを使用して、事前定義された数の範囲で時分割メソッドを作成できます。
以下は上書きできません。
\core_analytics\local\time_splitting\base::append_rangeindex
および \core_analytics\local\time_splitting\base::infer_sample_info
\core_analytics\local\analyser\base::get_most_recent_prediction_range
は \core_analytics\local\time_splitting\base::get_most_recent_prediction_range
に移動され、時分割メソッドで上書きできなくなりました 。
計算可能(core_analytics\calculable)
このインターフェイスは、\core_analytics\local\Indicator\base および \core_analytics\local\target\base によって既に実装されているものです。より詳細な制御が必要な場合は、ターゲットや指標を \core_analytics\calculable ベースからコーディングすることが可能です。
指標とターゲットの両方がこのインターフェースを実装する必要があります。これは、独立変数(指標)または従属変数(ターゲット)として計算で使用されるデータ要素を定義します。
モデルの作成方法
新しいモデルはphpで作成および実装でき、配布用のMoodleプラグインの一部としてパッケージ化できます。モデルコンポーネントとモデルの例は、 https://github.com/dmonllao/moodle-local_testanalytics で提供されています。
注:サードパーティのプラグイン開発者は、新しい要素(ターゲット、指標など)をドキュメントに追加できます。それらのコンポーネントに提供されるページ。 これらのドキュメントページは、モデルを編集するためにWeb UIからリンクされています。
問題を定義する
予測する対象(ターゲット)とこれらの予測の対象(サンプル)を定義することから始めます。これらの概念の説明は上記にあります。 APIはあらゆる種類のモデルに使用できますが、学生の成功 のようなものを予測したい場合、この定義はおそらく教育学の基礎を持っているはずです。 (たとえば、含まれているモデル脱落リスクのある学生は、Community of Inquiryの理論的フレームワークに基づいており、学生がコースを完了することを予測しようとします。 CoIフレームワークの3つのコンポーネント(教育的存在、社会的存在、認知的存在)を表すように設計された指標に基づいています。ターゲットがどのように定義されるかを明確にすることから始めます。既知の例を使用してトレーニングする必要があります。たとえば、学生ごとのコースの最終成績を予測する場合、モデルのトレーニングに使用されるコースには正確な最終成績が含まれている必要があります。
各サンプルの予測はいくつですか?
次の決定は、各サンプルに対して取得する予測の数です(たとえば、コース開始前の1つの予測、または毎週の予測)。各サンプルの単一の予測は、コード化に必要なAPIの深さの点で、さまざまな時点での複数の予測よりも単純です。
これらは絶対的なステートメントではありませんが、一般的には次のとおりです。
- 特定の時点でサンプルごとに単一の予測が必要な場合は、サイト全体のアナライザーを再利用するか、ターゲットの is_valid_sample() メソッドを使用して独自のサンプルの有効性を定義して制御できます。
- サンプルごとに異なる時点で複数の予測が必要な場合は、分析可能な要素を再利用するか、独自の要素を定義して( \core_analytics\analysisable 拡張)、独自のアナライザーを再利用または定義して、これらの分析可能な要素を取得します。ターゲットの is_valid_analysable() メソッドを使用してアナライザーの有効性を制御できます。
- 活動レベルでの予測が必要な場合は、by_course アナライザーを使用してください。そうしないと、スケーラビリティの問題が発生する可能性があります(ただし、コースごとの要素の処理は、各コースの処理後にメモリをクリーンアップするのに役立ちますが、サイトの各grade_gradesレコードのメモリ計算に保存することを想像してください)。
この決定は次の理由で重要です。
- 分析間隔は、分析可能な時間の開始と終了に適用されます(たとえば、四半期 は、コースの期間を4つの部分に分割できます)。
- 予測結果は、管理インターフェースで分析可能なものごとにグルーピングされ、予測が一覧表示されます。
- デフォルトでは、分析可能なレベルでケイパビリティ moodle/analytics:listinsights を使用して洞察がユーザに通知されます(ただし、これはターゲットで上書きできるデフォルトの動作にすぎません)。
既存の分析間隔のいくつかは、コースの長さに比例することに注意してください。たとえば、四半期、10分の1などです。これにより、異なる長さのコースを同じサンプルに含めることができますが、コースの開始日と終了日を定義する必要があります。今後3日間 など、定義されたコースの長さに依存しない他の分析間隔も利用できます。これらは、開始日と終了日が決まっていない自習型コースに適しています。
この段階で単一の分析間隔を必要とする必要はなく、モデルがトレーニングされるたびに変更できます。モデルが分析可能ごとに単一の予測を行うか、複数の予測を行うかを定義する必要があります。
ターゲットを作成します
#ターゲット(core_analytics\local\target\base)セクションで指定されているとおり。
モデルを作成します
システムに新しいモデルを追加するには、PHPファイルで定義する必要があります。プラグインとコアサブシステムは、db/analytics.phpファイルに記述してデフォルトの予測モデルを宣言します。モデルは、db/install.phpファイルを介して手動で作成しないでください。 (Moodle config.phpを参照するスタンドアロンPHPファイルで必要なコマンドを実行することも可能です。)
モデルを作成するには、少なくともそのターゲットと、オプションで一連のインジケーターと時間分割方法を指定します。
//ターゲットをインスタンス化します:ユーザをスパマーとして分類します
$target = \core_analytics\manager::get_target('\mod_yours\analytics\target\spammer_users');
//指標のインスタンス化:ユーザがスパマーであることを予測する2つの異なる指標
$indicator1 = \core_analytics\manager::get_indicator('\mod_yours\analytics\indicator\posts_straight_after_new_account_created');
$indicator2 = \core_analytics\manager::get_indicator('\mod_yours\analytics\indicator\posts_contain_important_viagra');
$indicators = array($indicator1->get_id() => $indicator1, $indicator2->get_id() => $indicator2);
//モデルを作成します
//3番目と4番目の引数(時間分割方法と予測プロセッサ)はオプションであることに注意してください。 4番目の引数はMoodle3.6以降で利用可能です。
$model = \core_analytics\model::create($target, $indicators, '\core\analytics\time_splitting\single_range', '\mlbackend_python\processor');
モデルを有効にする前に、モデルの予測がどれだけ優れているかを評価することに関心がある場合があるため、モデルはデフォルトで無効になっています。 MoodleUIまたは分析APIを使用してモデルを有効にすることができます。
$model->enable();
指標
ターゲットに必要なアナライザー(アナライザーはサンプルを提供するものです)と、多かれ少なかれ、どの時間分割方法が適しているかは既にわかっています。これで、正確な予測につながると思われる指標のリストを選択できます。予測したいターゲットに固有の独自のインジケーターを作成する必要がある場合があります。
サイト管理 > アナリティクス > 分析モデル を使用して、使用可能な指標のリストを表示し、それらのいくつかをモデルに追加できます。
APIの使用例
これは、予測モデルと、アナリティクスAPIを使用してそれらをコーディングする方法のリストです。
脱落リスクのある学生(学生の活動に基づく。Moodle3.4 に含まれています)
- 時分割: 四半期、四半期累積、十分位数、十分位数累積..
- アナライザーのサンプル: 学生の登録(分析可能な要素はコースです)
- target::is_valid_analysable
- 予測用=進行中のコース
- トレーニングの場合=活動のある終了したコース
- target::is_valid_sample = true
- 仮定に基づく(静的) :いいえ、予測は終了したコースデータに基づく必要があります
コースの内容に関与しない(コースの内容に基づく)
- 時分割: 単一範囲
- アナライザーサンプル: コース(分析可能な要素はサイトです)
- target::is_valid_analysable = true
- target::is_valid_sample
- 予測の場合 = コースは開始日に近い
- トレーニングの場合 = トレーニングなし
- 仮定に基づく(静的) :はい、コース活動を簡単に見るだけで十分です(たとえば、コース活動は魅力的ですか?)
指導なし(Moodle 3.4に含まれる、教師が割り当てられていない開始日に近いコース)
- 時分割: 単一範囲
- アナライザーサンプル: コース(分析可能な要素はサイトです)コースを分析可能として使用しても機能します
- target::is_valid_analysable = true
- target::is_valid_sample
- 予測の場合 = 開始日に近いコース
- トレーニングの場合 = トレーニングなし
- 仮定に基づく(静的) :はい、教師がいるかどうかを確認してください
遅い課題の提出(学生の活動に基づく)
- 時分割: 分析可能な終了日に近い(1週間前、X日前...)
- アナライザーのサンプル: 課題の送信(分析可能な要素は活動です)
- target::is_valid_analysable
- 予測の場合 = 課題は提出可能です
- トレーニングの場合 = 過去の割り当て期日
- target::is_valid_sample = true
- 仮定に基づく(静的) :いいえ、予測は以前の学生の活動に基づく必要があります
スパムユーザ(疑わしい活動に基づく)
- 時分割: 2つの部分、1つはユーザ作成から4時間後、もう1つは2日後(単なる例)
- アナライザーのサンプル: ユーザ(分析可能な要素はユーザです)
- target::is_valid_analysable = true
- target::is_valid_sample
- 予測の場合 = ユーザが作成されてから4時間または2日が経過しました
- トレーニングの場合 = ユーザが作成されてから2日が経過しました(ターゲット= 1を計算するために記録されたスパマーフラグ、それ以外の場合はスパマーなし)
- 仮定に基づく(静的) :いいえ、予測はユーザの活動ログに基づく必要がありますが、これは静的モデルとしても実行できます。
悪い時間を過ごしている学生
- 時分割: 四半期累積または十分位累積
- アナライザーのサンプル: 学生の登録(分析可能な要素はコースです)
- target::is_valid_analysable
- 予測用 = 進行中およびコース活動
- トレーニングの場合 = 終了したコース
- target::is_valid_sample = true
- 仮定に基づく(静的) :いいえ、理想的には以前のケースに基づく必要があります
学生を対象としないコース(学生の活動を確認する)
- 時分割: 四半期、累積四半期、十分位数..。
- アナライザーサンプル: コース(分析可能な要素はコースです)
- target::is_valid_analysable = true
- target::is_valid_sample
- 予測用 = 進行中のコース
- トレーニングの場合 = 終了したコース
- 仮定に基づく(静的) :いいえ、活動ログに基づく必要があります
学生は小テストに失敗します(他の学生の小テストの受験、他の活動の学生、小テストに合格するための受験回数などに基づく)
- 時分割: 単一範囲
- アナライザーのサンプル: 活動での学生の成績、別名grade_grades id(分析可能な要素はコースです)
- target::is_valid_analysable
- 予測用 = 小テスト付きの進行中のコース
- トレーニング用 = 小テスト付きの継続コース
- target::is_valid_sample
- 予測の場合 = コースのX%以上の学生が小テストを受験し、サンプル(学生)はまだ小テストを試受験していません
- トレーニングの場合 = 学生が小テストを少なくともX回受験したか(X回受験しても合格しなかった場合は失敗としてカウントされるためX)、または学生は小テストに合格しました
- 仮定に基づく(静的) :いいえ、以前の学生の記録に基づいています
クラスター環境
'analytics/outputdir' 設定は、複数のフロントエンドノードを持つMoodleサイトで使用して、ノード間で共有ディレクトリを指定できます。このディレクトリは、機械学習バックエンドがトレーニング済みのアルゴリズム(内部変数の重みなど)を格納し、後でそれらを使用して予測を取得するために使用できます。 Moodle cronロックは、機械学習アルゴリズムをトレーニングし、それらから予測を取得する分析タスクの複数の実行を防ぎます。