Cook Recipes

You can use the advanced editor to build projects using datasets that you have stored in your Graphext workspace. Using the advanced editor is like assembling code to execute your project and gives you more control over the configuration of your network and the transformations made to your dataset. Access the advanced editor from the bottom of your project setup wizard after you've selected a dataset to work with.

You can open the advanced editor at any point whilst setting up the project. As you add steps using the wizard, these functions will be added to the code inside your advanced editor.

"Type a few lines of code, you create an organism."

- Richard Powers

Projects are formed using nothing more than a number of steps. These steps are functions that accept some data and output new, transformed or enriched data. A recipe can have an arbitrary number of steps and can generate an arbitrary number of intermediate datasets. But, the output must always be a single dataset that serves as the basis for your project's network visualization.


Opening the Advanced Editor

You can open the advanced editor at any point after selecting a dataset and before executing the project. As you choose options from the project sidebar, functions are added to your advanced editor.

To access the advanced editor, select a dataset from your Graphext workspace then click 'Open advanced editor' from the bottom of the right sidebar window that appears.

How to Open the Advanced Editor

  1. Start from the 'Datasets' panel of your Graphext workspace.
  2. Select a dataset to start working with.
  3. A sidebar will appear on the right of your screen.
  4. You can open the advanced editor at any point by selecting 'Open advanced editor' from the bottom of the sidebar.
  5. Start building your analysis using the sidebar visual editor.
  6. When you are ready, select 'Open the advanced editor'.
  7. Edit the code inside the advanced editor to customize your project setup.
  8. Consult the technical documentation for more information on steps that you can add or customize.
  9. Return to the visual editor by selecting 'Open visual editor' from the bottom of the right sidebar.
  10. Done ... Continue and execute your project when you have finished editing.


Your Dataset

When you open the Recipe Editor, you will have done so having selected first a dataset that serves as the main input for the recipe. This dataset is made available by default with the name ds, and so the simplest possible recipe is simply written as follows.

create_project(ds)

This builds a project with a single step called create_project, which accepts a dataset as input and has no output. This is a special case. Since the result of this step is the creation of a project, it doesn't generate any output that can be further processed inside the recipe.

In practice, you'll almost always want to somehow transform or enrich your dataset however, and so you'll want to add one or more of the many steps available in Graphext before the final step of project creation.


Steps

Syntax

In general, the syntax for adding a step is very simple and always written as follows.

step_name(inputs, ..., {params}) -> (outputs, ...)

The inputs may be either specific columns of a dataset, a dataset itself, or a model. Details about the expected types of inputs depend on the specific step in question. Documentation on the different steps available in the advanced editor is available here.

As the step's last argument in parenthesis, you can provide parameters to configure how the step will transform the input data. Finally, in another set of parenthesis (and separated by ->), you provide names for the outputs that the step will generate. Again, the outputs may be one or more columns or datasets.

To differentiate between input datasets and columns, column names need to be prefixed with the name of the dataset it belongs to, while datasets can be referred to by their name only. In other words, ds refers to the dataset with the name ds and to pick out a specific column you'd use either ds.my_column or ds["my_column"]. The two forms are generally interchangeable, but the latter is required if a column name contains spaces.

An Example Step

A simple step that splits the texts in a given column at the first comma, might be written as follows.

split_string(ds.text, {"pattern": ","}) -> (ds.left_part, ds.right_part)

The result of the split will be two new columns named "left_part" and "right_part" in the dataset `ds`. A very simple recipe including this transformation could be written as follows.

# Transform the input data
split_string(ds.text, {"pattern": ","}) -> (ds.left_part, ds.right_part)

# Select which dataset forms the basis for the final project
create_project(ds)

The columns resulting from the split will now be included in the project that is created.

Autocompleting Step Names

Usually, when you start typing the beginning of a step's name in the Recipe editor, the rest of the step's signature will be autocompleted, including the default names of any outputs it creates. So you only need to change the names if you don't like the default ones or if they clash with other outputs you may have generated already.


Parameters

Parameters let you configure how a step will process its inputs. The syntax of parameters corresponds to a valid json object, for those familiar with json or javascript. For those who are not, it's simply a number of quoted parameter names and corresponding values in between curly braces.

{"pattern": ","}

In this example, "pattern" is the parameter's name and "," represents its value. In general, all parameter names must be quoted strings, while values may also be quoted strings as well as numbers, lists of numbers or strings or another nested object in curly braces, following the above rules.

Each step's individual documentation will describe its valid parameters. Additionally, the advanced editor will help you configure the step by highlighting any invalid parameters you may accidentally have selected.


For more information on constructing projects using the advanced editor, check out Graphext's technical documentation. We also recommend that you try building projects using the wizard's visual editor and opening the advanced editor to inspect which steps have been added and how they are configured.

Need Something Different?

We know that data isn't always clean and simple.
Have a look through these topics if you can't see what you are looking for.