Creating Custom "Mode Commands" in Sage Worksheets
• smc
What is a Mode Command?
By default, running a cell in a Sage worksheet causes the input to be run as Sage commands, with output from Sage written to the output of the cell. Mode commands in a Sage worksheet cause the input to be run through some other process to create cell output. For example,
- Typing
%md
at the start of a cell causes cell input to be rendered as markdown in the cell output. - Typing
%r
causes cell input to be treated as statements in the R language, with corresponding output. - Typing
%HTML
causes cell input to be treated as HTML, rendered as the output.
There are many built-in modes (e.g. Cython, GAP, Pari, R, Python, Markdown, HTML, etc…)
Note: If it is not the default mode of your *.sagews
worksheet, a mode command must be the first line of a cell. In other words, make sure the command %md
, %r
, or %HTML
is the first line of a cell.
Alternatively, you can make any mode the default for all cells in the worksheet using %default_mode <some_mode>
. Then all cells will be using that chosen mode. If you choose this approach, you may still explicitly use %sage
for cells you want processed by the Sage interpreter (or %foo
to explicitly switch to any non-default mode).
There is an entire section of the FAQ page SageMathCloud Worksheet (and User Interface) Help dedicated to questions about the built-in modes. It had 10 questions-and-answers in it as of July 28, 2016.
Is there a list of all currently supported % modes in SageMathCloud?
You can view available built-in modes by selecting Help > Mode commands in the Sage toolbar while cursor is in a sage cell. That will
insert the line print('\n'.join(modes()))
into the current cell.
What is a Custom Mode Command?
Custom mode commands are modes defined by the user. Like any mode command, a custom mode command processes the input section of a cell and writes the output. As stated in the help for modes,
Create your own mode command by defining a function that takes a string as input and outputs a string. (Yes, it is that simple.)
Examples of Custom Mode Commands
Custom mode commands can be used to
- render or compile cell input into cell output
- send commands to other processes and show the results
Here are some examples:
Example 1: View CSV data as a table
Define the mode in a sage cell, as follows:
Input:
Output:
NOTE: Sage’s show
command is also aware of Pandas tables,
so if you instead define
then %csv_table
will produce nice HTML output.
Example 2: View JSON converted to YAML
Define the mode:
Input:
Output:
Example 3: Convert Units of Measure
In this example, each input line is a number with units, possibly followed by target units. If target units are not specified, SI units are the target. This example uses the Sage Units of Measurement package.
Define the mode:
Input:
Output:
Example 4: Display Reverse Complement of Nucleotide Sequences
This example uses Biopython, which is already installed on SageMathCloud.
Define the mode:
Input:
Output:
Example 5: Run Multiple Shell Processes
Suppose you want several bash processes with different working directories or environment variables controlled from the same worksheet. You can use the built-in jupyter
command to create several custom modes.
More information on “the sage-jupyter bridge” is available at Sage Jupyter. Code creating a mode for anaconda3 is available by selecting Modes > Jupyter bridge. You can view available Jupyter kernels by selecting Help > Jupyter kernels in the Sage toolbar while cursor is in a sage cell. That will
insert the line print(jupyter.available_kernels())
into the current cell.
Define the modes:
Cell 1:
Cell 2:
Cell 3:
Example 6: Connect to Remote Server and Run Shell Commands
In this example, any cell in the custom mode consists of shell commands to be run on a remote server. The same session is used for all cells in the given mode.
Notes:
- The SageMathCloud project must have Internet access. This is an upgrade, only available to users with a paid subscription. (See also “Why Should I Purchase a Subscription?”.)
- Configure ssh public and private keys with empty passphrase.
- Set host and user for the remote connection.
- You may want to set IdentityFile in your ~/.ssh/config file.
Define the mode:
Input:
Output:
Input in second cell, showing that working directory is retained
Example 7: Nicely typesetting output from the FriCAS computer algebra system
The following function takes whatever the cell input is, executes the code in FriCAS
, performs some simple substitutions on the FriCAS
output and then displays it using Markdown
:
Define the mode:
With this mode, FriCAS
can generate output that is (almost) compatible with Markdown
format.
For example you can use this new mode in a cell with the following input:
Output: This will evaluate ‘sqrt(2)/2+1’ and display the result in both LaTeX format and MathML formats (in a MathML capable browser).
Note: The current version of Sage (6.6 and earlier) requires a patch to correct a bug in the fricas/axiom interface.