README
¶
Rowan
Overview
Rowan is a Go library for working with tabular data. It provides a simple Table abstraction, along with common data transformation utilities such as column extracting, mapping, up to range and z-score scaling, to support data preprocessing workflows.
Quick Start
The example below demonstrates creating a Table, applying a scaler, and exporting the result.
Download this excel file (sample.xlsx) to follow the example!
tbl, err := rowan.FromExcel("docs/assets/sample.xlsx")
if err != nil {
panic(err)
}
tbl.Display()
newTbl := tbl.Categorize()
newTbl.Display()
zScaler := scale.NewZScaler()
if err := zScaler.Fit(newTbl, "Score", "Points"); err != nil {
panic(err)
}
finalTbl, err := zScaler.Transform(newTbl)
if err != nil {
panic(err)
}
finalTbl.Display()
if err := finalTbl.WriteCSV("my_final_table.csv"); err != nil {
panic(err)
}
Features
- Tabular data model
A simpleTablestructure with named columns and consistent row length. - Data Ingestion
Ingest tabular data from CSV, Excel, Google Sheets, and Go structs into a unifiedTable. - Table inspection and access
Retrieve column names, table length, and column values. - Column operations
Select, map, categorize, and transform column values for downstream processing. - Data transformation
Built-in scalers such asRangeScalerandZScalerwith explicit Fit and Transform steps. - Data export
ExportTabledata to common tabular formats such as CSV.
Further Reading
For detailed documentation and additional examples, see the full documentation:
License
This project is licensed under the MIT License.
See the LICENSE file for details.
Documentation
¶
Index ¶
- type CSVOption
- type ExcelOption
- type SheetsOption
- type Table
- func FromCSV(path string, opts ...CSVOption) (*Table, error)
- func FromExcel(path string, argOpts ...ExcelOption) (*Table, error)
- func FromSheets(ctx context.Context, spreadsheet string, options ...SheetsOption) (*Table, error)
- func FromStructs[T any](rows []T) (*Table, error)
- func New(data map[string][]any, columnsOrder ...[]string) (*Table, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CSVOption ¶
CSVOption is an alias of csv.Option used to configure CSV reading behavior.
This alias allows CSV-related options to be exposed through the rowan package without requiring users to import the internal csv package directly.
func WithDelimiter ¶
WithDelimiter returns a CSVOption that sets the delimiter rune used when parsing a CSV file.
This is a convenience wrapper around csv.WithDelimiter.
type ExcelOption ¶
ExcelOption is an alias for excel.Option, allowing users to pass configuration options to control how Excel files are read without importing the internal excel package.
func WithExcelRange ¶
func WithExcelRange(rangeA1 string) ExcelOption
WithRange specifies the A1 notation range to read from the sheet (e.g. "Sheet1!A1:D100").
type SheetsOption ¶
SheetsOption is an alias of sheets.Option, re-exported to avoid leaking the internal sheets package while still allowing users to configure FromSheets behavior.
func WithSheetsRange ¶
func WithSheetsRange(rangeA1 string) SheetsOption
WithRange specifies the A1 notation range to read from the sheet (e.g. "Sheet1!A1:D100").
func WithSheetsURL ¶
func WithSheetsURL() SheetsOption
WithSheetsURL configures FromSheets to treat the spreadsheet argument as a full Google Sheets URL instead of a raw spreadsheet ID.
type Table ¶
Table is an alias of table.Table exposed. This allows working with Table directly via the rowan package without importing the internal table package.
Table represents a simple in-memory table structure. It contains the column names, the underlying data per column, and the number of rows.
func FromCSV ¶
FromCSV reads a CSV file and constructs a Table from its contents.
The CSV file is parsed into column-oriented data, where each column is inferred to have a consistent type across all rows. The original column order from the CSV header is preserved.
Optional CSVOption values can be provided to customize parsing behavior such as delimiter selection.
func FromExcel ¶
func FromExcel(path string, argOpts ...ExcelOption) (*Table, error)
FromExcel reads an Excel file from the specified path and constructs a Table from its contents. The first row of the sheet is treated as the header (column names).
Optional ExcelOption values can be provided to customize behavior, such as selecting a specific sheet or A1 range.
FromExcel returns a Table with parsed data, or an error if reading or parsing fails.
func FromSheets ¶
FromSheets constructs a Table from a Google Sheets document.
The spreadsheet argument may be a Spreadsheet ID or full URL. Additional options can be provided to control how the sheet is read (e.g. range, or sheet name).
Internally, this function delegates reading to the sheets package and converts the result into a Table.
func FromStructs ¶
FromStructs constructs a Table from a slice of structs.
Each exported struct field becomes a column in the resulting table. The column name is derived from the struct field name by default, or from the `rowan` struct tag if present.
Fields tagged with `rowan:"-"` or unexported fields are ignored.
Example:
type User struct {
ID int `rowan:"id"`
Name string
Email string `rowan:"-"`
}
tbl, err := rowan.FromStructs([]User{...})
func New ¶
New creates a new Table from the given column-oriented data. This function is a convenience wrapper around table.New.
Parameters:
- data: map[string][]any, where each key is a column name and the value is a slice of values.
- columnsOrder (optional): variadic slice specifying the desired order of columns in the Table. If provided and not nil, the Table will use this order. If not provided, the order will follow the order of iteration over the map (which is non-deterministic in Go). Only the first slice is used if multiple slices are provided.
All columns must have the same length, otherwise an error is returned.
Returns:
- *Table: the constructed Table instance
- error: error if the data is empty, if a column in columnsOrder is missing, or if column lengths are inconsistent.
Source Files
Directories