Is there a handy function to rename a variable in an expression?

[simoami]

I'm wondering if there is a handy function or code to rename multiple instances of a variable by name in an expression? This would work similar to Rename Symbol in VS Code.

[josdejong]

I think you can use a regex, but you have to be careful to use word boundries and a case sensitive search.

You can also parse the expression using math.parse(expr), and then use the .transform(...) method to find all SymbolNode occurrences and rename them. Docs: https://mathjs.org/docs/expressions/expression_trees.html (search for the transform method, it has an example).

[gwhitney]

Alternatively, you can use resolve which is basically a variable substitution function, together with the flexible definition of what a "scope" is:

const xToFoo = {
    get: v => v === 'x' ? new math.SymbolNode('foo') : undefined,
    set: () => {},
    keys: () => ['x'],
    has: v => v === 'x'
}
const substituted = math.resolve(math.parse('x + f(x) + y'), xToFoo)
console.log(substituted.toString()) // 'foo + f(foo) + y'

Note that you might be tempted by the much simpler

const subs2 = math.resolve(math.parse('x + f(x) + y'), {x: new math.SymbolNode('foo')})

and that will seem to work, but it will produce a re-entrant mathjs expression in which all of the occurrences of foo are literally the same Node entity, which will work for some simple operations (like converting to a string), but create subtle bugs/errors in more complicated operations (like math.simplify) -- so it is best to avoid this version altogether except possibly in the innards of a function that is just going to do the substitution and return the string and then throw away the resulting parse "tree" (which is no longer a tree after the subs2 resolve operation).

[simoami]

@josdejong @gwhitney Thank you for the suggestions.

I started working on this using the parse() method and the available isXxxxx node validators, but it seems error prone, given some edge cases like: locally defined variables vs externally supplied variables via scope, name spaced variables in dot notations, units mistaken for variable names. I will check out resolve as it seems to be a nice approach and see if it works for us.

Related question: In the past, I had to write a function that outputs all external parameters, as dependencies. This allowed me to scan though expressions that would need to be recomputed if one of their dependent variables changed. This is what ended up working great for us. Do you think it's overkill?

/**
   * Extracts variables used in the expression that are not locally defined.
   * @private
   * @param {MathNode} node - The parsed math expression tree node.
   * @returns {Array<string>} A list of unique variable names found in the expression.
   */
  private extractVariables(node: MathNode): Array<string> {
    const variables: Array<string> = [];
    const localVariables = new Set<string>();

    const traverse = (currentNode: MathNode): void => {
      if (isAssignmentNode(currentNode) && isSymbolNode(currentNode.object)) {
        localVariables.add(currentNode.name);
        traverse((currentNode as AssignmentNode).value);
      } else if (isOperatorNode(currentNode)) {
        for (const arg of currentNode.args) {
          traverse(arg);
        }
      } else if (
        isSymbolNode(currentNode) &&
        !localVariables.has(currentNode.name)
      ) {
        // don't interpret units like 'kg' as variables
        try {
          unit(currentNode.name);
        } catch {
          variables.push(currentNode.name);
        }
      } else if (isFunctionNode(currentNode) || isOperatorNode(currentNode)) {
        for (const arg of currentNode.args) {
          traverse(arg);
        }
      } else if (isParenthesisNode(currentNode)) {
        traverse((currentNode as ParenthesisNode).content);
      } else if (isBlockNode(currentNode)) {
        for (const block of currentNode.blocks) {
          traverse(block.node);
        }
      } else if (isAccessorNode(currentNode)) {
        const variableName = currentNode.toString();
        if (!localVariables.has(variableName)) {
          variables.push(variableName);
        }
      } else if (isArrayNode(currentNode)) {
        for (const item of currentNode.items) {
          traverse(item);
        }
      }
    };

    traverse(node);
    return Array.from(new Set(variables)); // Remove duplicates
  }

[gwhitney]

I'm glad your function worked well to extract free variables for you. From a theoretical perspective, it can't actually be complete or correct. For examples (not meant as an attempt to be comprehensive):

1. It assumes that a variable is bound as soon as it appears in the left-hand position of an assignment, but x does occur as a free variable in the expression x = 1 + x. You should only consider the variable bound after the assignment (so for example there is no free variable x in [x = 1 + y, x]).
2. You have not exhausted all node types, so your function will terminate and miss free variables for example in a RelationalNode like x < 7.
3. I think you may report built-in constants like pi, which you probably don't want to do.
4. I am confused about your AccessorNode case; what is it needed for? An AccessorNode has an object, which is often a SymbolNode, and an index, which is always an IndexNode, but any variables therein will appear in nested SymbolNodes. So I am curious what case you were catching here that didn't get caught by the SymbolNode case...

In particular because of (2), it is best whenever possible to iterate over a parse tree using one of the provided utility methods, which are either "deep" in that they visit the entire subtree of the node they are called on, or "shallow" in that they visit only the node's immediate children: filter (deep), forEach (shallow), traverse (deep), map (shallow), or transform (deep). Each of these takes a callback that is called on each node visited. These utilities know about all node types, so they will visit every appropriate node. And this way, in the callback, you can concentrate just on the relevant node types, and do nothing for the other nodes. This will simplify your code considerably: in your case, you only take actions on assignment nodes, symbol nodes, and maybe accessor nodes -- you can just do nothing on all other node types and let the utility worry about the traversal. In your case, the built in traverse seems most appropriate, although you could possibly use filter instead, except that in the end you want a set of strings rather than an array of SymbolNodes of all of the free variable instances. But you could filter, and then build the set of strings from the result of the filter. See https://mathjs.org/docs/expressions/expression_trees.html for details.

[gwhitney]

units mistaken for variable names. I will check out resolve

Unfortunately, math.resolve will happily substitute foo in for kg. If you want to avoid this behavior, it seems like the easiest way is to ignore requests to substitute variables that happen to have the name of a valid unit, before you ever call resolve. The fact is, because of units like s, mathjs does not decide if an expression is a unit or a variable reference until evaluation time. With this convention, you can use 4s to multiply the value of s in the scope by four, or to represent four seconds -- but the latter is only possible if s is undefined in the scope. The scope and all unit names share a single namespace.

[josdejong]

Good points @simoami about these edge cases.

• local variables: you can protect against that by checking for FunctionAssignmentNode and stopping the transform there, see example below.
• name spaced variables in dot notations: by default it will not be renamed, since a dot notation like the x in "obj.x" is parsed as a ConstantNode and not a SymbolNode. Or would you like have an option to rename the x in such a case? (if so: in the transform function you could detect an AccessorNode containing a ConstantNode with the variable name you want to rename)
• units: right now, when defining a variable that has the same name as a unit, it will be evaluated as the variable value and not the unit. So I think you can ignore checking for units. But if you want alternative behavior, you can test whether a symbol is a unit using math.Unit.isValuelessUnit(symbol) and then either throw an error (not allowing to overwrite a unit), rename it, or leave it as a unit.

I think the following example may be close to what you are looking for?

import { parse, SymbolNode } from 'mathjs'

console.log(rename(parse('x ^ 2 + y'), 'x', 'foo').toString())        // "foo ^ 2 + y"
console.log(rename(parse('f(x) = x ^ 2'), 'x', 'foo').toString())     // "f(x) = x ^ 2"
console.log(rename(parse('f(y) = x ^ 2 + y'), 'x', 'foo').toString()) // "f(y) = foo ^ 2 + y"
console.log(rename(parse('obj.x + 2'), 'x', 'foo').toString())        // "obj.x + 2"

function rename(expr, name, newName) {
  return expr.transform(node => {
    if (node.isSymbolNode && node.name === name) {
      return new SymbolNode(newName)
    }

    if (node.isFunctionAssignmentNode && node.params.includes(name)) {
      // prevent rewriting local variables like renaming "x" in "f(x) = x^2"
      return node.clone()
    }

    return node
  })
}