New open source Java Data Library

CupOfTea Labs released CupOfTea 0.24.0, an open source Java data manipulation library that provides DataFrame-style filtering, aggregation, joins, and statistical operations on a columnar engine using primitive arrays and BitSet null bitmasks. The library requires Java 17 LTS or later and Maven 3.8+ or Gradle 7+, and ships as a modular set of artifacts — cupoftea-core plus optional CSV, JSON, Excel, Parquet, Arrow, Plot, SQL, HTML, YAML, and XML format modules, or the cupoftea-all aggregator. CupOfTea 0.24.0 adds a first-class Schema definition, an NA missing-value model distinct from empty strings, BigDecimal decimal arithmetic, O(n) quantiles and median via Introselect, rolling and expanding windows, and direct mapping to Java Records and POJOs.

CupOfTea is a lightweight library for data manipulation in Java. It provides a simple and efficient API to work with large structured datasets, enabling operations such as filtering, aggregation, joining, and data analysis. - Create DataFrames from arrays, lists, CSV files, and other sources. - First-class Schema definition: Schema.of "year", INT, "price", DOUBLE . - Optional automatic type inference on CSV, JSON, and Excel ingest. - First-class missing-value model NA distinct from empty strings "" . - Full support for java.time LocalDate , LocalDateTime , Instant . - Exact currency arithmetic using BigDecimal Schema.DECIMAL . - Column selection, row filtering, grouping, aggregation, and slicing operations. - Relational joins: innerJoin , leftJoin , rightJoin , outerJoin , crossJoin with automatic column deduplication, multi-key support, and customizable suffixes. - Statistical Operations & Summary : High-performance linear$O n $ quantiles and median via Introselect , sample and population variance and standard deviation, skewness, kurtosis, covariance, correlation matrix corr , and descriptive summary describe . - Window, Rolling & Cumulative Functions : Sliding rolling windows df.rolling w , expanding windows df.expanding , cumulative operations cumsum , cumprod , cummin , cummax , time series shifts lead , lag , diff , pctChange , and SQL-like analytical window partitioning and ranking df.window .partitionBy ... .orderBy ... .rank . - Read and write CSV, JSON, Excel, Parquet, and YAML files. - DTO & Record Mapping : Import and export standard Java POJOs/JavaBeans and Java Records directly CupOfTea.read .records ... , df.write .records ... , CupOfTea.read .dtos ... , df.write .dtos ... . - Columnar Engine : High-performance contiguous memory layout ColumnVector with primitive int , double , long , float , boolean , String , and BitSet null bitmasks , eliminating per-cell boxed object overhead and row hash lookups. - Unified Mutation Modes : Fluent IN PLACE builder by default with opt-in COPY ON WRITE via .asCopyOnWrite and .asInPlace . - Deep Copy : Explicit .copy deep-copy method on CupOfTea and IDataFrame . - Immutable Row API : Strongly-typed, unmodifiable Row objects with typed accessors getInt , getString , getDouble , getBoolean , getLocalDate , etc. and zero leaking of internal mutable row maps. - Java : Java 17 LTS or later - Build tool : Maven 3.8+ or Gradle 7+ CupOfTea is modular. You can import only the core engine and whichever IO format modules your project needs, or include cupoftea-all for full format support. Add the core dependency to your pom.xml : <dependency <groupId io.github.cupoftea-labs</groupId <artifactId cupoftea-core</artifactId <version 0.24.0</version </dependency Add optional format modules as needed CSV, JSON, Excel, Parquet, Arrow, Plot, SQL, HTML, YAML, XML : php < -- Example: Add CSV and JSON format support -- <dependency <groupId io.github.cupoftea-labs</groupId <artifactId cupoftea-csv</artifactId <version 0.24.0</version </dependency <dependency <groupId io.github.cupoftea-labs</groupId <artifactId cupoftea-json</artifactId <version 0.24.0</version </dependency < -- Or import all formats with the aggregator module: -- < -- <dependency <groupId io.github.cupoftea-labs</groupId <artifactId cupoftea-all</artifactId <version 0.24.0</version </dependency -- For more details on releases and publishing, see docs/community/releasing.md https://github.com/cupoftea-labs/cupoftea/blob/master/docs/community/releasing.md . Groovy DSL build.gradle : // Core library implementation 'io.github.cupoftea-labs:cupoftea-core:0.24.0' // Optional format modules implementation 'io.github.cupoftea-labs:cupoftea-csv:0.24.0' implementation 'io.github.cupoftea-labs:cupoftea-json:0.24.0' // Or all formats at once: // implementation 'io.github.cupoftea-labs:cupoftea-all:0.24.0' Kotlin DSL build.gradle.kts : // Core library implementation "io.github.cupoftea-labs:cupoftea-core:0.24.0" // Optional format modules implementation "io.github.cupoftea-labs:cupoftea-csv:0.24.0" implementation "io.github.cupoftea-labs:cupoftea-json:0.24.0" // Or all formats at once: // implementation "io.github.cupoftea-labs:cupoftea-all:0.24.0" | Module | Description | Dependencies / Formats | |---|---|---| | cupoftea-core | Core DataFrame engine, filtering, aggregation, SPI interfaces | Zero heavy external deps | | cupoftea-csv | CSV format reader and writer | OpenCSV | | cupoftea-json | JSON format reader and writer | Jackson Databind | | cupoftea-excel | Excel format reader .xlsx / .xls | Apache POI 5.5.1 | | cupoftea-parquet | Parquet format reader and writer | Apache Parquet / Hadoop | | cupoftea-arrow | Apache Arrow IPC and Feather zero-copy format reader and writer | Apache Arrow Vector & Netty | | cupoftea-sql | SQL database reader and writer via JDBC with batching and transaction support | JDBC java.sql , javax.sql | | cupoftea-html | HTML table reader | Jsoup | | cupoftea-yaml | YAML format reader and writer | SnakeYAML | | cupoftea-xml | XML format reader | Standard Java XML DOM | | cupoftea-plot | Declarative plotting engine Vega-Lite , HTML export, desktop preview | Jackson Databind | | cupoftea-all | Meta-module aggregating all format and plot modules | All above formats & plotting | IO formats are dynamically discovered via ServiceLoader . Ensure the corresponding format module is on your classpath: python import com.cupoftea.CupOfTea; import com.cupoftea.table.Row; import com.cupoftea.table.Schema; import static com.cupoftea.table.Schema. ; import java.io.File; public class Main { public static void main String args { // Read CSV using fluent API CupOfTea df = CupOfTea.read .csv "data.csv" ; df.print ; // Perform filtering with immutable Row CupOfTea filtered = df.filter row - row.getInt "age" = null && row.getInt "age" 30 ; filtered.print ; // Core pandas-like ops: // Selection and dropping of columns use copy for independent views CupOfTea selected = df.copy .select "name", "age", "salary" ; CupOfTea withoutDept = df.copy .drop "department" ; // Inspection: head, tail, and slicing df.head 5 .print ; df.tail 3 .print ; CupOfTea slice = df.slice 0, 2 ; // Position-based indexing iloc with negative index support Row lastRow = df.iloc -1 ; Object cell = df.iloc 0, 1 ; CupOfTea subset = df.iloc .slice 0, 2, 0, 2 ; // Index-based indexing loc df.setIndex "id" ; Row person = df.loc 101 ; Object name = df.loc 101, "name" ; // Missing value imputation & cleaning using copy for branching CupOfTea filled = df.copy .fillna 0 ; CupOfTea cleaned = df.copy .dropna ; // drops rows with any missing value // Relational joins CupOfTea depts = CupOfTea.read .csv "departments.csv" ; CupOfTea joined = df.innerJoin depts, "department" ; // Or left, right, outer, cross joins: // CupOfTea left = df.leftJoin depts, "department" ; // CupOfTea cross = df.crossJoin depts ; // DataFrame concatenation vertical / rows or horizontal / columns CupOfTea moreData = CupOfTea.read .csv "more data.csv" ; CupOfTea stacked = df.concat moreData ; // or CupOfTea.concat df, moreData // Write to multiple formats filtered.write .csv "filtered.csv" ; filtered.write .json "filtered.json" ; // Or switch to COPY ON WRITE for immutable transformation chains CupOfTea cowDf = df.copy .asCopyOnWrite ; CupOfTea withoutSalary = cowDf.removeColumn "salary" ; } } Format-specific options can also be configured: // Read CSV with custom separator CupOfTea df = CupOfTea.read .option "separator", ";" .csv new File "data.csv" ; CupOfTea provides specialized, fluent columnar expressions for string manipulation and date/time feature engineering: // Vectorized text manipulation df.withColumn "name upper", df.col "name" .str.toUpperCase ; df.transformColumn "name", df.col "name" .str.trim .capitalize ; // Check prefix, suffix, and containment returns BooleanColumnVector BooleanColumnVector isEng = df.col "department" .str.startsWith "Eng" ; // Vectorized temporal operations df.withColumn "hire year", df.col "hire date" .dt.year ; df.withColumn "days since", df.col "hire date" .dt.daysBetween LocalDate.now ; df.transformColumn "hire date", df.col "hire date" .dt.plusMonths 6 ; CupOfTea provides a declarative plotting API df.plot backed by Vega-Lite specifications, producing standalone responsive HTML charts with zero heavy external GUI or native dependencies: CupOfTea df = CupOfTea.read .csv "data.csv" ; // Scatter plot with title, custom labels and desktop preview df.plot .scatter "experience", "salary" .title "Salary vs Experience" .show ; // Histogram with custom binning df.plot .hist "age", 20 .show ; // Grouped bar chart saved to standalone interactive HTML file df.plot .bar "department", "headcount" .saveHtml "chart.html" ; // Box plot comparing salary distributions across departments df.plot .box "department", "salary" .show ; // Line chart, area chart, and 2D heatmap matrix df.plot .line "year", "revenue" .show ; df.plot .area "date", "active users" .show ; df.plot .heatmap "department", "job level", "headcount" .show ; - Interactive HTML Table df.toHtml : Renders responsive HTML with sticky column headers, data type indicators, and client-side pagination: String html = df.toHtml ; // Default pagination with 25 rows per page String fullDoc = df.toHtml TableHtmlConfiguration.builder .pageSize 50 .fullDocument true .build ; - Seamless Jupyter / IJava Cell Rendering : CupOfTea , IDataFrame , and Chart objects implement the standard notebook MIME rendering contract renderHtml and render returning text/html . When a DataFrame or chart expression is evaluated in a Jupyter cell via IJava or Polyglot Notebooks , it renders natively and interactively inside the cell output area. CupOfTea supports multi-threaded parallel execution across row filtering, column mapping, whole-DataFrame aggregations, and GroupBy operations using vectorized chunking and prefix-sum scans: // Switch to parallel execution mode using ForkJoinPool.commonPool CupOfTea parDf = df.asParallel ; // Custom thread pool and parallel threshold ExecutorService customPool = Executors.newFixedThreadPool 8 ; df.parallel customPool .withParallelThreshold 50 000 ; // Parallel filtering with zero-copy vectorized chunking CupOfTea filtered = parDf.filter row - row.getDouble "salary" 80 000.0 ; // Parallel column transformations parDf.mapDouble "salary", s - s 1.10 ; // Parallel whole-DataFrame aggregations Object totalRevenue = parDf.sumOf "revenue" ; Double avgScore = parDf.meanOf "score" ; // Parallel chunk-partitioned GroupBy aggregations CupOfTea summary = parDf.groupBy "department" .agg Aggregations.sum "salary" , Aggregations.mean "experience" , Aggregations.count "employee id" ; // Switch back to sequential single-threaded execution CupOfTea seqDf = parDf.asSequential ; - Window and rolling functions. - Time series resampling and frequency conversion. Contributions are welcome To contribute, follow these steps: 1. Fork the repository. 2. Create a branch for your feature git checkout -b my-feature . 3. Commit your changes git commit -m 'Add new feature' . 4. Push to the branch git push origin my-feature . 5. Open a pull request. This project is licensed under the Apache License, Version 2.0 https://github.com/cupoftea-labs/cupoftea/blob/master/LICENSE . See the LICENSE https://github.com/cupoftea-labs/cupoftea/blob/master/LICENSE file for the full license text.