dataframe

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2026 License: Apache-2.0 Imports: 12 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetMapKeys 

func GetMapKeys[K comparable, V any](input_map map[K]V) (collection.Set[K], error)

Types

type AggFunc added in v0.2.0 

type AggFunc string

AggFunc represents the aggregation function to use in pivot table operations. 

const (
	// AggSum computes the sum of values.
	AggSum AggFunc = "sum"
	// AggMean computes the mean of values.
	AggMean AggFunc = "mean"
	// AggCount counts non-null values.
	AggCount AggFunc = "count"
	// AggMin computes the minimum value.
	AggMin AggFunc = "min"
	// AggMax computes the maximum value.
	AggMax AggFunc = "max"
)

type BoolCol 

type BoolCol []bool

BoolColumn represents a column slice of bool values.

type Column 

type Column []any

Column represents a column slice of any type.

type ConcatAxis 

type ConcatAxis int

ConcatAxis specifies the axis along which to concatenate. 

const (
	// AxisIndex (0) concatenates along rows (stacking DataFrames vertically).
	AxisIndex ConcatAxis = 0
	// AxisColumns (1) concatenates along columns (joining DataFrames horizontally).
	AxisColumns ConcatAxis = 1
)

type ConcatJoin 

type ConcatJoin string

ConcatJoin specifies how to handle indexes on the non-concatenation axis. 

const (
	// JoinOuter takes the union of indexes (all columns/rows, with nulls for missing).
	JoinOuter ConcatJoin = "outer"
	// JoinInner takes the intersection of indexes (only common columns/rows).
	JoinInner ConcatJoin = "inner"
)

type ConcatOptions 

type ConcatOptions struct {
	// Axis is the axis to concatenate along. Default: AxisIndex (0).
	Axis ConcatAxis

	// Join determines how to handle indexes on other axis. Default: JoinOuter.
	Join ConcatJoin

	// IgnoreIndex if true, do not use the index values along the concatenation axis.
	// The resulting axis will be labeled 0, 1, ..., n-1. Default: false.
	IgnoreIndex bool

	// VerifyIntegrity if true, check whether the new concatenated axis contains duplicates.
	// This can be expensive. Default: false.
	VerifyIntegrity bool

	// Sort if true, sort non-concatenation axis if it is not already aligned. Default: false.
	Sort bool
}

ConcatOptions configures the behavior of the Concat function.

func DefaultConcatOptions 

func DefaultConcatOptions() ConcatOptions

DefaultConcatOptions returns the default options for Concat.

type DataFrame 

type DataFrame struct {
	sync.RWMutex
	Columns     map[string]collection.Series
	ColumnOrder []string
	Index       []string // Row labels, defaults to string representations of row numbers
}

func Concat 

func Concat(objs []*DataFrame, opts ...ConcatOptions) (*DataFrame, error)

Concat concatenates DataFrames along a particular axis. This is an internal version used by other dataframe methods. For the public API, use gpandas.Concat.

func (*DataFrame) Drop 

func (df *DataFrame) Drop(opts DropOptions) (*DataFrame, error)

Drop removes specified labels from rows or columns.

Remove rows or columns by specifying label names and corresponding axis, or by directly specifying index or column names.

Parameters:

  • opts: DropOptions struct configuring the drop operation

Returns:

  • *DataFrame: new DataFrame with labels removed (nil if Inplace=true)
  • error: nil if successful, otherwise an error

Example: 

// Drop columns "A" and "B"
result, err := df.Drop(dataframe.DropOptions{Columns: []string{"A", "B"}})

// Drop columns using Labels and Axis
result, err := df.Drop(dataframe.DropOptions{Labels: []string{"A"}, Axis: 1})

// Drop rows by index label
result, err := df.Drop(dataframe.DropOptions{Index: []string{"0", "2"}})

// Drop in place
_, err := df.Drop(dataframe.DropOptions{Columns: []string{"A"}, Inplace: true})

// Ignore missing labels
result, err := df.Drop(dataframe.DropOptions{Columns: []string{"X"}, Errors: "ignore"})

func (*DataFrame) GroupBy 

func (df *DataFrame) GroupBy(by []string, axis int) (*GroupBy, error)

GroupBy groups the DataFrame using a mapper or by a Series of columns. A groupby operation involves some combination of splitting the object, applying a function, and combining the results. This can be used to group large amounts of data and compute operations on these groups.

Parameters:

  • by: A slice of strings representing the column names to group by.
  • axis: The axis to group along. 0 for rows, 1 for columns. Currently only axis 0 is supported for grouping by columns.

Returns:

  • A pointer to a GroupBy object.
  • An error if the operation fails (e.g., invalid column names).

func (*DataFrame) Head 

func (df *DataFrame) Head(n ...int) *DataFrame

Head returns the first n rows of the DataFrame. If n is not provided, it defaults to 5.

func (*DataFrame) ILoc 

func (df *DataFrame) ILoc() *iLocIndexer

ILoc returns an integer position-based indexer for the DataFrame

func (*DataFrame) Len 

func (df *DataFrame) Len() int

Len returns the number of rows in the DataFrame.

func (*DataFrame) Loc 

func (df *DataFrame) Loc() *LocIndexer

Loc returns a label-based indexer for the DataFrame

func (*DataFrame) Melt added in v0.2.0 

func (df *DataFrame) Melt(opts MeltOptions) (*DataFrame, error)

Melt unpivots a DataFrame from wide to long format.

This operation transforms columns into rows, keeping identifier variables fixed while "melting" the specified value columns.

Parameters:

  • opts: MeltOptions configuring the melt operation

Returns:

  • *DataFrame: the melted DataFrame in long format
  • error: nil if successful, otherwise an error

Example: 

// Wide format DataFrame:
//   Name  | Math | Science
//   Alice | 90   | 85
//   Bob   | 80   | 75
//
melted, err := df.Melt(dataframe.MeltOptions{
    IdVars:    []string{"Name"},
    ValueVars: []string{"Math", "Science"},
    VarName:   "Subject",
    ValueName: "Score",
})
// Result (long format):
//   Name  | Subject | Score
//   Alice | Math    | 90
//   Alice | Science | 85
//   Bob   | Math    | 80
//   Bob   | Science | 75

func (*DataFrame) Merge 

func (df *DataFrame) Merge(other *DataFrame, on string, how MergeHow) (*DataFrame, error)

Merge combines two DataFrames based on a specified column and merge type.

Parameters:

other: The DataFrame to merge with the current DataFrame.

on: The name of the column to merge on. This column must exist in both DataFrames.

how: The type of merge to perform. It can be one of the following:

  • LeftMerge: Keep all rows from the left DataFrame and match rows from the right DataFrame.
  • RightMerge: Keep all rows from the right DataFrame and match rows from the left DataFrame.
  • InnerMerge: Keep only rows that have matching values in both DataFrames.
  • FullMerge: Keep all rows from both DataFrames, filling in missing values with null.

Returns:

  • A new DataFrame containing the merged data with proper null handling.
  • An error if the merge operation fails, such as if the specified column does not exist in one or both DataFrames.

Note: Null values in the merge key column are handled specially - they never match with other null values.

Examples: 

// Create two sample DataFrames
df1 := &DataFrame{
	Columns: []string{"ID", "Name"},
	Data: [][]any{
		{1, "Alice"},
		{2, "Bob"},
		{3, "Charlie"},
	},
}

df2 := &DataFrame{
	Columns: []string{"ID", "Age"},
	Data: [][]any{
		{1, 25},
		{2, 30},
		{4, 35},
	},
}

// Inner merge example (only matching IDs)
result, err := df1.Merge(df2, "ID", InnerMerge)
// Result:
// ID | Name    | Age
// 1  | Alice   | 25
// 2  | Bob     | 30

// Left merge example (all rows from df1)
result, err := df1.Merge(df2, "ID", LeftMerge)
// Result:
// ID | Name    | Age
// 1  | Alice   | 25
// 2  | Bob     | 30
// 3  | Charlie | null

// Full merge example (all rows from both)
result, err := df1.Merge(df2, "ID", FullMerge)
// Result:
// ID | Name    | Age
// 1  | Alice   | 25
// 2  | Bob     | 30
// 3  | Charlie | null
// 4  | null    | 35

func (*DataFrame) PivotTable added in v0.2.0 

func (df *DataFrame) PivotTable(opts PivotTableOptions) (*DataFrame, error)

PivotTable creates a spreadsheet-style pivot table as a DataFrame.

The pivot table aggregates data based on the specified index and columns, applying the aggregation function to the values.

Parameters:

  • opts: PivotTableOptions configuring the pivot operation

Returns:

  • *DataFrame: the pivot table result
  • error: nil if successful, otherwise an error

Example: 

df := &DataFrame{...}  // DataFrame with columns: "A", "B", "C", "D"
pivot, err := df.PivotTable(dataframe.PivotTableOptions{
    Index:   []string{"A"},
    Columns: "B",
    Values:  []string{"C"},
    AggFunc: dataframe.AggSum,
})

func (*DataFrame) PlotBar added in v0.2.0 

func (df *DataFrame) PlotBar(xCol, yCol string, opts *plot.ChartOptions) error

PlotBar creates a bar chart from DataFrame columns. xCol specifies the column to use for x-axis labels. yCol specifies the column to use for y-axis values (must be numeric). opts configures chart appearance and output location.

Returns an error if: - DataFrame is empty - Either column does not exist - yCol is not numeric (int64 or float64) - Chart generation or file write fails

Example: 

opts := &plot.ChartOptions{
    Title: "Sales by Category",
    Width: 800,
    Height: 600,
    OutputPath: "output/bar_chart.html",
}
err := df.PlotBar("category", "sales", opts)

func (*DataFrame) PlotLine added in v0.2.0 

func (df *DataFrame) PlotLine(xCol string, yCols []string, opts *plot.ChartOptions) error

PlotLine creates a line chart from DataFrame columns. xCol specifies the column to use for x-axis labels. yCols specifies one or more columns to use for y-axis values (must be numeric). opts configures chart appearance and output location.

Returns an error if: - DataFrame is empty - Any column does not exist - Any yCol is not numeric (int64 or float64) - Chart generation or file write fails

Example: 

// Single series
opts := &plot.ChartOptions{
    Title: "Temperature Over Time",
    OutputPath: "output/line_chart.html",
}
err := df.PlotLine("date", []string{"temperature"}, opts)

// Multiple series
err := df.PlotLine("date", []string{"temp_min", "temp_max"}, opts)

func (*DataFrame) PlotPie added in v0.2.0 

func (df *DataFrame) PlotPie(labelCol, valueCol string, opts *plot.ChartOptions) error

PlotPie creates a pie chart from DataFrame columns. labelCol specifies the column to use for pie slice labels. valueCol specifies the column to use for pie slice values (must be numeric). opts configures chart appearance and output location.

Returns an error if: - DataFrame is empty - Either column does not exist - valueCol is not numeric (int64 or float64) - Chart generation or file write fails

Example: 

opts := &plot.ChartOptions{
    Title: "Market Share",
    Width: 800,
    Height: 600,
    OutputPath: "output/pie_chart.html",
}
err := df.PlotPie("product", "revenue", opts)

func (*DataFrame) Rename 

func (df *DataFrame) Rename(columns map[string]string) error

Rename changes the names of specified columns in the DataFrame.

The method allows renaming multiple columns at once by providing a map where:

  • Keys are the current/original column names
  • Values are the new column names to replace them with

The operation is thread-safe as it uses mutex locking to prevent concurrent modifications.

Parameters:

  • columns: map[string]string where keys are original column names and values are new names

Returns:

  • error: nil if successful, otherwise an error describing what went wrong

Possible errors:

  • If the columns map is empty
  • If the DataFrame is nil
  • If any specified original column name doesn't exist in the DataFrame
  • If there are any issues with internal set operations

Example: 

df := &DataFrame{
    Columns: []string{"A", "B", "C"},
    Data:    [][]any{{1, 2, 3}, {4, 5, 6}},
}

// Rename columns "A" to "X" and "B" to "Y"
err := df.Rename(map[string]string{
    "A": "X",
    "B": "Y",
})

// Result:
// Columns will be ["X", "Y", "C"]

Thread Safety:

The method uses sync.Mutex to ensure thread-safe operation when modifying column names. The lock is automatically released using defer when the function returns.

Note:

  • All specified original column names must exist in the DataFrame
  • The operation modifies the DataFrame in place
  • Column order remains unchanged

func (*DataFrame) ResetIndex 

func (df *DataFrame) ResetIndex()

ResetIndex resets the index to default integer sequence ("0", "1", "2", ...).

func (*DataFrame) Select 

func (df *DataFrame) Select(columns ...string) (*DataFrame, error)

Select returns a new DataFrame with only the specified columns. If a single column is requested, still returns a DataFrame (not a Series).

func (*DataFrame) SelectCol 

func (df *DataFrame) SelectCol(column string) (collection.Series, error)

SelectCol returns a single column as a Series reference. This provides direct access to the underlying Series.

func (*DataFrame) SetIndex 

func (df *DataFrame) SetIndex(index []string) error

SetIndex sets custom row labels for the DataFrame. The length of the index must match the number of rows in the DataFrame.

func (*DataFrame) Slice 

func (df *DataFrame) Slice(indices []int) (*DataFrame, error)

Slice returns a new DataFrame containing only the rows specified by indices.

func (*DataFrame) String 

func (df *DataFrame) String() string

String returns a string representation of the DataFrame in a formatted table.

The method creates a visually appealing ASCII table representation of the DataFrame with the following features:

  • Column headers are displayed in the first row
  • Data is aligned to the left within columns
  • Table borders and separators use ASCII characters
  • Each cell's content is automatically converted to string representation
  • Null values are displayed as "null"
  • A summary line showing dimensions ([rows x columns]) is appended

The table format follows this pattern: 

+-----+-----+-----+
| Col1| Col2| Col3|
+-----+-----+-----+
| val1| val2| null|
| val4| val5| val6|
+-----+-----+-----+
[2 rows x 3 columns]

Parameters:

  • None (receiver method on DataFrame)

Returns:

  • string: The formatted table representation of the DataFrame

Example: 

df := &DataFrame{
    Columns: []string{"A", "B"},
    Data:    [][]any{{1, 2}, {3, 4}},
}
fmt.Println(df.String())

Note:

  • All values are converted to strings using fmt.Sprintf("%v", val)
  • Null values are displayed as "null"
  • The table is rendered using the github.com/olekukonko/tablewriter package

func (*DataFrame) Tail 

func (df *DataFrame) Tail(n ...int) *DataFrame

Tail returns the last n rows of the DataFrame. If n is not provided, it defaults to 5.

func (*DataFrame) ToCSV 

func (df *DataFrame) ToCSV(filepath string, separator ...string) (string, error)

ToCSV converts the DataFrame to a CSV string representation or writes it to a file.

Parameters:

  • filepath: file path to write the CSV to (empty string to return as string)
  • separator: optional separator for the CSV (defaults to comma)

Returns:

  • string: CSV representation of the DataFrame if filepath is empty
  • error: nil if successful, otherwise an error describing what went wrong

Note: If filepath is provided, the method returns ("", nil) on success Null values are represented as empty strings in the CSV output.

Example: 

// Get CSV as string with default comma separator
csv, err := df.ToCSV("")

// Get CSV as string with custom separator
csv, err := df.ToCSV("", ";")

// Write to file with default comma separator
_, err := df.ToCSV("path/to/output.csv")

// Write to file with custom separator
_, err := df.ToCSV("path/to/output.csv", ";")

type DropOptions 

type DropOptions struct {
	// Labels are the index or column labels to drop.
	// A single label or slice of labels.
	Labels []string

	// Axis specifies whether to drop from the index (0) or columns (1).
	// Default is 0 (index/rows).
	Axis int

	// Index is an alternative to specifying Labels with Axis=0.
	// Specifies row labels to drop.
	Index []string

	// Columns is an alternative to specifying Labels with Axis=1.
	// Specifies column names to drop.
	Columns []string

	// Inplace specifies whether to modify the DataFrame in place.
	// If true, modifies in place and returns nil.
	// If false (default), returns a new DataFrame.
	Inplace bool

	// Errors specifies how to handle missing labels.
	// "raise" (default): raise an error if any labels are not found.
	// "ignore": suppress errors for missing labels.
	Errors string
}

DropOptions configures the Drop operation. Use Labels+Axis OR Index/Columns directly (not both).

type FloatCol 

type FloatCol []float64

FloatColumn represents a column slice of float64 values.

type GoPandas 

type GoPandas struct{}

type GroupBy 

type GroupBy struct {
	// contains filtered or unexported fields
}

GroupBy represents a grouped DataFrame.

func (*GroupBy) Apply 

func (gb *GroupBy) Apply(f func(*DataFrame) (*DataFrame, error)) (*DataFrame, error)

Apply applies a function to each group and combines the results.

func (*GroupBy) Max 

func (gb *GroupBy) Max() (*DataFrame, error)

Max computes the maximum of each group.

func (*GroupBy) Mean 

func (gb *GroupBy) Mean() (*DataFrame, error)

Mean computes the mean of each group.

func (*GroupBy) Min 

func (gb *GroupBy) Min() (*DataFrame, error)

Min computes the minimum of each group.

func (*GroupBy) Sum 

func (gb *GroupBy) Sum() (*DataFrame, error)

Sum computes the sum of each group.

type IntCol 

type IntCol []int64

IntColumn represents a column slice of int64 values.

type LocIndexer 

type LocIndexer struct {
	// contains filtered or unexported fields
}

LocIndexer provides label-based indexing for DataFrames

func (*LocIndexer) At 

func (l *LocIndexer) At(rowLabel string, columnName string) (any, error)

At returns a single value using row label and column name

func (*LocIndexer) Col 

func (l *LocIndexer) Col(columnName string) (collection.Series, error)

Col returns a single column as a Series reference

func (*LocIndexer) Cols 

func (l *LocIndexer) Cols(columnNames []string) (*DataFrame, error)

Cols returns multiple columns as a new DataFrame

func (*LocIndexer) IsNullAt 

func (l *LocIndexer) IsNullAt(rowLabel string, columnName string) (bool, error)

IsNullAt returns whether the value at the given row label and column name is null

func (*LocIndexer) Row 

func (l *LocIndexer) Row(rowLabel string) (*DataFrame, error)

Row returns a single row as a new DataFrame using row label

func (*LocIndexer) Rows 

func (l *LocIndexer) Rows(rowLabels []string) (*DataFrame, error)

Rows returns multiple rows as a new DataFrame using row labels

type MeltOptions added in v0.2.0 

type MeltOptions struct {
	// IdVars specifies the column(s) to use as identifier variables.
	// These columns will be kept as-is in the output.
	IdVars []string

	// ValueVars specifies the column(s) to unpivot.
	// If empty, all columns not in IdVars will be used.
	ValueVars []string

	// VarName is the name for the variable column.
	// Default: "variable"
	VarName string

	// ValueName is the name for the value column.
	// Default: "value"
	ValueName string
}

MeltOptions configures the behavior of the Melt function.

type MergeHow 

type MergeHow string

MergeHow represents the type of merge operation 

const (
	LeftMerge  MergeHow = "left"
	RightMerge MergeHow = "right"
	InnerMerge MergeHow = "inner"
	FullMerge  MergeHow = "full"
)

type PivotTableOptions added in v0.2.0 

type PivotTableOptions struct {
	// Index specifies the column(s) to use as row labels for the pivot table.
	// These columns will be used to group rows.
	Index []string

	// Columns specifies the column whose unique values will become new column headers.
	Columns string

	// Values specifies the column(s) to aggregate.
	Values []string

	// AggFunc specifies the aggregation function to apply.
	// Supported values: "sum", "mean", "count", "min", "max".
	// Default: "mean"
	AggFunc AggFunc

	// FillValue is the value to use for missing combinations.
	// If nil, missing values will remain null.
	FillValue any
}

PivotTableOptions configures the behavior of the PivotTable function.

type StringCol 

type StringCol []string

StringColumn represents a column slice of string values.

type TypeColumn 

type TypeColumn[T comparable] []T

TypeColumn represents a column slice of a comparable type T.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.