Edit and run code in CloudStor SWAN

SWAN uses Jupyter Notebooks. With it, you can:

• Write and edit code.
• Run code in your browser.
• Preview code output.
• View rich media representations of computational results.
• Write and use interactive JavaScript widgets.
• Add explanatory text using Markdown.
• Code mathematical equations using LaTeX syntax in Markdown.

Video tutorial

Create a Jupyter Notebook

1. Open a SWAN session.
2. Under the Notebook heading, click the coding language you want to use.
   
   SWAN will open a new notebook.
   Notebooks have the file extension .ipynb.

Cells in notebooks

You can use cells within a notebook to break up your code, add rich text comments and mathematical equations, or include raw text. For example, you might have a cell for loading libraries, a cell for reading data, a cell for analysing the data and a cell for visualising the output.

When your code is broken up into cells, you can run single cells of code individually – useful if you just want to check the code you’re currently working on. By default, SWAN displays the output from a cell just beneath it.

SWAN displays code cells with [    ]: in front of them.

Notebook checkpoints and nbdiff

SWAN automatically saves your notebooks to your CloudStor drive. However, you can also manually save them to create checkpoints. You can use checkpoints to compare your existing notebook against a previous version – particularly useful if you’re collaborating with other people on your SWAN session. If you preferred the earlier version, you can revert the entire notebook to the checkpoint.

Note that checkpoints are limited: SWAN only stores your most recent checkpoint. If you want more control over file versions – so, for example, you can revert to a file from three versions ago – set up git in your SWAN session.

Add code to a notebook

To add code to a Jupyter Notebook in SWAN:

1. Double-click the notebook to open it. 
2. Click a code cell. When the border turns blue, it’s editable and you can start typing.
3. Click to save your code and create a checkpoint.

Run code in a notebook

To run all of the code in a Jupyter Notebook in SWAN:

1. Double-click the notebook to open it. 
2. Click .

To run only the code in a particular code block:

1. Click the code block to highlight it.
2. Click .

To stop code that’s currently running, click .

Save a notebook

SWAN automatically saves your notebooks to your CloudStor drive. However, if you want to change the filename of the notebook or the location it’s saved to, you can manually save it.

1. Click File > Save Notebook As… in the main menu.
   
2. Enter the location and filename and click Save.
   Note: Keep the .ipynb file extension, so that you can open your notebook again in future.
   
   By default, your notebook is saved in the SWAN_SESSIONS folder in your main CloudStor folder. The SWAN session notebook folder will be saved as SWAN_SESSION_yyyy.dd.mm_hh.mm.ss_UTC
   
   If you want to save your notebook to a different CloudStor location, enter the folder location starting with cloudstor/. For example, cloudstor/research_project/shared_work/gather_input.ipynb. This tells SWAN that you want to save the file directly to CloudStor, instead of using the default SWAN session folder.

Shut down a notebook

1. Click File in the main menu.
2. Click Close and Shutdown Notebook.
   
   

Note: Closing the Notebook tab does not shut down the session.

Change the coding language for a notebook

Each notebook displays its coding language in its toolbar.

To change the compiler used for the notebook so you can code in a different language:

NOTE: This will change the compiler for all code cells in the notebook. If you’ve already written code in the notebook, you will most likely be unable to run the old code until you rewrite it in the new coding language.

1. Click the name of the language in the notebook toolbar.
   
   
2. Select a coding language from the drop down list.
3. Click Select.

Change the filename for a notebook

To change the name of a notebook:

1. Right-click the filename on the notebook window’s tab.
   
   
2. Click Rename Notebook….
3. Enter the new filename.
4. Click Rename.

Alternatively:

1. Right-click the filename in the side navigation bar.
2. Click Rename.
3. Enter the new filename and press Enter.

Revert to a previous version of a notebook

If you’ve been saving your notebooks manually and creating checkpoints, you can revert a notebook to the state it was in at the last saved checkpoint. This will undo any changes you have made since.

To revert a notebook to its checkpoint:

1. Open the notebook you want to revert.
2. Click File > Revert Notebook to Checkpoint in the main menu.
3. Click Revert.

Tag a notebook block

You can add plain text tags to blocks in a notebook. Tags can include alphanumeric and punctuation characters, but not spaces. If you add a space between words in a tag, Jupyter Notebooks will interpret it as two separate tags.

To tag a block:

1. Click on the block.
2. Click on the opposite side of the window to the side menu.
3. Click Add Tag.
4. Enter your tag text.
5. Press Enter or click +.

Add metadata to a notebook

The basic metadata for a notebook looks like this:

{
    "kernelspec": {
        "display_name": "Python 3",
        "language": "python",
        "name": "python3"
    },
    "language_info": {
        "codemirror_mode": {
            "name": "ipython",
            "version": 3
        },
        "file_extension": ".py",
        "mimetype": "text/x-python",
        "name": "python",
        "nbconvert_exporter": "python",
        "pygments_lexer": "ipython3",
        "version": "3.9.12"
    }
}

It consists of:

• Categories, which have a name and multiple attributes surrounded with curly brackets.
• Attributes, which have a name and a value.

To add or edit metadata for a Jupyter Notebook:

1. Open the notebook.
2. Click on the opposite side of the window to the side menu.
3. Click Advanced Tools to expand the section.
4. Add a category for your metadata. For example:
   

   "developer_bio": {
   }
   

5. Add attributes for your metadata. For example:
   

   "developer_bio": {
       "name": "Lee Taylor",
       "website": "https://leetaylor.example.com",
       "email": "lee@example.com"
   }    

Import a notebook from CloudStor

You can import Jupyter Notebooks into your SWAN session from CloudStor, including from previous SWAN sessions.

To import a notebook:

1. Double-click cloudstor in the side navigation bar. 
2. Navigate to the notebook file you want to import.

Drag it to the / icon above the file listing in the side navigation bar.
This will copy the file to your SWAN session’s main folder.