Matrix

This is a Groovy library (that also works in Java) to make it easy to work with a matrix (tabular i.e. 2-dimensional) data. Whenever you have a structure like this List<List<?>> (typically defined in Groovy like this def myList = [ [1,2,3], [3.4, 7.12, 0.19] ]) a Matrix or a Grid can greatly enhance the experience of working with that data structure.

The Matrix project consists of the following modules:

1. matrix-core The matrix-core is the heart of the matrix project. It contains the Matrix and Grid classes as well as several utility classes to do basic statistics (sum, mean, median, sd, variance, counts, frequency etc.) and to convert data into various shapes and formats See tests for more usage examples or the javadocs for more info.
2. matrix-arff provides reading and writing of ARFF (Attribute-Relation File Format) files.
3. matrix-avro provides ways to import and export between Matrix and Avro.
4. matrix-bigquery provides ways to import and export between Matrix and Google Big Query.
5. matrix-bom Bill of materials for simpler dependency management.
6. matrix-charts provides the Charm grammar-of-graphics rendering engine and export utilities for creating charts in various formats (file, JavaFX, SVG) based on Matrix data.
7. matrix-csv provides a more advanced way to import and export between a Matrix and a CSV file using commons-csv(matrix-core has basic support for doing this built in)
8. matrix-datasets contains some common datasets used in R and Python such as mtcars, iris, diamonds, plantgrowth, toothgrowth etc.
9. matrix-ggplot provides a ggplot2-style charting API (very close to the ggplot2 library in R). Delegates to the Charm engine in matrix-charts.
10. matrix-groovy-ext provides Groovy extensions for more idiomatic numeric operations with Matrix.
11. matrix-gsheets provides ways to import and export between a Matrix and a Google Sheets spreadsheet
12. matrix-json provides ways to import and export between a Matrix and Json
13. matrix-logging optional convenience logging setup for Groovy scripts and small tools.
14. matrix-parquet provides ways to import and export between Matrix and Parquet.
15. matrix-pict provides a familiar chart-type-first API for common visualizations such as bar, line, area, pie, scatter, bubble, histogram, and box charts. Delegates to the Charm engine in matrix-charts.
16. matrix-smile Integration between Matrix and the Smile library (Statistical Machine Intelligence and Learning Engine).
17. matrix-spreadsheet provides ways to import and export between a Matrix and an Excel or OpenOffice Calc spreadsheet
18. matrix-sql relational database interaction
19. matrix-stats The stats library contains statistical methods and tests including correlations, normalization, regression, formula/model-frame workflows, linear algebra, interpolation, t-tests, time-series diagnostics, numerical solvers, distributions, and clustering.
20. matrix-tablesaw interoperability between Matrix and the Tablesaw library. Experimental
21. matrix-xchart allows you to create charts in various formats (file, svg, swing) based on Matrix data and the XChart library.

Setup

Matrix targets Groovy 5 and JDK 21. Binary builds can be downloaded from the Matrix project release page but if you use a build system that handles dependencies via maven central (gradle, maven ivy etc.) you can add your dependencies from there . The group name is se.alipsa.matrix. The version numbers of the matrix modules does not align with each other so a way to handle this in a simpler way is to use the bom file.

An example for matrix-core is as follows for Gradle

implementation(platform('se.alipsa.matrix:matrix-bom:2.5.1'))
implementation('se.alipsa.matrix:matrix-core')

...or the following for maven

<project>
   ...
   <dependencyManagement>
      <dependencies>
         <dependency>
            <groupId>se.alipsa.matrix</groupId>
            <artifactId>matrix-bom</artifactId>
            <version>2.5.1</version>
            <type>pom</type>
            <scope>import</scope>
         </dependency>
      </dependencies>
   </dependencyManagement>
   <dependencies>
      <dependency>
         <groupId>se.alipsa.matrix</groupId>
         <artifactId>matrix-core</artifactId>
      </dependency>
      <dependency>
         <groupId>org.apache.groovy</groupId>
         <artifactId>groovy-all</artifactId>
         <version>5.0.7</version>
      </dependency>
   </dependencies>
   ...
</project>

Matrix-all convenience dependency

When you want every Matrix module and its transitive dependencies, matrix-all is a convenient alternative to importing matrix-bom and selecting individual modules. It is simpler, but less flexible and brings in more dependencies.

matrix-all intentionally does not include a Groovy runtime, so add the Groovy version your application uses explicitly:

implementation('org.apache.groovy:groovy-all:5.0.7') 
implementation('se.alipsa.matrix:matrix-all:2.5.1')

<project>
   ...
   <dependencies>
      <dependency>
         <groupId>org.apache.groovy</groupId>
         <artifactId>groovy-all</artifactId>
         <version>5.0.7</version>
      </dependency>
      <dependency>
         <groupId>se.alipsa.matrix</groupId>
         <artifactId>matrix-all</artifactId>
         <version>2.5.1</version>
      </dependency>
   </dependencies>
   ...
</project>

Logging

Matrix itself does not require SLF4J, Log4j, JUL, or any other logging framework. Matrix logs through a small matrix-core logger backed by the JDK System.Logger facade.

Some Matrix modules use third-party libraries that log through SLF4J, Log4j, JUL, or JDK Platform Logging. Applications should choose one logging backend and route the other logging APIs into it. Groovy script users who want an out-of-the-box default can add matrix-logging. See Logging setup for Gradle and Maven examples for SLF4J/Logback, Log4j 2, and JUL.

Java Version Requirements

The project requires JDK 21. While some modules may work with higher JDK versions, the following constraints apply:

Module(s)	Constraint	Reason
matrix-parquet, matrix-avro	JDK 21 max	Hadoop 3.4.x dependencies do not support JDK 22+
matrix-charts	JDK 21 max	JavaFX 23.x is the latest version compatible with JDK 21; JavaFX 24+ requires JDK 22+
matrix-smile	JDK 21 min	Smile 4.x is used (requires at least java 21; Smile 5+ requires Java 25)

Since Matrix is a library, it makes sense to stay on java 21 to ensure compatibility across all modules for the foreseeable future. These constraints are enforced in build.gradle via dependency version ceiling rules.

For more information see the tutorial and the readme file and test classes in each subproject.