apjanke / octave-tablicious Goto Github PK

View Code? Open in Web Editor NEW

28.0 5.0 11.0 28.81 MB

Table (relational, tabular data) implementation for GNU Octave

Home Page: https://apjanke.github.io/octave-tablicious/

License: GNU General Public License v3.0

MATLAB 89.51% M 0.92% Makefile 0.67% Shell 0.10% C++ 0.40% Mercury 7.31% Objective-C 1.07%

octave relational-algebra

octave-tablicious's Introduction

Tablicious for GNU Octave

Tablicious provides tabular/relational data structures for Octave. You can think of it as "pandas for Octave".

WARNING: This library is currently beta quality. Do not use it in any production or business code! Seriously!!

This package attempts to provide a set of mostly-Matlab-compatible implementations of the table class and related structures and functions. It provides:

table and related construction/conversion functions
Missing Data support
- ismissing and friends: rmmissing, standardizeMissing
- @missing
- fillmissing is not implemented yet, because that requires some actual math.
eqn and isnanny
- These are experimental Octave extensions for dealing with NaN-like values. They are used by table, ismissing, and friends, but should be generally useful, and need to be global so they can be overridden by user-defined classes.
string
categorical

It currently does not provide, but we would like to add:

timetable
Table I/O, such as readtable, writetable, and csvread/dlmread table support

The string and categorical support are incomplete, and less mature than the rest of the package.

Installation and usage

Quick start

To get started using or testing this project, install it using Octave's pkg function:

pkg install https://github.com/apjanke/octave-tablicious/releases/download/v0.3.7/tablicious-0.3.7.tar.gz
pkg load tablicious

Installation for development

If you want to hack on the Tablicious code itself, set it up like this:

Clone the repo
- git clone https://github.com/apjanke/octave-tablicious
Add the inst/ directory from the repo to your Octave path.

Documentation

Once you have Tablicious installed, the user manual will show up in the Octave GUI’s documentation browser. You can also run help <foo> or doc <foo> for any of the classes or functions in Tablicious.

The documentation for the latest development version can be viewed online at https://apjanke.github.io/octave-tablicious/doc/tablicious.html.

See the doc-project/ directory for notes on this project, especially for Developer Notes and Design and Justification, which discusses how and why this library is written. Also see CONTRIBUTING if you would like to contribute to this project.

Contributing

See CONTRIBUTING.md for more details.

No Matlab usage!

To avoid issues with the Matlab license's Non-Compete clause, this project needs to be developed entirely using Octave, and not using Matlab at all, including for testing or benchmarking purposes. Please do not submit any Matlab test or benchmark results, or any code produced using Matlab. And if you know anything about how the Matlab internals work, please do not tell me!

Author and Acknowledgments

Tablicious is created by Andrew Janke.

Thanks to Polkadot Stingray for powering my coding sessions.

Shout out to Mike Miller for showing me how to properly structure an Octave package repo, and encouraging me to contribute.

Thanks to Sebastian Schöps for getting me more involved in Octave development in the first place, via his Octave.app project.

octave-tablicious's People

Contributors

Stargazers

Watchers

Forkers

mtmiller scivision dgmz tabbar seedalive jayant-ism rdzman pratyushd35 reprostat

octave-tablicious's Issues

`pkg uninstall chrono` on Windows 10 fails if Chrono has been loaded during that Octave process

After a clean install withpkg install https://github.com/apjanke/octave-addons-chrono/releases/download/v0.1.0/chrono-0.1.0.tar.gz:

>> pkg install https://github.com/apjanke/octave-addons-chrono/releases/download/
v0.1.0/chrono-0.1.0.tar.gz
warning: doc_cache_create: unusable help text found in file 'calendarDuration'
warning: Failed detecting system time zone: Unrecognized Windows time zone ID: 'Eastern Standard
Time
DisplayName                : (UTC-05:00) Eastern Time (US & Canada)
StandardName               : Eastern Standard Time
DaylightName               : Eastern Daylight Time
BaseUtcOffset              : -05:00:00
SupportsDaylightSavingTime : True



'
Falling back to ''
warning: doc_cache_create: unusable help text found in file 'datetime'
warning: doc_cache_create: unusable help text found in file 'duration'
>> pkg list chrono
Package Name  | Version | Installation directory
--------------+---------+-----------------------
      chrono  |   0.1.0 | C:\Octave\OCTAVE~1.1\share\octave\packages\chrono-0.1.0
>> cd('C:\Octave\OCTAVE~1.1\share\octave\packages\chrono-0.1.0')
>> runtests .
Processing files in C:\Octave\OCTAVE~1.1\share\octave\packages\chrono-0.1.0:

  datetime.m .................................................. PASS      3/4
                                                                  FAIL    1
  duration.m .................................................. PASS      3/3

The following files in C:\Octave\OCTAVE~1.1\share\octave\packages\chrono-0.1.0 have no tests:

NaT.m               days.m              milliseconds.m      years.m
calendarDuration.m  hours.m             minutes.m
calmonths.m         isdatetime.m        seconds.m
calyears.m          isduration.m        timezones.m
>> pkg uninstall chrono
error: couldn't delete directory C:\Octave\OCTAVE~1.1\share\octave\packages\chrono-0.1.0: Permiss
ion denied
error: called from
    uninstall at line 120 column 11
    pkg at line 451 column 7
>>

Add newlines to my error messages

So they don't show backtraces.

Make Makefile project-generic

The Makefile has a hardcoded packagename in the make local step (for "octave_chrono_make_local"). Generify this so the Makefile can be copied between projects without modification.

"doc_cache_create: unusable help text found in file 'datetime'" in install

>> pkg install /Users/janke/local/repos/octave-addons-chrono/target/chrono-0.1.2.tar.gz
warning: doc_cache_create: unusable help text found in file 'calendarDuration'
warning: doc_cache_create: unusable help text found in file 'datetime'
warning: doc_cache_create: unusable help text found in file 'duration'
>>

Dimension names (with customizability)

Matlab's table allows you to change the dimension names. This interacts with the rowDimName argument for sortrows and other methods. Add support for this.

categorical.summary

Need a summary() for categorical in addition to the one for table.

I suppose maybe we should just make a big polymorphic one and cover many data types. E.g. numerics are obvious. And it would be nice to have one that summarizes string arrays by cardinality/density/chunkiness. Just like each table variable of that form is summarized.

vartype

vartype is fancy: it produces an object which can be used to index into a table, selecting variables which match a type specification. This means it needs to return an object (that we need to define a classdef for), and handling its logic can be done either in subsref/subsasgn of table, or in a subsind method of the returned class.

Summary data display

Gonna need to do a whole type hierarchy for this.

Each variable needs a custom sub-display output based on its type.
Since per-variable summary types vary, we'll need a heterogeneous collection of custom per-variable summary objects.
Maybe we could collect those in a struct of sub-objects.
- But we'll also need object-level summary data for object-level stuff like tbl.Description.
- So, a table-level object that has a collection of table-level properties, and then a struct of heterogeneous per-variable summary objects?

I'm thinking:

octave.table.internal.TableSummary
- field .TableProperties: struct of (name, string)
- field .VariableSummaries: struct of (name, octave.table.internal.VariableSummary subclasses)
octave.table.internal.VariableSummary
- abstract type with concrete subtypes for various variable types
- method print(this, indent) for incorporation into indented table summary output
- concrete subclasses for:
  - Numeric (with polymorphic handling of actual scalar numeric values for display of min/max/median/mean/etc)
  - logical
  - cellstr
  - table for nested tables, sheesh
    - maybe this is a wrapper around octave.table.internal.TableSummary?
    - do we recursively display the full indented table summary for the nested table, or just a top-level summary? See #22 (“nested table support”).
  - datetime
    - harder because datetime itself is not implemented yet
  - categorical
    - harder because categorical itself is not implemented yet
- will need a generic one that just contains a dumb single-string summary of the variable

Maybe remove `semidiff`

semidiff exists as just an alias for antijoin. It's there because I tend to use "semidiff", even though "antijoin" is the much more common term (based on Google search results).

Consider removing semidiff to reduce cognitive load on API clients and override responsibilities for things that want to duck type or participate in inheritance with table.

Nested table support

Need to support nested tables. That is, tables, with table-valued variables. These behave somewhat differently than the regular polymorphic array behavior. For example, they have special display formats in the prettyprint output (See the splitvars doco and the summary doco).

Include RowNames in disp and prettyprint output

All basic `table` functions

This is a list of all the functions/methods we need to implement for basic Matlab-compatible table functionality.

I'll give these a check mark when the “basic” functionality is implemented, even if not all options are supported. At that point, the options for that function should get its own issue to track it.

Construction/Conversion

I/O - #49

Summary Info

Sort/Rearrange

Sort

sortrows – #12
unique
issortedrows
topkrows

Rearrange

Reshape

rows2vars
stack
unstack
inner2outer

Customize

addprop
rmprop

Relational

join – Basic/default behavior is done, but no options supported, and there are a lot of significant options here.
innerjoin – #16
outerjoin – This is going to be a hard one, because we have to determine fill values for arbitrary types in a polymorphic manner.
union
intersect
ismember
setdiff
setxor

Relational (Octave/Janke extensions)

Missing values - #17

ismissing – #17
standardizeMissing – #17
rmmissing – #17
fillmissing

Function application

Function application (Janke extensions)

evalWithVars
restrict (with eval string input support)
groupby – Janke's preferred interface for doing group & aggregate operations.

In Travis, on test failure, get failed test details into build output

Currently:

$ make test
octave --no-gui --silent --norc --eval="octave_chrono_make_local"
Built __oct_time_binsearch__
./dev-tools/runtests.sh inst
octave: X11 DISPLAY environment variable not set
octave: disabling GUI features
Processing files in /home/travis/build/apjanke/octave-chrono/inst:
  datetime.m ............................................. PASS    0/4    FAIL 4
  duration.m ............................................. PASS    0/3    FAIL 3
The following files in /home/travis/build/apjanke/octave-chrono/inst have no tests:
NaT.m               days.m              milliseconds.m      years.m
calendarDuration.m  hours.m             minutes.m
calmonths.m         isdatetime.m        seconds.m
calyears.m          isduration.m        timezones.m
runtests.sh: Some tests FAILED!
Makefile:174: recipe for target 'test' failed
make: *** [test] Error 1
The command "make test" exited with 2.

I want full details of exactly which tests failed in a run that had failures.

plot(table) methods

Write methods that lets you say plot(tbl, keyCol) and have it plot its contents as timeseries, scatter plots, and so on.

Right now you have to say:

plot(C.Key, [C.A2 C.A3 C.B2 C.B3])
xlabel('Key')
legend({'A2' 'A2' 'B2' 'B3'})

Should take the specified column as X, and all the other columns (or a user-specified set of columns) as Y.
- Maybe it should even default to taking the first column as X, and the remaining columns as Y.
Should automatically fill in the XLabel and legend.
For timetable, should automatically take Row Times as X by default
Maybe support timeseries, too

In addition, it should support stairs, scatter, maybe histogram, stackedplot, boxplot, maybe bar and barh, and so on.

As far as I can tell, Matlab does not support this.

What you should probably do is write this plotting toolkit as a layer on top of table and base handle graphics plotting, and publish it as a Matlab toolbox, too.

Also consider how plotting would work for timetable objects. Maybe this stuff could be factored out to a shared mixin superclass.

Plots to include

2-D plots

3-D plots

Sheesh, that's a lot of plotting functions. Maybe this isn't such a great idea. I don't know how much value the convenience of plotting from a table has vs that work.

On the other hand, the work is probably just proportional to how much it takes to map variable names and values to inputs of the underlying plot calls, which is what all users of tables would have to do in their absence, so it might be a good value.

Maybe just do the more commonly used plotting functions. If nothing else, adding these would be a good test of whether I have decent example data sets available in Octave or Tablicious, and would be good practice using these functions.

API stack management for error message function name prefixing

Octave error messages are supposed to be prefixed with the function name that raises them. Right now, Chrono hardcodes function names in its error messages. That's annoying because it's a hardcode, and because internal function names are exposed. Only user-facing API function names should actually be presented.

Fix this by making a public-API function call stack tracking mechanism.

Octave `pkg` and Texinfo/QHelp support

This thing needs to be installable as an Octave pkg package. Needs:

Installability from a release URL
Qt QHelp documentation support so doc <whatever> works

Use octave-chrono as a model for this. Except, now that this has a class with a bunch of methods, would be nice to add support for multi-part Texinfo documentation where each Texinfo fragment is positioned in the source code next to the method it's documenting, instead of requiring it all to be in a single block at the top of the classdef file.

Supporting multiple Texinfo blocks has some complications: helptext blocks attached to methods are logically associated with the methods, and they can be reordered based on class structure by the helptext interpreter. Texinfo is a linear document, and simply concatenating multiple Texinfo blocks found within the source code would tie the document structure to the source code ordering. Sigh.

Doing this will require additional build/release steps. Oh well; it's necessary.

`datetime` support

All of the timetable and date/time support in table kind of wants a datetime class to exist, which it doesn't in Octave.

This affects all of internal variable representation, timetable obviously, and the Excel and CSV I/O functions.

I have a start of one going at octave-chrono, but it's nowhere near acceptance into core Octave or even Octave Forge.

Clarify `mustBeA()` vs `mustBeType()`

I currently have a mustBeType() private function, but it's using isa(...) instead of isequal(class(x), ...). By naming convention, I think mustBeA() should be using isa(), and mustBeType should be using the exact isequal(class(...)...) test. Resolve this.

Move stuff into +octave namespace

If the idea is to get Tablicious into core Octave 6, and provide the package as a compatibility package for older Octaves, it should be using the same namespaces as it will end up in once added to Octave. I think that will be the +octave namespace for non-Matlab-compatible stuff.

Move stuff out of the +tablicious namespace into +octave, like +octave/+table and +octave/+internal.

Degenerate natural `realjoin` should be Cartesian product

Right now, a degenerate realjoin (that is, no variable names in common) produces an error, just like a degenerate join. In relational algebra, a degenerate join (no key columns in common) produces a Cartesian product, not an error. realjoin should probably do that.

The “plain” join should not degenerate to cartesian product, for Matlab compatibility: I'm pretty sure Matlab's table's join requires at least 1 common key column, defined either naturally or by input options.

Unit Tests

This package needs tests (BISTs). For everything.

'legacy' option for union(), intersect(), setdiff(), and other setwise operations

I didn't bother implementing the 'legacy' option for the setwise operations, or even detecting it and raising a "not implemented" error. Do this, at least to the point where it passes the 'legacy' flag on to the core Octave union/intersect/etc functions, or produces an appropriate error.

Should probably detect and silently ignore the 'rows' option flag, too.

sizeof for table, string, categorical, datetime

Need to override sizeof for my classes. The built-in Octave sizeof doesn't count user-defined object sizes correctly.

Group detection logic

Need to define group detection logic. This is needed for splitapply, varfun's GroupVariables option, and so on. This is a big enough piece of work that it needs its own tracking issue.

sizeof() and whos() Bytes display

sizeof(tbl) and the Bytes display in whos both report 0 bytes for the size of table objects.

I think this is because the default Octave sizeof and whos don't have support for classdef objects, and consider all classdef objects to be 0 bytes. whos doesn't respect sizeof overrides, either.

Upstream bug report: https://savannah.gnu.org/bugs/?55810.

Could partially fix this by overriding sizeof. I'd rather see this fixed in core Octave, though.

Convert helptext to Octave style doco

What function doco there is, is currently in Matlab helptext style. Convert it to Octave texinfo format.

`realjoin()` method

Make a realjoin() method that removes the key restrictions of Matlab table's join() and does a full relational-algebra JOIN with many-to-many key relationships (where “many” can be 0, 1, or more on either side).

GNU Octave code style

Will need to get this into standard GNU Octave code style before it'll be accepted in to core Octave, and probably in order to get it on to Octave Forge.

Use double-quoted strings by default
Use ! instead of ~
Maybe snake_case for identifiers?

Also Texinfo format documentation; see #2, #28.

Move examples to separate class and/or namespace

There's a table.exampleSpDb example method in table. That's a bad place for it because

a) it clutters up the table interface, and
b) as a member of the table class, it has access to private methods, but examples should really be written as clients of table, using only table's public API.

Extract the examples to a separate tableExamples or table.examples class or namespace (which does not inherit from table).

Allow some prohibited structural operations

We have these prohibited structural operations, because they don't make sense in the general case for table:

transpose
ctranspose
circshift
length
shiftdims

But some of them make sense in some cases for some values of tables. For example:

transpose and/or ctranspose could work when RowNames are present and are all distinct, valid variable names.
circshift could make sense for just dims 1 and 2.
length, though it's lousy usage, is well-defined as just max(size(this))..
shiftdims could be allowed to operate on just dims 1 and 2, in the cases where transpose is valid.

Consider allowing and implementing these.

QHelp collection does not get unregistered when you uninstall without unloading first

Do this:

>> pkg install https://github.com/apjanke/octave-addons-chrono/releases/download/v0.1.1/chrono-0.1.1.tar.gz
>> doc
>> pkg load chrono
>> pkg uninstall chrono

The "Chrono for Octave" manual will still be sitting there in the doc browser.

`.Properties` access

Matlab's table supports the magic .Properties dot-reference to access object properties instead of a variable named Properties.

This currently doesn't work.

>> [s,p,sp] = table_examples.SpDb;
>> s.Properties.VariableNames
error: table has no variable named 'Properties'
error: called from
    getVar at line 575 column 9
    subsref at line 303 column 15

Implement this. Needs to be supported for both rvalue (subsref) and lvalue (sugsasgn) access.

“missing” value indicator semantics

There's a whole section of work to be done for missing value indicators. Need to support heterogeneous cell arrays of indicator values, with support for NaN, NaT, Inf, etc, with polymorphic value detection.

I think some of this can be built on top of an ismissing(x, indicator) function that supports indicator properly, along with a standard missing value mapping:

standardizeMissing(x, indicator) is just x(ismissing(x, indicator)) = standardMissingValueForTypeOf(x).
rmmissing(x, indicator) is just x(ismissing(x, indicator)) = []
fillmissing(x, indicator) is more complicated, because you have to decide how to fill, but its selection of values to fill is probably just ismissing(x, indicator)

Though supporting polymorphism for standardMissingValueForTypeOf(x) in a way that user-defined classdefs can override will be a bit harder, especially if methods(some_classdef) is still not working.

For table support, we can probably defer fillmissing(), or maybe all the (..., indicator) support, to the core fillmissing/ismissing functions, just letting them bomb with a "not implemented" message, because that part isn't table's responsibility.

`sortrows` harmonization with Octave negative-index inputs

table.sortrows is implemented in terms of sortrows, including passing its options on to the individual variables' sortrows calls. The problem is that table.sortrows declares that it supports all the Matlab sortrows arguments and options. But Octave's sortrows doesn't support that. In particular:

Octave's sortrows doesn't support MissingPlacement or ComparisonMethod name/val options.
Octave represents descending column sorts with a negative column index, instead of a separate 'ascend'/'descend' option.

Harmonize this as much as you can. This may include putting in an upstream Octave bug to request support for additional Matlab-compatible calling forms in its native sortrows. Also, decide whether table's sortrows, in particular its column and 'ascend'/'descend' options should primarily match Octave's or Matlab's, or if it's going to try to combine both in its public interface.

todatetime() and tolocaldate() functions

Typing out datetime.ofDatenum() is tedious. And the default datetime constructor behavior of interpreting input numerics as datevecs instead of datenums is a bummer. Add a todatetime() global function as a convenience converter. If you add localdate, add a tolocaldate() global function, too.

Optimized simultaneous set operations calculation

It's possible that it would be more efficient to simultaneously calculate a combination of join, symmetric semijoin, and/or symmetric antijoin all at the same time (using an optimized merge-sort-based simultaneous-calculation oct-file, done on top of a single call to proxyKeysForMatrixes).

This could be a performance win because much of the cost of relational operations for tables with non-numeric variables is in the cost of computing the proxy keys. The proxy keys for two tables are the same regardless of which relational operation is being done, so you can compute them once and re-use them for all relational operations between the same two input tables.

Consider adding this as an advanced feature.

This would be an Octave extension, because Matlab does not define any mechanism for this. (I don't know if Matlab even uses proxy keys at all.)

Maybe replace `isa (x, 'table')` checks with `istable (x)`

Maybe replace isa (x, 'table') checks with istable (x). Consider the override semantics of istable() before doing so.

fillmissing: movmean and movmedian support

Most of fillmissing() is implemented, but it's still missing support for the 'movmean' and 'movmedian' fill methods.

What's the difference between Matlab table’s `join()` and `innerjoin()`?

Isn't join() itself a natural inner join? Does innerjoin() relax the key relationship restrictions of join()?

Degenerate natural semijoin and antijoin should produce output instead of error

The degenerate cases of natural semijoin and antijoin where they have no variable names in common probably have a correct output, so they should produce output instead of error like they do now.

I think it's the case that:
a) The degenerate case of JOIN is the cartesian product (all rows in A match all rows in B).
b) Thus, the degenerate case of semijoin should be that all rows in the inputs are kept.
c) And thus, the degenerate case of antijoin should be the empty set, because antijoin is simply the inverse of the results of semijoin.
But I need to verify that.

Table file I/O

Matlab's table support includes I/O functions for reading and writing tables to and from various file types:

I/O Functionality

It supports CSV, TSV/delimited, fixed-width fields, and Excel files. (And Open Office .ods files?)

Excel files are going to be the big issue here. They're a complex file format that's hard to parse, so we'll probably need to pull in a library to do this. Apache FOP would be the obvious choice for me. But that's Java, and Java is not available in all Octave builds, so Octave prefers not to have anything in core that depends on Java. And I'd like to see Tablicious make it in to core Octave some day.

This is going to be a big task.

References

TODO

Research C/C++ Excel I/O libraries.
Research the Octave Forge io package to see if I can build on top of that.
- For both Excel and regular csv/dlm reading.

N-dimensional non-matrix variable value support

Based on https://www.mathworks.com/help/matlab/ref/table2array.html, it looks like Matlab's table supports variable values with more than 2 dimensions. None of my current code supports that.

`timetable` class

There's a Matlab timetable class closely related to table. It should probably be included for full support.

Doing this well probably means defining an abstract “tabular” superclass that both table and timetable inherit from, with the subclasses specializing row identifiers to either RowNames or RowTimes. Bleh.

Doing this well also probably really wants a datetime class to be implemented, so the row times can be represented as datetime or another type-aware time type, instead of doubles that are forced by context to be interpreted as datenums. Meh.

Low priority because it's not needed for table to work on its own.

Make internal implementation methods private

There are some methods that are intended for internal use, but are currently public on table so they can be used in debugging. When development is more stable, make them private. Or at least Hidden.

resolveColRef
resolveRowColRefs
subsetRows
subsetCols
setcol

Have Makefile check for adequate texinfo version

We require something like Texinfo 5.x or 6.x. Texinfo 4.8 is too old, and if you run with it, you'll get these errors:

$ make doc                                                                                                                           ✘ 2 master ✖ ✱
cd doc && make all
makeinfo --no-split -o chrono.info chrono.texi
chrono.texi:10: warning: unrecognized encoding name `UTF-8'.
chrono.texi:31: warning: undefined flag: VERSION.
chrono.texi:53: warning: undefined flag: VERSION.
chrono.texi:79: warning: undefined flag: VERSION.
chrono.texi:729: warning: undefined flag: VERSION.
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:389: `Functions Alphabetically' has no Up field (perhaps incorrect sectioning?).
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:335: `Functions by Category' has no Up field (perhaps incorrect sectioning?).
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:243: `Defined Time Zones' has no Up field (perhaps incorrect sectioning?).
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:148: `datenum Compatibility' has no Up field (perhaps incorrect sectioning?).
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:335: warning: unreferenced node `Functions by Category'.
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:243: warning: unreferenced node `Defined Time Zones'.
/Users/janke/local/repos/octave-chrono/doc//chrono.texi:148: warning: unreferenced node `datenum Compatibility'.
makeinfo: Removing output file `chrono.info' due to errors; use --force to preserve.
make[1]: *** [chrono.info] Error 1
make: *** [doc] Error 2

Check explicitly for the Texinfo version so you can produce a more helpful error message when user is running with a too-old version.

Metadata for Properties & Variables (VariableUnits, VariableDescriptions, CustomProperties)

More properties we need to support:

Description
VariableUnits
VariableDescriptions
CustomProperties, ugh.

These should be included in the summary() output, maybe in prettyprint(), and they need to be propagated correctly when combining tables.

See also #4 (Dimension names), #20 (circshift and friends).

User guide doco for functional areas

See how issue #1 has all the table functions split up by functional area? Make a similar section of the user guide under the “table Class” section which discusses those functional areas, how to think of them, and how to use the methods in them.

Distinguish 0-row table with present but 0-long `RowNames` from non-present `RowNames`?

Currently, whether a table has RowNames or not is represented by whether the .RowNames field is empty or not. But in the degenerate case of a 0-row table, this can't distinguish between the case where it does not have row names, and the case where it does have row names but it's just a 0-long array because there are 0 rows in the table. Maybe do something about this; maybe with a separate HasRowNames flag field.

localdate object

Make a localdate object that is just a date, not a date/time. Analagous to Joda-Time’s LocalDate object.

Storage representation should probably be a 32-bit signed integer that is the number of days since the Unix epoch (Jan 1, 1970).

No implicit conversion between localdate and datetime! "Type safety" is the major reason for this class to exist. Or maybe, localdates can be assigned to datetimes, but not vice versa. That’s probably safe enough Or maybe allow assignment from datetime to local date, but only if the fractional part of the datetime is exactly zero. That’s maybe safe enough. But probably not: it won’t catch coding errors when your test data just happens to contain all-midnights, and then you go to production and fractional days slip in and you end up with a run time error in production.

To make initial implementation easy, you can cheap out and do the datestr(), datevec(), and datestruct() implementations by widening the underlying date values to datenums, using the Octave-provided datenum conversion functions, and then truncating the output as appropriate. A better implementation would provide its own calendrical calculations.

Checklist

Basic implementation – apjanke/octave-chrono@5bc4d02
Arithmetic
Interconversion with datetime

Change “columns” terminology to “variables”

The current work-in-progress uses the terms "cols"/"columns" and "vars"/"variables" interchangeably. This is wrong: they should all be "variables" when referring to one of the things exposed/contained/aggregated at the top level of of the table container; "columns" are properties of thosee individual variables; arguably, the column count of the table should be the sum of the column counts of the variables. Rename to reflect this.