verri / jules

Statistical computing library that aims to provide R-like experience in modern C++

Jules

Jules is a statistical computing library that aims to provide R-like experience in modern C++.

Currently, it focus on a versatile, yet easy-to-use multi-dimensional array implementation with some common statistical functionalities.

A implementation of data frames and their common operations inspired by Tidyverse is also intended, but it will probably require many features to come to C++ in the next years.

Dependencies

• C++17 compiler
  • Tested on GCC 7.4.0 and Clang 7.0.0
• debug_assert
• range-v3 (soon to be superseded by C++20 Ranges)
• CBLAS (optional)
• Catch (testing)

Installation

If you intend to use BLAS optimized functions, make sure CBLAS is installed.

Recommended: Local Git Submodule

The recommended installation of the library is including it as a submodule of your Git project.

In your project, do

$ git submodule add https://github.com/verri/jules.git external/jules

Local copy

Download the latest release and unzip it.

System-wide installation

For Arch Linux users, install the AUR package jules-git via pacaur, makepkg, or any other method of your preference.

System-wide installation is recommended only if you are sure about what you doing.

Clone the repository.

$ git clone https://github.com/verri/jules.git
$ cd jules

Install via CMake 3.0+.

$ cmake -H. -Bbuild
$ cmake --build build --target install

Usage and Compilation

Jules is a header-only library, so you just need to instruct the compiler its location.

Recommended: CMake 3.0+

If you installed the library as a submodule, include the following line in your CMakeLists.txt

add_subdirectory(external/jules)
target_link_libraries(my-target PRIVATE jules)

If you installed system-wide, use

find_package(Cool REQUIRED)
target_link_libraries(my-target PRIVATE ${Cool_LIBRARY})

If using BLAS, make sure to link to your target.

find_package(BLAS REQUIRED)
target_link_libraries(my-target PRIVATE ${BLAS_LIBRARIES})

Compiler flags

You can directly specify the compiler flags:

CXXFLAGS="-std=c++17 -isystem/path/to/release/include"

If using BLAS, make sure to link it using -lblas or -lcblas, depending on your system.

Documentation

Generated with standardese here (not up-to-date, since standardese is not progressing very well).

Soon, we should provide a cheatsheet with a summary of functionalities. In the meantime, the examples in the test folder should suffice.

Acknowledgements

This project is supported by FAPESP as part of the project "High level data classification based on complex network applied to invariant pattern recognition" (2013/25876-6).

jules's Issues

Base/Numeric utilities based on R base package.

All these functions should receive an range with 0 or more elements.
The result for an empty range must be well defined.

Arithmetic

• sum
  • sum(empty<T>) returns jules::numeric_traits<T>::additive_identity()
• prod
  • prod(empty<T>) returns jules::numeric_traits<T>::multiplicative_identity()
• mean
  • Effectively mean(rng) -> sum(rng) / length(rng)
• max
  • max(empty<T>) returns jules::numeric_traits<T>::unbounded_min()
• min
  • min(empty<T>) returns jules::numeric_traits<T>::unbounded_max()

Logical:

• all
  • all(empty<bool>) returns true
• any
  • any(empty<bool>) returns false
• none
  • none(empty<bool>) returns true
• which
• count
• freq

Set operations:

All of them assume that the input ranges are sorted.

• unique
• set_difference
• set_union
• set_intersection
• includes

The ones that return a range will return jules::const_vector by default.
A mechanism to control this output should be provided.

Fast indirect slicing for jules::vector

We can exploit the simple nature of jules::vector to improve indirect slicing, which is very common.

• Simplified version of indirect_slicing/do_slice
• Using move semantics so we do not copy indexes

Disable array operator if operation is invalid.

It is necessary to arrays work well with ranges.
If operating with a range::view, it will call operator| for the elements instead of operating the array.

jules::random must not depend on Array.

Since it uses jules::array it cannot be inside jules::base (circular dependency).

Array allocator must consider POD and noexcept constructors.

Column class shouldn't have a name

The name should be part of the dataframe object.

dplyr-like dataframe operations.

Dataframes should be modified using only dplyr-like operations and views.
Raw exposure of columns may result in an invalid dataframe.

Function as objects

So they work as a parameter in apply.

Disable bitwise operators for arrays.

• Ranges TS uses operator| for actions and views;
• Other libraries my also use them;
• They are not common in high level codes;
• There is always apply as an alternative.

Add in-place constructors.

Elements of jules::base_array and jules::base_column may not have a copy constructor.

GCC-6 cannot link cblas on travis.

Module structure and dependencies.

-> means depends on

Structure

• Core
  • Debug (standalone)
  • Type (standalone)
  • Range
• Base -> Core
  • Async
  • Numeric
  • Random
• Array -> Base
  • Slice (standalone, except for Base and Core)
  • Expression, Ref, Contiguous, Indirect, Base Array
  • IO
  • Functional
  • BLAS
  • Numeric
• Dataframe -> Array
  • Column
  • Expression -> Column
  • Dataframe -> Expression
  • IO -> everything else

Dependencies

Dataframe -> Array -> Base -> Core

Implement jules::const_vector

Thread-safe, memory-shared vector with constant values.

It should decrease memory usage in cases where std::vector<jules::index_t> are required.

Reduce header dependencies.

Maybe create a <jules/array.hpp>.

Document the formatted input and output of arrays.

• { a b c }; or
• { a, b, c }

coverage: Travis gcov cannot understand clang output.

Do not use std::iterator

std::iterator is probably going to be deprecated soon.