@khanacademy/perseus 0.0.1 → 0.2.1

package/src/widgets/grapher/util.jsx

@@ -0,0 +1,806 @@
+/* eslint-disable one-var */
+// @flow
+import {point as kpoint} from "@khanacademy/kmath";
+import * as React from "react";
+import _ from "underscore";
+
+import Graphie from "../../components/graphie.jsx";
+import {getDependencies} from "../../dependencies.js";
+import Util from "../../util.js";
+
+import type {Coord} from "../../interactive2/types";
+import type {PerseusScore} from "../../types";
+
+// $FlowFixMe[prop-missing]
+const Plot = Graphie.Plot;
+
+export const DEFAULT_BACKGROUND_IMAGE = {
+    url: null,
+};
+
+// TODO(charlie): These really need to go into a utility file as they're being
+// used by both interactive-graph and now grapher.
+function canonicalSineCoefficients(coeffs) {
+    // For a curve of the form f(x) = a * Sin(b * x - c) + d,
+    // this function ensures that a, b > 0, and c is its
+    // smallest possible positive value.
+    let amplitude = coeffs[0];
+    let angularFrequency = coeffs[1];
+    let phase = coeffs[2];
+    const verticalOffset = coeffs[3];
+
+    // Guarantee a > 0
+    if (amplitude < 0) {
+        amplitude *= -1;
+        angularFrequency *= -1;
+        phase *= -1;
+    }
+
+    const period = 2 * Math.PI;
+    // Guarantee b > 0
+    if (angularFrequency < 0) {
+        angularFrequency *= -1;
+        phase *= -1;
+        phase += period / 2;
+    }
+
+    // Guarantee c is smallest possible positive value
+    while (phase > 0) {
+        phase -= period;
+    }
+    while (phase < 0) {
+        phase += period;
+    }
+
+    return [amplitude, angularFrequency, phase, verticalOffset];
+}
+
+function canonicalTangentCoefficients(coeffs) {
+    // For a curve of the form f(x) = a * Tan(b * x - c) + d,
+    // this function ensures that a, b > 0, and c is its
+    // smallest possible positive value.
+    let amplitude = coeffs[0];
+    let angularFrequency = coeffs[1];
+    let phase = coeffs[2];
+    const verticalOffset = coeffs[3];
+
+    // Guarantee a > 0
+    if (amplitude < 0) {
+        amplitude *= -1;
+        angularFrequency *= -1;
+        phase *= -1;
+    }
+
+    const period = Math.PI;
+    // Guarantee b > 0
+    if (angularFrequency < 0) {
+        angularFrequency *= -1;
+        phase *= -1;
+        phase += period / 2;
+    }
+
+    // Guarantee c is smallest possible positive value
+    while (phase > 0) {
+        phase -= period;
+    }
+    while (phase < 0) {
+        phase += period;
+    }
+
+    return [amplitude, angularFrequency, phase, verticalOffset];
+}
+
+const PlotDefaults = {
+    areEqual: function (coeffs1, coeffs2) {
+        return Util.deepEq(coeffs1, coeffs2);
+    },
+
+    Movable: Plot,
+
+    getPropsForCoeffs: function (coeffs) {
+        return {
+            fn: _.partial(this.getFunctionForCoeffs, coeffs),
+        };
+    },
+};
+
+const Linear = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/67aaf581e6d9ef9038c10558a1f70ac21c11c9f8.png",
+
+    defaultCoords: [
+        [0.25, 0.75],
+        [0.75, 0.75],
+    ],
+
+    getCoefficients: function (coords) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        const denom = p2[0] - p1[0];
+        const num = p2[1] - p1[1];
+
+        if (denom === 0) {
+            return;
+        }
+
+        const m = num / denom;
+        const b = p2[1] - m * p2[0];
+        return [m, b];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const m = coeffs[0],
+            b = coeffs[1];
+        return m * x + b;
+    },
+
+    getEquationString: function (coords) {
+        const coeffs = this.getCoefficients(coords);
+        const m = coeffs[0],
+            b = coeffs[1];
+        return "y = " + m.toFixed(3) + "x + " + b.toFixed(3);
+    },
+});
+
+const Quadratic = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/e23d36e6fc29ee37174e92c9daba2a66677128ab.png",
+
+    defaultCoords: [
+        [0.5, 0.5],
+        [0.75, 0.75],
+    ],
+
+    // $FlowFixMe[prop-missing]
+    Movable: Graphie.Parabola,
+
+    getCoefficients: function (coords) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        // Parabola with vertex (h, k) has form: y = a * (h - k)^2 + k
+        const h = p1[0];
+        const k = p1[1];
+
+        // Use these to calculate familiar a, b, c
+        const a = (p2[1] - k) / ((p2[0] - h) * (p2[0] - h));
+        const b = -2 * h * a;
+        const c = a * h * h + k;
+
+        return [a, b, c];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return (a * x + b) * x + c;
+    },
+
+    getPropsForCoeffs: function (coeffs) {
+        return {
+            a: coeffs[0],
+            b: coeffs[1],
+            c: coeffs[2],
+        };
+    },
+
+    getEquationString: function (coords) {
+        const coeffs = this.getCoefficients(coords);
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return (
+            "y = " +
+            a.toFixed(3) +
+            "x^2 + " +
+            b.toFixed(3) +
+            "x + " +
+            c.toFixed(3)
+        );
+    },
+});
+
+const Sinusoid = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/3d68e7718498475f53b206c2ab285626baf8857e.png",
+
+    defaultCoords: [
+        [0.5, 0.5],
+        [0.6, 0.6],
+    ],
+
+    // $FlowFixMe[prop-missing]
+    Movable: Graphie.Sinusoid,
+
+    getCoefficients: function (coords) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        const a = p2[1] - p1[1];
+        const b = Math.PI / (2 * (p2[0] - p1[0]));
+        const c = p1[0] * b;
+        const d = p1[1];
+
+        return [a, b, c, d];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2],
+            d = coeffs[3];
+        return a * Math.sin(b * x - c) + d;
+    },
+
+    getPropsForCoeffs: function (coeffs) {
+        return {
+            a: coeffs[0],
+            b: coeffs[1],
+            c: coeffs[2],
+            d: coeffs[3],
+        };
+    },
+
+    getEquationString: function (coords) {
+        const coeffs = this.getCoefficients(coords);
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2],
+            d = coeffs[3];
+        return (
+            "y = " +
+            a.toFixed(3) +
+            " sin(" +
+            b.toFixed(3) +
+            "x - " +
+            c.toFixed(3) +
+            ") + " +
+            d.toFixed(3)
+        );
+    },
+
+    areEqual: function (coeffs1, coeffs2) {
+        return Util.deepEq(
+            canonicalSineCoefficients(coeffs1),
+            canonicalSineCoefficients(coeffs2),
+        );
+    },
+});
+
+const Tangent = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/7db80d23c35214f98659fe1cf0765811c1bbfbba.png",
+
+    defaultCoords: [
+        [0.5, 0.5],
+        [0.75, 0.75],
+    ],
+
+    getCoefficients: function (coords) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        const a = p2[1] - p1[1];
+        const b = Math.PI / (4 * (p2[0] - p1[0]));
+        const c = p1[0] * b;
+        const d = p1[1];
+
+        return [a, b, c, d];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2],
+            d = coeffs[3];
+        return a * Math.tan(b * x - c) + d;
+    },
+
+    getEquationString: function (coords) {
+        const coeffs = this.getCoefficients(coords);
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2],
+            d = coeffs[3];
+        return (
+            "y = " +
+            a.toFixed(3) +
+            " sin(" +
+            b.toFixed(3) +
+            "x - " +
+            c.toFixed(3) +
+            ") + " +
+            d.toFixed(3)
+        );
+    },
+
+    areEqual: function (coeffs1, coeffs2) {
+        return Util.deepEq(
+            canonicalTangentCoefficients(coeffs1),
+            canonicalTangentCoefficients(coeffs2),
+        );
+    },
+});
+
+const Exponential = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/9cbfad55525e3ce755a31a631b074670a5dad611.png",
+
+    defaultCoords: [
+        [0.5, 0.55],
+        [0.75, 0.75],
+    ],
+
+    defaultAsymptote: [
+        [0, 0.5],
+        [1.0, 0.5],
+    ],
+
+    /**
+     * Add extra constraints for movement of the points or asymptote (below):
+     *   newCoord: [x, y]
+     *     The end position of the point or asymptote endpoint
+     *   oldCoord: [x, y]
+     *     The old position of the point or asymptote endpoint
+     *   coords:
+     *     An array of coordinates representing the proposed end configuration
+     *     of the plot coordinates.
+     *   asymptote:
+     *     An array of coordinates representing the proposed end configuration
+     *     of the asymptote.
+     *
+     * Return: either a coordinate (to be used as the resulting coordinate of
+     * the move) or a boolean, where `true` uses newCoord as the resulting
+     * coordinate, and `false` uses oldCoord as the resulting coordinate.
+     */
+    extraCoordConstraint: function (
+        newCoord,
+        oldCoord,
+        coords,
+        asymptote,
+        graph,
+    ) {
+        const y = _.head(asymptote)[1];
+        return _.all(coords, (coord) => coord[1] !== y);
+    },
+
+    extraAsymptoteConstraint: function (
+        newCoord,
+        oldCoord,
+        coords,
+        asymptote,
+        graph,
+    ) {
+        const y = newCoord[1];
+        const isValid =
+            _.all(coords, (coord) => coord[1] > y) ||
+            _.all(coords, (coord) => coord[1] < y);
+
+        if (isValid) {
+            return [oldCoord[0], y];
+        }
+        // Snap the asymptote as close as possible, i.e., if the user moves
+        // the mouse really quickly into an invalid region
+        const oldY = oldCoord[1];
+        const wasBelow = _.all(coords, (coord) => coord[1] > oldY);
+        if (wasBelow) {
+            const bottomMost = _.min(_.map(coords, (coord) => coord[1]));
+            return [oldCoord[0], bottomMost - graph.snapStep[1]];
+        }
+        const topMost = _.max(_.map(coords, (coord) => coord[1]));
+        return [oldCoord[0], topMost + graph.snapStep[1]];
+    },
+
+    allowReflectOverAsymptote: true,
+
+    getCoefficients: function (coords, asymptote) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        const c = _.head(asymptote)[1];
+        const b = Math.log((p1[1] - c) / (p2[1] - c)) / (p1[0] - p2[0]);
+        const a = (p1[1] - c) / Math.exp(b * p1[0]);
+        return [a, b, c];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return a * Math.exp(b * x) + c;
+    },
+
+    getEquationString: function (coords, asymptote) {
+        if (!asymptote) {
+            return null;
+        }
+        const coeffs = this.getCoefficients(coords, asymptote);
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return (
+            "y = " +
+            a.toFixed(3) +
+            "e^(" +
+            b.toFixed(3) +
+            "x) + " +
+            c.toFixed(3)
+        );
+    },
+});
+
+const Logarithm = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/f6491e99d34af34d924bfe0231728ad912068dc3.png",
+
+    defaultCoords: [
+        [0.55, 0.5],
+        [0.75, 0.75],
+    ],
+
+    defaultAsymptote: [
+        [0.5, 0],
+        [0.5, 1.0],
+    ],
+
+    extraCoordConstraint: function (
+        newCoord,
+        oldCoord,
+        coords,
+        asymptote,
+        graph,
+    ) {
+        const x = _.head(asymptote)[0];
+        return (
+            _.all(coords, (coord) => coord[0] !== x) &&
+            coords[0][1] !== coords[1][1]
+        );
+    },
+
+    extraAsymptoteConstraint: function (
+        newCoord,
+        oldCoord,
+        coords,
+        asymptote,
+        graph,
+    ) {
+        const x = newCoord[0];
+        const isValid =
+            _.all(coords, (coord) => coord[0] > x) ||
+            _.all(coords, (coord) => coord[0] < x);
+
+        if (isValid) {
+            return [x, oldCoord[1]];
+        }
+        // Snap the asymptote as close as possible, i.e., if the user moves
+        // the mouse really quickly into an invalid region
+        const oldX = oldCoord[0];
+        const wasLeft = _.all(coords, (coord) => coord[0] > oldX);
+        if (wasLeft) {
+            const leftMost = _.min(_.map(coords, (coord) => coord[0]));
+            return [leftMost - graph.snapStep[0], oldCoord[1]];
+        }
+        const rightMost = _.max(_.map(coords, (coord) => coord[0]));
+        return [rightMost + graph.snapStep[0], oldCoord[1]];
+    },
+
+    allowReflectOverAsymptote: true,
+
+    getCoefficients: function (coords, asymptote) {
+        // It's easiest to calculate the logarithm's coefficients by thinking
+        // about it as the inverse of the exponential, so we flip x and y and
+        // perform some algebra on the coefficients. This also unifies the
+        // logic between the two 'models'.
+        const flip = (coord) => [coord[1], coord[0]];
+        const inverseCoeffs = Exponential.getCoefficients(
+            _.map(coords, flip),
+            _.map(asymptote, flip),
+        );
+        const c = -inverseCoeffs[2] / inverseCoeffs[0];
+        const b = 1 / inverseCoeffs[0];
+        const a = 1 / inverseCoeffs[1];
+        return [a, b, c];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x, asymptote) {
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return a * Math.log(b * x + c);
+    },
+
+    getEquationString: function (coords, asymptote) {
+        if (!asymptote) {
+            return null;
+        }
+        const coeffs = this.getCoefficients(coords, asymptote);
+        const a = coeffs[0],
+            b = coeffs[1],
+            c = coeffs[2];
+        return (
+            "y = ln(" +
+            a.toFixed(3) +
+            "x + " +
+            b.toFixed(3) +
+            ") + " +
+            c.toFixed(3)
+        );
+    },
+});
+
+const AbsoluteValue = _.extend({}, PlotDefaults, {
+    url: "https://ka-perseus-graphie.s3.amazonaws.com/8256a630175a0cb1d11de223d6de0266daf98721.png",
+
+    defaultCoords: [
+        [0.5, 0.5],
+        [0.75, 0.75],
+    ],
+
+    getCoefficients: function (coords) {
+        const p1 = coords[0];
+        const p2 = coords[1];
+
+        const denom = p2[0] - p1[0];
+        const num = p2[1] - p1[1];
+
+        if (denom === 0) {
+            return;
+        }
+
+        let m = Math.abs(num / denom);
+        if (p2[1] < p1[1]) {
+            m *= -1;
+        }
+        const horizontalOffset = p1[0];
+        const verticalOffset = p1[1];
+
+        return [m, horizontalOffset, verticalOffset];
+    },
+
+    getFunctionForCoeffs: function (coeffs, x) {
+        const m = coeffs[0],
+            horizontalOffset = coeffs[1],
+            verticalOffset = coeffs[2];
+        return m * Math.abs(x - horizontalOffset) + verticalOffset;
+    },
+
+    getEquationString: function (coords) {
+        const coeffs = this.getCoefficients(coords);
+        const m = coeffs[0],
+            horizontalOffset = coeffs[1],
+            verticalOffset = coeffs[2];
+        return (
+            "y = " +
+            m.toFixed(3) +
+            "| x - " +
+            horizontalOffset.toFixed(3) +
+            "| + " +
+            verticalOffset.toFixed(3)
+        );
+    },
+});
+
+/* Utility functions for dealing with graphing interfaces. */
+const functionTypeMapping = {
+    linear: Linear,
+    quadratic: Quadratic,
+    sinusoid: Sinusoid,
+    tangent: Tangent,
+    exponential: Exponential,
+    logarithm: Logarithm,
+    absolute_value: AbsoluteValue,
+};
+
+export const allTypes: $FlowFixMe = _.keys(functionTypeMapping);
+
+export function functionForType(
+    // TODO(jeremy): Actually `$Keys<typeof functionTypeMapping>` but that
+    // triggers Flow to require all of our Plot types to be fully typed which
+    // is a big amount of work/change.
+    type: string,
+): $FlowFixMe {
+    return functionTypeMapping[type];
+}
+
+export const validate = (
+    state: $FlowFixMe,
+    rubric: $FlowFixMe,
+): PerseusScore => {
+    if (state.type !== rubric.correct.type) {
+        return {
+            type: "points",
+            earned: 0,
+            total: 1,
+            message: null,
+        };
+    }
+
+    // We haven't moved the coords
+    if (state.coords == null) {
+        return {
+            type: "invalid",
+            message: null,
+        };
+    }
+
+    // Get new function handler for grading
+    const grader = functionForType(state.type);
+    const guessCoeffs = grader.getCoefficients(state.coords, state.asymptote);
+    const correctCoeffs = grader.getCoefficients(
+        rubric.correct.coords,
+        rubric.correct.asymptote,
+    );
+
+    if (guessCoeffs == null || correctCoeffs == null) {
+        return {
+            type: "invalid",
+            message: null,
+        };
+    }
+    if (grader.areEqual(guessCoeffs, correctCoeffs)) {
+        return {
+            type: "points",
+            earned: 1,
+            total: 1,
+            message: null,
+        };
+    }
+    return {
+        type: "points",
+        earned: 0,
+        total: 1,
+        message: null,
+    };
+};
+
+export const getEquationString = (props: $FlowFixMe): string => {
+    const plot = props.plot;
+    if (plot.type && plot.coords) {
+        const handler = functionForType(plot.type);
+        const result = handler.getEquationString(plot.coords, plot.asymptote);
+        return result || "";
+    }
+    return "";
+};
+
+export const pointsFromNormalized = (
+    coordsList: $ReadOnlyArray<Coord>,
+    range: [Coord, Coord],
+    step: [number, number],
+    snapStep: [number, number],
+): $ReadOnlyArray<Coord> => {
+    const numSteps = function (range, step) {
+        return Math.floor((range[1] - range[0]) / step);
+    };
+
+    return coordsList.map((coords) => {
+        const unsnappedPoint = coords.map((coord, i) => {
+            const currRange = range[i];
+            const currStep = step[i];
+            const nSteps = numSteps(currRange, currStep);
+            const tick = Math.round(coord * nSteps);
+            return currRange[0] + currStep * tick;
+        });
+        // In some graphing widgets, e.g. interactive-graph, you can rely
+        // on the Graphie to handle snapping. Here, we need the points
+        // returned to already be snapped so that the plot that goes
+        // through them is correct.
+        // $FlowFixMe[invalid-tuple-arity] improve unsnappedPoint type so it knows arity
+        return kpoint.roundTo(unsnappedPoint, snapStep);
+    });
+};
+
+export const maybePointsFromNormalized = (
+    coordsList: ?$ReadOnlyArray<Coord>,
+    range: [Coord, Coord],
+    step: [number, number],
+    snapStep: [number, number],
+): ?$ReadOnlyArray<Coord> => {
+    if (coordsList) {
+        return pointsFromNormalized(coordsList, range, step, snapStep);
+    }
+    return coordsList;
+};
+
+/* Given a plot type, return the appropriate default value for a grapher
+ * widget's plot props: type, default coords, default asymptote. */
+export const defaultPlotProps = (
+    type: string,
+    graph: $FlowFixMe,
+): $FlowFixMe => {
+    // The coords are null by default, to indicate that the user has not
+    // moved them from the default position, and that this widget should
+    // therefore be considered empty and ineligible for grading. The user
+    // *can* move the coords from the default position and then back if
+    // they really want to submit the default coords as their answer, but
+    // we currently don't write questions that require this.
+    //
+    // We *do* write questions in which the asymptote should be left in
+    // the default position. For this reason, we fill in the default
+    // asymptote rather than leaving it null; if the user moves the coords
+    // but not the asymptote, the widget is non-empty and eligible for
+    // grading.
+    //
+    // TODO(mattdr): Consider an updated scoring function that marks the
+    // default coords as empty *unless* they're the correct coords. This
+    // would remove this default-coords-are-always-wrong constraints on
+    // the questions we write, while still maintaining our kind behavior
+    // when users forget to update a widget... but we'd also be revealing
+    // extra information. It would be valid to always submit the default
+    // widget before even reading the question; you can't lose, but you
+    // might get a free win.
+    const model = functionForType(type);
+    const gridStep = [1, 1];
+    const snapStep = Util.snapStepFromGridStep(gridStep);
+    return {
+        type,
+        asymptote: maybePointsFromNormalized(
+            model.defaultAsymptote,
+            graph.range,
+            graph.step,
+            snapStep,
+        ),
+        coords: null,
+    };
+};
+
+/* Given a list of available types, choose which to use. */
+export const chooseType = _.first;
+
+export const getGridAndSnapSteps = (
+    options: $FlowFixMe,
+    boxSize: number,
+): {|
+    gridStep: [number, number],
+    snapStep: [number, number],
+|} => {
+    const gridStep =
+        options.gridStep ||
+        Util.getGridStep(options.range, options.step, boxSize);
+    const snapStep = options.snapStep || Util.snapStepFromGridStep(gridStep);
+    return {
+        gridStep: gridStep,
+        snapStep: snapStep,
+    };
+};
+
+const defaultGraph: {|
+    labels: $ReadOnlyArray<string>,
+    range: [Coord, Coord],
+    step: [number, number],
+    backgroundImage: $FlowFixMe,
+    markings: string,
+    rulerLabel: string,
+    rulerTicks: number,
+    valid: boolean,
+    showTooltips: boolean,
+|} = {
+    labels: ["x", "y"],
+    range: [
+        [-10, 10],
+        [-10, 10],
+    ],
+    step: [1, 1],
+    backgroundImage: DEFAULT_BACKGROUND_IMAGE,
+    markings: "graph",
+    rulerLabel: "",
+    rulerTicks: 10,
+    valid: true,
+    showTooltips: false,
+};
+const defaultPlot = defaultPlotProps("linear", defaultGraph);
+
+export const DEFAULT_GRAPHER_PROPS: $FlowFixMe = {
+    graph: defaultGraph,
+    plot: defaultPlot,
+    availableTypes: [defaultPlot.type],
+};
+
+export const typeToButton = (type: string): $FlowFixMe => {
+    const capitalized = type.charAt(0).toUpperCase() + type.substring(1);
+    const staticUrl = getDependencies().staticUrl;
+
+    return {
+        value: type,
+        title: capitalized,
+        content: (
+            <img src={staticUrl(functionForType(type).url)} alt={capitalized} />
+        ),
+    };
+};