Using Dataframes

Introduction

GAMA 2026-06 introduces the dataframe type: a tabular data structure with named columns, similar to a dataframe in R or pandas. It is designed for loading, transforming, and saving tabular data — CSV or Excel files, SQL query results, or data built directly in GAML — without having to juggle lists of lists.

A dataframe is a value like any other: it can be stored in an attribute, passed to actions, and displayed with write.

Creating a dataframe

The dataframe_with operator builds a dataframe from a list of column names and a list of rows:

dataframe df <- dataframe_with(["name", "age"], [["Alice", 30], ["Bob", 25]]);
write pretty_print(df);

You can also cast a compatible value (e.g. a matrix or a map of columns) with the dataframe casting operator:

dataframe df2 <- dataframe(my_matrix);

Loading and saving files

The dataframe_file constructor reads a dataframe from a file; the format is deduced from the extension (csv, tsv, json, xlsx, parquet, avro):

dataframe cities <- dataframe(dataframe_file("../includes/cities.csv"));

Use is_dataframe(a_file) to test whether a file can be read as a dataframe.

Inspecting a dataframe

• pretty_print(df) returns a readable, aligned string representation of the dataframe (an extended form takes maximum row/column/width limits: pretty_print(df, max_rows, max_cols, max_width)).
• cell(df, row_index, "column") returns the value at the given row index and column name.
• df row_at i and df column_at j return a single row or column as a list.
• rows_list(df) and columns_list(df) return all rows (or columns) as a list of lists.

Transforming a dataframe

All transformation operators return a new dataframe and leave the original untouched.

• df select_columns ["name", "age"] keeps only the given columns.
• filter(df, "column", value) keeps only the rows where the column equals the value.
• df iloc [0, 2, 4] keeps only the rows at the given indices (df iloc 0 returns a single row as a list).
• add_column(df, "new_col", default_value) adds a column filled with a default value.
• df remove_empty "column" removes the rows with an empty value in the column.
• df1 + df2 concatenates two dataframes.
• join(df1, df2, "key") inner-joins two dataframes on a common key column. Variants accept a list of key columns and an explicit join type: join(df1, df2, ["key1", "key2"], "left") — one of "inner" (default), "left", "right" or "full".
• pivot(df, "index_col", "pivot_col", "value_col") pivots the dataframe: the index column becomes row labels, the pivot column values become new column names, and the value column provides the cell values.

dataframe adults <- filter(people, "status", "adult") select_columns ["name", "age"];

Dataframes and databases

Dataframes integrate directly with SQL databases via JDBC:

• load_sql(jdbc_url, user, password, query) runs a SQL query and returns the result as a dataframe.
• load_table(jdbc_url, user, password, table_name) loads a whole table into a dataframe.
• save_table(df, jdbc_url, user, password, table_name) saves a dataframe to an existing table with a compatible schema.

Pass empty strings for user/password if the database does not require credentials.

dataframe results <- load_sql("jdbc:sqlite:../includes/Student.db", "", "", "SELECT * FROM registration");

The insert action of the database skill also accepts a dataframe to insert several rows in a single batch — see Using Database.

Full list of operators

See the Dataframe-related operators section of the operators reference.