Developer Documentation

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
  • Differences Between: [Versions 37 and 311]

    Prediction model representation.

    Copyright: 2016 David Monllao {@link}
    License: GNU GPL v3 or later
    File Size: 2034 lines (73 kb)
    Included or required:0 times
    Referenced: 0 times
    Includes or requires: 0 files

    Defines 2 classes

    Class: model  - X-Ref

    Prediction model representation.

    __construct($model)   X-Ref

    param: int|\stdClass $model
    return: void

    is_available()   X-Ref
    Quick safety check to discard site models which required components are not available anymore.

    return: bool

    get_id()   X-Ref
    Returns the model id.

    return: int

    get_model_obj()   X-Ref
    Returns a plain \stdClass with the model data.

    return: \stdClass

    get_target()   X-Ref
    Returns the model target.

    return: \core_analytics\local\target\base

    get_indicators()   X-Ref
    Returns the model indicators.

    return: \core_analytics\local\indicator\base[]

    get_potential_indicators()   X-Ref
    Returns the list of indicators that could potentially be used by the model target.

    It includes the indicators that are part of the model.

    return: \core_analytics\local\indicator\base[]

    get_analyser($options = array()   X-Ref
    Returns the model analyser (defined by the model target).

    param: array $options Default initialisation with no options.
    return: \core_analytics\local\analyser\base

    init_analyser($options = array()   X-Ref
    Initialises the model analyser.

    param: array $options
    return: void

    Class: does  - X-Ref

    get_time_splitting()   X-Ref
    Returns the model time splitting method.

    return: \core_analytics\local\time_splitting\base|false Returns false if no time splitting.

    get_potential_timesplittings()   X-Ref
    Returns the time-splitting methods that can be used by this model.

    return: \core_analytics\local\time_splitting\base[]

    create(\core_analytics\local\target\base $target, array $indicators,$timesplittingid = false, $processor = null)   X-Ref
    Creates a new model. Enables it if $timesplittingid is specified.

    param: \core_analytics\local\target\base $target
    param: \core_analytics\local\indicator\base[] $indicators
    param: string|false $timesplittingid The time splitting method id (its fully qualified class name)
    param: string|null $processor The machine learning backend this model will use.
    return: \core_analytics\model

    exists(\core_analytics\local\target\base $target, $indicators = false)   X-Ref
    Does this model exist?

    If no indicators are provided it considers any model with the provided
    target a match.

    param: \core_analytics\local\target\base $target
    param: \core_analytics\local\indicator\base[]|false $indicators
    return: bool

    update($enabled, $indicators = false, $timesplittingid = '', $predictionsprocessor = false,$contextids = false)   X-Ref
    Updates the model.

    param: int|bool $enabled
    param: \core_analytics\local\indicator\base[]|false $indicators False to respect current indicators
    param: string|false $timesplittingid False to respect current time splitting method
    param: string|false $predictionsprocessor False to respect current predictors processor value
    param: int[]|false $contextids List of context ids for this model. False to respect the current list of contexts.
    return: void

    delete()   X-Ref
    Removes the model.

    return: void

    evaluate($options = array()   X-Ref
    Evaluates the model.

    This method gets the site contents (through the analyser) creates a .csv dataset
    with them and evaluates the model prediction accuracy multiple times using the
    machine learning backend. It returns an object where the model score is the average
    prediction accuracy of all executed evaluations.

    param: array $options
    return: \stdClass[]

    train()   X-Ref
    Trains the model using the site contents.

    This method prepares a dataset from the site contents (through the analyser)
    and passes it to the machine learning backends. Static models are skipped as
    they do not require training.

    return: \stdClass

    predict()   X-Ref
    Get predictions from the site contents.

    It analyses the site contents (through analyser classes) looking for samples
    ready to receive predictions. It generates a dataset with all samples ready to
    get predictions and it passes it to the machine learning backends or to the
    targets based on assumptions to get the predictions.

    return: \stdClass

    get_predictions_processor($checkisready = true)   X-Ref
    Returns the model predictions processor.

    param: bool $checkisready
    return: \core_analytics\predictor

    format_predictor_predictions($predictorresult)   X-Ref
    Formats the predictor results.

    param: array $predictorresult
    return: array

    execute_prediction_callbacks(&$predictions, $indicatorcalculations)   X-Ref
    Execute the prediction callbacks defined by the target.

    param: \stdClass[] $predictions
    param: array $indicatorcalculations
    return: array

    trigger_insights($samplecontexts, $predictionrecords)   X-Ref
    Generates insights and updates the cache.

    param: \context[] $samplecontexts
    param: \stdClass[] $predictionrecords
    return: void

    get_static_predictions(&$indicatorcalculations)   X-Ref
    Get predictions from a static model.

    param: array $indicatorcalculations
    return: \stdClass[]

    prepare_prediction_record($sampleid, $rangeindex, $prediction, $predictionscore, $calculations)   X-Ref
    Stores the prediction in the database.

    param: int $sampleid
    param: int $rangeindex
    param: int $prediction
    param: float $predictionscore
    param: string $calculations
    return: \context

    save_predictions($records)   X-Ref
    Save the prediction objects.

    param: \stdClass[] $records

    enable($timesplittingid = false)   X-Ref
    Enabled the model using the provided time splitting method.

    param: string|false $timesplittingid False to respect the current time splitting method.
    return: void

    is_static()   X-Ref
    Is this a static model (as defined by the target)?.

    Static models are based on assumptions instead of in machine learning
    backends results.

    return: bool

    is_enabled()   X-Ref
    Is this model enabled?

    return: bool

    is_trained()   X-Ref
    Is this model already trained?

    return: bool

    mark_as_trained()   X-Ref
    Marks the model as trained

    return: void

    get_predictions_contexts($skiphidden = true)   X-Ref
    Get the contexts with predictions.

    param: bool $skiphidden Skip hidden predictions
    return: \stdClass[]

    any_prediction_obtained()   X-Ref
    Has this model generated predictions?

    We don't check analytics_predictions table because targets have the ability to
    ignore some predicted values, if that is the case predictions are not even stored
    in db.

    return: bool

    uses_insights()   X-Ref
    Whether this model generates insights or not (defined by the model's target).

    return: bool

    predictions_exist(\context $context)   X-Ref
    Whether predictions exist for this context.

    param: \context $context
    return: bool

    get_predictions(\context $context, $skiphidden = true, $page = false, $perpage = 100)   X-Ref
    Gets the predictions for this context.

    param: \context $context
    param: bool $skiphidden Skip hidden predictions
    param: int $page The page of results to fetch. False for all results.
    param: int $perpage The max number of results to fetch. Ignored if $page is false.
    return: array($total, \core_analytics\prediction[])

    get_prediction_actions(?\context $context)   X-Ref
    Returns the actions executed by users on the predictions.

    param: \context|null $context
    return: \moodle_recordset

    prediction_sample_data($predictionobj)   X-Ref
    Returns the sample data of a prediction.

    param: \stdClass $predictionobj
    return: array

    predictions_sample_data(array $predictionrecords)   X-Ref
    Returns the samples data of the provided predictions.

    param: \stdClass[] $predictionrecords
    return: array

    append_calculations_info(array $predictionrecords, array $samplesdata)   X-Ref
    Appends the calculation info to the samples data.

    param: \stdClass[] $predictionrecords
    param: array $samplesdata
    return: array

    prediction_sample_description(\core_analytics\prediction $prediction)   X-Ref
    Returns the description of a sample

    param: \core_analytics\prediction $prediction
    return: array 2 elements: list(string, \renderable)

    default_output_dir()   X-Ref
    Returns the default output directory for prediction processors

    return: string

    get_output_dir($subdirs = array()   X-Ref
    Returns the output directory for prediction processors.

    Directory structure as follows:
    - Evaluation runs:
    - Training  & prediction runs:

    param: array $subdirs
    param: bool $onlymodelid Preference over $subdirs
    return: string

    get_unique_id()   X-Ref
    Returns a unique id for this model.

    This id should be unique for this site.

    return: string

    export(\renderer_base $output)   X-Ref
    Exports the model data for displaying it in a template.

    param: \renderer_base $output The renderer to use for exporting
    return: \stdClass

    export_model(string $zipfilename, bool $includeweights = true)   X-Ref
    Exports the model data to a zip file.

    param: string $zipfilename
    param: bool $includeweights Include the model weights if available
    return: string Zip file path

    import_model(string $zipfilepath)   X-Ref
    Imports the provided model.

    Note that this method assumes that model_config::check_dependencies has already been called.

    param: string $zipfilepath Zip file path
    return: \core_analytics\model

    can_export_configuration()   X-Ref
    Can this model be exported?

    return: bool

    get_logs($limitfrom = 0, $limitnum = 0)   X-Ref
    Returns the model logs data.

    param: int $limitfrom
    param: int $limitnum
    return: \stdClass[]

    get_training_data()   X-Ref
    Merges all training data files into one and returns it.

    return: \stored_file|false

    trained_locally()   X-Ref
    Has the model been trained using data from this site?

    This method is useful to determine if a trained model can be evaluated as
    we can not use the same data for training and for evaluation.

    return: bool

    flag_file_as_used(\stored_file $file, $action)   X-Ref
    Flag the provided file as used for training or prediction.

    param: \stored_file $file
    param: string $action
    return: void

    log_result($timesplittingid, $score, $dir = false, $info = false, $evaluationmode = 'configuration')   X-Ref
    Log the evaluation results in the database.

    param: string $timesplittingid
    param: float $score
    param: string $dir
    param: array $info
    param: string $evaluationmode
    return: int The inserted log id

    indicator_classes($indicators)   X-Ref
    Utility method to return indicator class names from a list of indicator objects

    param: \core_analytics\local\indicator\base[] $indicators
    return: string[]

    clear()   X-Ref
    Clears the model training and prediction data.

    Executed after updating model critical elements like the time splitting method
    or the indicators.

    return: void

    get_name()   X-Ref
    Returns the name of the model.

    By default, models use their target's name as their own name. They can have their explicit name, too. In which
    case, the explicit name is used instead of the default one.

    return: string|lang_string

    rename(string $name)   X-Ref
    Renames the model to the given name.

    When given an empty string, the model falls back to using the associated target's name as its name.

    param: string $name The new name for the model, empty string for using the default name.

    inplace_editable_name()   X-Ref
    Returns an inplace editable element with the model's name.

    return: \core\output\inplace_editable

    invalid_timesplitting_selected()   X-Ref
    Returns true if the time-splitting method used by this model is invalid for this model.

    return: bool

    add_prediction_ids($predictionrecords)   X-Ref
    Adds the id from {analytics_predictions} db table to the prediction \stdClass objects.

    param: \stdClass[] $predictionrecords
    return: \stdClass[] The prediction records including their ids in {analytics_predictions} db table.

    get_samples(array $sampleids)   X-Ref
    Wrapper around analyser's get_samples to skip DB's max-number-of-params exception.

    param: array  $sampleids
    return: array

    get_contexts()   X-Ref
    Contexts where this model should be active.

    return: \context[] Empty array if there are no context restrictions.

    purge_insights_cache()   X-Ref
    Purges the insights cache.

    heavy_duty_mode()   X-Ref
    Increases system memory and time limits.

    return: void