\input texinfo    @c -*-texinfo-*-

@c %**start of header

@set VERSION 0.4.7

@setfilename tablicious.info
@settitle Tablicious v@value{VERSION}
@documentencoding UTF-8

@c %**end of header

@copying
This manual is for Tablicious, version @value{VERSION}.

Copyright @copyright{} 2019, 2023, 2024, 2025, 2026 Andrew Janke

@quotation
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.
@end quotation
@end copying

@documentdescription
User manual for Tablicious for Octave.
@end documentdescription

@titlepage
@title  Tablicious for GNU Octave
@subtitle version @value{VERSION}, February 2026
@author Andrew Janke
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@dircategory Math
@direntry
* Tablicious: (tablicious).         Tablicious package for Octave
@end direntry

@shortcontents
@contents

@ifnottex
@node Top, Introduction
@top Tablicious for GNU Octave

This manual is for Tablicious, version @value{VERSION}.
@end ifnottex

@menu
* Introduction::
* Getting Started::
* Table Representation::
* Date and Time Representation::
* Validation Functions::
* Example Data Sets::
* Data Sets from R::
* Missing Functionality::
* API Reference::
* Copying::
@end menu


@node Introduction
@chapter Introduction

@quotation
Time is an illusion. Lunchtime doubly so.

@author Douglas Adams
@end quotation


This is the manual for the Tablicious package version @value{VERSION} for GNU Octave.

Tablicious provides somewhat-Matlab-compatible tabular data and date/time support for
GNU Octave.
This includes a @code{table} class with support for filtering and join operations;
@code{datetime}, @code{duration}, and related classes;
Missing Data support; @code{string} and @code{categorical} data types;
and other miscellaneous things.

This document is a work in progress. You are invited to help improve it and
submit patches.

Tablicious’s classes are designed to be convenient to use while still being efficient.
The data representations used by Tablicious are designed to be efficient and suitable
for working with large-ish data sets. A “large-ish” data set is one that can have
millions of elements or rows, but still fits in main computer memory. Tablicious’s main
relational and arithmetic operations are all implemented using vectorized
operations on primitive Octave data types.

Tablicious was written by Andrew Janke <@email{floss@@apjanke.net}>. Support can be
found on the @url{https://github.com/apjanke/octave-tablicious, Tablicious project
GitHub page}.


@node Getting Started
@chapter Getting Started

The easiest way to obtain Tablicious is by using Octave's @code{pkg} package manager.
To install the development prerelease of Tablicious, run this in Octave:

@example
pkg install https://github.com/apjanke/octave-tablicious/releases/download/v0.4.7/tablicious-0.4.7.tar.gz
@end example

(Check the releases page at @url{https://github.com/apjanke/octave-tablicious/releases} to
find out what the actual latest release number is.)

For development, you can obtain the source code for Tablicious from the project repo on GitHub at
@url{https://github.com/apjanke/octave-tablicious}. Make a local clone of the repo.
Then add the @file{inst} directory in the repo to your Octave path.



@node Table Representation
@chapter Table Representation

Tablicious provides the @code{table} class for representing tabular data.

A @code{table} is an array object that represents a tabular data structure. It holds
multiple named “variables”, each of which is a column vector, or a 2-D matrix whose
rows are read as records.

A @code{table} is composed of multiple “variables”, each with a name, which all have
the same number of rows. (A @code{table} variable is like a “column” in SQL tables
or in R or Python/pandas dataframes. Whenever you read “variable” here, think
“column”.) Taken together, the @var{i}-th element or row of each variable compose
a single record or observation.

Tables are good ways of arranging data if you have data that would otherwise be stored
in a few separate variables which all need to be kept in the same shape and order,
especially if you might want to do element-wise comparisons involving two or more of
those variables. That’s basically all a @code{table} is: it holds a collection of
variables, and makes sure they are all kept aligned and ordered in the same way.

Tables are a lot like SQL tables or result sets, and are based on the same relational
algebra theory that SQL is. Many common, even powerful, SQL operations can be done
in Octave using @code{table} arrays. It’s like having your own in-memory SQL engine.

@node Table Construction
@section Table Construction

There are two main ways to construct a @code{table} array: build one up by combining
multiple variables together, or convert an existing tabular-organized array into a
@code{table}.

To build an array from multiple variables, use the @code{table(@dots{})} constructor, passing
in all of your variables as separate inputs. It takes any number of inputs. Each input
becomes a table variable in the new @code{table} object. If you pass your constructor
inputs directly from variables, it automatically picks up their names and uses them
as the table variable names. Otherwise, if you’re using more complex expressions, you’ll
need to supply the @code{'VariableNames'} option.

To convert a tabular-organized array of another type into a @code{table}, use the
conversion functions like @code{array2table}, @code{struct2table} and @code{cell2table}.
@code{array2table} and @code{cell2table} take each column of the input array and turn
it into a separate table variable in the resulting @code{table}. @code{struct2table} takes
the fields of a struct and puts them into table variables.

@node Tables vs SQL
@section Tables vs SQL

Here’s a table (ha!) of what SQL and relational algebar operations correspond to
what Octave @code{table} operations.

In this table, @code{t} is a variable holding a @code{table} array, and @code{ix} is
some indexing expression.

@multitable @columnfractions .33 .33 .33
@headitem SQL @tab Relational @tab Octave @code{table}
@item SELECT
@tab PROJECT
@tab @code{subsetvars}, @code{t(:,ix)}
@item WHERE
@tab RESTRICT
@tab @code{subsetrows}, @code{t(ix,:)}
@item INNER JOIN
@tab JOIN
@tab @code{innerjoin}
@item OUTER JOIN
@tab OUTER JOIN
@tab @code{outerjoin}
@item FROM @code{@var{table1}, @var{table2}, @dots{}}
@tab Cartesian product
@tab @code{cartesian}
@item GROUP BY
@tab SUMMARIZE
@tab @code{groupby}
@item DISTINCT
@tab (automatic)
@tab @code{unique(t)}
@end multitable

Note that there is one big difference between relational algebra and SQL & Octave
@code{table}: Relations in relational algebra are sets, not lists.
There are no duplicate rows in relational algebra, and there is no ordering.
So every operation there does an implicit @code{DISTINCT}/@code{unique()} on its
results, and there‘s no @code{ORDER BY}/@code{sort()}. This is not the case in SQL
or Octave @code{table}.

Note for users coming from Matlab: Matlab does not provide a general @code{groupby}
function. Instead, you have to variously use @code{rowfun}, @code{grpstats},
@code{groupsummary}, and manual code to accomplish “group by” operations.

Note: I wrote this based on my understanding of relational algebra from reading
C. J. Date books. Other people’s understanding and terminology may differ. - apjanke



@node Date and Time Representation
@chapter Date and Time Representation

Tablicious provides the @code{datetime} class for representing points in time.

There’s also @code{duration} and @code{calendarDuration} for representing
periods or durations of time. Like vector quantities along the time line,
as opposed to @code{datetime} being a point along the time line.

@node datetime Class
@section @code{datetime} Class

A @code{datetime} is an array object that represents points in time in the familiar
Gregorian calendar.

This is an attempt to reproduce the functionality of Matlab's @code{datetime}. It
also contains some Octave-specific extensions.

The underlying representation is that of a datenum (a @code{double}
containing the number of days since the Matlab epoch), but encapsulating it in an
object provides several benefits: friendly human-readable display, type safety,
automatic type conversion, and time zone support. In addition to the underlying
datenum array, a @code{datetime} inclues an optional @code{TimeZone} property
indicating what time zone the datetimes are in.

So, basically, a @code{datetime} is an object wrapper around a datenum array,
plus time zone support.

@menu
* Datenum Compatibility::
@end menu

@node Datenum Compatibility
@subsection Datenum Compatibility

While the underlying data representation of @code{datetime} is compatible with
(in fact, identical to) that of datenums, you cannot directly combine them
via assignment, concatenation, or most arithmetic operations.

This is because of the signature of the @code{datetime} constructor. When combining
objects and primitive types like @code{double}, the primitive type is promoted to an
object by calling the other object's one-argument constructor on it. However, the
one-argument numeric-input consstructor for @code{datetime} does not accept datenums:
it interprets its input as datevecs instead. This is due to a design decision on
Matlab's part; for compatibility, Octave does not alter that interface.

To combine @code{datetime}s with datenums, you can convert the datenums to @code{datetime}s
by calling @code{datetime.ofDatenum} or @code{datetime(x, 'ConvertFrom', 'datenum')}, or you
can convert the @code{datetime}s to datenums by accessing its @code{dnums} field with
@code{x.dnums}.

Examples:

@example
dt = datetime('2011-03-04')
dn = datenum('2017-01-01')
[dt dn]
    @result{} error: datenum: expected date vector containing [YEAR, MONTH, DAY, HOUR, MINUTE, SECOND]
[dt datetime.ofDatenum(dn)]
    @result{} 04-Mar-2011   01-Jan-2017
@end example

Also, if you have a zoned @code{datetime}, you can’t combine it with a datenum, because datenums
do not carry time zone information.


@node Time Zones
@section Time Zones

Tablicious has support for representing dates in time zones and for converting between time zones.

A @code{datetime} may be "zoned" or "zoneless". A zoneless @code{datetime} does not have a time zone
associated with it. This is represented by an empty @code{TimeZone} property on the @code{datetime}
object. A zoneless @code{datetime} represents the local time in some unknown time zone, and assumes a
continuous time scale (no DST shifts).

A zoned @code{datetime} is associated with a time zone. It is represented by having the time zone's
IANA zone identifier (e.g. @code{'UTC'} or @code{'America/New_York'}) in its @code{TimeZone}
property. A zoned @code{datetime} represents the local time in that time zone.

By default, the @code{datetime} constructor creates unzoned @code{datetime}s. To
make a zoned @code{datetime}, either pass the @code{'TimeZone'} option to the constructor,
or set the @code{TimeZone} property after object creation. Setting the @code{TimeZone}
property on a zoneless @code{datetime} declares that it's a local time in that time zone.
Setting the @code{TimeZone} property on a zoned @code{datetime} turns it back into a
zoneless @code{datetime} without changing the local time it represents.

You can tell a zoned from a zoneless time zone in the object display because the time zone
is included for zoned @code{datetime}s.

@example
% Create an unzoned datetime
d = datetime('2011-03-04 06:00:00')
    @result{}  04-Mar-2011 06:00:00

% Create a zoned datetime
d_ny = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/New_York')
    @result{}  04-Mar-2011 06:00:00 America/New_York
% This is equivalent
d_ny = datetime('2011-03-04 06:00:00');
d_ny.TimeZone = 'America/New_York'
    @result{}  04-Mar-2011 06:00:00 America/New_York

% Convert it to Chicago time
d_chi.TimeZone = 'America/Chicago'
    @result{}  04-Mar-2011 05:00:00 America/Chicago
@end example

When you combine two zoned @code{datetime}s via concatenation, assignment, or
arithmetic, if their time zones differ, they are converted to the time zone of
the left-hand input.

@example
d_ny = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/New_York')
d_la = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/Los_Angeles')
d_la - d_ny
    @result{} 03:00:00
@end example

You cannot combine a zoned and an unzoned @code{datetime}. This results in an error
being raised.

@quotation Warning
Normalization of "nonexistent" times (like between 02:00 and 03:00 on a "spring forward"
DST change day) is not implemented yet. The results of converting a zoneless local time
into a time zone where that local time did not exist are currently undefined.
@end quotation

@menu
* Defined Time Zones::
@end menu

@node Defined Time Zones
@subsection Defined Time Zones

Tablicious's time zone data is drawn from the @uref{https://www.iana.org/time-zones,
IANA Time Zone Database}, also known as the “Olson Database”. Tablicious includes a
copy of this database in its distribution so it can work on Windows, which does
not supply it like Unix systems do.

You can use the @code{timezones} function to list the time zones known to Tablicious. These will be
all the time zones in the IANA database on your system (for Linux and macOS) or in the IANA
time zone database redistributed with Tablicious (for Windows).

@quotation Note
The IANA Time Zone Database only covers dates from about the year 1880 to 2038. Converting
time zones for @code{datetime}s outside that range is currently unimplemented. (Tablicious
needs to add support for proleptic POSIX time zone rules, which are used to govern
behavior outside that date range.)
@end quotation

@node Durations
@section Durations

@menu
* duration Class::
* calendarDuration Class::
@end menu

@node duration Class
@subsection @code{duration} Class

A @code{duration} represents a period of time in fixed-length seconds (or minutes, hours,
or whatever you want to measure it in.)

A @code{duration} has a resolution of about a nanosecond for typical dates. The underlying
representation is a @code{double} representing the number of days elapsed, similar to a
datenum, except it's interpreted as relative to some other reference point you provide,
instead of being relative to the Matlab/Octave epoch.

You can add or subtract a @code{duration} to a @code{datetime} to get another @code{datetime}.
You can also add or subtract @code{durations} to each other.

@node calendarDuration Class
@subsection @code{calendarDuration} Class

A @code{calendarDuration} represents a period of time in variable-length calendar
components. For example, years and months can have varying numbers of days, and days
in time zones with Daylight Saving Time have varying numbers of hours. A
@code{calendarDuration} does arithmetic with "whole" calendar periods.

@code{calendarDuration}s and @code{duration}s cannot be directly combined, because
they are not semantically equivalent. (This may be relaxed in the future to allow
@code{duration}s to be interpreted as numbers of days when combined with
@code{calendarDuration}s.)

@example
d = datetime('2011-03-04 00:00:00')
    @result{} 04-Mar-2011
cdur = calendarDuration(1, 3, 0)
    @result{} 1y 3mo
d2 = d + cdur
    @result{} 04-Jun-2012
@end example


@node Validation Functions
@chapter Validation Functions

Tablicious provides several validation functions which can be used to check properties
of function arguments, variables, object properties, and other expressions. These can
be used to express invariants in your program and catch problems due to input errors,
incorrect function usage, or other bugs.

These validation functions are named following the pattern @code{mustBeXxx}, where @code{Xxx}
is some property of the input it is testing. Validation functions may check the type,
size, or other aspects of their inputs.

The most common place for validation functions to be used will probably be at the
beginning of functions, to check the input arguments and ensure that the contract of
the function is not being violated. If in the future Octave gains the ability to
declaratively express object property constraints, they will also be of use there.

Be careful not to get too aggressive with the use of validation functions: while using
them can make sure invariants are followed and your program is correct, they also reduce
the code’s ability to make use of duck typing, reducing its flexibility. Whether you want
to make this trade-off is a design decision you will have to consider.

When a validation function’s condition is violated, it raises an error that includes a
description of the violation in the error message. This message will include a label for
the input that describes what is being tested. By default, this label is initialized
with @code{inputname()}, so when you are calling a validator on a function argument or
variable, you will generally not need to supply a label. But if you’re calling it on
an object property or an expression more complex than a simple variable reference, the
validator cannot automatically detect the input name for use in the label. In this case,
make use of the optional trailing argument(s) to the functions to manually supply a
label for the value being tested.

@example
% Validation of a simple variable does not need a label
mustBeScalar (x);
% Validation of a field or property reference does need a label
mustBeScalar (this.foo, 'this.foo');
@end example


@node Example Data Sets
@chapter Example Data Sets

Tablicious comes with several example data sets that you can use to explore how
its functions and objects work. These are accessed through the
@code{tblish.datasets} and @code{tblish.dataset} classes.

To see a list of the available data sets, run @code{tblish.datasets.list()}.
Then to load one of the example data sets, run
@code{tblish.datasets.load('examplename')}. For example:

@example
tblish.datasets.list
t = tblish.datasets.load('cupcake')
@end example

You can also load it by calling @code{tblish.dataset.<name>}. This does
the same thing. For example:

@example
t = tblish.dataset.cupcake
@end example

When you load a data set, it either returns all its data in a single variable
(if you capture it), or loads its data into one or more variables in your
workspace (if you call it with no outputs).

Each example data set comes with help text that describes the data set and
provides examples of how to work with it. This help is found using the @code{doc}
command on @code{tblish.dataset.<name>}, where @var{<name>} is the name of
the data set.

For example:

@example
doc tblish.dataset.cupcake
@end example

(The command @code{help tblish.dataset.<name>} ought to work too, but it
currently doesn’t. This may be due to an issue with Octave’s @code{help}
command.)

@node Data Sets from R
@section Data Sets from R

Many of Tablicious’ example data sets are based on the example datasets
found in R’s @code{datasets} package. R can be found at
@url{https://www.r-project.org/}, and documentation for its @code{datasets}
is at @url{https://rdrr.io/r/datasets/datasets-package.html}.
Thanks to the R developers for producing the original data sets here.

Tablicious’ examples’ code tries to replicate the R examples, so it can
be useful to compare the two of them if you are moving from one language to
another.

Core Octave currently lacks some of the plotting features found in the R
examples, such as LOWESS smoothing and linear model characteristic plots, so
you will just find “TODO” placeholders for these in Tablicious’ example code.

@node Missing Functionality
@chapter Missing Functionality

Tablicious is based on Matlab’s table and date/time APIs and supports some of
their major functionality.
But not all of it is implemented yet. The missing parts are currently:

@itemize
@item File I/O like @code{readtable()} and @code{writetable()}
@item @code{summary()} @code{categorical}
@item Assignment to table variables using @code{.}-indexing
@item @code{timetable}
@item POSIX time zone support for years outside the IANA time zone database coverage
@item Week-of-year (ISO calendar) calculations
@item Various @code{'ConvertFrom'} forms for @code{datetime} and @code{duration} constructors
@item Support for LDML formatting for @code{datetime}
@item Various functions:
@itemize
@item @code{between}
@item @code{caldiff}
@item @code{dateshift}
@item @code{week}
@end itemize
@item @code{isdst}, @code{isweekend}
@item @code{calendarDuration.split}
@item @code{duration.Format} support
@item Moving window methods in @code{fillmissing}
@item @code{UTCOffset} and @code{DSTOffset} fields in the output of @code{timezones()}
@item Plotting support
@item Things omitted for compatibility:
@itemize
@item @code{ismissing} function
@end itemize
@end itemize

A global @code{ismissing} function is intentionally omitted from Tablicious to avoid
conflict with the Octave Forge statistics package. @code{ismissing} methods for
various classes in Tablicious are defined. Tablicious also supplies an @code{isnanny}
function with behavior similar to @code{ismissing} for clients which which wish to
have @code{ismissing}-like behavior using a dependency only on Tablicious.

It is the author’s hope that many of these will be implemented some day.

These areas of missing functionality are tracked on the Tablicious issue
tracker at @url{https://github.com/apjanke/octave-tablicious/issues} and
@url{https://github.com/users/apjanke/projects/3}.


@node API Reference
@chapter API Reference

@node API by Category
@section API by Category
@subsection Tables
@table @asis
@item table
Tabular data array containing multiple columnar variables.

@xref{table}.
@item array2table
Convert an array to a table.

@xref{array2table}.
@item cell2table
Convert a cell array to a table.

@xref{cell2table}.
@item struct2table
Convert struct to a table.

@xref{struct2table}.
@item tableOuterFillValue


@xref{tableOuterFillValue}.
@item vartype
Filter by variable type for use in suscripting.

@xref{vartype}.
@item istable
True if input is a ‘table’ array or other table-like type, false otherwise.

@xref{istable}.
@item istimetable
True if input is a ‘timetable’ array or other timetable-like type, false otherwise.

@xref{istimetable}.
@item istabular
True if input is eitehr a ‘table’ or ‘timetable’ array, or an object like them.

@xref{istabular}.
@item tblish.evalWithTableVars
Evaluate an expression against a table array’s variables.

@xref{tblish.evalWithTableVars}.
@item tblish.table.grpstats
Statistics by group for a table array.

@xref{tblish.table.grpstats}.
@end table
@subsection Strings and Categoricals
@table @asis
@item string
A string array of Unicode strings.

@xref{string}.
@item NaS
“Not-a-String".

@xref{NaS}.
@item contains
Test if strings contain a pattern.

@xref{contains}.
@item dispstrs
Display strings for array.

@xref{dispstrs}.
@item categorical
Categorical variable array.

@xref{categorical}.
@item iscategorical
True if input is a ‘categorical’ array, false otherwise.

@xref{iscategorical}.
@item NaC
“Not-a-Categorical".

@xref{NaC}.
@item discretize
Group data into discrete bins or categories.

@xref{discretize}.
@end table
@subsection Dates and Times
@table @asis
@item datetime
Represents points in time using the Gregorian calendar.

@xref{datetime}.
@item NaT
“Not-a-Time”.

@xref{NaT}.
@item todatetime
Convert input to a Tablicious datetime array, with convenient interface.

@xref{todatetime}.
@item localdate
Represents a complete day using the Gregorian calendar.

@xref{localdate}.
@item isdatetime
True if input is a ‘datetime’ array, false otherwise.

@xref{isdatetime}.
@item calendarDuration
Durations of time using variable-length calendar periods, such as days, months, and years, which may vary in length over time.

@xref{calendarDuration}.
@item iscalendarduration
True if input is a ‘calendarDuration’ array, false otherwise.

@xref{iscalendarduration}.
@item calmonths
Create a ‘calendarDuration’ that is a given number of calendar months long.

@xref{calmonths}.
@item calyears
Construct a ‘calendarDuration’ a given number of years long.

@xref{calyears}.
@item days
Duration in days.

@xref{days}.
@item duration
Represents durations or periods of time as an amount of fixed-length time (i.e.

@xref{duration}.
@item hours
Create a ‘duration’ X hours long, or get the hours in a ‘duration’ X.

@xref{hours}.
@item isduration
True if input is a ‘duration’ array, false otherwise.

@xref{isduration}.
@item milliseconds
Create a ‘duration’ X milliseconds long, or get the milliseconds in a ‘duration’ X.

@xref{milliseconds}.
@item minutes
Create a ‘duration’ X hours long, or get the hours in a ‘duration’ X.

@xref{minutes}.
@item seconds
Create a ‘duration’ X seconds long, or get the seconds in a ‘duration’ X.

@xref{seconds}.
@item timezones
List all the time zones defined on this system.

@xref{timezones}.
@item years
Create a ‘duration’ X years long, or get the years in a ‘duration’ X.

@xref{years}.
@end table
@subsection Missing Data
@table @asis
@item missing
Generic auto-converting missing value.

@xref{missing}.
@item isnanny
Test if elements are NaN or NaN-like.

@xref{isnanny}.
@item eqn
Determine element-wise equality, treating NaNs as equal

@xref{eqn}.
@end table
@subsection Validation Functions
@table @asis
@item mustBeA


@xref{mustBeA}.
@item mustBeCellstr


@xref{mustBeCellstr}.
@item mustBeCharvec


@xref{mustBeCharvec}.
@item mustBeFinite


@xref{mustBeFinite}.
@item mustBeInteger


@xref{mustBeInteger}.
@item mustBeMember


@xref{mustBeMember}.
@item mustBeNonempty


@xref{mustBeNonempty}.
@item mustBeNumeric


@xref{mustBeNumeric}.
@item mustBeReal


@xref{mustBeReal}.
@item mustBeSameSize


@xref{mustBeSameSize}.
@item mustBeScalar


@xref{mustBeScalar}.
@item mustBeScalarLogical


@xref{mustBeScalarLogical}.
@item mustBeVector


@xref{mustBeVector}.
@end table
@subsection Miscellaneous
@table @asis
@item colvecfun
Apply a function to column vectors in array.

@xref{colvecfun}.
@item dispstrs
Display strings for array.

@xref{dispstrs}.
@item head
Get first K rows of an array.

@xref{head}.
@item isfile


@xref{isfile}.
@item isfolder


@xref{isfolder}.
@item pp
Alias for prettyprint, for interactive use.

@xref{pp}.
@item scalarexpand
Expand scalar inputs to match size of non-scalar inputs.

@xref{scalarexpand}.
@item size2str
Format an array size for display.

@xref{size2str}.
@item splitapply
Split data into groups and apply function.

@xref{splitapply}.
@item tail
Get last K rows of an array.

@xref{tail}.
@item vecfun
Apply function to vectors in array along arbitrary dimension.

@xref{vecfun}.
@item tblish.sizeof2
Approximate size of an array in bytes, with object support.

@xref{tblish.sizeof2}.
@end table
@subsection Example Datasets
@table @asis
@item tblish.datasets
Example dataset collection.

@xref{tblish.datasets}.
@item tblish.dataset
The ‘tblish.dataset’ class provides convenient access to the various datasets included with Tablicious.

@xref{tblish.dataset}.
@end table
@subsection Example Code
@table @asis
@item tblish.examples.coplot
Conditioning plot.

@xref{tblish.examples.coplot}.
@item tblish.examples.plot_pairs
Plot pairs of variables against each other.

@xref{tblish.examples.plot_pairs}.
@item tblish.examples.SpDb
The classic Suppliers-Parts example database.

@xref{tblish.examples.SpDb}.
@end table
@subsection Uncategorized
@table @asis
@item caldays
Create a ‘calendarDuration’ that is a given number of calendar days long.

@xref{caldays}.
@end table

@node API Alphabetically
@section API Alphabetically
@menu
* array2table:: Convert an array to a table.
* caldays::	Create a ‘calendarDuration’ that is a given number of
		calendar days long.
* calendarDuration::	Durations of time using variable-length calendar
		periods, such as days, months, and years, which may vary in
		length over time.
* calmonths::	Create a ‘calendarDuration’ that is a given number of
		calendar months long.
* calyears::	Construct a ‘calendarDuration’ a given number of years
		long.
* categorical:: Categorical variable array.
* cell2table::	Convert a cell array to a table.
* colvecfun::	Apply a function to column vectors in array.
* contains::	Test if strings contain a pattern.
* datetime::	Represents points in time using the Gregorian calendar.
* days::	Duration in days.
* discretize::	Group data into discrete bins or categories.
* dispstrs::	Display strings for array.
* duration::	Represents durations or periods of time as an amount of
		fixed-length time (i.e.
* eqn:: Determine element-wise equality, treating NaNs as equal
* head::	Get first K rows of an array.
* hours::	Create a ‘duration’ X hours long, or get the hours in a
		‘duration’ X.
* iscalendarduration::	True if input is a ‘calendarDuration’ array,
		false otherwise.
* iscategorical::	True if input is a ‘categorical’ array, false
		otherwise.
* isdatetime::	True if input is a ‘datetime’ array, false otherwise.
* isduration::	True if input is a ‘duration’ array, false otherwise.
* isfile::	
* isfolder::	
* isnanny::	Test if elements are NaN or NaN-like.
* istable::	True if input is a ‘table’ array or other table-like
		type, false otherwise.
* istabular::	True if input is eitehr a ‘table’ or ‘timetable’
		array, or an object like them.
* istimetable:: True if input is a ‘timetable’ array or other
		timetable-like type, false otherwise.
* localdate::	Represents a complete day using the Gregorian calendar.
* milliseconds::	Create a ‘duration’ X milliseconds long, or get
		the milliseconds in a ‘duration’ X.
* minutes::	Create a ‘duration’ X hours long, or get the hours in a
		‘duration’ X.
* missing::	Generic auto-converting missing value.
* mustBeA::	
* mustBeCellstr::	
* mustBeCharvec::	
* mustBeFinite::	
* mustBeInteger::	
* mustBeMember::	
* mustBeNonempty::	
* mustBeNumeric::	
* mustBeReal::	
* mustBeSameSize::	
* mustBeScalar::	
* mustBeScalarLogical:: 
* mustBeVector::	
* NaC:: “Not-a-Categorical".
* NaS:: “Not-a-String".
* NaT:: “Not-a-Time”.
* pp::	Alias for prettyprint, for interactive use.
* scalarexpand::	Expand scalar inputs to match size of non-scalar
		inputs.
* seconds::	Create a ‘duration’ X seconds long, or get the seconds
		in a ‘duration’ X.
* size2str::	Format an array size for display.
* splitapply::	Split data into groups and apply function.
* string::	A string array of Unicode strings.
* struct2table::	Convert struct to a table.
* table::	Tabular data array containing multiple columnar variables.
* tableOuterFillValue:: 
* tail::	Get last K rows of an array.
* tblish.dataset::	The ‘tblish.dataset’ class provides convenient
		access to the various datasets included with Tablicious.
* tblish.datasets::	Example dataset collection.
* tblish.evalWithTableVars::	Evaluate an expression against a table
		array’s variables.
* tblish.examples.coplot::	Conditioning plot.
* tblish.examples.plot_pairs::	Plot pairs of variables against each other.
* tblish.examples.SpDb::	The classic Suppliers-Parts example
		database.
* tblish.sizeof2::	Approximate size of an array in bytes, with object
		support.
* tblish.table.grpstats::	Statistics by group for a table array.
* timezones::	List all the time zones defined on this system.
* todatetime::	Convert input to a Tablicious datetime array, with
		convenient interface.
* vartype::	Filter by variable type for use in suscripting.
* vecfun::	Apply function to vectors in array along arbitrary
		dimension.
* years::	Create a ‘duration’ X years long, or get the years in a
		‘duration’ X.
@end menu

@node array2table
@subsection array2table
@deftypefn {Function} {@var{out} =} array2table (@var{c})
@deftypefnx {Function} {@var{out} =} array2table (@dots{}, @code{'VariableNames'}, @var{VariableNames})
@deftypefnx {Function} {@var{out} =} array2table (@dots{}, @code{'RowNames'}, @var{RowNames})

Convert an array to a table.

Converts a 2-D array to a table, with columns in the array becoming variables in
the output table. This is typically used on numeric arrays, but it can
be applied to any type of array.

You may not want to use this on cell arrays, though, because you will
end up with a table that has all its variables of type cell. If you use
@code{cell2table} instead, columns of the cell array which can be
condensed into primitive arrays will be. With @code{array2table}, they
won't be.

See also: @ref{cell2table}, @ref{table}, @ref{struct2table}

@end deftypefn


@node caldays
@subsection caldays
@deftypefn {Function File} {@var{out} =} caldays (@var{x})
Create a @code{calendarDuration} that is a given number of calendar days
long.

Input @var{x} is a numeric array specifying the number of calendar days.

This is a shorthand alternative to calling the @code{calendarDuration}
constructor with @code{calendarDuration(0, 0, x)}.

Returns a new @code{calendarDuration} object of the same size as @var{x}.

@xref{calendarDuration}.

@end deftypefn


@node calendarDuration
@subsection calendarDuration
@deftp {Class} calendarDuration

Durations of time using variable-length calendar periods, such as days,
months, and years, which may vary in length over time. (For example, a
calendar month may have 28, 30, or 31 days.)

@end deftp

@deftypeivar calendarDuration @code{char} Format

The format to display this @code{calendarDuration} in. Currently unsupported.

This is a single value that applies to the whole array.

@end deftypeivar


@node calendarDuration.calendarDuration
@subsubsection calendarDuration.calendarDuration

@deftypefn {Constructor} {@var{obj} =} calendarDuration ()

Constructs a new scalar @code{calendarDuration} of zero elapsed time.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} calendarDuration (@var{Y}, @var{M}, @var{D})
@deftypefnx {Constructor} {@var{obj} =} calendarDuration (@var{Y}, @var{M}, @
  @var{D}, @var{H}, @var{MI}, @var{S})

Constructs new @code{calendarDuration} arrays based on input values.

@end deftypefn

@node calendarDuration.datevec
@subsubsection calendarDuration.datevec

@deftypefn {Method} {[@var{dvec}] =} datevec (@var{obj})
@deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})

Convert a @code{calendarDuration} to a datevec whose elements represent its
components of. The components are the year, month, day, hour, minute, and
second quantities of this @code{calendarDuration}.

When nargout is 0 or 1, returns a double array of size n-by-6, where n is
@code{numel(obj)}. When nargout is 2 or more, returns double arrays the
same size as @var{obj}.

@end deftypefn

@node calendarDuration.dispstrs
@subsubsection calendarDuration.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Get display strings for each element of @var{obj}.

Returns a cellstr the same size as @var{obj}.

@end deftypefn

@node calendarDuration.ismissing
@subsubsection calendarDuration.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})

True if input elements are missing.

This is equivalent to @code{ismissing}.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node calendarDuration.isnan
@subsubsection calendarDuration.isnan

@deftypefn {Method} {@var{out} =} isnan (@var{obj})

True if input elements are NaN.

This is equivalent to @code{ismissing}, and is provided for compatibility
and polymorphic programming purposes.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node calendarDuration.minus
@subsubsection calendarDuration.minus

@deftypefn {Method} {@var{out} =} times (@var{A}, @var{B})

Subtraction: Subtracts one @code{calendarDuration} from another.

Returns a @code{calendarDuration}.

@end deftypefn

@node calendarDuration.mtimes
@subsubsection calendarDuration.mtimes

@deftypefn {Method} {@var{out} =} times (@var{obj}, @var{B})

Multiplication: Multiplies a @code{calendarDuration} by a numeric factor.

This does not do true matrix multiplication, so at least one of the input arguments
must be scalar.

Returns a @code{calendarDuration}.

@end deftypefn

@node calendarDuration.plus
@subsubsection calendarDuration.plus

@deftypefn {Method} {@var{out} =} plus (@var{obj}, @var{B})

Addition: add to a @code{calendarDuration}.

All the calendar elements (properties) of the two inputs are added
together. No normalization is done across the elements, aside from
the normalization of NaNs.

@var{B} may be a @code{calendarDuration}, @code{duration}, or numeric.
If @var{B} is numeric, it is converted to a @code{calendarDuration}
using @code{caldays(B)}.

Returns a @code{calendarDuration}.

@end deftypefn

@node calendarDuration.times
@subsubsection calendarDuration.times

@deftypefn {Method} {@var{out} =} times (@var{obj}, @var{B})

Multiplication: Multiplies a @code{calendarDuration} by a numeric factor @var{B}.

Returns a @code{calendarDuration}.

@end deftypefn

@node calendarDuration.uminus
@subsubsection calendarDuration.uminus

@deftypefn {Method} {@var{out} =} uminus (@var{obj})

Unary minus. Negates the sign of @var{obj}, which is equivalent to negating each
of its components.

@end deftypefn

@node calmonths
@subsection calmonths
@deftypefn {Function File} {@var{out} =} calmonths (@var{x})
Create a @code{calendarDuration} that is a given number of calendar months
long.

Input @var{x} is a numeric array specifying the number of calendar months.

This is a shorthand alternative to calling the @code{calendarDuration}
constructor with @code{calendarDuration(0, x, 0)}.

Returns a new @code{calendarDuration} object of the same size as @var{x}.

@xref{calendarDuration}.

@end deftypefn


@node calyears
@subsection calyears
@deftypefn {Function} {@var{out} =} calyears (@var{x})

Construct a @code{calendarDuration} a given number of years long.

This is a shorthand for calling @code{calendarDuration(@var{x}, 0, 0)}.

@xref{calendarDuration}.

@end deftypefn


@node categorical
@subsection categorical
@deftp {Class} categorical

Categorical variable array.

A @code{categorical} array represents an array of values of a categorical
variable. Each @code{categorical} array stores the element values along
with a list of the categories, and indicators of whether the categories
are ordinal (that is, they have a meaningful mathematical ordering), and
whether the set of categories is protected (preventing new categories
from being added to the array).

In addition to the categories defined in the array, a categorical array
may have elements of "undefined" value. This is not considered a
category; rather, it is the absence of any known value. It is
analagous to a @code{NaN} value.

This class is not fully implemented yet. Missing stuff:

@itemize @bullet
@item
gt, ge, lt, le
@item
Ordinal support in general
@item
countcats
@item
summary

@end itemize

@end deftp

@deftypeivar categorical @code{uint16} code

The numeric codes of the array element values. These are indexes into the
@code{cats} category list.

This is a planar property.

@end deftypeivar

@deftypeivar categorical @code{logical} tfMissing

A logical mask indicating whether each element of the array is missing
(that is, undefined).

This is a planar property.

@end deftypeivar

@deftypeivar categorical @code{cellstr} cats

The names of the categories in this array. This is the list into which
the @code{code} values are indexes.

@end deftypeivar

@deftypeivar categorical @code{scalar_logical} isOrdinal

A scalar logical indicating whether the categories in this array have an
ordinal relationship.

@end deftypeivar


@node categorical.addcats
@subsubsection categorical.addcats

@deftypefn {Method} {@var{out} =} addcats (@var{obj}, @var{newcats})

Add categories to categorical array.

Adds the specified categories to @var{obj}, without changing any of
its values.

@var{newcats} is a cellstr listing the category names to add to
@var{obj}.

@end deftypefn

@node categorical.categorical
@subsubsection categorical.categorical

@deftypefn {Constructor} {@var{obj} =} categorical ()

Constructs a new scalar categorical whose value is undefined.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} categorical (@var{vals})
@deftypefnx {Constructor} {@var{obj} =} categorical (@var{vals}, @var{valueset})
@deftypefnx {Constructor} {@var{obj} =} categorical (@var{vals}, @var{valueset}, @var{category_names})
@deftypefnx {Constructor} {@var{obj} =} categorical (@dots{}, @code{'Ordinal'}, @var{Ordinal})
@deftypefnx {Constructor} {@var{obj} =} categorical (@dots{}, @code{'Protected'}, @var{Protected})

Constructs a new categorical array from the given values.

@var{vals} is the array of values to convert to categoricals.

@var{valueset} is the set of all values from which @var{vals} is drawn.
If omitted, it defaults to the unique values in @var{vals}.

@var{category_names} is a list of category names corresponding to
@var{valueset}. If omitted, it defaults to @var{valueset}, converted
to strings.

@var{Ordinal} is a logical indicating whether the category values in
@var{obj} have a numeric ordering relationship. Defaults to false.

@var{Protected} indicates whether @var{obj} should be protected, which
prevents the addition of new categories to the array. Defaults to
false.

@end deftypefn

@node categorical.categories
@subsubsection categorical.categories

@deftypefn {Method} {@var{out} =} categories (@var{obj})

Get a list of the categories in @var{obj}.

Gets a list of the categories in @var{obj}, identified by their
category names.

Returns a cellstr column vector.

@end deftypefn

@node categorical.cellstr
@subsubsection categorical.cellstr

@deftypefn {Method} {@var{out} =} cellstr (@var{obj})

Convert to cellstr.

Converts @var{obj} to a cellstr array. The strings will be the
category names for corresponding values, or @code{''} for undefined
values.

Returns a cellstr array the same size as @var{obj}.

@end deftypefn

@node categorical.dispstrs
@subsubsection categorical.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Display strings.

Gets display strings for each element in @var{obj}. The display strings are
either the category string, or @code{'<undefined>'} for undefined values.

Returns a cellstr array the same size as @var{obj}.

@end deftypefn

@node categorical.double
@subsubsection categorical.double

@deftypefn {Method} {@var{out} =} double (@var{obj})

Convert to double array, by getting the underlying code values.

Converts @var{obj} to a string array. The doubles will be the
underlying numeric code values of @var{obj}, or @code{NaN} for
undefined values.

The numeric code values of two different categorical arrays do
*not* necessarily correspond to the same string values, and can
*not* be meaningfully compared for equality or ordering.

Returns a @code{double} array the same size as @var{obj}.

@end deftypefn

@node categorical.iscategory
@subsubsection categorical.iscategory

@deftypefn {Method} {@var{out} =} iscategory (@var{obj}, @var{catnames})

Test whether input is a category on a categorical array.

@var{catnames} is a cellstr listing the category names to check against
@var{obj}.

Returns a logical array the same size as @var{catnames}.

@end deftypefn

@node categorical.ismissing
@subsubsection categorical.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})

Test whether elements are missing.

For categorical arrays, undefined elements are considered to be
missing.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node categorical.isnanny
@subsubsection categorical.isnanny

@deftypefn {Method} {@var{out} =} isnanny (@var{obj})

Test whethere elements are NaN-ish.

Checks where each element in @var{obj} is NaN-ish. For categorical
arrays, undefined values are considered NaN-ish; any other
value is not.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node categorical.isordinal
@subsubsection categorical.isordinal

@deftypefn {Method} {@var{out} =} isordinal (@var{obj})

Whether @var{obj} is ordinal.

Returns true if @var{obj} is ordinal (as determined by its
@code{IsOrdinal} property), and false otherwise.

@end deftypefn

@node categorical.isundefined
@subsubsection categorical.isundefined

@deftypefn {Method} {@var{out} =} isundefined (@var{obj})

Test whether elements are undefined.

Checks whether each element in @var{obj} is undefined. "Undefined" is
a special value defined by @code{categorical}. It is equivalent to
a @code{NaN} or a @code{missing} value.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node categorical.mergecats
@subsubsection categorical.mergecats

@deftypefn {Method} {@var{out} =} mergecats (@var{obj}, @var{oldcats})
@deftypefnx {Method} {@var{out} =} mergecats (@var{obj}, @var{oldcats}, @var{newcat})

Merge multiple categories.

Merges the categories @var{oldcats} into a single category. If @var{newcat}
is specified, that new category is added if necessary, and all of @var{oldcats}
are merged into it. @var{newcat} must be an existing category in @var{obj} if
@var{obj} is ordinal.

If @var{newcat} is not provided, all of @var{odcats} are merged into
@code{oldcats@{1@}}.

@end deftypefn

@node categorical.missing
@subsubsection categorical.missing

@deftypefn {Static Method} {@var{out} =} categorical.missing ()
@deftypefnx {Static Method} {@var{out} =} categorical.missing (sz)

Create an array of missing (undefined) categoricals.

Creates a categorical array whose elements are all missing (<undefined>).

This is a convenience alias for @ref{categorical.undefined}, so you can call
it generically. It returns strictly the same results as calling
@ref{categorical.undefined} with the same arguments.

Returns a categorical array.

See also: categorical.undefined

@end deftypefn

@node categorical.removecats
@subsubsection categorical.removecats

@deftypefn {Method} {@var{out} =} removecats (@var{obj})

Removes all unused categories from @var{obj}. This is equivalent to
@code{out = squeezecats (obj)}.

@end deftypefn

@deftypefn {Method} {@var{out} =} removecats (@var{obj}, @var{oldcats})

Remove categories from categorical array.

Removes the specified categories from @var{obj}. Elements of @var{obj}
whose values belonged to those categories are replaced with undefined.

@var{newcats} is a cellstr listing the category names to add to
@var{obj}.

@end deftypefn

@node categorical.renamecats
@subsubsection categorical.renamecats

@deftypefn {Method} {@var{out} =} renamecats (@var{obj}, @var{newcats})
@deftypefnx {Method} {@var{out} =} renamecats (@var{obj}, @var{oldcats}, @var{newcats})

Rename categories.

Renames some or all of the categories in @var{obj}, without changing
any of its values.

@end deftypefn

@node categorical.reordercats
@subsubsection categorical.reordercats

@deftypefn {Method} {@var{out} =} reordercats (@var{obj})
@deftypefnx {Method} {@var{out} =} reordercats (@var{obj}, @var{newcats})

Reorder categories.

Reorders the categories in @var{obj} to match @var{newcats}.

@var{newcats} is a cellstr that must be a reordering of @var{obj}’s existing
category list. If @var{newcats} is not supplied, sorts the categories
in alphabetical order.

@end deftypefn

@node categorical.setcats
@subsubsection categorical.setcats

@deftypefn {Method} {@var{out} =} setcats (@var{obj}, @var{newcats})

Set categories for categorical array.

Sets the categories to use for @var{obj}. If any current categories
are absent from the @var{newcats} list, current values of those
categories become undefined.

@end deftypefn

@node categorical.squeezecats
@subsubsection categorical.squeezecats

@deftypefn {Method} {@var{out} =} squeezecats (@var{obj})

Remove unused categories.

Removes all categories which have no corresponding values in @var{obj}’s
elements.

This is currently unimplemented.

@end deftypefn

@node categorical.string
@subsubsection categorical.string

@deftypefn {Method} {@var{out} =} string (@var{obj})

Convert to string array.

Converts @var{obj} to a string array. The strings will be the
category names for corresponding values, or <missing> for undefined
values.

Returns a @code{string} array the same size as @var{obj}.

@end deftypefn

@node categorical.summary
@subsubsection categorical.summary

@deftypefn {Method} {} summary (@var{obj})

Display summary of array’s values.

Displays a summary of the values in this categorical array. The output
may contain info like the number of categories, number of undefined values,
and frequency of each category.

@end deftypefn

@node categorical.undefined
@subsubsection categorical.undefined

@deftypefn {Static Method} {@var{out} =} categorical.undefined ()
@deftypefnx {Static Method} {@var{out} =} categorical.undefined (sz)

Create an array of undefined categoricals.

Creates a categorical array whose elements are all <undefined>.

@var{sz} is the size of the array to create. If omitted or empty, creates
a scalar.

Returns a categorical array.

See also: categorical.missing

@end deftypefn

@node cell2table
@subsection cell2table
@deftypefn {Function} {@var{out} =} cell2table (@var{c})
@deftypefnx {Function} {@var{out} =} cell2table (@dots{}, @code{'VariableNames'}, @var{VariableNames})
@deftypefnx {Function} {@var{out} =} cell2table (@dots{}, @code{'RowNames'}, @var{RowNames})

Convert a cell array to a table.

Converts a 2-dimensional cell matrix into a table. Each column in the
input @var{c} becomes a variable in @var{out}. For columns that contain
all scalar values of @code{cat}-compatible types, they are “popped out”
of their cells and condensed into a homogeneous array of the contained
type.

See also: @ref{array2table}, @ref{table}, @ref{struct2table}

@end deftypefn


@node colvecfun
@subsection colvecfun
@deftypefn {Function} {@var{out} =} colvecfun (@var{fcn}, @var{x})

Apply a function to column vectors in array.

Applies the given function @var{fcn} to each column vector in the
array @var{x}, by iterating over the indexes along all dimensions except
dimension 1. Collects the function return values in an output array.

@var{fcn} must be a function which takes a column vector and returns a column
vector of the same size. It does not have to return the same type as
@var{x}.

Returns the result of applying fcn to each column in x, all concatenated
together in the same shape as x.

@end deftypefn


@node contains
@subsection contains
@deftypefn {Function} {@var{out} =} colvecfun (@var{str}, @var{pattern})
@deftypefnx {Function} {@var{out} =} colvecfun (@dots{}, @code{'IgnoreCase'}, @var{IgnoreCase})

Test if strings contain a pattern.

Tests whether the given strings contain the given pattern(s).

@var{str} (char, cellstr, or string) is a list of strings to compare against
pattern.

@var{pattern} (char, cellstr, or string) is a list of patterns to match. These are
literal plain string patterns, not regex patterns. If more than one pattern
is supplied, the return value is true if the string matched any of them.

Returns a logical array of the same size as the string array represented by
@var{str}.

See also: startsWith, endsWith

@end deftypefn


@node datetime
@subsection datetime
@deftp {Class} datetime

Represents points in time using the Gregorian calendar.

The underlying values are doubles representing the number of days since the
Matlab epoch of "January 0, year 0". This has a precision of around nanoseconds
for typical times.

A @code{datetime} array is an array of date/time values, with each element
holding a complete date/time. The overall array may also have a TimeZone and a
Format associated with it, which apply to all elements in the array.


This is an attempt to reproduce the functionality of Matlab's @code{datetime}. It
also contains some Octave-specific extensions.

@end deftp

@deftypeivar datetime @code{double} dnums

The underlying datenums that represent the points in time. These are always in UTC.

This is a planar property: the size of @code{dnums} is the same size as the
containing @code{datetime} array object.

@end deftypeivar

@deftypeivar datetime @code{char} TimeZone

The time zone this @code{datetime} array is in. Empty if this does not have a
time zone associated with it (“unzoned”). The name of an IANA time zone if
this does.

Setting the @code{TimeZone} of a @code{datetime} array changes the time zone it
is presented in for strings and broken-down times, but does not change the
underlying UTC times that its elements represent.

@end deftypeivar

@deftypeivar datetime @code{char} Format

The format to display this @code{datetime} in. Currently unsupported.

@end deftypeivar


@node datetime.colon
@subsubsection datetime.colon

@deftypefn {Method} {@var{out} =} colon (@var{lo}, @var{hi})
@deftypefnx {Method} {@var{out} =} colon (@var{hi}, @var{inc}, @var{hi})

Generate a sequence of uniformly-spaced values.

This method implements the behavior for the colon operator (@code{lo:hi} or
@code{lo:inc:hi} calls) for the datetime type.

"Uniformly-spaced" means uniform in terms of the duration or calendarDuration
value used as the increment. Calendar durations are not necessarily equal-sized in
terms of the amount of actual time contained in them, so when using a
calendarDuration as the increment, the resulting vector may not be, and often will
not be, uniformly spaced in terms of actual (non-"calendar") time.

The @var{inc} argument may be a duration, calendarDuration, or numeric. Numerics
are taken to be a number of days (uniform-size days, not calendar days), and are
converted to a duration object with @code{duration.ofDays (inc)}. The default value
for @var{inc}, used in the two-arg @code{lo:hi} is 1, that is, 1 day of exactly 24
hours.

Returns a datetime vector.

WARNING: There are issues with negative-direction sequences. When hi is less than
lo, this will always produce an empty array, even if @var{inc} is a negative value.
And there are cases with calendarDurations that have both Months, Days and/or Times
with mixed signs that values may move in the "wrong" direction, or produce an
infinite loop. If these problem cases can be correctly identified, but not
corrected, those cases may raise an error future releases of Tablicious.

@end deftypefn

@node datetime.convertDatenumTimeZone
@subsubsection datetime.convertDatenumTimeZone

@deftypefn {Static Method} {@var{out} =} datetime.convertDatenumTimeZone @
 (@var{dnum}, @var{fromZoneId}, @var{toZoneId})

Convert a datenum from one time zone to another.

@var{dnum} is a datenum array to convert.

@var{fromZoneId} is a charvec containing the IANA Time Zone identifier for
the time zone to convert from.

@var{toZoneId} is a charvec containing the IANA Time Zone identifier for
the time zone to convert to.

Returns a datenum array the same size as @var{dnum}.

@end deftypefn

@node datetime.datenum
@subsubsection datetime.datenum

@deftypefn {Method} {@var{out} =} datenum (@var{obj})

Convert this to datenums that represent the same local time.

Returns double array of same size as this.

@end deftypefn

@node datetime.datenum2posix
@subsubsection datetime.datenum2posix

@deftypefn {Static Method} {@var{out} =} datetime.datenum2posix (@var{dnums})

Converts Octave datenums to Unix dates.

The input datenums are assumed to be in UTC.

Returns a double, which may have fractional seconds.

@end deftypefn

@node datetime.datestr
@subsubsection datetime.datestr

@deftypefn {Method} {@var{out} =} datestr (@var{obj})
@deftypefnx {Method} {@var{out} =} datestr (@var{obj}, @dots{})

Format @var{obj} as date strings. Supports all arguments that core Octave's
@code{datestr} does.

Returns date strings as a 2-D char array.

@end deftypefn

@node datetime.datestrs
@subsubsection datetime.datestrs

@deftypefn {Method} {@var{out} =} datestrs (@var{obj})
@deftypefnx {Method} {@var{out} =} datestrs (@var{obj}, @dots{})

Format @var{obj} as date strings, returning cellstr.
Supports all arguments that core Octave's @code{datestr} does.

Returns a cellstr array the same size as @var{obj}.

@end deftypefn

@node datetime.datestruct
@subsubsection datetime.datestruct

@deftypefn {Method} {@var{out} =} datestruct (@var{obj})

Converts this to a "datestruct" broken-down time structure.

A "datestruct" is a format of struct that Tablicious came up with. It is a scalar
struct with fields Year, Month, Day, Hour, Minute, and Second, each containing
a double array the same size as the date array it represents.

The values in the returned broken-down time are those of the local time
in this' defined time zone, if it has one.

Returns a struct with fields Year, Month, Day, Hour, Minute, and Second.
Each field contains a double array of the same size as this.

@end deftypefn

@node datetime.datetime
@subsubsection datetime.datetime

@deftypefn {Constructor} {@var{obj} =} datetime ()

Constructs a new scalar @code{datetime} containing the current local time, with
no time zone attached.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} datetime (@var{datevec})
@deftypefnx {Constructor} {@var{obj} =} datetime (@var{datestrs})
@deftypefnx {Constructor} {@var{obj} =} datetime (@var{in}, @code{'ConvertFrom'}, @var{inType})
@deftypefnx {Constructor} {@var{obj} =} datetime @
  (@var{Y}, @var{M}, @var{D}, @var{H}, @var{MI}, @var{S})
@deftypefnx {Constructor} {@var{obj} =} datetime @
  (@var{Y}, @var{M}, @var{D}, @var{H}, @var{MI}, @var{MS})
@deftypefnx {Constructor} {@var{obj} =} datetime @
  (@dots{}, @code{'Format'}, @var{Format}, @code{'InputFormat'}, @var{InputFormat}, @
   @code{'Locale'}, @var{InputLocale}, @code{'PivotYear'}, @var{PivotYear}, @
   @code{'TimeZone'}, @var{TimeZone})

Constructs a new @code{datetime} array based on input values.

@end deftypefn

@node datetime.datevec
@subsubsection datetime.datevec

@deftypefn {Method} {@var{out} =} datevec (@var{obj})
@deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})

Convert this to a datevec that represent the same local wall time.

When nargout is 0 or 1, returns a double array of size n-by-6, where n is
@code{numel(obj)}. When nargout is 2 or more, returns double arrays the
same size as @var{obj}.

@end deftypefn

@node datetime.diff
@subsubsection datetime.diff

@deftypefn {Method} {@var{out} =} diff (@var{obj})

Differences between elements.

Computes the difference between each successive element in @var{obj}, as a
@code{duration}.

Returns a @code{duration} array the same size as @var{obj}.

@end deftypefn

@node datetime.dispstrs
@subsubsection datetime.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Get display strings for each element of @var{obj}.

Returns a cellstr the same size as @var{obj}.

@end deftypefn

@node datetime.eq
@subsubsection datetime.eq

@deftypefn {Method} {@var{out} =} eq (@var{A}, @var{B})

True if @var{A} is equal to @var{B}. This defines the @code{==} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.ge
@subsubsection datetime.ge

@deftypefn {Method} {@var{out} =} ge (@var{A}, @var{B})

True if @var{A} is greater than or equal to @var{B}. This defines the @code{>=} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.gmtime
@subsubsection datetime.gmtime

@deftypefn {Method} {@var{out} =} gmtime (@var{obj})

Convert to TM_STRUCT structure in UTC time.

Converts @var{obj} to a TM_STRUCT style structure array. The result is in
UTC time. If @var{obj} is unzoned, it is assumed to be in UTC time.

Returns a struct array in TM_STRUCT style.

@end deftypefn

@node datetime.gt
@subsubsection datetime.gt

@deftypefn {Method} {@var{out} =} gt (@var{A}, @var{B})

True if @var{A} is greater than @var{B}. This defines the @code{>} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.hms
@subsubsection datetime.hms

@deftypefn {Method} {[@var{h}, @var{m}, @var{s}] =} hms (@var{obj})

Get the Hour, Minute, and Second components of a @var{datetime}. These are the time
of day components. The Year, Month, and Day components are ignored, and not
incorporated in to the result.

For zoned @code{datetime}s, these will be local times in the associated time zone.

Returns double arrays the same size as @code{obj}.

@end deftypefn

@node datetime.isbetween
@subsubsection datetime.isbetween

@deftypefn {Method} {@var{out} =} isbetween (@var{obj}, @var{lower}, @var{upper})

Tests whether the elements of @var{obj} are between @var{lower} and
@var{upper}.

All inputs are implicitly converted to @code{datetime} arrays, and are subject
to scalar expansion.

Returns a logical array the same size as the scalar expansion of the inputs.

@end deftypefn

@node datetime.ismissing
@subsubsection datetime.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})

Test whether array elements are missing.

For @code{string} arrays, the special NaT value is considered missing.
This is equivalent to a NaN used as a datenum.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.isnan
@subsubsection datetime.isnan

@deftypefn {Method} {@var{out} =} isnan (@var{obj})

True if input elements are NaT. This is an alias for @code{isnat}
to support type compatibility and polymorphic programming.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.isnat
@subsubsection datetime.isnat

@deftypefn {Method} {@var{out} =} isnat (@var{obj})

True if input elements are NaT.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.le
@subsubsection datetime.le

@deftypefn {Method} {@var{out} =} le (@var{A}, @var{B})

True if @var{A} is less than or equal to@var{B}. This defines the @code{<=} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.linspace
@subsubsection datetime.linspace

@deftypefn {Method} {@var{out} =} linspace (@var{from}, @var{to}, @var{n})

Linearly-spaced values in date/time space.

Constructs a vector of @code{datetime}s that represent linearly spaced points
starting at @var{from} and going up to @var{to}, with @var{n} points in the
vector.

@var{from} and @var{to} are implicitly converted to @code{datetime}s.

@var{n} is how many points to use. If omitted, defaults to 100.

Returns an @var{n}-long @code{datetime} vector.

@end deftypefn

@node datetime.localtime
@subsubsection datetime.localtime

@deftypefn {Method} {@var{out} =} localtime (@var{obj})

Convert to TM_STRUCT structure in UTC time.

Converts @var{obj} to a TM_STRUCT style structure array. The result is a
local time in the system default time zone. Note that the system default
time zone is always used, regardless of what TimeZone is set on @var{obj}.

If @var{obj} is unzoned, it is assumed to be in UTC time.

Returns a struct array in TM_STRUCT style.

Example:
@example
dt = datetime;
dt.TimeZone = datetime.SystemTimeZone;
tm_struct = localtime (dt);
@end example

@end deftypefn

@node datetime.lt
@subsubsection datetime.lt

@deftypefn {Method} {@var{out} =} lt (@var{A}, @var{B})

True if @var{A} is less than @var{B}. This defines the @code{<} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.minus
@subsubsection datetime.minus

@deftypefn {Method} {@var{out} =} minus (@var{A}, @var{B})

Subtraction (@code{-} operator). Subtracts a @code{duration},
@code{calendarDuration} or numeric @var{B} from a @code{datetime} @var{A},
or subtracts two @code{datetime}s from each other.

If both inputs are @code{datetime}, then the output is a @code{duration}.
Otherwise, the output is a @code{datetime}.

Numeric @var{B} inputs are implicitly converted to @code{duration} using
@code{duration.ofDays}.

Returns an array the same size as @var{A}.

@end deftypefn

@node datetime.NaT
@subsubsection datetime.NaT

@deftypefn {Static Method} {@var{out} =} datetime.NaT ()
@deftypefnx {Static Method} {@var{out} =} datetime.NaT (@var{sz})

“Not-a-Time”: Creates NaT-valued arrays.

Constructs a new @code{datetime} array of all @code{NaT} values of
the given size. If no input @var{sz} is given, the result is a scalar @code{NaT}.

@code{NaT} is the @code{datetime} equivalent of @code{NaN}. It represents a missing
or invalid value. @code{NaT} values never compare equal to, greater than, or less
than any value, including other @code{NaT}s. Doing arithmetic with a @code{NaT} and
any other value results in a @code{NaT}.

@end deftypefn

@node datetime.ne
@subsubsection datetime.ne

@deftypefn {Method} {@var{out} =} ne (@var{A}, @var{B})

True if @var{A} is not equal to @var{B}. This defines the @code{!=} operator
for @code{datetime}s.

Inputs are implicitly converted to @code{datetime} using the one-arg
constructor or conversion method.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node datetime.ofDatenum
@subsubsection datetime.ofDatenum

@deftypefn {Static Method} {@var{obj} =} datetime.ofDatenum (@var{dnums})

Converts a datenum array to a datetime array.

Returns an unzoned @code{datetime} array of the same size as the input.

@end deftypefn

@node datetime.ofDatestruct
@subsubsection datetime.ofDatestruct

@deftypefn {Static Method} {@var{obj} =} datetime.ofDatestruct (@var{dstruct})

Converts a datestruct to a datetime array.

A datestruct is a special struct format used by Tablicious that has fields
Year, Month, Day, Hour, Minute, and Second. It is not a standard Octave datatype.

Returns an unzoned @code{datetime} array.

@end deftypefn

@node datetime.plus
@subsubsection datetime.plus

@deftypefn {Method} {@var{out} =} plus (@var{A}, @var{B})

Addition (@code{+} operator). Adds a @code{duration}, @code{calendarDuration},
or numeric @var{B} to a @code{datetime} @var{A}.

@var{A} must be a @code{datetime}.

Numeric @var{B} inputs are implicitly converted to @code{duration} using
@code{duration.ofDays}.

WARNING: Arithmetic with calendarDuration arguments on datetimes in time zones
which use Daylight Saving Time may be buggy.

Returns @code{datetime} array the same size as @var{A}.

@end deftypefn

@node datetime.posix2datenum
@subsubsection datetime.posix2datenum

@deftypefn {Static Method} {@var{dnums} =} datetime.posix2datenum (@var{pdates})

Converts POSIX (Unix) times to datenums

Pdates (numeric) is an array of POSIX dates. A POSIX date is the number
of seconds since January 1, 1970 UTC, excluding leap seconds. The output
is implicitly in UTC.

@end deftypefn

@node datetime.posixtime
@subsubsection datetime.posixtime

@deftypefn {Method} {@var{out} =} posixtime (@var{obj})

Converts this to POSIX time values (seconds since the Unix epoch)

Converts this to POSIX time values that represent the same time. The
returned values will be doubles that may include fractional second values.
POSIX times are, by definition, in UTC.

Returns double array of same size as this.

@end deftypefn

@node datetime.proxyKeys
@subsubsection datetime.proxyKeys

@deftypefn {Method} {[@var{keysA}, @var{keysB}] =} proxyKeys (@var{a}, @var{b})

Computes proxy key values for two datetime arrays. Proxy keys are numeric
values whose rows have the same equivalence relationships as the elements of
the inputs.

This is primarily for Tablicious's internal use; users will typically not need to call
it or know how it works.

Returns two 2-D numeric matrices of size n-by-k, where n is the number of elements
in the corresponding input.

@end deftypefn

@node datetime.timeofday
@subsubsection datetime.timeofday

@deftypefn {Method} {@var{out} =} timeofday (@var{obj})

Get the time of day (elapsed time since midnight).

For zoned @code{datetime}s, these will be local times in the associated time zone.

Returns a @code{duration} array the same size as @code{obj}.

@end deftypefn

@node datetime.week
@subsubsection datetime.week

@deftypefn {Method} {@var{out} =} week (@var{obj})

Get the week of the year.

This method is unimplemented.

@end deftypefn

@node datetime.ymd
@subsubsection datetime.ymd

@deftypefn {Method} {[@var{y}, @var{m}, @var{d}] =} ymd (@var{obj})

Get the Year, Month, and Day components of @var{obj}.

For zoned @code{datetime}s, these will be local times in the associated time zone.

Returns double arrays the same size as @code{obj}.

@end deftypefn

@node datetime.ymdhms
@subsubsection datetime.ymdhms

@deftypefn {Method} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} ymdhms @
  (@var{obj})

Get the Year, Month, Day, Hour, Minute, and Second components of a @var{obj}.

For zoned @code{datetime}s, these will be local times in the associated time zone.

Returns double arrays the same size as @code{obj}.

@end deftypefn

@node days
@subsection days
@deftypefn {Function} {@var{out} =} days (@var{x})

Duration in days.

If @var{x} is numeric, then @var{out} is a @code{duration} array in units
of fixed-length 24-hour days, with the same size as @var{x}.

If @var{x} is a @code{duration}, then returns a @code{double} array the same
size as @var{x} indicating the number of fixed-length days that each duration
is.

@end deftypefn


@node discretize
@subsection discretize
@deftypefn {Function} {[@var{Y}, @var{E}] =} discretize (@var{X}, @var{n})
@deftypefnx {Function} {[@var{Y}, @var{E}] =} discretize (@var{X}, @var{edges})
@deftypefnx {Function} {[@var{Y}, @var{E}] =} discretize (@var{X}, @var{dur})
@deftypefnx {Function} {[@var{Y}, @var{E}] =} discretize (@dots{}, @code{'categorical'})
@deftypefnx {Function} {[@var{Y}, @var{E}] =} discretize (@dots{}, @code{'IncludedEdge'}, @var{IncludedEdge})

Group data into discrete bins or categories.

@var{n} is the number of bins to group the values into.

@var{edges} is an array of edge values defining the bins.

@var{dur} is a @code{duration} value indicating the length of time of each
bin.

If @code{'categorical'} is specified, the resulting values are a @code{categorical}
array instead of a numeric array of bin indexes.

Returns:
 @var{Y} - the bin index or category of each value from @var{X}
 @var{E} - the list of bin edge values

@end deftypefn


@node dispstrs
@subsection dispstrs
@deftypefn {Function} {@var{out} =} dispstrs (@var{x})

Display strings for array.

Gets the display strings for each element of @var{x}. The display strings
should be short, one-line, human-presentable strings describing the
value of that element.

The default implementation of @code{dispstrs} can accept input of any
type, and has decent implementations for Octave’s standard built-in types,
but will have opaque displays for most user-defined objects.

This is a polymorphic method that user-defined classes may override
with their own custom display that is more informative.

Returns a cell array the same size as @var{x}.

@end deftypefn


@node duration
@subsection duration
@deftp {Class} duration

Represents durations or periods of time as an amount of fixed-length
time (i.e. fixed-length seconds). It does not care about calendar things
like months and days that vary in length over time.

This is an attempt to reproduce the functionality of Matlab's @code{duration}. It
also contains some Octave-specific extensions.

Duration values are stored as double numbers of days, so they are an
approximate type. In display functions, by default, they are displayed with
millisecond precision, but their actual precision is closer to nanoseconds
for typical times.

@end deftp

@deftypeivar duration @code{double} days

The underlying datenums that represent the durations, as number of (whole and
fractional) days. These are uniform 24-hour days, not calendar days.

This is a planar property: the size of @code{days} is the same size as the
containing @code{duration} array object.

@end deftypeivar

@deftypeivar duration @code{char} Format

The format to display this @code{duration} in. Currently unsupported.

@end deftypeivar


@node duration.char
@subsubsection duration.char

@deftypefn {Method} {@var{out} =} char (@var{obj})

Convert to char. The contents of the strings will be the same as
returned by @code{dispstrs}.

This is primarily a convenience method for use on scalar @var{obj}s.

Returns a 2-D char array with one row per element in @var{obj}.

@end deftypefn

@node duration.datevec
@subsubsection duration.datevec

@deftypefn {Method} {[@var{dvec}] =} datevec (@var{obj})
@deftypefnx {Method} {[@var{Y}, @var{M}, @var{D}, @var{H}, @var{MN}, @var{S}] =} datevec (@var{obj})

Convert @var{obj} to a datevec whose elements represent the components of
this duration. The components are the year, month, days, hour, minute, and
second quantities of this duration. The years are in terms of fixed size
years that are 365.2425 days long, and days are fixed size 24-hour days.
The fixed size year size can be found in the FixedSizeYearDays constant
class property on the duration class. The month component is always zero,
since months are variable lengths and there is no equivalent fixed size
month. Thus, the days component may be more than 31.

When nargout is 0 or 1, returns a double array of size n-by-6, where n is
@code{numel(obj)}. When nargout is 2 or more, returns double arrays the
same size as @var{obj}.

@end deftypefn

@node duration.dispstrs
@subsubsection duration.dispstrs

@deftypefn {Method} {@var{out} =} duration (@var{obj})

Get display strings for each element of @var{obj}.

Returns a cellstr the same size as @var{obj}.

@end deftypefn

@node duration.hms
@subsubsection duration.hms

@deftypefn {Method} {[@var{h}, @var{m}, @var{s}] =} hms (@var{obj})

Get the Hour, Minute, and Second values of a @var{duration}. These are
the hour, minute, and second values that when combined are equal to the
same duration value.

Returns double arrays the same size as @code{obj}.

@end deftypefn

@node duration.hours
@subsubsection duration.hours

@deftypefn {Method} {@var{out} =} hours (@var{obj})

Equivalent number of hours.

Gets the number of fixed-length 60-minute hours that is equivalent
to this duration.

Returns double array the same size as @var{obj}.

@end deftypefn

@node duration.linspace
@subsubsection duration.linspace

@deftypefn {Method} {@var{out} =} linspace (@var{from}, @var{to}, @var{n})

Linearly-spaced values in time duration space.

Constructs a vector of @code{duration}s that represent linearly spaced points
starting at @var{from} and going up to @var{to}, with @var{n} points in the
vector.

@var{from} and @var{to} are implicitly converted to @code{duration}s.

@var{n} is how many points to use. If omitted, defaults to 100.

Returns an @var{n}-long @code{datetime} vector.

@end deftypefn

@node duration.milliseconds
@subsubsection duration.milliseconds

@deftypefn {Method} {@var{out} =} milliseconds (@var{obj})

Equivalent number of milliseconds.

Gets the number of milliseconds that is equivalent
to this duration.

Returns double array the same size as @var{obj}.

@end deftypefn

@node duration.minutes
@subsubsection duration.minutes

@deftypefn {Method} {@var{out} =} minutes (@var{obj})

Equivalent number of minutes.

Gets the number of fixed-length 60-second minutes that is equivalent
to this duration.

Returns double array the same size as @var{obj}.

@end deftypefn

@node duration.ofDays
@subsubsection duration.ofDays

@deftypefn {Static Method} {@var{obj} =} duration.ofDays (@var{dnums})

Converts a double array representing durations in whole and fractional days
to a @code{duration} array. This is the method that is used for implicit conversion
of numerics in many cases.

Returns a @code{duration} array of the same size as the input.

@end deftypefn

@node duration.seconds
@subsubsection duration.seconds

@deftypefn {Method} {@var{out} =} seconds (@var{obj})

Equivalent number of seconds.

Gets the number of seconds that is equivalent
to this duration.

Returns double array the same size as @var{obj}.

@end deftypefn

@node duration.years
@subsubsection duration.years

@deftypefn {Method} {@var{out} =} years (@var{obj})

Equivalent number of years.

Gets the number of fixed-length 365.2425-day years that is equivalent
to this duration.

Returns double array the same size as @var{obj}.

@end deftypefn

@node eqn
@subsection eqn
@deftypefn {Function} {@var{out} =} eqn (@var{A}, @var{B})

Determine element-wise equality, treating NaNs as equal

out = eqn (A, B)

@code{eqn} is just like @code{eq} (the function that implements the
@code{==} operator), except
that it considers NaN and NaN-like values to be equal. This is the element-wise
equivalent of @code{isequaln}.

@code{eqn} uses @code{isnanny} to test for NaN and NaN-like values,
which means that NaNs and NaTs are considered to be NaN-like, and
string arrays’ “missing” and categorical objects’ “undefined” values
are considered equal, because they are NaN-ish.

Developer's note: the name “@code{eqn}” is a little unfortunate,
because “eqn” could also be an abbreviation for “equation”. But this
name follows the @code{isequaln} pattern of appending an “n” to the
corresponding non-NaN-equivocating function.

See also: @code{eq}, @code{isequaln}, @ref{isnanny}

@end deftypefn


@node head
@subsection head
@deftypefn {Function} {@var{out} =} head (@var{A})
@deftypefnx {Function} {@var{out} =} head (@var{A}, @var{k})

Get first K rows of an array.

Returns the array @var{A}, subsetted to its first @var{k} rows. This means
subsetting it to the first @code{(min (k, size (A, 1)))} elements along
dimension 1, and leaving all other dimensions unrestricted.

@var{A} is the array to subset.

@var{k} is the number of rows to get. @var{k} defaults to 8 if it is omitted
or empty.

If there are less than @var{k} rows in @var{A}, returns all rows.

Returns an array of the same type as @var{A}, unless ()-indexing @var{A}
produces an array of a different type, in which case it returns that type.

See also: tail

@end deftypefn


@node hours
@subsection hours
@deftypefn {Function File} {@var{out} =} hours (@var{x})
Create a @code{duration} @var{x} hours long, or get the hours in a @code{duration}
@var{x}.

If input is numeric, returns a @code{duration} array that is that many hours in
time.

If input is a @code{duration}, converts the @code{duration} to a number of hours.

Returns an array the same size as @var{x}.
@end deftypefn


@node iscalendarduration
@subsection iscalendarduration
@deftypefn {Function} {@var{out} =} iscalendarduration (@var{x})

True if input is a @code{calendarDuration} array, false otherwise.

Respects @code{iscalendarduration} override methods on user-defined classes, even if
they do not inherit from @code{calendarDuration} or were known to Tablicious at
authoring time.

Returns a scalar logical.

@end deftypefn


@node iscategorical
@subsection iscategorical
@deftypefn {Function} {@var{out} =} iscategorical (@var{x})

True if input is a @code{categorical} array, false otherwise.

Respects @code{iscategorical} override methods on user-defined classes, even if
they do not inherit from @code{categorical} or were known to Tablicious at
authoring time.

Returns a scalar logical.

@end deftypefn


@node isdatetime
@subsection isdatetime
@deftypefn {Function} {@var{out} =} isdatetime (@var{x})

True if input is a @code{datetime} array, false otherwise.

Respects @code{isdatetime} override methods on user-defined classes, even if
they do not inherit from @code{datetime} or were known to Tablicious at
authoring time.

Returns a scalar logical.

@end deftypefn


@node isduration
@subsection isduration
@deftypefn {Function} {@var{out} =} isduration (@var{x})

True if input is a @code{duration} array, false otherwise.

Respects @code{isduration} override methods on user-defined classes, even if
they do not inherit from @code{duration} or were known to Tablicious at
authoring time.

Returns a scalar logical.

@end deftypefn


@node isfile
@subsection isfile
@emph{Not documented}
@node isfolder
@subsection isfolder
@emph{Not documented}
@node isnanny
@subsection isnanny
@deftypefn {Function} {@var{out} =} isnanny (@var{X})

Test if elements are NaN or NaN-like.

Tests if input elements are NaN, NaT, or otherwise NaN-like. This is true
if @code{isnan()} or @code{isnat()} returns true, and is false for types that do not support
@code{isnan()} or @code{isnat()}.

This function only exists because:

@enumerate a
@item
Matlab decided to call their NaN values for datetime “NaT” instead, and
test for them with a different “isnat()” function, and
@item
isnan() errors out for some types that do not support isnan(), like cells.
@item
Octave does not define an @code{ismissing} function, but the Octave Forge statistics
package does, and adding an @code{ismissing} function to Tablicious would conflict
with that in hard-to-resolve ways.
@end enumerate

@code{isnanny()} smooths over those differences so you can call it polymorphically on
any input type. Hopefully.

Under normal operation, @code{isnanny()} should not throw an error for any type or
value of input.

See also: ismissing, @code{isnan}, @code{isnat}, @ref{eqn}, @code{isequaln}

@end deftypefn


@node istable
@subsection istable
@deftypefn {Function} {@var{out} =} istable (@var{x})

True if input is a @code{table} array or other table-like type, false
otherwise.

Respects @code{istable} override methods on user-defined classes, even if
they do not inherit from @code{table} or were known to Tablicious at
authoring time.

User-defined classes should only override @code{istable} to return true if
they conform to the @code{table} public interface. That interface is not
well-defined or documented yet, so maybe you don't want to do that yet.

Returns a scalar logical.

@end deftypefn


@node istabular
@subsection istabular
@deftypefn {Function} {@var{out} =} istabular (@var{x})

True if input is eitehr a @code{table} or @code{timetable} array, or an object
like them.

Respects @code{istable} and @code{istimetable} override methods on user-defined
classes, even if they do not inherit from @code{table} or were known to Tablicious
at authoring time.

Returns a scalar logical.

@end deftypefn


@node istimetable
@subsection istimetable
@deftypefn {Function} {@var{out} =} istimetable (@var{x})

True if input is a @code{timetable} array or other timetable-like type, false
otherwise.

Respects @code{istimetable} override methods on user-defined classes, even if
they do not inherit from @code{table} or were known to Tablicious at
authoring time.

User-defined classes should only override @code{istimetable} to return true if
they conform to the @code{table} public interface. That interface is not
well-defined or documented yet, so maybe you don't want to do that yet.

Returns a scalar logical.

@end deftypefn


@node localdate
@subsection localdate
@deftp {Class} localdate

Represents a complete day using the Gregorian calendar.

This class is useful for indexing daily-granularity data or representing
time periods that cover an entire day in local time somewhere. The major
purpose of this class is "type safety", to prevent time-of-day values
from sneaking in to data sets that should be daily only. As a secondary
benefit, this uses less memory than datetimes.

@end deftp

@deftypeivar localdate @code{double} dnums

The underlying datenum values that represent the days. The datenums are at
the midnight that is at the start of the day it represents.

These are doubles, but
they are restricted to be integer-valued, so they represent complete days, with
no time-of-day component.

@end deftypeivar

@deftypeivar localdate @code{char} Format

The format to display this @code{localdate} in. Currently unsupported.

@end deftypeivar


@node localdate.datenum
@subsubsection localdate.datenum

@deftypefn {Method} {@var{out} =} datenum (@var{obj})

Convert this to datenums that represent midnight on @var{obj}’s days.

Returns double array of same size as this.

@end deftypefn

@node localdate.datestr
@subsubsection localdate.datestr

@deftypefn {Method} {@var{out} =} datestr (@var{obj})
@deftypefnx {Method} {@var{out} =} datestr (@var{obj}, @dots{})

Format @var{obj} as date strings. Supports all arguments that core Octave's
@code{datestr} does.

Returns date strings as a 2-D char array.

@end deftypefn

@node localdate.datestrs
@subsubsection localdate.datestrs

@deftypefn {Method} {@var{out} =} datestrs (@var{obj})
@deftypefnx {Method} {@var{out} =} datestrs (@var{obj}, @dots{})

Format @var{obj} as date strings, returning cellstr.
Supports all arguments that core Octave's @code{datestr} does.

Returns a cellstr array the same size as @var{obj}.

@end deftypefn

@node localdate.datestruct
@subsubsection localdate.datestruct

@deftypefn {Method} {@var{out} =} datestruct (@var{obj})

Converts this to a “datestruct” broken-down time structure.

A “datestruct” is a format of struct that Tablicious came up with. It is a scalar
struct with fields Year, Month, and Day, each containing
a double array the same size as the date array it represents. This format
differs from the “datestruct” used by @code{datetime} in that it lacks
Hour, Minute, and Second components. This is done for efficiency.

The values in the returned broken-down time are those of the local time
in @var{obj}’s defined time zone, if it has one.

Returns a struct with fields Year, Month, and Day.
Each field contains a double array of the same size as this.

@end deftypefn

@node localdate.dispstrs
@subsubsection localdate.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Get display strings for each element of @var{obj}.

Returns a cellstr the same size as @var{obj}.

@end deftypefn

@node localdate.isnan
@subsubsection localdate.isnan

@deftypefn {Method} {@var{out} =} isnan (@var{obj})

True if input elements are NaT. This is an alias for @code{isnat}
to support type compatibility and polymorphic programming.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node localdate.isnat
@subsubsection localdate.isnat

@deftypefn {Method} {@var{out} =} isnat (@var{obj})

True if input elements are NaT.

Returns logical array the same size as @var{obj}.

@end deftypefn

@node localdate.localdate
@subsubsection localdate.localdate

@deftypefn {Constructor} {@var{obj} =} localdate ()

Constructs a new scalar @code{localdate} containing the current local date.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} localdate (@var{datenums})
@deftypefnx {Constructor} {@var{obj} =} localdate (@var{datestrs})
@deftypefnx {Constructor} {@var{obj} =} localdate (@var{Y}, @var{M}, @var{D})
@deftypefnx {Constructor} {@var{obj} =} localdate (@dots{}, @code{'Format'}, @var{Format})

Constructs a new @code{localdate} array based on input values.

@end deftypefn

@node localdate.NaT
@subsubsection localdate.NaT

@deftypefn {Static Method} {@var{out} =} localdate.NaT ()
@deftypefnx {Static Method} {@var{out} =} localdate.NaT (@var{sz})

“Not-a-Time”: Creates NaT-valued arrays.

Constructs a new @code{datetime} array of all @code{NaT} values of
the given size. If no input @var{sz} is given, the result is a scalar @code{NaT}.

@code{NaT} is the @code{datetime} equivalent of @code{NaN}. It represents a missing
or invalid value. @code{NaT} values never compare equal to, greater than, or less
than any value, including other @code{NaT}s. Doing arithmetic with a @code{NaT} and
any other value results in a @code{NaT}.

This static method is provided because the global @code{NaT} function creates
@code{datetime}s, not @code{localdate}s

@end deftypefn

@node localdate.posixtime
@subsubsection localdate.posixtime

@deftypefn {Method} {@var{out} =} posixtime (@var{obj})

Converts this to POSIX time values for midnight of @var{obj}’s days.

Converts this to POSIX time values that represent the same date. The
returned values will be doubles that will not include fractional second values.
The times returned are those of midnight UTC on @var{obj}’s days.

Returns double array of same size as this.

@end deftypefn

@node localdate.ymd
@subsubsection localdate.ymd

@deftypefn {Method} {[@var{y}, @var{m}, @var{d}] =} ymd (@var{obj})

Get the Year, Month, and Day components of @var{obj}.

Returns double arrays the same size as @code{obj}.

@end deftypefn

@node milliseconds
@subsection milliseconds
@deftypefn {Function File} {@var{out} =} milliseconds (@var{x})
Create a @code{duration} @var{x} milliseconds long, or get the milliseconds in a @code{duration}
@var{x}.

If input is numeric, returns a @code{duration} array that is that many milliseconds in
time.

If input is a @code{duration}, converts the @code{duration} to a number of milliseconds.

Returns an array the same size as @var{x}.
@end deftypefn


@node minutes
@subsection minutes
@deftypefn {Function File} {@var{out} =} hours (@var{x})
Create a @code{duration} @var{x} hours long, or get the hours in a @code{duration}
@var{x}.

@end deftypefn


@node missing
@subsection missing
@deftp {Class} missing

Generic auto-converting missing value.

@code{missing} is a generic missing value that auto-converts to other
types.

A @code{missing} array indicates a missing value, of no particular type. It auto-
converts to other types when it is combined with them via concatenation or
other array combination operations.

This class is currently EXPERIMENTAL. Use at your own risk.

Note: This class does not actually work for assignment. If you do this:

@example
  x = 1:5
  x(3) = missing
@end example

It’s supposed to work, but I can’t figure out how to do this in a normal
classdef object, because there doesn’t seem to be any function that’s implicitly
called for type conversion in that assignment. Darn it.

@end deftp


@node missing.dispstrs
@subsubsection missing.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Display strings.

Gets display strings for each element in @var{obj}.

For @code{missing}, the display strings are always @code{'<missing>'}.

Returns a cellstr the same size as @var{obj}.

@end deftypefn

@node missing.ismissing
@subsubsection missing.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})

Test whether elements are missing values.

@code{ismissing} is always true for @code{missing} arrays.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node missing.isnan
@subsubsection missing.isnan

@deftypefn {Method} {@var{out} =} isnan (@var{obj})

Test whether elements are NaN.

@code{isnan} is always true for @code{missing} arrays.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node missing.isnanny
@subsubsection missing.isnanny

@deftypefn {Method} {@var{out} =} isnanny (@var{obj})

Test whether elements are NaN-like.

@code{isnanny} is always true for @code{missing} arrays.

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node missing.missing
@subsubsection missing.missing

@deftypefn {Constructor} {@var{obj} =} missing ()

Constructs a scalar @code{missing} array.

The constructor takes no arguments, since there’s only one
@code{missing} value.

@end deftypefn

@node mustBeA
@subsection mustBeA
@emph{Not documented}
@node mustBeCellstr
@subsection mustBeCellstr
@emph{Not documented}
@node mustBeCharvec
@subsection mustBeCharvec
@emph{Not documented}
@node mustBeFinite
@subsection mustBeFinite
@emph{Not documented}
@node mustBeInteger
@subsection mustBeInteger
@emph{Not documented}
@node mustBeMember
@subsection mustBeMember
@emph{Not documented}
@node mustBeNonempty
@subsection mustBeNonempty
@emph{Not documented}
@node mustBeNumeric
@subsection mustBeNumeric
@emph{Not documented}
@node mustBeReal
@subsection mustBeReal
@emph{Not documented}
@node mustBeSameSize
@subsection mustBeSameSize
@emph{Not documented}
@node mustBeScalar
@subsection mustBeScalar
@emph{Not documented}
@node mustBeScalarLogical
@subsection mustBeScalarLogical
@emph{Not documented}
@node mustBeVector
@subsection mustBeVector
@emph{Not documented}
@node NaC
@subsection NaC
@deftypefn {Function} {@var{out} =} NaC ()
@deftypefnx {Function} {@var{out} =} NaC (@var{sz})

“Not-a-Categorical". Creates missing-valued categorical arrays.

Returns a new @code{categorical} array of all missing values of
the given size. If no input @var{sz} is given, the result is a scalar missing
categorical.

@code{NaC} is the @code{categorical} equivalent of @code{NaN} or @code{NaT}. It
represents a missing, invalid, or null value. @code{NaC} values never compare
equal to any value, including other @code{NaC}s.

@code{NaC} is a convenience function which is strictly a wrapper around
@code{categorical.undefined} and returns the same results, but may be more convenient
to type and/or more readable, especially in array expressions with several values.

See also: categorical.undefined

@end deftypefn


@node NaS
@subsection NaS
@deftypefn {Function} {@var{out} =} NaS ()
@deftypefnx {Function} {@var{out} =} NaS (@var{sz})

“Not-a-String". Creates missing-valued string arrays.

Returns a new @code{string} array of all missing values of
the given size. If no input @var{sz} is given, the result is a scalar missing
string.

@code{NaS} is the @code{string} equivalent of @code{NaN} or @code{NaT}. It
represents a missing, invalid, or null value. @code{NaS} values never compare
equal to any value, including other @code{NaS}s.

@code{NaS} is a convenience function which is strictly a wrapper around
@code{string.missing} and returns the same results, but may be more convenient
to type and/or more readable, especially in array expressions with several values.

See also: string.missing

@end deftypefn


@node NaT
@subsection NaT
@deftypefn {Function} {@var{out} =} NaT ()
@deftypefnx {Function} {@var{out} =} NaT (@var{sz})

“Not-a-Time”. Creates missing-valued datetime arrays.

Constructs a new @code{datetime} array of all @code{NaT} values of
the given size. If no input @var{sz} is given, the result is a scalar @code{NaT}.

@code{NaT} is the @code{datetime} equivalent of @code{NaN}. It represents a missing
or invalid value. @code{NaT} values never compare equal to, greater than, or less
than any value, including other @code{NaT}s. Doing arithmetic with a @code{NaT} and
any other value results in a @code{NaT}.

@code{NaT} currently cannot create NaT arrays of type @code{localdate}. To do that,
use @ref{localdate.NaT} instead.

@end deftypefn


@node pp
@subsection pp
@deftypefn {Function} {} pp (@var{X})
@deftypefnx {Function} {} pp (@var{A}, @var{B}, @var{C}, @dots{})
@deftypefnx {Function} {} pp (@code{'A'}, @code{'B'}, @code{'C'}, @dots{})
@deftypefnx {Function} {} pp @code{A} @code{B} @code{C} @dots{}

Alias for prettyprint, for interactive use.

This is an alias for prettyprint(), with additional name-conversion magic.

If you pass in a char, instead of pretty-printing that directly, it will
grab and pretty-print the variable of that name from the caller’s workspace.
This is so you can conveniently run it from the command line.

@end deftypefn


@node scalarexpand
@subsection scalarexpand
@deftypefn {Function} {[@var{out1}, @var{out2}, @dots{}, @var{outN}] =} scalarexpand @
  (@var{x1}, @var{x2}, @dots{}, @var{xN})

Expand scalar inputs to match size of non-scalar inputs.

Expands each scalar input argument to match the size of the non-scalar
input arguments, and returns the expanded values in the corresponding
output arguments. @code{repmat} is used to do the expansion.

Works on any input types that support @code{size}, @code{isscalar}, and
@code{repmat}.

It is an error if any of the non-scalar inputs are not the same size as
all of the other non-scalar inputs.

Returns as many output arguments as there were input arguments.

Examples:

@example
x1 = rand(3);
x2 = 42;
x3 = magic(3);
[x1, x2, x3] = scalarexpand (x1, x2, x3)
@end example

@end deftypefn


@node seconds
@subsection seconds
@deftypefn {Function File} {@var{out} =} seconds (@var{x})
Create a @code{duration} @var{x} seconds long, or get the seconds in a @code{duration}
@var{x}.

If input is numeric, returns a @code{duration} array that is that many seconds in
time.

If input is a @code{duration}, converts the @code{duration} to a number of seconds.

Returns an array the same size as @var{x}.
@end deftypefn


@node size2str
@subsection size2str
@deftypefn {Function} {@var{out} =} size2str (@var{sz})

Format an array size for display.

Formats the given array size @var{sz} as a string for human-readable
display. It will be in the format “d1-by-d2-...-by-dN”, for the @var{N}
dimensions represented by @var{sz}.

@var{sz} is an array of dimension sizes, in the format returned by
the @code{size} function.

Returns a charvec.

Examples:
@example
str = size2str (size (magic (4)))
    @result{} str = 4-by-4
@end example

@end deftypefn


@node splitapply
@subsection splitapply
@deftypefn {Function} {@var{out} =} splitapply (@var{func}, @var{X}, @var{G})
@deftypefnx {Function} {@var{out} =} splitapply (@var{func}, @var{X1}, @dots{}, @var{XN}, @var{G})
@deftypefnx {Function} {[@var{Y1}, @dots{}, @var{YM}] =} splitapply (@dots{})

Split data into groups and apply function.

@var{func} is a function handle to call on each group of inputs in turn.

@var{X}, @var{X1}, @dots{}, @var{XN} are the input variables that are split into
groups for the function calls. If @var{X} is a @code{table}, then its contained
variables are “popped out” and considered to be the @var{X1} @dots{} @var{XN}
input variables.

@var{G} is the grouping variable vector. It contains a list of integers that
identify which group each element of the @var{X} input variables belongs to.
NaNs in @var{G} mean that element is ignored.

Vertically concatenates the function outputs for each of the groups and returns them in
as many variables as you capture.

Returns the concatenated outputs of applying @var{func} to each group.

See also: @ref{table.groupby}, @ref{table.splitapply}

@end deftypefn


@node string
@subsection string
@deftp {Class} string

A string array of Unicode strings.

A string array is an array of strings, where each array element is a single
string.

The string class represents strings, where:
@itemize @bullet
@item
Each element of a string array is a single string

@item
A single string is a 1-dimensional row vector of Unicode characters

@item
Those characters are encoded in UTF-8

@itemize @bullet
@item
This last bit depends on the fact that Octave chars are UTF-8 now
@end itemize

@end itemize

This should correspond pretty well to what people think of as strings, and
is pretty compatible with people’s typical notion of strings in Octave.

String arrays also have a special “missing” value, that is like the string
equivalent of NaN for doubles or “undefined” for categoricals, or SQL NULL.

This is a slightly higher-level and more strongly-typed way of representing
strings than cellstrs are. (A cellstr array is of type cell, not a text-
specific type, and allows assignment of non-string data into it.)

Be aware that while string arrays interconvert with Octave chars and cellstrs,
Octave char elements represent 8-bit UTF-8 code units, not Unicode code points.

This class really serves three roles:

@enumerate
@item
It is a type-safe object wrapper around Octave’s base primitive character types.

@item
It adds ismissing() semantics.

@item
And it introduces Unicode support.

@end enumerate

Not clear whether it’s a good fit to have the Unicode support wrapped
up in this. Maybe it should just be a simple object wrapper
wrapper, and defer Unicode semantics to when core Octave adopts them for
char and cellstr. On the other hand, because Octave chars are UTF-8, not UCS-2,
some methods like strlength() and reverse() are just going to be wrong if
they delegate straight to chars.

“Missing” string values work like NaNs. They are never considered equal,
less than, or greater to any other string, including other missing strings.
This applies to set membership and other equivalence tests.

TODO: Need to decide how far to go with Unicode semantics, and how much to
just make this an object wrapper over cellstr and defer to Octave's existing
char/string-handling functions.

TODO: demote_strings should probably be static or global, so that other
functions can use it to hack themselves into being string-aware.

@end deftp


@node string.cell
@subsubsection string.cell

@deftypefn {Method} {@var{out} =} cell (@var{obj})

Convert to cell array.

Converts this to a cell, which will be a cellstr. Missing values are
converted to @code{''}.

This method returns the same values as @code{cellstr(obj)}; it is just provided
for interface compatibility purposes.

Returns a cell array of the same size as @var{obj}.

@end deftypefn

@node string.cellstr
@subsubsection string.cellstr

@deftypefn {Method} {@var{out} =} cellstr (@var{obj})

Convert to cellstr.

Converts @var{obj} to a cellstr. Missing values are converted to @code{''}.

Returns a cellstr array of the same size as @var{obj}.

@end deftypefn

@node string.char
@subsubsection string.char

@deftypefn {Method} {@var{out} =} char (@var{obj})

Convert to char array.

Converts @var{obj} to a 2-D char array. It will have as many rows
as @var{obj} has elements.

It is an error to convert missing-valued @code{string} arrays to
char. (NOTE: This may change in the future; it may be more appropriate)
to convert them to space-padded empty strings.)

Returns 2-D char array.

@end deftypefn

@node string.cmp
@subsubsection string.cmp

@deftypefn {Method} {[@var{out}, @var{outA}, @var{outB}] =} cmp (@var{A}, @var{B})

Value ordering comparison, returning -1/0/+1.

Compares each element of @var{A} and @var{B}, returning for
each element @code{i} whether @code{A(i)} was less than (-1),
equal to (0), or greater than (1) the corresponding @code{B(i)}.

TODO: What to do about missing values? Should missings sort to the end
(preserving total ordering over the full domain), or should their comparisons
result in a fourth "null"/"undef" return value, probably represented by NaN?
FIXME: The current implementation does not handle missings.

Returns a numeric array @var{out} of the same size as the scalar expansion
of @var{A} and @var{B}. Each value in it will be -1, 0, or 1.

Also returns scalar-expanded copies of @var{A} and @var{B} as @var{outA} and
@var{outB}, as a programming convenience.

@end deftypefn

@node string.decode
@subsubsection string.decode

@deftypefn {Static Method} {@var{out} =} string.decode (@var{bytes}, @var{charsetName})

Decode encoded text from bytes.

Decodes the given encoded text in @var{bytes} according to the specified
encoding, given by @var{charsetName}.

Returns a scalar string.

See also: @ref{string.encode}

@end deftypefn

@node string.dispstrs
@subsubsection string.dispstrs

@deftypefn {Method} {@var{out} =} dispstrs (@var{obj})

Display strings for array elements.

Gets display strings for all the elements in @var{obj}. These display strings
will either be the string contents of the element, enclosed in @code{"..."},
and with CR/LF characters replaced with @code{'\r'} and @code{'\n'} escape sequences,
or @code{"<missing>"} for missing values.

Returns a cellstr of the same size as @var{obj}.

@end deftypefn

@node string.empty
@subsubsection string.empty

@deftypefn {Function} {@var{out} =} empty (@var{sz})

Get an empty string array of a specified size.

The argument sz is optional. If supplied, it is a numeric size
array whose product must be zero. If omitted, it defaults to [0 0].

The size may also be supplied as multiple arguments containing
scalar numerics.

Returns an empty string array of the requested size.

@end deftypefn

@node string.encode
@subsubsection string.encode

@deftypefn {Method} {@var{out} =} encode (@var{obj}, @var{charsetName})

Encode string in a given character encoding.

@var{obj} must be scalar.

@var{charsetName} (charvec) is the name of a character encoding.
(TODO: Document what determines the set of valid encoding names.)

Returns the encoded string as a @code{uint8} vector.

See also: @ref{string.decode}.

@end deftypefn

@node string.endsWith
@subsubsection string.endsWith

@deftypefn {Method} {@var{out} =} endsWith (@var{obj}, @var{pattern})
@deftypefnx {Method} {@var{out} =} endsWith (@var{obj}, @var{pattern}, 'IgnoreCase', true/false)

Test if string ends with pattern.

Returns a logical array the size of the scalar expansion of @var{obj} and @var{pattern}.

@end deftypefn

@node string.erase
@subsubsection string.erase

@deftypefn {Method} {@var{out} =} erase (@var{obj}, @var{match})

Erase matching substring.

Erases the substrings in @var{obj} which match the @var{match} input.

Returns a string array of the same size as @var{obj}.

@end deftypefn

@node string.ismissing
@subsubsection string.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})

Test whether array elements are missing.

For @code{string} arrays, only the special “missing” value is
considered missing. Empty strings are not considered missing,
the way they are with cellstrs.

Returns a logical array the same size as @code{obj}.

@end deftypefn

@node string.isnanny
@subsubsection string.isnanny

@deftypefn {Method} {@var{out} =} isnanny (@var{obj})

Test whether array elements are NaN-like.

Missing values are considered nannish; any other string value is not.

Returns a logical array of the same size as @var{obj}.

@end deftypefn

@node string.isstring
@subsubsection string.isstring

@deftypefn {Method} {@var{out} =} isstring (@var{obj})

Test if input is a string array.

@code{isstring} is always true for @code{string} inputs.

Returns a scalar logical.

@end deftypefn

@node string.lower
@subsubsection string.lower

@deftypefn {Method} {@var{out} =} lower (@var{obj})

Convert to lower case.

Converts all the characters in all the strings in @var{obj} to lower case.

This currently delegates to Octave’s own @code{lower()} function to
do the conversion, so whatever character class handling it has, this
has.

Returns a string array of the same size as @var{obj}.

@end deftypefn

@node string.missing
@subsubsection string.missing

@deftypefn {Static Method} {@var{out} = } string.missing (@var{sz})

Missing string value.

Creates a string array of all-missing values of the specified size @var{sz}.
If @var{sz} is omitted, creates a scalar missing string.

Returns a string array of size @var{sz} or [1 1].

See also: NaS

@end deftypefn

@node string.plus
@subsubsection string.plus

@deftypefn {Method} {@var{out} =} plus (@var{a}, @var{b})

String concatenation via plus operator.

Concatenates the two input arrays, string-wise. Inputs that are
not string arrays are converted to string arrays.

The concatenation is done by calling `strcat` on the inputs, and has the
same behavior.

Returns a string array the same size as the scalar expansion of its
inputs.

See also: string.strcat

@end deftypefn

@node string.regexprep
@subsubsection string.regexprep

@deftypefn {Method} {@var{out} =} regexprep (@var{obj}, @var{pat}, @var{repstr})
@deftypefnx {Method} {@var{out} =} regexprep (@dots{}, @var{varargin})

Replace based on regular expression matching.

Replaces all the substrings matching a given regexp pattern @var{pat} with
the given replacement text @var{repstr}.

Returns a string array of the same size as @var{obj}.

@end deftypefn

@node string.reverse
@subsubsection string.reverse

@deftypefn {Method} {@var{out} =} reverse (@var{obj})

Reverse string, character-wise.

Reverses the characters in each string in @var{obj}. This operates on
Unicode characters (code points), not on bytes, so it is guaranteed
to produce valid UTF-8 as its output.

Returns a string array the same size as @var{obj}.

@end deftypefn

@node string.reverse_bytes
@subsubsection string.reverse_bytes

@deftypefn {Method} {@var{out} =} reverse_bytes (@var{obj})

Reverse string, byte-wise.

Reverses the bytes in each string in @var{obj}. This operates on bytes
(Unicode code units), not characters.

This may well produce invalid strings as a result, because reversing a
UTF-8 byte sequence does not necessarily produce another valid UTF-8
byte sequence.

You probably do not want to use this method. You probably want to use
@code{string.reverse} instead.

Returns a string array the same size as @var{obj}.

See also: @ref{string.reverse}

@end deftypefn

@node string.startsWith
@subsubsection string.startsWith

@deftypefn {Method} {@var{out} =} startsWith (@var{obj}, @var{pattern})
@deftypefnx {Method} {@var{out} =} startsWith (@var{obj}, @var{pattern}, 'IgnoreCase', true/false)

Test if string starts with pattern.

Returns a logical array the size of the scalar expansion of @var{obj} and @var{pattern}.

@end deftypefn

@node string.strcat
@subsubsection string.strcat

@deftypefn {Method} {@var{out} =} strcat (@var{varargin})

String concatenation.

Concatenates the corresponding elements of all the input arrays,
string-wise. Inputs that are not string arrays are converted to
string arrays.

The semantics of concatenating missing strings with non-missing
strings has not been determined yet.

Returns a string array the same size as the scalar expansion of its
inputs.

@end deftypefn

@node string.strcmp
@subsubsection string.strcmp

@deftypefn {Method} {@var{out} =} strcmp (@var{A}, @var{B})

String comparison.

Tests whether each element in A is exactly equal to the corresponding
element in B. Missing values are not considered equal to each other.

This does the same comparison as @code{A == B}, but is not polymorphic.
Generally, there is no reason to use @code{strcmp} instead of @code{==}
or @code{eq} on string arrays, unless you want to be compatible with
cellstr inputs as well.

Returns logical array the size of the scalar expansion of A and B.

@end deftypefn

@node string.strfind
@subsubsection string.strfind

@deftypefn {Method} {@var{out} =} strfind (@var{obj}, @var{pattern})
@deftypefnx {Method} {@var{out} =} strfind (@dots{}, @var{varargin})

Find pattern in string.

Finds the locations where @var{pattern} occurs in the strings of @var{obj}.

TODO: It’s ambiguous whether a scalar this should result in a numeric
out or a cell array out.

Returns either an index vector, or a cell array of index vectors.

@end deftypefn

@node string.string
@subsubsection string.string

@deftypefn {Constructor} {@var{obj} =} string ()
@deftypefnx {Constructor} {@var{obj} =} string (@var{in})

Construct a new string array.

The zero-argument constructor creates a new scalar string array
whose value is the empty string.

The other constructors construct a new string array by converting
various types of inputs.

@itemize
@item
chars and cellstrs are converted via cellstr()
@item
numerics are converted via num2str()
@item
datetimes are converted via datestr()
@end itemize

@end deftypefn

@node string.strlength
@subsubsection string.strlength

@deftypefn {Method} {@var{out} =} strlength (@var{obj})

String length in characters (actually, UTF-16 code units).

Gets the length of each string, counted in UTF-16 code units. In most
cases, this is the same as the number of characters. The exception is for
characters outside the Unicode Basic Multilingual Plane, which are
represented with UTF-16 surrogate pairs, and thus will count as 2 characters
each.

The reason this method counts UTF-16 code units, instead of Unicode code
points (true characters), is for Matlab compatibility.

This is the string length method you probably want to use,
not @code{strlength_bytes}.

Returns double array of the same size as @var{obj}. Returns NaNs for missing
strings.

See also: @ref{string.strlength_bytes}

@end deftypefn

@node string.strlength_bytes
@subsubsection string.strlength_bytes

@deftypefn {Method} {@var{out} =} strlength_bytes (@var{obj})

String length in bytes.

Gets the length of each string in @var{obj}, counted in Unicode UTF-8
code units (bytes). This is the same as @code{numel(str)} for the corresponding
Octave char vector for each string, but may not be what you
actually want to use. You may want @code{strlength} instead.

Returns double array of the same size as @var{obj}. Returns NaNs for missing
strings.

See also: @ref{string.strlength}

@end deftypefn

@node string.strrep
@subsubsection string.strrep

@deftypefn {Method} {@var{out} =} strrep (@var{obj}, @var{match}, @var{replacement})
@deftypefnx {Method} {@var{out} =} strrep (@dots{}, @var{varargin})

Replace occurrences of pattern with other string.

Replaces matching substrings in @var{obj} with a given replacement string.

@var{varargin} is passed along to the core Octave @code{strrep} function. This
supports whatever options it does.
TODO: Maybe document what those options are.

Returns a string array of the same size as @var{obj}.

@end deftypefn

@node string.upper
@subsubsection string.upper

@deftypefn {Method} {@var{out} =} upper (@var{obj})

Convert to upper case.

Converts all the characters in all the strings in @var{obj} to upper case.

This currently delegates to Octave’s own @code{upper()} function to
do the conversion, so whatever character class handling it has, this
has.

Returns a string array of the same size as @var{obj}.

@end deftypefn

@node struct2table
@subsection struct2table
@deftypefn {Function} {@var{out} =} struct2table (@var{s})
@deftypefnx {Function} {@var{out} =} struct2table (@dots{}, @code{'AsArray'}, @var{AsArray})

Convert struct to a table.

Converts the input struct @var{s} to a @code{table}.

@var{s} may be a scalar struct or a nonscalar struct array.

The @var{AsArray} option is not implemented yet.

Returns a @code{table}.

@end deftypefn


@node table
@subsection table
@deftp {Class} table

Tabular data array containing multiple columnar variables.

A @code{table} is a tabular data structure that collects multiple parallel
named variables.
Each variable is treated like a column. (Possibly a multi-columned column, if
that makes sense.)
The types of variables may be heterogeneous.

A table object is like an SQL table or resultset, or a relation, or a
DataFrame in R or Pandas.

A table is an array in itself: its size is @var{nrows}-by-@var{nvariables},
and you can index along the rows and variables by indexing into the table
along dimensions 1 and 2.

A note on accessing properties of a @code{table} array: Because .-indexing is
used to access the variables inside the array, it can’t also be directly used
to access properties as well. Instead, do @code{t.Properties.<property>} for
a table @code{t}. That will give you a property instead of a variable.
(And due to this mechanism, it will cause problems if you have a @code{table}
with a variable named @code{Properties}. Try to avoid that.)

WARNING ABOUT HANDLE CLASSES IN TABLE VARIABLES

Using a handle class in a table variable (column) value may lead to unpredictable
and buggy behavior! A handle class array is a reference type, and it holds shared
mutable state, which may be shared with references to it in other table arrays or
outside the table array. The table class makes no guarantees about what it will
or will not do internally with arrays that are held in table variables, and any
operation on a table holding handle arrays may have unpredictable and undesirable
side effects. These side effects may change between versions of Tablicious.

We currently recommend that you do not use handle classes in table variables. It
may be okay to use handle classes *inside* cells or other non-handle composite types
that are used in table variables, but this hasn't been fully thought through or
tested.

See also: tblish.table.grpstats, tblish.evalWithTableVars, tblish.examples.SpDb

@end deftp

@deftypeivar table @code{cellstr} VariableNames

The names of the variables in the table, as a cellstr row vector.

@end deftypeivar

@deftypeivar table @code{cell} VariableValues

A cell vector containing the values for each of the variables.
@code{VariableValues(i)} corresponds to @code{VariableNames(i)}.

@end deftypeivar

@deftypeivar table @code{cellstr} RowNames

An optional list of row names that identify each row in the table. This
is a cellstr column vector, if present.

@end deftypeivar

@deftypeivar table @code{cellstr} DimensionNames

Names for the two dimensions of the table array, as a cellstr row vector. Always
exactly 2-long, because tables are always exactly 2-D. Defaults to
@code{@{"Row", "Variables"@}}. (I feel the singular "Row" and plural "Variables" here
are inconsistent, but that's what Matlab uses, so Tablicious uses it too, for
Matlab compatibility.)

@end deftypeivar


@node table.addvars
@subsubsection table.addvars

@deftypefn {Method} {@var{out} =} addvars (@var{obj}, @var{var1}, @dots{}, @var{varN})
@deftypefnx {Method} {@var{out} =} addvars (@dots{}, @code{'Before'}, @var{Before})
@deftypefnx {Method} {@var{out} =} addvars (@dots{}, @code{'After'}, @var{After})
@deftypefnx {Method} {@var{out} =} addvars (@dots{}, @
  @code{'NewVariableNames'}, @var{NewVariableNames})

Add variables to table.

Adds the specified variables to a table.

@end deftypefn

@node table.antijoin
@subsubsection table.antijoin

@deftypefn {Method} {[@var{outA}, @var{ixA}, @var{outB}, @var{ixB}] =} antijoin @
  (@var{A}, @var{B})

Natural antijoin (AKA “semidifference”).

Computes the anti-join of A and B. The anti-join is defined as all the
rows from one input which do not have matching rows in the other input.

Returns:
  @var{outA} - all the rows in A with no matching row in B
  @var{ixA} - the row indexes into A which produced @var{outA}
  @var{outB} - all the rows in B with no matching row in A
  @var{ixB} - the row indexes into B which produced @var{outB}

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

@end deftypefn

@node table.cartesian
@subsubsection table.cartesian

@deftypefn {Method} {[@var{out}, @var{ixs}] =} cartesian (@var{A}, @var{B})

Cartesian product of two tables.

Computes the Cartesian product of two tables. The Cartesian product is
each row in A combined with each row in B.

Due to the definition and structural constraints of table, the two inputs
must have no variable names in common. It is an error if they do.

The Cartesian product is seldom used in practice. If you find yourself
calling this method, you should step back and re-evaluate what you are
doing, asking yourself if that is really what you want to happen. If nothing
else, writing a function that calls cartesian() is usually much less
efficient than alternate ways of arriving at the same result.

This implementation does not remove duplicate values.
TODO: Determine whether this duplicate-removing behavior is correct.

The ordering of the rows in the output is not specified, and may be implementation-
dependent. TODO: Determine if we can lock this behavior down to a fixed,
defined ordering, without killing performance.

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

@end deftypefn

@node table.convertvars
@subsubsection table.convertvars

@deftypefn {Method} {@var{out} =} convertvars (@var{obj}, @var{vars}, @var{dataType})

Convert variables to specified data type.

Converts the variables in @var{obj} specified by @var{vars} to the specified data type.

@var{vars} is a cellstr or numeric vector specifying which variables to convert.

@var{dataType} specifies the data type to convert those variables to. It is either
a char holding the name of the data type, or a function handle which will
perform the conversion. If it is the name of the data type, there must
either be a one-arg constructor of that type which accepts the specified
variables' current types as input, or a conversion method of that name
defined on the specified variables' current type.

Returns a table with the same variable names as @var{obj}, but with converted
types.

@end deftypefn

@node table.findgroups
@subsubsection table.findgroups

@deftypefn {Method} {[@var{G}, @var{TID}] =} findgroups (@var{obj})

Find groups within a table’s row values.

Finds groups within a table’s row values and get group numbers. A group
is a set of rows that have the same values in all their variable elements.

Returns:
  @var{G} - A double column vector of group numbers created from @var{obj}.
  @var{TID} - A table containing the row values corresponding to the group numbers.

@end deftypefn

@node table.getvar
@subsubsection table.getvar

@deftypefn {Method} {[@var{out}, @var{name}]} = getvar (@var{obj}, @var{varRef})

Get value and name for single table variable.

@var{varRef} is a variable reference. It may be a name or an index. It
may only specify a single table variable.

Returns:
  @var{out} – the value of the referenced table variable
  @var{name} – the name of the referenced table variable

@end deftypefn

@node table.getvars
@subsubsection table.getvars

@deftypefn {Method} {[@var{out1}, @dots{}]} = getvars (@var{obj}, @var{varRef})

Get values for one ore more table variables.

@var{varRef} is a variable reference in the form of variable names or
indexes.

Returns as many outputs as @var{varRef} referenced variables. Each output
contains the contents of the corresponding table variable.

@end deftypefn

@node table.groupby
@subsubsection table.groupby

@deftypefn {Method} {[@var{out}] =} groupby (@var{obj}, @var{groupvars}, @var{aggcalcs})

Find groups in table data and apply functions to variables within groups.

This works like an SQL @code{"SELECT ... GROUP BY ..."} statement.

@var{groupvars} (cellstr, numeric) is a list of the grouping variables,
identified by name or index.

@var{aggcalcs} is a specification of the aggregate calculations to perform
on them, in the form @code{@{}@var{out_var}@code{,} @var{fcn}@code{,} @var{in_vars}@code{; ...@}}, where:
  @var{out_var} (char) is the name of the output variable
  @var{fcn} (function handle) is the function to apply to produce it
  @var{in_vars} (cellstr) is a list of the input variables to pass to fcn

Returns a table.

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

@end deftypefn

@node table.height
@subsubsection table.height

@deftypefn {Method} {@var{out} =} height (@var{obj})

Number of rows in table.

For a zero-variable table, this currently always returns 0. This is a bug,
and will change in the future. It should be possible for zero-variable table
arrays to have any number of rows.

@end deftypefn

@node table.horzcat
@subsubsection table.horzcat

@deftypefn {Method} {@var{out} =} horzcat (@var{varargin})

Horizontal concatenation.

Combines tables by horizontally concatenating them.
Inputs that are not tables are automatically converted to tables by calling
table() on them. Inputs must have all distinct variable names.

Output has the same RowNames as @code{varargin@{1@}}. The variable names and values
are the result of the concatenation of the variable names and values lists
from the inputs.

@end deftypefn

@node table.innerjoin
@subsubsection table.innerjoin

@deftypefn {Method} {[@var{out}, @var{ixa}, @var{ixb}] =} innerjoin (@var{A}, @var{B})
@deftypefnx {Method} {[@dots{}] =} innerjoin (@var{A}, @var{B}, @dots{})

Combine two tables by rows using key variables.

Computes the relational inner join between two tables. “Inner” means that
only rows which had matching rows in the other input are kept in the
output.

TODO: Document options.

Returns:
  @var{out} - A table that is the result of joining A and B
  @var{ix} - Indexes into A for each row in out
  @var{ixb} - Indexes into B for each row in out

@end deftypefn

@node table.intersect
@subsubsection table.intersect

@deftypefn {Method} {[@var{C}, @var{ia}, @var{ib}] =} intersect (@var{A}, @var{B})

Set intersection.

Computes the intersection of two tables. The intersection is defined to be the unique
row values which are present in both of the two input tables.

Returns:
  @var{C} - A table containing all the unique row values present in both A and B.
  @var{ia} - Row indexes into A of the rows from A included in C.
  @var{ib} - Row indexes into B of the rows from B included in C.

@end deftypefn

@node table.isempty
@subsubsection table.isempty

@deftypefn {Method} {@var{out} =} isempty (@var{obj})

Test whether array is empty.

For tables, @code{isempty} is true if the number of rows is 0 or the number
of variables is 0.

@end deftypefn

@node table.ismember
@subsubsection table.ismember

@deftypefn {Method} {[@var{tf}, @var{loc}] =} ismember (@var{A}, @var{B})

Set membership.

Finds rows in A that are members of B.

Returns:
  @var{tf} - A logical vector indicating whether each A(i,:) was present in B.
  @var{loc} - Indexes into B of rows that were found.

@end deftypefn

@node table.ismissing
@subsubsection table.ismissing

@deftypefn {Method} {@var{out} =} ismissing (@var{obj})
@deftypefnx {Method} {@var{out} =} ismissing (@var{obj}, @var{indicator})

Find missing values.

Finds missing values in @var{obj}’s variables.

If indicator is not supplied, uses the standard missing values for each
variable’s data type. If indicator is supplied, the same indicator list is
applied across all variables.

All variables in this must be vectors. (This is due to the requirement
that @code{size(out) == size(obj)}.)

Returns a logical array the same size as @var{obj}.

@end deftypefn

@node table.istable
@subsubsection table.istable

@deftypefn {Method} {@var{tf} =} istable (@var{obj})

True if input is a table.

@end deftypefn

@node table.join
@subsubsection table.join

@deftypefn {Method} {[@var{C}, @var{ib}] =} join (@var{A}, @var{B})
@deftypefnx {Method} {[@var{C}, @var{ib}] =} join (@var{A}, @var{B}, @dots{})

Combine two tables by rows using key variables, in a restricted form.

This is not a "real" relational join operation. It has the restrictions
that:
 1) The key values in B must be unique.
 2) Every key value in A must map to a key value in B.
These are restrictions inherited from the Matlab definition of table.join.

You probably don’t want to use this method. You probably want to use
innerjoin or outerjoin instead.

See also: @ref{table.innerjoin}, @ref{table.outerjoin}

@end deftypefn

@node table.mergevars
@subsubsection table.mergevars

@deftypefn {Method} {@var{out} =} mergevars (@var{obj}, @var{vars})
@deftypefnx {Method} {@var{out} =} mergevars (@dots{}, @
  @code{'NewVariableName'}, @var{NewVariableName})
@deftypefnx {Method} {@var{out} =} mergevars (@dots{}, @
  @code{'MergeAsTable'}, @var{MergeAsTable})

Merge table variables into a single variable.

@end deftypefn

@node table.movevars
@subsubsection table.movevars

@deftypefn {Method} {@var{out} =} movevars (@var{obj}, @var{vars}, @var{relLocation}, @var{location})

Move around variables in a table.

@var{vars} is a list of variables to move, specified by name or index.

@var{relLocation} is @code{'Before'} or @code{'After'}.

@var{location} indicates a single variable to use as the target location,
specified by name or index. If it is specified by index, it is the index
into the list of *unmoved* variables from @var{obj}, not the original full
list of variables in @var{obj}.

Returns a table with the same variables as @var{obj}, but in a different order.

@end deftypefn

@node table.ndims
@subsubsection table.ndims

@deftypefn {Method} {@var{out} =} ndims (@var{obj})

Number of dimensions

For tables, @code{ndims(obj)} is always 2, because table arrays are always
2-D (rows-by-columns).

@end deftypefn

@node table.numel
@subsubsection table.numel

@deftypefn {Method} {@var{out} =} numel (@var{obj})

Total number of elements in table (actually 1).

For compatibility reasons with Octave's OOP interface and subsasgn behavior,
table's numel is defined to always return 1. It is not useful for client
code to query a table's size using numel. This is an incompatibility with
Matlab.

@end deftypefn

@node table.outerfillvals
@subsubsection table.outerfillvals

@deftypefn {Method} {@var{out} =} outerfillvals (@var{obj})

Get fill values for outer join.

Returns a table with the same variables as this, but containing only
a single row whose variable values are the values to use as fill values
when doing an outer join.

@end deftypefn

@node table.outerjoin
@subsubsection table.outerjoin

@deftypefn {Method} {[@var{out}, @var{ixa}, @var{ixb}] =} outerjoin (@var{A}, @var{B})
@deftypefnx {Method} {[@dots{}] =} outerjoin (@var{A}, @var{B}, @dots{})

Combine two tables by rows using key variables, retaining unmatched rows.

Computes the relational outer join of tables A and B. This is like a
regular join, but also includes rows in each input which did not have
matching rows in the other input; the columns from the missing side are
filled in with placeholder values.

TODO: Document options.

Returns:
  @var{out} - A table that is the result of the outer join of A and B
  @var{ixa} - indexes into A for each row in out
  @var{ixb} - indexes into B for each row in out

@end deftypefn

@node table.prettyprint
@subsubsection table.prettyprint

@deftypefn {Method} {} prettyprint (@var{obj})

Display table's values in tabular format. This prints the contents
of the table in human-readable, tabular form.

Variables which contain objects are displayed using the strings
returned by their @code{dispstrs} method, if they define one.

@end deftypefn

@node table.realjoin
@subsubsection table.realjoin

@deftypefn {Method} {[@var{out}, @var{ixs}] =} realjoin (@var{A}, @var{B})
@deftypefnx {Method} {[@dots{}] =} realjoin (@var{A}, @var{B}, @dots{})

"Real" relational inner join, without key restrictions

Performs a "real" relational natural inner join between two tables,
without the key restrictions that JOIN imposes.

Currently does not support tables which have RowNames. This may be
added in the future.

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

Name/value option arguments are: @var{Keys}, @var{LeftKeys}, @var{RightKeys},
@var{LeftVariables}, @var{RightVariables}.

FIXME: Document those options.

Returns:
  @var{out} - A table that is the result of joining A and B
  @var{ixs} - Indexes into A for each row in out

@end deftypefn

@node table.removevars
@subsubsection table.removevars

@deftypefn {Method} {@var{out} =} removevars (@var{obj}, @var{vars})

Remove variables from table.

Deletes the variables specified by @var{vars} from @var{obj}.

@var{vars} may be a char, cellstr, numeric index vector, or logical
index vector.

@end deftypefn

@node table.renamevars
@subsubsection table.renamevars

@deftypefn {Method} {@var{out} =} renamevars (@var{obj}, @var{renameMap})

Rename variables in a table.

Renames selected variables in the table @var{obj} based on the mapping
provided in @var{renameMap}.

@var{renameMap} is an n-by-2 cellstr array, with the old variable names
in the first column, and the corresponding new variable names in the
second column.

Variables which are not included in @var{renameMap} are not modified.

It is an error if any variables named in the first column of @var{renameMap}
are not present in @var{obj}.

Renames
@end deftypefn

@node table.repelem
@subsubsection table.repelem

@deftypefn {Method} {@var{out} =} repelem (@var{obj}, @var{R})
@deftypefnx {Method} {@var{out} =} repelem (@var{obj}, @var{R_1}, @var{R_2})

Replicate elements of matrix.

Replicates elements of this table matrix by applying repelem to each of
its variables. This

Only two dimensions are supported for @code{repelem} on tables.

@end deftypefn

@node table.repmat
@subsubsection table.repmat

@deftypefn {Method} {@var{out} =} repmat (@var{obj}, @var{sz})

Replicate matrix.

Repmats a table by repmatting each of its variables vertically.

For tables, repmatting is only supported along dimension 1. That is, the
values of sz(2:end) must all be exactly 1. This behavior may change in the
future to support repmatting horizontally, with the added variable names being
automatically changed to maintain uniqueness of variable names within the
resulting table.

Returns a new table with the same variable names and types as tbl, but
with a possibly different row count.

@end deftypefn

@node table.restrict
@subsubsection table.restrict

@deftypefn {Method} {@var{out} =} restrict (@var{obj}, @var{expr})
@deftypefnx {Method} {@var{out} =} restrict (@var{obj}, @var{ix})

Subset rows using variable expression or index.

Subsets a table row-wise, using either an index vector or an expression
involving @var{obj}’s variables.

If the argument is a numeric or logical vector, it is interpreted as an
index into the rows of this. (Just as with `subsetrows (this, index)`.)

If the argument is a char, then it is evaulated as an M-code expression,
with all of this’ variables available as workspace variables, as with
@code{tblish.evalWithTableVars}. The output of expr must be a numeric or logical index
vector (This form is a shorthand for
@code{out = subsetrows (this, tblish.evalWithTableVars (this, expr))}.)

TODO: Decide whether to name this to "where" to be more like SQL instead
of relational algebra.

Examples:
@example
[s,p,sp] = tblish.examples.SpDb;
prettyprint (restrict (p, 'Weight >= 14 & strcmp(Color, "Red")'))
@end example

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

See also: tblish.evalWithTableVars

@end deftypefn

@node table.rowfun
@subsubsection table.rowfun

@deftypefn {Method} {@var{out} =} varfun (@var{func}, @var{obj})
@deftypefnx {Method} {@var{out} =} varfun (@dots{}, @code{'OptionName'}, @var{OptionValue}, @dots{})

Apply function to rows in table and collect outputs.

This applies the function @var{func} to the elements of each row of
@var{obj}’s variables, and collects the concatenated output(s) into the
variable(s) of a new table.

@var{func} is a function handle. It should take as many inputs as there
are variables in @var{obj}. Or, it can take a single input, and you must
specify @code{'SeparateInputs', false} to have the input variables
concatenated before being passed to @var{func}. It may return multiple
argouts, but to capture those past the first one, you must explicitly
specify the @code{'NumOutputs'} or @code{'OutputVariableNames'} options.

Supported name/value options:
@table @code
@item 'OutputVariableNames'
Names of table variables to store combined function output arguments in.
@item 'NumOutputs'
Number of output arguments to call function with. If omitted, defaults to
number of items in @var{OutputVariableNames} if it is supplied, otherwise
defaults to 1.
@item 'SeparateInputs'
If true, input variables are passed as separate input arguments to @var{func}.
If false, they are concatenated together into a row vector and passed as
a single argument. Defaults to true.
@item 'ErrorHandler'
A function to call as a fallback when calling @var{func} results in an error.
It is passed the caught exception, along with the original inputs passed
to @var{func}, and it has a “second chance” to compute replacement values
for that row. This is useful for converting raised errors to missing-value
fill values, or logging warnings.
@item 'ExtractCellContents'
Whether to “pop out” the contents of the elements of cell variables in
@var{obj}, or to leave them as cells. True/false; default is false. If
you specify this option, then @var{obj} may not have any multi-column
cell-valued variables.
@item 'InputVariables'
If specified, only these variables from @var{obj} are used as the function
inputs, instead of using all variables.
@item 'GroupingVariables'
Not yet implemented.
@item 'OutputFormat'
The format of the output. May be @code{'table'} (the default),
@code{'uniform'}, or @code{'cell'}. If it is @code{'uniform'} or @code{'cell'},
the output variables are returned in multiple output arguments from
@code{'rowfun'}.
@end table

Returns a @code{table} whose variables are the collected output arguments
of @var{func} if @var{OutputFormat} is @code{'table'}. Otherwise, returns
multiple output arguments of whatever type @var{func} returned (if
@var{OutputFormat} is @code{'uniform'}) or cells (if @var{OutputFormat}
is @code{'cell'}).

@end deftypefn

@node table.rows2vars
@subsubsection table.rows2vars

@deftypefn {Method} {@var{out} =} rows2vars (@var{obj})
@deftypefnx {Method} {@var{out} =} rows2vars (@var{obj}, @
  @code{'VariableNamesSource'}, @var{VariableNamesSource})
@deftypefnx {Method} {@var{out} =} rows2vars (@dots{}, @
  @code{'DataVariables'}, @var{DataVariables})

Reorient table, swapping rows and variables dimensions.

This flips the dimensions of the given table @var{obj}, swapping the
orientation of the contained data, and swapping the row names/labels
and variable names.

The variable names become a new variable named “OriginalVariableNames”.

The row names are drawn from the column @var{VariableNamesSource} if it
is specified. Otherwise, if @var{obj} has row names, they are used.
Otherwise, new variable names in the form “VarN” are generated.

If all the variables in @var{obj} are of the same type, they are concatenated
and then sliced to create the new variable values. Otherwise, they are
converted to cells, and the new table has cell variable values.

@end deftypefn

@node table.semijoin
@subsubsection table.semijoin

@deftypefn {Method} {[@var{outA}, @var{ixA}, @var{outB}, @var{ixB}] =} semijoin @
  (@var{A}, @var{B})

Natural semijoin.

Computes the natural semijoin of tables A and B. The semi-join of tables
A and B is the set of all rows in A which have matching rows in B, based
on comparing the values of variables with the same names.

This method also computes the semijoin of B and A, for convenience.

Returns:
  @var{outA} - all the rows in A with matching row(s) in B
  @var{ixA} - the row indexes into A which produced @var{outA}
  @var{outB} - all the rows in B with matching row(s) in A
  @var{ixB} - the row indexes into B which produced @var{outB}

This is a Tablicious/Octave extension, not defined in the Matlab table interface.

@end deftypefn

@node table.setdiff
@subsubsection table.setdiff

@deftypefn {Method} {[@var{C}, @var{ia}] =} setdiff (@var{A}, @var{B})

Set difference.

Computes the set difference of two tables. The set difference is defined to be
the unique row values which are present in table A that are not in table B.

Returns:
  @var{C} - A table containing the unique row values in A that were not in B.
  @var{ia} - Row indexes into A of the rows from A included in C.

@end deftypefn

@node table.setDimensionNames
@subsubsection table.setDimensionNames

@deftypefn {Method} {@var{out} =} setDimensionNames (@var{obj}, @var{names})
@deftypefnx {Method} {@var{out} =} setDimensionNames (@var{obj}, @var{ix}, @var{names})

Set dimension names.

Sets the @code{DimensionNames} for this table to a new list of names.

@var{names} is a char or cellstr vector. It must have the same number of elements
as the number of dimension names being assigned.

@var{ix} is an index vector indicating which dimension names to set. If
omitted, it sets all two of them. Since there are always two dimension,
the indexes in @var{ix} may never be higher than 2.

This method exists because the @code{obj.Properties.DimensionNames = @dots{}}
assignment form did not originally work, possibly due to an Octave bug, or more
likely due to a bug in Tablicious prior to the early 0.4.x versions. That was
fixed around 0.4.4. This method may be deprecated and removed at some point, since
it is not part of the standard Matlab table interface, and is now redundant with
the @code{obj.Properties.DimensionNames = @dots{}} assignment form.

@end deftypefn

@node table.setRowNames
@subsubsection table.setRowNames

@deftypefn {Method} {@var{out} =} setRowNames (@var{obj}, @var{names})

Set row names.

Sets the row names on @var{obj} to @var{names}.

@var{names} is a cellstr column vector, with the same number of rows as
@var{obj} has.

@end deftypefn

@node table.setvar
@subsubsection table.setvar

@deftypefn {Method} {@var{out} =} setvar (@var{obj}, @var{varRef}, @var{value})

Set value for a variable in table.

This sets (adds or replaces) the value for a variable in @var{obj}. It
may be used to change the value of an existing variable, or add a new
variable.

This method exists primarily because I cannot get @code{obj.foo = value} to work,
apparently due to an issue with Octave's subsasgn support.

@var{varRef} is a variable reference, either the index or name of a variable.
If you are adding a new variable, it must be a name, and not an index.

@var{value} is the value to set the variable to. If it is scalar or
a single string as charvec, it is scalar-expanded to match the number
of rows in @var{obj}.

@end deftypefn

@node table.setVariableNames
@subsubsection table.setVariableNames

@deftypefn {Method} {@var{out} =} setVariableNames (@var{obj}, @var{names})
@deftypefnx {Method} {@var{out} =} setVariableNames (@var{obj}, @var{ix}, @var{names})

Set variable names.

Sets the @code{VariableNames} for this table to a new list of names.

@var{names} is a char or cellstr vector. It must have the same number of elements
as the number of variable names being assigned.

@var{ix} is an index vector indicating which variable names to set. If
omitted, it sets all of them present in @var{obj}.

This method exists because the @code{obj.Properties.VariableNames = @dots{}}
assignment form does not work, possibly due to an Octave bug.

@end deftypefn

@node table.setxor
@subsubsection table.setxor

@deftypefn {Method} {[@var{C}, @var{ia}, @var{ib}] =} setxor (@var{A}, @var{B})

Set exclusive OR.

Computes the setwise exclusive OR of two tables. The set XOR is defined to be
the unique row values which are present in one or the other of the two input
tables, but not in both.

Returns:
  @var{C} - A table containing all the unique row values in the set XOR of A and B.
  @var{ia} - Row indexes into A of the rows from A included in C.
  @var{ib} - Row indexes into B of the rows from B included in C.

@end deftypefn

@node table.size
@subsubsection table.size

@deftypefn {Method} {@var{sz} =} size (@var{obj})
@deftypefnx {Method} {[@var{nr}, @var{nv}] =} size (@var{obj})
@deftypefnx {Method} {[@var{nr}, @var{nv}, @dots{}] =} size (@var{obj})

Gets the size of a table.

For tables, the size is [number-of-rows x number-of-variables].
This is the same as @code{[height(obj), width(obj)]}.

@end deftypefn

@node table.splitapply
@subsubsection table.splitapply

@deftypefn {Method} {@var{out} =} splitapply (@var{func}, @var{obj}, @var{G})
@deftypefnx {Method} {[@var{Y1}, @dots{}, @var{YM}] =} splitapply (@var{func}, @var{obj}, @var{G})

Split table data into groups and apply function.

Performs a splitapply, using the variables in @var{obj} as the input X variables
to the @code{splitapply} function call.

See also: splitapply, table.groupby, tblish.table.grpstats

@end deftypefn

@node table.splitvars
@subsubsection table.splitvars

@deftypefn {Method} {@var{out} =} splitvars (@var{obj})
@deftypefnx {Method} {@var{out} =} splitvars (@var{obj}, @var{vars})
@deftypefnx {Method} {@var{out} =} splitvars (@dots{}, @
  @code{'NewVariableNames'}, @var{NewVariableNames})

Split multicolumn table variables.

Splits multicolumn table variables into new single-column variables.
If @var{vars} is supplied, splits only those variables. If @var{vars}
is not supplied, splits all multicolumn variables.

@end deftypefn

@node table.squeeze
@subsubsection table.squeeze

@deftypefn {Method} {@var{obj} =} squeeze (@var{obj})

Remove singleton dimensions.

For tables, this is always a no-op that returns the input unmodified,
because tables always have exactly 2 dimensions, and 2-D arrays are unaffected
by squeeze.

@end deftypefn

@node table.stack
@subsubsection table.stack

@deftypefn {Method} {@var{out} =} stack (@var{obj}, @var{vars})
@deftypefnx {Method} {@var{out} =} stack (@dots{}, @
  @code{'NewDataVariableName'}, @var{NewDataVariableName})
@deftypefnx {Method} {@var{out} =} stack (@dots{}, @
  @code{'IndexVariableName'}, @var{IndexVariableName})

Stack multiple table variables into a single variable.

@end deftypefn

@node table.summary
@subsubsection table.summary

@deftypefn {Method} summary (@var{obj})

Display a summary of a table's data.

Displays a summary of data in the input table. This will contain some
statistical information on each of its variables. The output is printed
to the Octave console (command window, stdout, or the like in your current
session), in a format suited for human consumption. The output format is
not fixed or formally defined, and may change over time. It is only
suitable for human display, and not for parsing or programmatic use.

This method supports, to some degree, extension by other packages. If your
Octave session has loaded other packages which supply extension implementaions
of `summary`, Tablicious will use those in preference to its own internal
implementation, and you will get different, and hopefully better, output.

@end deftypefn

@node table.table
@subsubsection table.table

@deftypefn {Constructor} {@var{obj} =} table ()

Constructs a new empty (0 rows by 0 variables) table.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} table (@var{var1}, @var{var2}, @dots{}, @var{varN})

Constructs a new table from the given variables. The variables passed as
inputs to this constructor become the variables of the table. Their names
are automatically detected from the input variable names that you used.

Note: If you call the constructor with exactly three arguments, and the first
argument is exactly the value '__tblish_backdoor__', that will trigger a special internal-use
backdoor calling form, and you will get incorrect results. This is a bug in
Tablicious.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} table (@code{'Size'}, @var{sz}, @
  @code{'VariableTypes'}, @var{varTypes})

Constructs a new table of the given size, and with the given variable types.
The variables will contain the default value for elements of that type.

@end deftypefn

@deftypefn {Constructor} {@var{obj} =} table (@dots{}, @code{'VariableNames'}, @var{varNames})
@deftypefnx {Constructor} {@var{obj} =} table (@dots{}, @code{'RowNames'}, @var{rowNames})

Specifies the variable names or row names to use in the constructed table.
Overrides the implicit names garnered from the input variable names.

@end deftypefn

@node table.table2array
@subsubsection table.table2array

@deftypefn {Method} {@var{s} =} table2struct (@var{obj})

Converts @var{obj} to a homogeneous array.

@end deftypefn

@node table.table2cell
@subsubsection table.table2cell

@deftypefn {Method} {@var{c} =} table2cell (@var{obj})

Converts table to a cell array. Each variable in @var{obj} becomes
one or more columns in the output, depending on how many columns
that variable has.

Returns a cell array with the same number of rows as @var{obj}, and
with as many or more columns as @var{obj} has variables.

@end deftypefn

@node table.table2struct
@subsubsection table.table2struct

@deftypefn {Method} {@var{s} =} table2struct (@var{obj})
@deftypefnx {Method} {@var{s} =} table2struct (@dots{}, @code{'ToScalar'}, @var{trueOrFalse})

Converts @var{obj} to a scalar structure or structure array.

Row names are not included in the output struct. To include them, you
must add them manually:
  s = table2struct (tbl, 'ToScalar', true);
  s.RowNames = tbl.Properties.RowNames;

Returns a scalar struct or struct array, depending on the value of the
@code{ToScalar} option.

@end deftypefn

@node table.union
@subsubsection table.union

@deftypefn {Method} {[@var{C}, @var{ia}, @var{ib}] =} union (@var{A}, @var{B})

Set union.

Computes the union of two tables. The union is defined to be the unique
row values which are present in either of the two input tables.

Returns:
  @var{C} - A table containing all the unique row values present in A or B.
  @var{ia} - Row indexes into A of the rows from A included in C.
  @var{ib} - Row indexes into B of the rows from B included in C.

@end deftypefn

@node table.varfun
@subsubsection table.varfun

@deftypefn {Method} {@var{out} =} varfun (@var{fcn}, @var{obj})
@deftypefnx {Method} {@var{out} =} varfun (@dots{}, @code{'OutputFormat'}, @var{outputFormat})
@deftypefnx {Method} {@var{out} =} varfun (@dots{}, @code{'InputVariables'}, @var{vars})
@deftypefnx {Method} {@var{out} =} varfun (@dots{}, @code{'ErrorHandler'}, @var{errorFcn})

Apply function to table variables.

Applies the given function @var{fcn} to each variable in @var{obj},
collecting the output in a table, cell array, or array of another type.

@end deftypefn

@node table.varnames
@subsubsection table.varnames

@deftypefn {Method} {@var{out} =} varnames (@var{obj})
@deftypefnx {Method} {@var{out} =} varnames (@var{obj}, @var{varNames})

Get or set variable names for a table.

Returns cellstr in the getter form. Returns an updated datetime in the
setter form.

@end deftypefn

@node table.vertcat
@subsubsection table.vertcat

@deftypefn {Method} {@var{out} =} vertcat (@var{varargin})

Vertical concatenation.

Combines tables by vertically concatenating them.

Inputs that are not tables are automatically converted to tables by calling
table() on them.

The inputs must have the same number and names of variables, and their
variable value types and sizes must be cat-compatible. The types of the resulting
variables are the types that result from doing a `vertcat()` on the variables
from the corresponding input tables, in the order they were input in.

@end deftypefn

@node table.width
@subsubsection table.width

@deftypefn {Method} {@var{out} =} width (@var{obj})

Number of variables in table.

Note that this is not the sum of the number of columns in each variable.
It is just the number of variables.

@end deftypefn

@node tableOuterFillValue
@subsection tableOuterFillValue
@emph{Not documented}
@node tail
@subsection tail
@deftypefn {Function} {@var{out} =} tail (@var{A})
@deftypefnx {Function} {@var{out} =} tail (@var{A}, @var{k})

Get last K rows of an array.

Returns the array @var{A}, subsetted to its last @var{k} rows. This means
subsetting it to the last @code{(min (k, size (A, 1)))} elements along
dimension 1, and leaving all other dimensions unrestricted.

@var{A} is the array to subset.

@var{k} is the number of rows to get. @var{k} defaults to 8 if it is omitted
or empty.

If there are less than @var{k} rows in @var{A}, returns all rows.

Returns an array of the same type as @var{A}, unless ()-indexing @var{A}
produces an array of a different type, in which case it returns that type.

See also: head

@end deftypefn


@node tblish.dataset
@subsection tblish.dataset
@deftp {Class} tblish.dataset

The @code{tblish.dataset} class provides convenient access to the various
datasets included with Tablicious.

This class just contains a bunch of static methods, each of which loads
the dataset of that name. It is provided as a convenience so you can use tab
completion or other run-time introspection on the dataset list.

@end deftp


@node tblish.dataset.airmiles
@subsubsection tblish.dataset.airmiles

@deftypefn {Static Method} {@var{out} =} airmiles ()

Passenger Miles on Commercial US Airlines, 1937-1960

@subsubheading Description

The revenue passenger miles flown by commercial airlines in the
United States for each year from 1937 to 1960.

@subsubheading Source

@cite{F.A.A. Statistical Handbook of Aviation}.

@subsubheading Examples

@example
t = tblish.dataset.airmiles;
plot (t.year, t.miles);
title ("airmiles data");
xlabel ("Passenger-miles flown by U.S. commercial airlines")
ylabel ("airmiles");

@end example


@end deftypefn

@node tblish.dataset.AirPassengers
@subsubsection tblish.dataset.AirPassengers

@deftypefn {Static Method} {@var{out} =} AirPassengers ()

Monthly Airline Passenger Numbers 1949-1960

@subsubheading Description

The classic Box & Jenkins airline data. Monthly totals of international
airline passengers, 1949 to 1960.

@subsubheading Source

Box, G. E. P., Jenkins, G. M. and Reinsel, G. C. (1976). @cite{Time Series
Analysis, Forecasting and Control}. Third Edition. San Francisco: Holden-Day.
Series G.

@subsubheading Examples

@example
## TODO: This example needs to be ported from R.

@end example


@end deftypefn

@node tblish.dataset.airquality
@subsubsection tblish.dataset.airquality

@deftypefn {Static Method} {@var{out} =} airquality ()

New York Air Quality Measurements from 1973

@subsubheading Description

Daily air quality measurements in New York, May to September 1973.

@subsubheading Format

@table @code
@item Ozone
Ozone concentration (ppb)
@item SolarR
Solar R (lang)
@item Wind
Wind (mph)
@item Temp
Temperature (degrees F)
@item Month
Month (1-12)
@item Day
Day of month (1-31)
@end table

@subsubheading Source

New York State Department of Conservation (ozone data) and the National
Weather Service (meteorological data).

@subsubheading References

Chambers, J. M., Cleveland, W. S., Kleiner, B. and Tukey, P. A. (1983).
@cite{Graphical Methods for Data Analysis}. Belmont, CA: Wadsworth.

@subsubheading Examples

@example
t = tblish.dataset.airquality
# Plot a scatter-plot plus a fitted line, for each combination of measurements
vars = @{"Ozone", "SolarR", "Wind", "Temp" "Month", "Day"@};
n_vars = numel (vars);
figure;
for i = 1:n_vars
  for j = 1:n_vars
    if (i == j)
      continue
    endif
    ix_subplot = (n_vars * (j - 1) + i);
    hax = subplot (n_vars, n_vars, ix_subplot);
    var_x = vars@{i@};
    var_y = vars@{j@};
    x = t.(var_x);
    y = t.(var_y);
    scatter (hax, x, y, 10);
    # Fit a cubic line to these points
    # TODO: Find out exactly what kind of fitted line R's example is using, and
    # port that.
    hold on
    p = polyfit (x, y, 3);
    x_hat = unique(x);
    p_y = polyval (p, x_hat);
    plot (hax, x_hat, p_y, "r");
  endfor
endfor

@end example


@end deftypefn

@node tblish.dataset.anscombe
@subsubsection tblish.dataset.anscombe

@deftypefn {Static Method} {@var{out} =} anscombe ()

Anscombe’s Quartet of “Identical” Simple Linear Regressions

@subsubheading Description

Four sets of x/y pairs which have the same statistical properties, but are
very different.

@subsubheading Format

The data comes in an array of 4 structs, each with fields as follows:

@table @code
@item x
The X values for this pair.
@item y
The Y values for this pair.
@end table

@subsubheading Source

Tufte, Edward R. (1989). @cite{The Visual Display of Quantitative Information}.
13–14. Cheshire, CT: Graphics Press.

@subsubheading References

Anscombe, Francis J. (1973). Graphs in statistical analysis. @cite{The
American Statistician}, 27, 17–21.

@subsubheading Examples

@example
data = tblish.dataset.anscombe

# Pick good limits for the plots
all_x = [data.x];
all_y = [data.y];
x_limits = [min(0, min(all_x)) max(all_x)*1.2];
y_limits = [min(0, min(all_y)) max(all_y)*1.2];

# Do regression on each pair and plot the input and results
figure;
haxs = NaN (1, 4);
for i_pair = 1:4
  x = data(i_pair).x;
  y = data(i_pair).y;
  # TODO: Port the anova and other characterizations from the R code
  # TODO: Do a linear regression and plot its line
  hax = subplot (2, 2, i_pair);
  haxs(i_pair) = hax;
  xlabel (sprintf ("x%d", i_pair));
  ylabel (sprintf ("y%d", i_pair));
  scatter (x, y, "r");
endfor

# Fiddle with the plot axes parameters
linkaxes (haxs);
xlim (haxs(1), x_limits);
ylim (haxs(1), y_limits);

@end example


@end deftypefn

@node tblish.dataset.attenu
@subsubsection tblish.dataset.attenu

@deftypefn {Static Method} {@var{out} =} attenu ()

Joyner-Boore Earthquake Attenuation Data

@subsubheading Description

Event data for 23 earthquakes in California, showing peak accelerations.

@subsubheading Format

@table @code
@item event
Event number
@item mag
Moment magnitude
@item station
Station identifier
@item dist
Station-hypocenter distance (km)
@item accel
Peak acceleration (g)
@end table

@subsubheading Source

Joyner, W.B., D.M. Boore and R.D. Porcella (1981). Peak horizontal acceleration
and velocity from strong-motion records including records from the 1979
Imperial Valley, California earthquake. USGS Open File report 81-365. Menlo
Park, CA.

@subsubheading References

Boore, D. M. and Joyner, W. B. (1982). The empirical prediction of ground
motion. @cite{Bulletin of the Seismological Society of America}, 72, S269–S268.

@subsubheading Examples

@example
# TODO: Port the example code from R
# It does coplot() and pairs(), which are higher-level plotting tools
# than core Octave provides. This could turn into a long example if we
# just use base Octave here.
@end example


@end deftypefn

@node tblish.dataset.attitude
@subsubsection tblish.dataset.attitude

@deftypefn {Static Method} {@var{out} =} attitude ()

The Chatterjee-Price Attitude Data

@subsubheading Description

Aggregated data from a survey of clerical employees at a large financial
organization.

@subsubheading Format

@table @code
@item rating
Overall rating.
@item complaints
Handling of employee complaints.
@item privileges
Does not allow special privileges.
@item learning
Opportunity to learn.
@item raises
Raises based on performance.
@item critical
Too critical.
@item advance
Advancement.
@end table

@subsubheading Source

Chatterjee, S. and Price, B. (1977). @cite{Regression Analysis by Example}. New York:
Wiley. (Section 3.7, p.68ff of 2nd ed.(1991).)

@subsubheading Examples

@example
t = tblish.dataset.attitude

tblish.examples.plot_pairs (t);

# TODO: Display table summary

# TODO: Whatever those statistical linear-model plots are that R is doing


@end example

@end deftypefn

@node tblish.dataset.austres
@subsubsection tblish.dataset.austres

@deftypefn {Static Method} {@var{out} =} austres ()

Australian Population

@subsubheading Description

Numbers of Australian residents measured quarterly from March 1971 to March 1994.

@subsubheading Format

@table @code
@item date
The month of the observation.
@item residents
The number of residents.
@end table

@subsubheading Source

Brockwell, P. J. and Davis, R. A. (1996). @cite{Introduction to Time Series and
Forecasting}. New York: Springer-Verlag.

@subsubheading Examples

@example
t = tblish.dataset.austres

plot (datenum (t.date), t.residents);
datetick x
xlabel ("Month"); ylabel ("Residents"); title ("Australian Residents");

@end example


@end deftypefn

@node tblish.dataset.beavers
@subsubsection tblish.dataset.beavers

@deftypefn {Static Method} {@var{out} =} beavers ()

Body Temperature Series of Two Beavers

@subsubheading Description

Body temperature readings for two beavers.

@subsubheading Format

@table @code
@item day
Day of observation (in days since the beginning of 1990), December 12–13 (beaver1)
and November 3–4 (beaver2).
@item time
Time of observation, in the form 0330 for 3:30am
@item temp
Measured body temperature in degrees Celsius.
@item activ
Indicator of activity outside the retreat.
@end table

@subsubheading Source

P. S. Reynolds (1994) Time-series analyses of beaver body temperatures.
Chapter 11 of Lange, N., Ryan, L., Billard, L., Brillinger, D., Conquest,
L. and Greenhouse, J. (Eds.) (1994) @cite{Case Studies in Biometry}. New York: John Wiley
and Sons.

@subsubheading Examples

@example
# TODO: This example needs to be ported from R.
@end example


@end deftypefn

@node tblish.dataset.BJsales
@subsubsection tblish.dataset.BJsales

@deftypefn {Static Method} {@var{out} =} BJsales ()

Sales Data with Leading Indicator

@subsubheading Description

Sales Data with Leading Indicator

@subsubheading Format

@table @code
@item record
Index of the record.
@item lead
Leading indicator.
@item sales
Sales volume.
@end table

@subsubheading Source

The data are given in Box & Jenkins (1976). Obtained from the Time Series Data
Library at @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/}.

@subsubheading References

Box, G. E. P. and Jenkins, G. M. (1976). @cite{Time Series Analysis, Forecasting and
Control}. San Francisco: Holden-Day. p. 537.

Brockwell, P. J. and Davis, R. A. (1991). @cite{Time Series: Theory and Methods},
Second edition. New York: Springer-Verlag. p. 414.

@subsubheading Examples

@example
# TODO: Come up with example code here

@end example


@end deftypefn

@node tblish.dataset.BOD
@subsubsection tblish.dataset.BOD

@deftypefn {Static Method} {@var{out} =} BOD ()

Biochemical Oxygen Demand

@subsubheading Description

Contains biochemical oxygen demand versus time in an evaluation of water quality.

@subsubheading Format

@table @code
@item Time
Time of the measurement (in days).
@item demand
Biochemical oxygen demand (mg/l).
@end table

@subsubheading Source

Bates, D.M. and Watts, D.G. (1988). @cite{Nonlinear Regression Analysis and Its
Applications}. New York: John Wiley & Sons. Appendix A1.4.

Originally from: Marske (1967). @cite{Biochemical Oxygen Demand Data
Interpretation Using Sum of Squares Surface}, M.Sc. Thesis, University of
Wisconsin – Madison.

@subsubheading Examples

@example
# TODO: Port this example from R

@end example


@end deftypefn

@node tblish.dataset.cars
@subsubsection tblish.dataset.cars

@deftypefn {Static Method} {@var{out} =} cars ()

Speed and Stopping Distances of Cars

@subsubheading Description

Speed of cars and distances taken to stop. Note that the data were recorded in the 1920s.

@subsubheading Format

@table @code
@item speed
Speed (mph).
@item dist
Stopping distance (ft).
@end table

@subsubheading Source

Ezekiel, M. (1930). @cite{Methods of Correlation Analysis}. New York: Wiley.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example

t = tblish.dataset.cars;


# TODO: Add Lowess smoothed lines to the plots

figure;
plot (t.speed, t.dist, "o");
xlabel ("Speed (mph)"); ylabel ("Stopping distance (ft)");
title ("cars data");

figure;
loglog (t.speed, t.dist, "o");
xlabel ("Speed (mph)"); ylabel ("Stopping distance (ft)");
title ("cars data (logarithmic scales)");

# TODO: Do the linear model plot

# Polynomial regression
figure;
plot (t.speed, t.dist, "o");
xlabel ("Speed (mph)"); ylabel ("Stopping distance (ft)");
title ("cars polynomial regressions");
hold on
xlim ([0 25]);
x2 = linspace (0, 25, 200);
for degree = 1:4
  [P, S, mu] = polyfit (t.speed, t.dist, degree);
  y2 = polyval(P, x2, [], mu);
  plot (x2, y2);
endfor


@end example


@end deftypefn

@node tblish.dataset.ChickWeight
@subsubsection tblish.dataset.ChickWeight

@deftypefn {Static Method} {@var{out} =} ChickWeight ()

Weight versus age of chicks on different diets

@subsubheading Format

@table @code
@item weight
a numeric vector giving the body weight of the chick (gm).
@item Time
a numeric vector giving the number of days since birth when the
measurement was made.
@item Chick
an ordered factor with levels 18 < ... < 48 giving a unique
identifier for the chick. The ordering of the levels groups chicks on the same
diet together and orders them according to their final weight (lightest to
heaviest) within diet.
@item Diet
a factor with levels 1, ..., 4 indicating which experimental diet
the chick received.
@end table

@subsubheading Source

Crowder, M. and Hand, D. (1990). @cite{Analysis of Repeated Measures}. London: Chapman and
Hall. (example 5.3)

Hand, D. and Crowder, M. (1996), @cite{Practical Longitudinal Data Analysis}. London: Chapman
and Hall. (table A.2)

Pinheiro, J. C. and Bates, D. M. (2000) @cite{Mixed-effects Models in S and S-PLUS}.
New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.ChickWeight

tblish.examples.coplot (t, "Time", "weight", "Chick");

@end example


@end deftypefn

@node tblish.dataset.chickwts
@subsubsection tblish.dataset.chickwts

@deftypefn {Static Method} {@var{out} =} chickwts ()

Chicken Weights by Feed Type

@subsubheading Description

An experiment was conducted to measure and compare the effectiveness of various
feed supplements on the growth rate of chickens.

Newly hatched chicks were randomly allocated into six groups, and each group
was given a different feed supplement. Their weights in grams after six weeks
are given along with feed types.

@subsubheading Format

@table @code
@item weight
Chick weight at six weeks (gm).
@item feed
Feed type.
@end table

@subsubheading Source

Anonymous (1948) @cite{Biometrika}, 35, 214.

@subsubheading References

McNeil, D. R. (1977). @code{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
# This example requires the statistics package from Octave Forge

t = tblish.dataset.chickwts

# Boxplot by group
figure
g = groupby (t, "feed", @{
  "weight", @@(x) @{x@}, "weight"
@});
boxplot (g.weight, 1);
xlabel ("feed"); ylabel ("Weight at six weeks (gm)");
xticklabels ([@{""@} cellstr(g.feed')]);

# Linear model
# TODO: This linear model thing and anova

@end example


@end deftypefn

@node tblish.dataset.co2
@subsubsection tblish.dataset.co2

@deftypefn {Static Method} {@var{out} =} co2 ()

Mauna Loa Atmospheric CO2 Concentration

@subsubheading Description

Atmospheric concentrations of CO2 are expressed in parts per million (ppm) and
reported in the preliminary 1997 SIO manometric mole fraction scale. Contains
monthly observations from 1959 to 1997.

@subsubheading Format

@table @code
@item date
Date of the month of the observation, as datetime.
@item co2
CO2 concentration (ppm).
@end table

@subsubheading Details

The values for February, March and April of 1964 were missing and have
been obtained by interpolating linearly between the values for January
and May of 1964.

@subsubheading Source

Keeling, C. D. and Whorf, T. P., Scripps Institution of Oceanography
(SIO), University of California, La Jolla, California USA 92093-0220.

@url{ftp://cdiac.esd.ornl.gov/pub/maunaloa-co2/maunaloa.co2}.

@subsubheading References

Cleveland, W. S. (1993). @code{Visualizing Data}. New Jersey: Summit Press.

@subsubheading Examples

@example
t = tblish.dataset.co2;

plot (datenum (t.date), t.co2);
datetick ("x");
xlabel ("Time"); ylabel ("Atmospheric concentration of CO2");
title ("co2 data set");

@end example


@end deftypefn

@node tblish.dataset.crimtab
@subsubsection tblish.dataset.crimtab

@deftypefn {Static Method} {@var{out} =} crimtab ()

Student’s 3000 Criminals Data

@subsubheading Description

Data of 3000 male criminals over 20 years old undergoing their sentences in the
chief prisons of England and Wales.

@subsubheading Format

This dataset contains three separate variables. The @code{finger_length} and
@code{body_height} variables correspond to the rows and columns of the
@code{count} matrix.

@table @code
@item finger_length
Midpoints of intervals of finger lengths (cm).
@item body_height
Body heights (cm).
@item count
Number of prisoners in this bin.
@end table

@subsubheading Details

Student is the pseudonym of William Sealy Gosset. In his 1908 paper he wrote
(on page 13) at the beginning of section VI entitled Practical Test of the
forgoing Equations:

“Before I had succeeded in solving my problem analytically, I had endeavoured
to do so empirically. The material used was a correlation table containing
the height and left middle finger measurements of 3000 criminals, from a
paper by W. R. MacDonell (Biometrika, Vol. I., p. 219). The measurements
were written out on 3000 pieces of cardboard, which were then very thoroughly
shuffled and drawn at random. As each card was drawn its numbers were written
down in a book, which thus contains the measurements of 3000 criminals in a
random order. Finally, each consecutive set of 4 was taken as a sample—750
in all—and the mean, standard deviation, and correlation of each sample
etermined. The difference between the mean of each sample and the mean of
the population was then divided by the standard deviation of the sample, giving
us the z of Section III.”

The table is in fact page 216 and not page 219 in MacDonell(1902). In the
MacDonell table, the middle finger lengths were given in mm and the heights
in feet/inches intervals, they are both converted into cm here. The midpoints
of intervals were used, e.g., where MacDonell has “4' 7"9/16 -- 8"9/16”, we
have 142.24 which is 2.54*56 = 2.54*(4' 8").

MacDonell credited the source of data (page 178) as follows: “The data on which
the memoir is based were obtained, through the kindness of Dr Garson, from the
Central Metric Office, New Scotland Yard... He pointed out on page 179 that:
“The forms were drawn at random from the mass on the office shelves; we are
therefore dealing with a random sampling.”

@subsubheading Source

@url{http://pbil.univ-lyon1.fr/R/donnees/criminals1902.txt} thanks to Jean R.
Lobry and Anne-Béatrice Dufour.

@subsubheading References

Garson, J.G. (1900). The metric system of identification of criminals, as used
in in Great Britain and Ireland. @cite{The Journal of the Anthropological
Institute of Great Britain and Ireland}, 30, 161–198.

MacDonell, W.R. (1902). On criminal anthropometry and the identification of
criminals. @cite{Biometrika}, 1(2), 177–227.

Student (1908). The probable error of a mean. @code{Biometrika}, 6, 1–25.

@subsubheading Examples

@example
# TODO: Port this from R

@end example


@end deftypefn

@node tblish.dataset.cupcake
@subsubsection tblish.dataset.cupcake

@deftypefn {Static Method} {@var{out} =} cupcake ()

Google Search popularity for "cupcake", 2004-2019

@subsubheading Description

Monthly popularity of worldwide Google search results for "cupcake", 2004-2019.

@subsubheading Format

@table @code
@item Month
Month when searches took place
@item Cupcake
An indicator of search volume, in unknown units
@end table

@subsubheading Source

Google Trends, @url{https://trends.google.com/trends/explore?q=%2Fm%2F03p1r4&date=all},
retrieved 2019-05-04 by Andrew Janke.

@subsubheading Examples

@example
t = tblish.dataset.cupcake
plot (datenum (t.Month), t.Cupcake)
title ('“Cupcake” Google Searches'); xlabel ("Year"); ylabel ("Unknown popularity metric");

@end example


@end deftypefn

@node tblish.dataset.discoveries
@subsubsection tblish.dataset.discoveries

@deftypefn {Static Method} {@var{out} =} discoveries ()

Yearly Numbers of Important Discoveries

@subsubheading Description

The numbers of “great” inventions and scientific discoveries in each year from 1860 to 1959.

@subsubheading Format

@table @code
@item year
Year.
@item discoveries
Number of “great” discoveries that year.
@end table

@subsubheading Source

@cite{The World Almanac and Book of Facts}, 1975 Edition, pages 315–318.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.discoveries;

plot (t.year, t.discoveries);
xlabel ("Time"); ylabel ("Number of important discoveries");
title ("discoveries data set");

@end example


@end deftypefn

@node tblish.dataset.DNase
@subsubsection tblish.dataset.DNase

@deftypefn {Static Method} {@var{out} =} DNase ()

Elisa assay of DNase

@subsubheading Description

Data obtained during development of an ELISA assay for the recombinant protein DNase in rat serum.

@subsubheading Format

@table @code
@item Run
Ordered @code{categorical} indicating the assay run.
@item conc
Known concentration of the protein (ng/ml).
@item density
Measured optical density in the assay (dimensionless).
@end table

@subsubheading Source

Davidian, M. and Giltinan, D. M. (1995). @cite{Nonlinear Models for Repeated
Measurement Data}. London: Chapman & Hall. (section 5.2.4, p. 134)

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models in S and
S-PLUS}. New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.DNase;

# TODO: Port this from R

tblish.examples.coplot (t, "conc", "density", "Run", "PlotFcn", @@scatter);
tblish.examples.coplot (t, "conc", "density", "Run", "PlotFcn", @@loglog, ...
  "PlotArgs", @{"o"@});

@end example


@end deftypefn

@node tblish.dataset.esoph
@subsubsection tblish.dataset.esoph

@deftypefn {Static Method} {@var{out} =} esoph ()

Smoking, Alcohol and Esophageal Cancer

@subsubheading Description

Data from a case-control study of (o)esophageal cancer in Ille-et-Vilaine, France.

@subsubheading Format

@table @code
@item item
Age group (years).
@item alcgp
Alcohol consumption (gm/day).
@item tobgp
Tobacco consumption (gm/day).
@item ncases
Number of cases.
@item ncontrols
Number of controls
@end table

@subsubheading Source

Breslow, N. E. and Day, N. E. (1980) @cite{Statistical Methods in Cancer Research.
Volume 1: The Analysis of Case-Control Studies}. Oxford: IARC Lyon / Oxford University Press.

@subsubheading Examples

@example
# TODO: Port this from R

# TODO: Port the anova output

# TODO: Port the fancy plot
# This involves a "mosaic plot", which is not supported by Octave, so this will
# take some work.

@end example


@end deftypefn

@node tblish.dataset.euro
@subsubsection tblish.dataset.euro

@deftypefn {Static Method} {@var{out} =} euro ()

Conversion Rates of Euro Currencies

@subsubheading Description

Conversion rates between the various Euro currencies.

@subsubheading Format

This data comes in two separate variables.

@table @code
@item euro
An 11-long vector of the value of 1 Euro in all participating currencies.
@item euro_cross
An 11-by-11 matrix of conversion rates between various Euro currencies.
@item euro_date
The date upon which these Euro conversion rates were fixed.
@end table

@subsubheading Details

The data set euro contains the value of 1 Euro in all currencies participating
in the European monetary union (Austrian Schilling ATS, Belgian Franc BEF,
German Mark DEM, Spanish Peseta ESP, Finnish Markka FIM, French Franc FRF,
Irish Punt IEP, Italian Lira ITL, Luxembourg Franc LUF, Dutch Guilder NLG and
Portuguese Escudo PTE). These conversion rates were fixed by the European
Union on December 31, 1998. To convert old prices to Euro prices, divide by the
respective rate and round to 2 digits.

@subsubheading Source

Unknown.

This example data set was derived from the R 3.6.0 example datasets, and they
do not specify a source.

@subsubheading Examples

@example
# TODO: Port this from R

# TODO: Example conversion

# TODO: "dot chart" showing euro-to-whatever conversion rates and vice versa

@end example


@end deftypefn

@node tblish.dataset.eurodist
@subsubsection tblish.dataset.eurodist

@deftypefn {Static Method} {@var{out} =} eurodist ()

Distances Between European Cities and Between US Cities

@subsubheading Description

@code{eurodist} gives road distances (in km) between 21 cities in Europe. The
data are taken from a table in The Cambridge Encyclopaedia.

@code{UScitiesD} gives “straight line” distances between 10 cities in the US.

@subsubheading Format

@table @code
@item eurodist
?????
@end table

TODO: Finish this.

@subsubheading Source

Crystal, D. Ed. (1990). @cite{The Cambridge Encyclopaedia}. Cambridge:
Cambridge University Press.

The US cities distances were provided by Pierre Legendre.

@subsubheading Examples



@end deftypefn

@node tblish.dataset.EuStockMarkets
@subsubsection tblish.dataset.EuStockMarkets

@deftypefn {Static Method} {@var{out} =} EuStockMarkets ()

Daily Closing Prices of Major European Stock Indices

@subsubheading Description

Contains the daily closing prices of major European stock indices: Germany DAX
(Ibis), Switzerland SMI, France CAC, and UK FTSE. The data are sampled in
business time, i.e., weekends and holidays are omitted.

@subsubheading Format

A multivariate time series with 1860 observations on 4 variables.

The starting date is the 130th day of 1991, with a frequency of 260 observations
per year.

@subsubheading Source

The data were kindly provided by Erste Bank AG, Vienna, Austria.

@subsubheading Examples

@example

t = tblish.dataset.EuStockMarkets;

# The fact that we're doing this munging means that table might have
# been the wrong structure for this data in the first place

t2 = removevars (t, "day");
index_names = t2.Properties.VariableNames;
day = 1:height (t2);
price = table2array (t2);

price0 = price(1,:);

rel_price = price ./ repmat (price0, [size(price, 1) 1]);

figure;
plot (day, rel_price);
legend (index_names);
xlabel ("Business day");
ylabel ("Relative price");



@end example


@end deftypefn

@node tblish.dataset.faithful
@subsubsection tblish.dataset.faithful

@deftypefn {Static Method} {@var{out} =} faithful ()

Old Faithful Geyser Data

@subsubheading Description

Waiting time between eruptions and the duration of the eruption for the Old
Faithful geyser in Yellowstone National Park, Wyoming, USA.

@subsubheading Format

@table @code
@item eruptions
Eruption time (mins).
@item waiting
Waiting time to next eruption (mins).
@end table

@subsubheading Source

W. Härdle.

@subsubheading References

Härdle, W. (1991). @cite{Smoothing Techniques with Implementation in S}. New York:
Springer.

Azzalini, A. and Bowman, A. W. (1990). A look at some data on the Old
Faithful geyser. @cite{Applied Statistics}, 39, 357–365.

@subsubheading Examples

@example
t = tblish.dataset.faithful;

# Munge the data, rounding eruption time to the second
e60 = 60 * t.eruptions;
ne60 = round (e60);
# TODO: Port zapsmall to Octave
eruptions = ne60 / 60;
# TODO: Display mean relative difference and bins summary

# Histogram of rounded eruption times
figure
hist (ne60, max (ne60))
xlabel ("Eruption time (sec)")
ylabel ("n")
title ("faithful data: Eruptions of Old Faithful")

# Scatter plot of eruption time vs waiting time
figure
scatter (t.eruptions, t.waiting)
xlabel ("Eruption time (min)")
ylabel ("Waiting time to next eruption (min)")
title ("faithful data: Eruptions of Old Faithful")
# TODO: Port Lowess smoothing to Octave

@end example


@end deftypefn

@node tblish.dataset.Formaldehyde
@subsubsection tblish.dataset.Formaldehyde

@deftypefn {Static Method} {@var{out} =} Formaldehyde ()

Determination of Formaldehyde

@subsubheading Description

These data are from a chemical experiment to prepare a standard curve for the
determination of formaldehyde by the addition of chromatropic acid and
concentrated sulphuric acid and the reading of the resulting purple color on
a spectrophotometer.

@subsubheading Format

@table @code
@item record
Observation record number.
@item carb
Carbohydrate (ml).
@item optden
Optical Density
@end table

@subsubheading Source

Bennett, N. A. and N. L. Franklin (1954). @cite{Statistical Analysis in
Chemistry and the Chemical Industry}. New York: Wiley.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.Formaldehyde;

figure
scatter (t.carb, t.optden)
# TODO: Add a linear model line
xlabel ("Carbohydrate (ml)")
ylabel ("Optical Density")
title ("Formaldehyde data")

# TODO: Add linear model summary output
# TOD: Add linear model summary plot

@end example


@end deftypefn

@node tblish.dataset.freeny
@subsubsection tblish.dataset.freeny

@deftypefn {Static Method} {@var{out} =} freeny ()

Freeny's Revenue Data

@subsubheading Description

Freeny’s data on quarterly revenue and explanatory variables.

@subsubheading Format

Freeny’s dataset consists of one observed dependent variable
(revenue) and four explanatory variables (lagged quartery
revenue, price index, income level, and market potential).

@table @code
@item date
Start date of the quarter for the observation.
@item y
Observed quarterly revenue.
TODO: Determine units (probably millions of USD?)
@item lag_quarterly_revenue
Quarterly revenue (@code{y}), lagged 1 quarter.
@item price_index
A price index
@item income_level
??? TODO: Fill this in
@item market_potential
??? TODO: Fill this in
@end table

@subsubheading Source

Freeny, A. E. (1977). @cite{A Portable Linear Regression Package with Test
Programs}. Bell Laboratories memorandum.

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

@subsubheading Examples

@example
t = tblish.dataset.freeny;

summary (t)

tblish.examples.plot_pairs (removevars (t, "date"))

# TODO: Create linear model and print summary

# TODO: Linear model plot

@end example


@end deftypefn

@node tblish.dataset.HairEyeColor
@subsubsection tblish.dataset.HairEyeColor

@deftypefn {Static Method} {@var{out} =} HairEyeColor ()

Hair and Eye Color of Statistics Students

@subsubheading Description

Distribution of hair and eye color and sex in 592 statistics students.

@subsubheading Format

This data set comes in multiple variables

@table @code
@item n
A 3-dimensional array containing the counts of students in each bucket. It
is arranged as hair-by-eye-by-sex.
@item hair
Hair colors for the indexes along dimension 1.
@item eye
Eye colors for the indexes along dimension 2.
@item sex
Sexes for the indexes along dimension 3.
@end table

@subsubheading Details

The Hair x Eye table comes rom a survey of students at the University of
Delaware reported by Snee (1974). The split by Sex was added by Friendly
(1992a) for didactic purposes.

This data set is useful for illustrating various techniques for the analysis
of contingency tables, such as the standard chi-squared test or, more
generally, log-linear modelling, and graphical methods such as mosaic plots,
sieve diagrams or association plots.

@subsubheading Source

@url{http://euclid.psych.yorku.ca/ftp/sas/vcd/catdata/haireye.sas}

Snee (1974) gives the two-way table aggregated over Sex. The Sex split of
the ‘Brown hair, Brown eye’ cell was changed to agree with that used by
Friendly (2000).

@subsubheading References

Snee, R. D. (1974). Graphical display of two-way contingency tables.
@cite{The American Statistician}, 28, 9–12.

Friendly, M. (1992a). Graphical methods for categorical data. @cite{SAS User
Group International Conference Proceedings}, 17, 190–200.
@url{http://www.math.yorku.ca/SCS/sugi/sugi17-paper.html}

Friendly, M. (1992b). Mosaic displays for loglinear models. @cite{Proceedings
of the Statistical Graphics Section}, American Statistical Association, pp.
61–68. @url{http://www.math.yorku.ca/SCS/Papers/asa92.html}

Friendly, M. (2000). @cite{Visualizing Categorical Data}. SAS Institute,
ISBN 1-58025-660-0.

@subsubheading Examples

@example
tblish.dataset.HairEyeColor

# TODO: Aggregate over sex and display a table of counts

# TODO: Port mosaic plot to Octave

@end example


@end deftypefn

@node tblish.dataset.Harman23cor
@subsubsection tblish.dataset.Harman23cor

@deftypefn {Static Method} {@var{out} =} Harman23cor ()

Harman Example 2.3

@subsubheading Description

A correlation matrix of eight physical measurements on 305 girls between
ages seven and seventeen.

@subsubheading Format

@table @code
@item cov
An 8-by-8 correlation matrix.
@item names
Names of the variables corresponding to the indexes of the correlation matrix’s
dimensions.
@end table

@subsubheading Source

Harman, H. H. (1976). @cite{Modern Factor Analysis}, Third Edition Revised.
Chicago: University of Chicago Press. Table 2.3.

@subsubheading Examples

@example
tblish.dataset.Harman23cor;

# TODO: Port factanal to Octave

@end example


@end deftypefn

@node tblish.dataset.Harman74cor
@subsubsection tblish.dataset.Harman74cor

@deftypefn {Static Method} {@var{out} =} Harman74cor ()

Harman Example 7.4

@subsubheading Description

A correlation matrix of 24 psychological tests given to 145 seventh and
eighth-grade children in a Chicago suburb by Holzinger and Swineford.

@subsubheading Format

@table @code
@item cov
A 2-dimensional correlation matrix.
@item vars
Names of the variables corresponding to the indexes along the dimensions of
@code{cov}.
@end table

@subsubheading Source

Harman, H. H. (1976). @cite{Modern Factor Analysis}, Third Edition
Revised. Chicago: University of Chicago Press. Table 7.4.

@subsubheading Examples

@example
tblish.dataset.Harman74cor;

# TODO: Port factanal to Octave

@end example


@end deftypefn

@node tblish.dataset.Indometh
@subsubsection tblish.dataset.Indometh

@deftypefn {Static Method} {@var{out} =} Indometh ()

Pharmacokinetics of Indomethacin

@subsubheading Description

Data on the pharmacokinetics of indometacin (or, older spelling,
‘indomethacin’).

@subsubheading Format

@table @code
@item Subject
Subject identifier.
@item time
Time since drug administration at which samples were drawn (hours).
@item conc
Plasma concentration of indomethacin (mcg/ml).
@end table

@subsubheading Details

Each of the six subjects were given an intravenous injection of indometacin.

@subsubheading Source

Kwan, Breault, Umbenhauer, McMahon and Duggan (1976). Kinetics of
Indomethacin absorption, elimination, and enterohepatic circulation in man.
@cite{Journal of Pharmacokinetics and Biopharmaceutics} 4, 255–280.

Davidian, M. and Giltinan, D. M. (1995). @cite{Nonlinear Models for Repeated
Measurement Data}. London: Chapman & Hall. (section 5.2.4, p. 129)

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models in S and
S-PLUS}. New York: Springer.


@end deftypefn

@node tblish.dataset.infert
@subsubsection tblish.dataset.infert

@deftypefn {Static Method} {@var{out} =} infert ()

Infertility after Spontaneous and Induced Abortion

@subsubheading Description

This is a matched case-control study dating from before the availability of
conditional logistic regression.

@subsubheading Format

@table @code
@item education
Index of the record.
@item age
Age in years of case.
@item parity
Count.
@item induced
Number of prior induced abortions, grouped into “0”, “1”, or “2 or more”.
@item case_status
0 = control, 1 = case.
@item spontaneous
Number of prior spontaneous abortions, grouped into “0”, “1”, or “2 or more”.
@item stratum
Matched set number.
@item pooled_stratum
Stratum number.
@end table

@subsubheading Note

One case with two prior spontaneous abortions and two prior induced abortions is omitted.

@subsubheading Source

Trichopoulos et al (1976). @cite{Br. J. of Obst. and Gynaec.} 83, 645–650.

@subsubheading Examples

@example
t = tblish.dataset.infert;

# TODO: Port glm() (generalized linear model) stuff to Octave

@end example


@end deftypefn

@node tblish.dataset.InsectSprays
@subsubsection tblish.dataset.InsectSprays

@deftypefn {Static Method} {@var{out} =} InsectSprays ()

Effectiveness of Insect Sprays

@subsubheading Description

The counts of insects in agricultural experimental units treated with different
insecticides.

@subsubheading Format

@table @code
@item spray
The type of spray.
@item count
Insect count.
@end table

@subsubheading Source

Beall, G., (1942). The Transformation of data from entomological field
experiments. @cite{Biometrika}, 29, 243–262.

@subsubheading References

McNeil, D. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.InsectSprays;

# TODO: boxplot

# TODO: AOV plots

@end example


@end deftypefn

@node tblish.dataset.iris
@subsubsection tblish.dataset.iris

@deftypefn {Static Method} {@var{out} =} iris ()

The Fisher Iris dataset: measurements of various flowers

@subsubheading Description

This is the classic Fisher Iris dataset.

@subsubheading Format

@table @code
@item Species
The species of flower being measured.
@item SepalLength
Length of sepals, in centimeters.
@item SepalWidth
Width of sepals, in centimeters.
@item PetalLength
Length of petals, in centimeters.
@item PetalWidth
Width of petals, in centimeters.
@end table

@subsubheading Source

@url{http://archive.ics.uci.edu/ml/datasets/Iris}

@subsubheading References

@url{https://en.wikipedia.org/wiki/Iris_flower_data_set}

Fisher, R. A. (1936). The use of multiple measurements in taxonomic problems.
Annals of Eugenics, 7, Part II, 179-188. also in @cite{Contributions
to Mathematical Statistics} (John Wiley, NY, 1950).

Duda, R.O., & Hart, P.E. (1973). @cite{Pattern Classification and Scene Analysis}.
(Q327.D83) New York: John Wiley & Sons. ISBN 0-471-22361-1. See page 218.

The data were collected by Anderson, Edgar (1935). The irises of the Gaspe
Peninsula. @cite{Bulletin of the American Iris Society}, 59, 2–5.

@subsubheading Examples

@example
# TODO: Port this example from R

@end example

@end deftypefn

@node tblish.dataset.islands
@subsubsection tblish.dataset.islands

@deftypefn {Static Method} {@var{out} =} islands ()

Areas of the World's Major Landmasses

@subsubheading Description

The areas in thousands of square miles of the landmasses which exceed 10,000
square miles.

@subsubheading Format

@table @code
@item name
The name of the island.
@item area
The area, in thousands of square miles.
@end table

@subsubheading Source

@cite{The World Almanac and Book of Facts}, 1975, page 406.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.islands;

# TODO: Port dot chart to Octave

@end example


@end deftypefn

@node tblish.dataset.JohnsonJohnson
@subsubsection tblish.dataset.JohnsonJohnson

@deftypefn {Static Method} {@var{out} =} JohnsonJohnson ()

Quarterly Earnings per Johnson & Johnson Share

@subsubheading Description

Quarterly earnings (dollars) per Johnson & Johnson share 1960–80.

@subsubheading Format

@table @code
@item date
Start date of the quarter.
@item earnings
Earnings per share (USD).
@end table

@subsubheading Source

Shumway, R. H. and Stoffer, D. S. (2000). @cite{Time Series Analysis and its
Applications}. Second Edition. New York: Springer. Example 1.1.

@subsubheading Examples

@example
t = tblish.dataset.JohnsonJohnson

# TODO: Yikes, look at all those plots. Port them to Octave.

@end example


@end deftypefn

@node tblish.dataset.LakeHuron
@subsubsection tblish.dataset.LakeHuron

@deftypefn {Static Method} {@var{out} =} LakeHuron ()

Level of Lake Huron 1875-1972

@subsubheading Description

Annual measurements of the level, in feet, of Lake Huron 1875–1972.

@subsubheading Format

@table @code
@item year
Year of the measurement
@item level
Lake level (ft).
@end table

@subsubheading Source

Brockwell, P. J. and Davis, R. A. (1991). @cite{Time Series and Forecasting
Methods}. Second edition. New York: Springer. Series A, page 555.

Brockwell, P. J. and Davis, R. A. (1996). @cite{Introduction to Time Series
and Forecasting}. New York: Springer. Sections 5.1 and 7.6.

@subsubheading Examples

@example
t = tblish.dataset.LakeHuron;

plot (t.year, t.level)
xlabel ("Year")
ylabel ("Lake level (ft)")
title ("Level of Lake Huron")

@end example


@end deftypefn

@node tblish.dataset.lh
@subsubsection tblish.dataset.lh

@deftypefn {Static Method} {@var{out} =} lh ()

Luteinizing Hormone in Blood Samples

@subsubheading Description

A regular time series giving the luteinizing hormone in blood samples at 10
minute intervals from a human female, 48 samples.

@subsubheading Format

@table @code
@item sample
The number of the observation.
@item lh
Level of luteinizing hormone.
@end table

@subsubheading Source

P.J. Diggle (1990). @cite{Time Series: A Biostatistical Introduction}. Oxford.
Table A.1, series 3.

@subsubheading Examples

@example
t = tblish.dataset.lh;

plot (t.sample, t.lh);
xlabel ("Sample Number");
ylabel ("lh level");

@end example


@end deftypefn

@node tblish.dataset.LifeCycleSavings
@subsubsection tblish.dataset.LifeCycleSavings

@deftypefn {Static Method} {@var{out} =} LifeCycleSavings ()

Intercountry Life-Cycle Savings Data

@subsubheading Description

Data on the savings ratio 1960–1970.

@subsubheading Format

@table @code
@item country
Name of the country.
@item sr
Aggregate personal savings.
@item pop15
Percentage of population under 15.
@item pop75
Percentage of population over 75.
@item dpi
Real per-capita disposable income.
@item ddpi
Percent growth rate of dpi.
@end table

@subsubheading Details

Under the life-cycle savings hypothesis as developed by Franco Modigliani, the
savings ratio (aggregate personal saving divided by disposable income) is
explained by per-capita disposable income, the percentage rate of change in
per-capita disposable income, and two demographic variables: the percentage
of population less than 15 years old and the percentage of the population over
75 years old. The data are averaged over the decade 1960–1970 to remove the
business cycle or other short-term fluctuations.

@subsubheading Source

The data were obtained from Belsley, Kuh and Welsch (1980). They in turn
obtained the data from Sterling (1977).

@subsubheading References

Sterling, Arnie (1977). Unpublished BS Thesis. Massachusetts Institute of
Technology.

Belsley, D. A., Kuh. E. and Welsch, R. E. (1980). @cite{Regression Diagnostics}.
New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.LifeCycleSavings;

# TODO: linear model

# TODO: pairs plot with Lowess smoothed line

@end example


@end deftypefn

@node tblish.dataset.Loblolly
@subsubsection tblish.dataset.Loblolly

@deftypefn {Static Method} {@var{out} =} Loblolly ()

Growth of Loblolly pine trees

@subsubheading Description

Records of the growth of Loblolly pine trees.

@subsubheading Format

@table @code
@item height
Tree height (ft).
@item age
Tree age (years).
@item Seed
Seed source for the tree. Ordering is according to increasing maximum height.
@end table

@subsubheading Source

Kung, F. H. (1986). Fitting logistic growth curve with predetermined carrying
capacity. @cite{Proceedings of the Statistical Computing Section}, American
Statistical Association, 340–343.

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models in S and
S-PLUS}. New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.Loblolly;

t2 = t(t.Seed == "329",:);
scatter (t2.age, t2.height)
xlabel ("Tree age (yr)");
ylabel ("Tree height (ft)");
title ("Loblolly data and fitted curve (Seed 329 only)")

# TODO: Compute and plot fitted curve

@end example


@end deftypefn

@node tblish.dataset.longley
@subsubsection tblish.dataset.longley

@deftypefn {Static Method} {@var{out} =} longley ()

Longley’s Economic Regression Data

@subsubheading Description

A macroeconomic data set which provides a well-known example for a highly
collinear regression.

@subsubheading Format

@table @code
@item Year
The year.
@item GNP_deflator
GNP implicit price deflator (1954=100).
@item GNP
Gross National Product.
@item Unemployed
Number of unemployed.
@item Armed_Forces
Number of people in the armed forces.
@item Population
“Noninstitutionalized” population ≥ 14 years of age.
@item Employed
Number of people employed.
@end table

@subsubheading Source

J. W. Longley (1967). An appraisal of least-squares programs from the point of
view of the user. @cite{Journal of the American Statistical Association}, 62,
819–841.

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

@subsubheading Examples

@example
t = tblish.dataset.longley;

# TODO: Linear model
# TODO: opar plot

@end example


@end deftypefn

@node tblish.dataset.lynx
@subsubsection tblish.dataset.lynx

@deftypefn {Static Method} {@var{out} =} lynx ()

Annual Canadian Lynx trappings 1821-1934

@subsubheading Description

Annual numbers of lynx trappings for 1821–1934 in Canada. Taken from Brockwell
& Davis (1991), this appears to be the series considered by Campbell & Walker
(1977).

@subsubheading Format

@table @code
@item year
Year of the record.
@item lynx
Number of lynx trapped.
@end table

@subsubheading Source

Brockwell, P. J. and Davis, R. A. (1991). @cite{Time Series and Forecasting
Methods}. Second edition. New York: Springer. Series G (page 557).

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

Campbell, M. J. and Walker, A. M. (1977). A Survey of statistical work on
the Mackenzie River series of annual Canadian lynx trappings for the years
1821–1934 and a new analysis. @cite{Journal of the Royal Statistical Society
series A}, 140, 411–431.

@subsubheading Examples

@example
t = tblish.dataset.lynx;

plot (t.year, t.lynx);
xlabel ("Year");
ylabel ("Lynx Trapped");

@end example


@end deftypefn

@node tblish.dataset.morley
@subsubsection tblish.dataset.morley

@deftypefn {Static Method} {@var{out} =} morley ()

Michelson Speed of Light Data

@subsubheading Description

A classical data of Michelson (but not this one with Morley) on measurements
done in 1879 on the speed of light. The data consists of five experiments,
each consisting of 20 consecutive ‘runs’. The response is the speed of
light measurement, suitably coded (km/sec, with 299000 subtracted).

@subsubheading Format

@table @code
@item Expt
The experiment number, from 1 to 5.
@item Run
The run number within each experiment.
@item Speed
Speed-of-light measurement.
@end table

@subsubheading Details

The data is here viewed as a randomized block experiment with @code{experiment}
and @code{run} as the factors. @code{run} may also be considered a quantitative
variate to account for linear (or polynomial) changes in the measurement over
the course of a single experiment.

@subsubheading Source

A. J. Weekes (1986). @cite{A Genstat Primer}. London: Edward Arnold.

S. M. Stigler (1977). Do robust estimators work with real data? @cite{Annals
of Statistics} 5, 1055–1098. (See Table 6.)

A. A. Michelson (1882). Experimental determination of the velocity of
light made at the United States Naval Academy, Annapolis. @cite{Astronomic
Papers}, 1, 135–8. U.S. Nautical Almanac Office. (See Table 24.).

@subsubheading Examples

@example
t = tblish.dataset.morley;

# TODO: Port to Octave

@end example


@end deftypefn

@node tblish.dataset.mtcars
@subsubsection tblish.dataset.mtcars

@deftypefn {Static Method} {@var{out} =} mtcars ()

Motor Trend 1974 Car Road Tests

@subsubheading Description

The data was extracted from the 1974 Motor Trend US magazine, and
comprises fuel consumption and 10 aspects of automobile design and
performance for 32 automobiles (1973–74 models).

@subsubheading Format

@table @code
@item mpg
Fuel efficiency in miles/gallon
@item cyl
Number of cylinders
@item disp
Displacement (cu. in.)
@item hp
Gross horsepower
@item drat
Rear axle ratio
@item wt
Weight (1,000 lbs)
@item qsec
1/4 mile time
@item vs
Engine type (0 = V-shaped, 1 = straight)
@item am
Transmission type (0 = automatic, 1 = manual)
@item gear
Number of forward gears
@item carb
Number of carburetors
@end table

@subsubheading Note

Henderson and Velleman (1981) comment in a footnote to Table 1: “Hocking
[original transcriber]’s noncrucial coding of the Mazda’s rotary engine
as a straight six-cylinder engine and the Porsche’s flat engine as a V
engine, as well as the inclusion of the diesel Mercedes 240D, have been
retained to enable direct comparisons to be made with previous analyses.”

@subsubheading Source

Henderson and Velleman (1981). Building multiple regression models
interactively. @cite{Biometrics}, 37, 391–411.

@subsubheading Examples

@example
# TODO: Port this example from R
@end example

@end deftypefn

@node tblish.dataset.nhtemp
@subsubsection tblish.dataset.nhtemp

@deftypefn {Static Method} {@var{out} =} nhtemp ()

Average Yearly Temperatures in New Haven

@subsubheading Description

The mean annual temperature in degrees Fahrenheit in New Haven, Connecticut,
from 1912 to 1971.

@subsubheading Format

@table @code
@item year
Year of the observation.
@item temp
Mean annual temperature (degrees F).
@end table

@subsubheading Source

Vaux, J. E. and Brinker, N. B. (1972) @cite{Cycles}, 1972, 117–121.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.nhtemp;

plot (t.year, t.temp);
title ("nhtemp data");
xlabel ("Mean annual temperature in New Haven, CT (deg. F)");

@end example


@end deftypefn

@node tblish.dataset.Nile
@subsubsection tblish.dataset.Nile

@deftypefn {Static Method} {@var{out} =} Nile ()

Flow of the River Nile

@subsubheading Description

Measurements of the annual flow of the river Nile at Aswan (formerly Assuan),
1871–1970, in m^3, “with apparent changepoint near 1898”
(Cobb(1978), Table 1, p.249).

@subsubheading Format

@table @code
@item year
Year of the record.
@item flow
Annual flow (cubic meters).
@end table

@subsubheading Source

Durbin, J. and Koopman, S. J. (2001). @cite{Time Series Analysis by State
Space Methods}. Oxford: Oxford University Press. @url{http://www.ssfpack.com/DKbook.html}

@subsubheading References

Balke, N. S. (1993). Detecting level shifts in time series. @cite{Journal of
Business and Economic Statistics}, 11, 81–92.

Cobb, G. W. (1978). The problem of the Nile: conditional solution to a
change-point problem. @cite{Biometrika} 65, 243–51.

@subsubheading Examples

@example
t = tblish.dataset.Nile;

figure
plot (t.year, t.flow);

# TODO: Port the rest of the example to Octave

@end example


@end deftypefn

@node tblish.dataset.nottem
@subsubsection tblish.dataset.nottem

@deftypefn {Static Method} {@var{out} =} nottem ()

Average Monthly Temperatures at Nottingham, 1920-1939

@subsubheading Description

A time series object containing average air temperatures at
Nottingham Castle in degrees Fahrenheit for 20 years.

@subsubheading Format

@table @code
@item record
Index of the record.
@item lead
Leading indicator.
@item sales
Sales volume.
@end table

@subsubheading Source

Anderson, O. D. (1976). @cite{Time Series Analysis and Forecasting:
The Box-Jenkins approach}. London: Butterworths. Series R.

@subsubheading Examples

@example
# TODO: Come up with example code here

@end example


@end deftypefn

@node tblish.dataset.npk
@subsubsection tblish.dataset.npk

@deftypefn {Static Method} {@var{out} =} npk ()

Classical N, P, K Factorial Experiment

@subsubheading Description

A classical N, P, K (nitrogen, phosphate, potassium) factorial experiment
on the growth of peas conducted on 6 blocks. Each half of a fractional
factorial design confounding the NPK interaction was used on 3 of the plots.

@subsubheading Format

@table @code
@item block
Which block (1 to 6).
@item N
Indicator (0/1) for the application of nitrogen.
@item P
Indicator (0/1) for the application of phosphate.
@item K
Indicator (0/1) for the application of potassium.
@item yield
Yield of peas, in pounds/plot. Plots were 1/70 acre.
@end table

@subsubheading Source

Imperial College, London, M.Sc. exercise sheet.

@subsubheading References

Venables, W. N. and Ripley, B. D. (2002). @cite{Modern Applied Statistics
with S}. Fourth edition. New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.npk;

# TODO: Port aov() and LM to Octave

@end example


@end deftypefn

@node tblish.dataset.occupationalStatus
@subsubsection tblish.dataset.occupationalStatus

@deftypefn {Static Method} {@var{out} =} occupationalStatus ()

Occupational Status of Fathers and their Sons

@subsubheading Description

Cross-classification of a sample of British males according to each subject’s
occupational status and his father’s occupational status.

@subsubheading Format

An 8-by-8 matrix of counts, with classifying fators @code{origin} (father’s
occupational status, levels 1:8) and @code{destination} (son’s
occupational status, levels 1:8).

@subsubheading Source

Goodman, L. A. (1979). Simple Models for the Analysis of Association in
Cross-Classifications having Ordered Categories. @cite{J. Am. Stat.
Assoc.}, 74 (367), 537–552.

@subsubheading Examples

@example
# TODO: Come up with example code here

@end example


@end deftypefn

@node tblish.dataset.Orange
@subsubsection tblish.dataset.Orange

@deftypefn {Static Method} {@var{out} =} Orange ()

Growth of Orange Trees

@subsubheading Description

Records of the growth of orange trees.

@subsubheading Format

@table @code
@item Tree
A categorical indicating on which tree the measurement is made.
Ordering is according to increasing maximum diameter.
@item age
Age of the tree (days since 1968-12-31).
@item circumference
Trunk circumference (mm).
This is probably “circumference at breast height”, a standard measurement in forestry.
@end table

@subsubheading Source

The data are given in Box & Jenkins (1976). Obtained from the Time Series Data
Library at @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/}.

@subsubheading References

Draper, N. R. and Smith, H. (1998). @cite{Applied Regression Analysis (3rd ed)}.
New York: Wiley. (exercise 24.N).

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models in S and
S-PLUS}. New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.Orange;

# TODO: Port coplot to Octave

# TODO: Linear model

@end example


@end deftypefn

@node tblish.dataset.OrchardSprays
@subsubsection tblish.dataset.OrchardSprays

@deftypefn {Static Method} {@var{out} =} OrchardSprays ()

Potency of Orchard Sprays

@subsubheading Description

An experiment was conducted to assess the potency of various constituents
of orchard sprays in repelling honeybees, using a Latin square design.

@subsubheading Format

@table @code
@item rowpos
Row of the design.
@item colpos
Column of the design
@item treatment
Treatment level.
@item decrease
Response.
@end table

@subsubheading Details

Individual cells of dry comb were filled with measured amounts of lime
sulphur emulsion in sucrose solution. Seven different concentrations of lime
sulphur ranging from a concentration of 1/100 to 1/1,562,500 in successive
factors of 1/5 were used as well as a solution containing no lime sulphur.

The responses for the different solutions were obtained by releasing 100
bees into the chamber for two hours, and then measuring the decrease in volume
of the solutions in the various cells.

An 8 x 8 Latin square design was used and the treatments were coded as follows:

A – highest level of lime sulphur
B – next highest level of lime sulphur
@dots{}
G – lowest level of lime sulphur
H – no lime sulphur

@subsubheading Source

Finney, D. J. (1947). @cite{Probit Analysis}. Cambridge.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.OrchardSprays;

tblish.examples.plot_pairs (t);

@end example


@end deftypefn

@node tblish.dataset.PlantGrowth
@subsubsection tblish.dataset.PlantGrowth

@deftypefn {Static Method} {@var{out} =} PlantGrowth ()

Results from an Experiment on Plant Growth

@subsubheading Description

Results from an experiment to compare yields (as measured by dried weight of
plants) obtained under a control and two different treatment conditions.

@subsubheading Format

@table @code
@item group
Treatment condition group.
@item weight
Weight of plants.
@end table

@subsubheading Source

Dobson, A. J. (1983). @cite{An Introduction to Statistical Modelling}.
London: Chapman and Hall.

@subsubheading Examples

@example
t = tblish.dataset.PlantGrowth;

# TODO: Port anova to Octave

@end example


@end deftypefn

@node tblish.dataset.precip
@subsubsection tblish.dataset.precip

@deftypefn {Static Method} {@var{out} =} precip ()

Annual Precipitation in US Cities

@subsubheading Description

The average amount of precipitation (rainfall) in inches for each of 70 United
States (and Puerto Rico) cities.

@subsubheading Format

@table @code
@item city
City observed.
@item precip
Annual precipitation (in).
@end table

@subsubheading Source

@cite{Statistical Abstracts of the United States}, 1975.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.precip;

# TODO: Port dot plot to Octave

@end example


@end deftypefn

@node tblish.dataset.presidents
@subsubsection tblish.dataset.presidents

@deftypefn {Static Method} {@var{out} =} presidents ()

Quarterly Approval Ratings of US Presidents

@subsubheading Description

The (approximately) quarterly approval rating for the President of the United
States from the first quarter of 1945 to the last quarter of 1974.

@subsubheading Format

@table @code
@item date
Approximate date of the observation.
@item approval
Approval rating (%).
@end table

@subsubheading Details

The data are actually a fudged version of the approval ratings. See McNeil’s book
for details.

@subsubheading Source

The Gallup Organisation.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.presidents;

figure
plot (datenum (t.date), t.approval)
datetick ("x")
xlabel ("Date")
ylabel ("Approval rating (%)")
title ("presidents data")

@end example


@end deftypefn

@node tblish.dataset.pressure
@subsubsection tblish.dataset.pressure

@deftypefn {Static Method} {@var{out} =} pressure ()

Vapor Pressure of Mercury as a Function of Temperature

@subsubheading Description

Data on the relation between temperature in degrees Celsius and vapor pressure
of mercury in millimeters (of mercury).

@subsubheading Format

@table @code
@item temperature
Temperature (deg C).
@item pressure
Pressure (mm Hg).
@end table

@subsubheading Source

Weast, R. C., ed. (1973). @cite{Handbook of Chemistry and Physics}. Cleveland: CRC Press.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.pressure;

figure
plot (t.temperature, t.pressure)
xlabel ("Temperature (deg C)")
ylabel ("Pressure (mm of Hg)")
title ("pressure data: Vapor Pressure of Mercury")

figure
semilogy (t.temperature, t.pressure)
xlabel ("Temperature (deg C)")
ylabel ("Pressure (mm of Hg)")
title ("pressure data: Vapor Pressure of Mercury")


@end example


@end deftypefn

@node tblish.dataset.Puromycin
@subsubsection tblish.dataset.Puromycin

@deftypefn {Static Method} {@var{out} =} Puromycin ()

Reaction Velocity of an Enzymatic Reaction

@subsubheading Description

Reaction velocity versus substrate concentration in an enzymatic reaction
involving untreated cells or cells treated with Puromycin.

@subsubheading Format

@table @code
@item state
Whether the cell was treated.
@item conc
Substrate concentrations (ppm).
@item rate
Instantaneous reaction rates (counts/min/min).
@end table

@subsubheading Details

Data on the velocity of an enzymatic reaction were obtained by Treloar
(1974). The number of counts per minute of radioactive product from the
reaction was measured as a function of substrate concentration in parts per
million (ppm) and from these counts the initial rate (or velocity) of the
reaction was calculated (counts/min/min). The experiment was conducted once
with the enzyme treated with Puromycin, and once with the enzyme untreated.

@subsubheading Source

The data are given in Box & Jenkins (1976). Obtained from the Time Series Data
Library at @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/}.

@subsubheading References

Bates, D.M. and Watts, D.G. (1988). @cite{Nonlinear Regression Analysis and
Its Applications}. New York: Wiley. Appendix A1.3.

Treloar, M. A. (1974). @cite{Effects of Puromycin on Galactosyltransferase
in Golgi Membranes}. M.Sc. Thesis, U. of Toronto.

@subsubheading Examples

@example
t = tblish.dataset.Puromycin;

# TODO: Port example to Octave

@end example


@end deftypefn

@node tblish.dataset.quakes
@subsubsection tblish.dataset.quakes

@deftypefn {Static Method} {@var{out} =} quakes ()

Locations of Earthquakes off Fiji

@subsubheading Description

The data set give the locations of 1000 seismic events of MB > 4.0. The events
occurred in a cube near Fiji since 1964.

@subsubheading Format

@table @code
@item lat
Latitude of event.
@item long
Longitude of event.
@item depth
Depth (km).
@item mag
Richter magnitude.
@item stations
Number of stations reporting.
@end table

@subsubheading Details

There are two clear planes of seismic activity. One is a major plate junction;
the other is the Tonga trench off New Zealand. These data constitute a subsample
from a larger dataset of containing 5000 observations.

@subsubheading Source

This is one of the Harvard PRIM-H project data sets. They in turn obtained it
from Dr. John Woodhouse, Dept. of Geophysics, Harvard University.

@subsubheading References

G. E. P. Box and G. M. Jenkins (1976). @cite{Time Series Analysis, Forecasting and
Control}. San Francisco: Holden-Day. p. 537.

P. J. Brockwell and R. A. Davis (1991). @cite{Time Series: Theory and Methods}.
Second edition. New York: Springer-Verlag. p. 414.

@subsubheading Examples

@example
# TODO: Come up with example code here

@end example


@end deftypefn

@node tblish.dataset.randu
@subsubsection tblish.dataset.randu

@deftypefn {Static Method} {@var{out} =} randu ()

Random Numbers from Congruential Generator RANDU

@subsubheading Description

400 triples of successive random numbers were taken from the VAX FORTRAN
function RANDU running under VMS 1.5.

@subsubheading Format

@table @code
@item record
Index of the record.
@item x
X value of the triple.
@item y
Y value of the triple.
@item z
Z value of the triple.
@end table

@subsubheading Details

In three dimensional displays it is evident that the triples fall on 15
parallel planes in 3-space. This can be shown theoretically to be true
for all triples from the RANDU generator.

These particular 400 triples start 5 apart in the sequence, that is they
are ((U[5i+1], U[5i+2], U[5i+3]), i= 0, ..., 399), and they are rounded
to 6 decimal places.

Under VMS versions 2.0 and higher, this problem has been fixed.

@subsubheading Source

David Donoho

@subsubheading Examples

@example
t = tblish.dataset.randu;


@end example


@end deftypefn

@node tblish.dataset.rivers
@subsubsection tblish.dataset.rivers

@deftypefn {Static Method} {@var{out} =} rivers ()

Lengths of Major North American Rivers

@subsubheading Description

This data set gives the lengths (in miles) of 141 “major” rivers in North
America, as compiled by the US Geological Survey.

@subsubheading Format

@table @code
@item rivers
A vector containing 141 observations.
@end table

@subsubheading Source

@cite{World Almanac and Book of Facts}, 1975, page 406.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
tblish.dataset.rivers;

longest_river = max (rivers)
shortest_river = min (rivers)

@end example


@end deftypefn

@node tblish.dataset.rock
@subsubsection tblish.dataset.rock

@deftypefn {Static Method} {@var{out} =} rock ()

Measurements on Petroleum Rock Samples

@subsubheading Description

Measurements on 48 rock samples from a petroleum reservoir.

@subsubheading Format

@table @code
@item area
Area of pores space, in pixels out of 256 by 256.
@item peri
Perimeter in pixels.
@item shape
Perimeter/sqrt(area).
@item perm
Permeability in milli-Darcies.
@end table

@subsubheading Details

Twelve core samples from petroleum reservoirs were sampled by 4
cross-sections. Each core sample was measured for permeability, and each
cross-section has total area of pores, total perimeter of pores, and shape.

@subsubheading Source

Data from BP Research, image analysis by Ronit Katz, U. Oxford.

@subsubheading Examples

@example
t = tblish.dataset.rock;

figure
scatter (t.area, t.perm)
xlabel ("Area of pores space (pixels out of 256x256)")
ylabel ("Permeability (milli-Darcies)")

@end example


@end deftypefn

@node tblish.dataset.sleep
@subsubsection tblish.dataset.sleep

@deftypefn {Static Method} {@var{out} =} sleep ()

Student’s Sleep Data

@subsubheading Description

Data which show the effect of two soporific drugs (increase in hours of sleep
compared to control) on 10 patients.

@subsubheading Format

@table @code
@item id
Patient ID.
@item group
Drug given.
@item extra
Increase in hours of sleep.
@end table

@subsubheading Details

The @code{group} variable name may be misleading about the data: They
represent measurements on 10 persons, not in groups.

@subsubheading Source

Cushny, A. R. and Peebles, A. R. (1905). The action of optical isomers:
II hyoscines. @cite{The Journal of Physiology}, 32, 501–510.

Student (1908). The probable error of the mean. @cite{Biometrika}, 6, 20.

@subsubheading References

Scheffé, Henry (1959). @cite{The Analysis of Variance}. New York, NY: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.sleep;

# TODO: Port to Octave

@end example


@end deftypefn

@node tblish.dataset.stackloss
@subsubsection tblish.dataset.stackloss

@deftypefn {Static Method} {@var{out} =} stackloss ()

Brownlee's Stack Loss Plant Data

@subsubheading Description

Operational data of a plant for the oxidation of ammonia to nitric acid.

@subsubheading Format

@table @code
@item AirFlow
Flow of cooling air.
@item WaterTemp
Cooling Water Inlet temperature.
@item AcidConc
Concentration of acid (per 1000, minus 500).
@item StackLoss
Stack loss
@end table

@subsubheading Details

“Obtained from 21 days of operation of a plant for the oxidation of ammonia
(NH3) to nitric acid (HNO3). The nitric oxides produced are absorbed in a
countercurrent absorption tower”. (Brownlee, cited by Dodge, slightly reformatted by MM.)

@code{AirFlow} represents the rate of operation of the plant. @code{WaterTemp} is the
temperature of cooling water circulated through coils in the absorption tower.
@code{AcidConc} is the concentration of the acid circulating, minus 50, times 10:
that is, 89 corresponds to 58.9 per cent acid. @code{StackLoss} (the dependent variable)
is 10 times the percentage of the ingoing ammonia to the plant that escapes from
the absorption column unabsorbed; that is, an (inverse) measure of the over-all
efficiency of the plant.

@subsubheading Source

Brownlee, K. A. (1960, 2nd ed. 1965). @cite{Statistical Theory and Methodology
in Science and Engineering}. New York: Wiley. pp. 491–500.

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

Dodge, Y. (1996). The guinea pig of multiple regression. In: @cite{Robust
Statistics, Data Analysis, and Computer Intensive Methods; In Honor of
Peter Huber’s 60th Birthday}, 1996, @cite{Lecture Notes in Statistics}
109, Springer-Verlag, New York.

@subsubheading Examples

@example
t = tblish.dataset.stackloss;

# TODO: Create linear model and print summary

@end example


@end deftypefn

@node tblish.dataset.state
@subsubsection tblish.dataset.state

@deftypefn {Static Method} {@var{out} =} state ()

US State Facts and Figures

@subsubheading Description

Data related to the 50 states of the United States of America.

@subsubheading Format

@table @code
@item abb
State abbreviation.
@item name
State name.
@item area
Area (sq mi).
@item lat
Approximate center (latitude).
@item lon
Approximate center (longitude).
@item division
State division.
@item revion
State region.
@item Population
Population estimate as of July 1, 1975.
@item Income
Per capita income (1974).
@item Illiteracy
Illiteracy as of 1970 (percent of population).
@item LifeExp
Lfe expectancy in years (1969-71).
@item Murder
Murder and non-negligent manslaughter rate per 100,000 population (1976).
@item HSGrad
Percent high-school graduates (1970).
@item Frost
Mean number of days with minimum temperature below freezing (1931-1960)
in capital or large city.
@end table

@subsubheading Source

U.S. Department of Commerce, Bureau of the Census (1977) @cite{Statistical
Abstract of the United States}.

U.S. Department of Commerce, Bureau of the Census (1977) @cite{County
and City Data Book}.

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

@subsubheading Examples

@example
t = tblish.dataset.state;

@end example


@end deftypefn

@node tblish.dataset.sunspot_month
@subsubsection tblish.dataset.sunspot_month

@deftypefn {Static Method} {@var{out} =} sunspot_month ()

Monthly Sunspot Data, from 1749 to “Present”

@subsubheading Description

Monthly numbers of sunspots, as from the World Data Center, aka SIDC. This
is the version of the data that may occasionally be updated when new counts
become available.

@subsubheading Format

@table @code
@item month
Month of the observation.
@item sunspots
Number of sunspots.
@end table

@subsubheading Source

WDC-SILSO, Solar Influences Data Analysis Center (SIDC), Royal Observatory
of Belgium, Av. Circulaire, 3, B-1180 BRUSSELS.
Currently at @url{http://www.sidc.be/silso/datafiles}.

@subsubheading Examples

@example
t = tblish.dataset.sunspot_month;


@end example


@end deftypefn

@node tblish.dataset.sunspot_year
@subsubsection tblish.dataset.sunspot_year

@deftypefn {Static Method} {@var{out} =} sunspot_year ()

Yearly Sunspot Data, 1700-1988

@subsubheading Description

Yearly numbers of sunspots from 1700 to 1988 (rounded to one digit).

@subsubheading Format

@table @code
@item year
Year of the observation.
@item sunspots
Number of sunspots.
@end table

@subsubheading Source

H. Tong (1996) @cite{Non-Linear Time Series}. Clarendon Press, Oxford, p. 471.

@subsubheading Examples

@example
t = tblish.dataset.sunspot_year;

figure
plot (t.year, t.sunspots)
xlabel ("Year")
ylabel ("Sunspots")

@end example


@end deftypefn

@node tblish.dataset.sunspots
@subsubsection tblish.dataset.sunspots

@deftypefn {Static Method} {@var{out} =} sunspots ()

Monthly Sunspot Numbers, 1749-1983

@subsubheading Description

Monthly mean relative sunspot numbers from 1749 to 1983. Collected at Swiss
Federal Observatory, Zurich until 1960, then Tokyo Astronomical Observatory.

@subsubheading Format

@table @code
@item month
Month of the observation.
@item sunspots
Number of observed sunspots.
@end table

@subsubheading Source

Andrews, D. F. and Herzberg, A. M. (1985) @cite{Data: A Collection
of Problems from Many Fields for the Student and Research Worker}.
New York: Springer-Verlag.

@subsubheading Examples

@example
t = tblish.dataset.sunspots;

figure
plot (datenum (t.month), t.sunspots)
datetick ("x")
xlabel ("Date")
ylabel ("Monthly sunspot numbers")
title ("sunspots data")


@end example


@end deftypefn

@node tblish.dataset.swiss
@subsubsection tblish.dataset.swiss

@deftypefn {Static Method} {@var{out} =} swiss ()

Swiss Fertility and Socioeconomic Indicators (1888) Data

@subsubheading Description

Standardized fertility measure and socio-economic indicators for each of 47
French-speaking provinces of Switzerland at about 1888.

@subsubheading Format

@table @code
@item Fertility
Ig, ‘common standardized fertility measure’.
@item Agriculture
% of males involved in agriculture as occupation.
@item Examination
% draftees receiving highest mark on army examination.
@item Education
% education beyond primary school for draftees.
@item Catholic
% ‘Catholic’ (as opposed to ‘Protestant’).
@item InfantMortality
Live births who live less than 1 year.
@end table

All variables but ‘Fertility’ give proportions of the population.

@subsubheading Source

(paraphrasing Mosteller and Tukey):

Switzerland, in 1888, was entering a period known as the demographic transition;
i.e., its fertility was beginning to fall from the high level typical of
underdeveloped countries.

The data collected are for 47 French-speaking “provinces” at about 1888.

Here, all variables are scaled to [0, 100], where in the original, all but
@code{Catholic} were scaled to [0, 1].

@subsubheading Note

Files for all 182 districts in 1888 and other years have been available at
@url{https://opr.princeton.edu/archive/pefp/switz.aspx}.

They state that variables @code{Examination} and @code{Education} are averages
for 1887, 1888 and 1889.

@subsubheading References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). @cite{The New S
Language}. Monterey: Wadsworth & Brooks/Cole.

@subsubheading Examples

@example
t = tblish.dataset.swiss;

# TODO: Port linear model to Octave

@end example


@end deftypefn

@node tblish.dataset.Theoph
@subsubsection tblish.dataset.Theoph

@deftypefn {Static Method} {@var{out} =} Theoph ()

Pharmacokinetics of Theophylline

@subsubheading Description

An experiment on the pharmacokinetics of theophylline.

@subsubheading Format

@table @code
@item Subject
Categorical identifying the subject on whom the observation was made. The
ordering is by increasing maximum concentration of theophylline observed.
@item Wt
Weight of the subject (kg).
@item Dose
Dose of theophylline administerred orally to the subject (mg/kg).
@item Time
Time since drug administration when the sample was drawn (hr).
@item conc
Theophylline concentration in the sample (mg/L).
@end table

@subsubheading Details

Boeckmann, Sheiner and Beal (1994) report data from a study by Dr. Robert
Upton of the kinetics of the anti-asthmatic drug theophylline. Twelve subjects
were given oral doses of theophylline then serum concentrations were measured
at 11 time points over the next 25 hours.

These data are analyzed in Davidian and Giltinan (1995) and Pinheiro and Bates
(2000) using a two-compartment open pharmacokinetic model, for which a
self-starting model function, SSfol, is available.

@subsubheading Source

The data are given in Box & Jenkins (1976). Obtained from the Time Series Data
Library at @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/}.

@subsubheading References

Boeckmann, A. J., Sheiner, L. B. and Beal, S. L. (1994). @cite{NONMEM Users
Guide: Part V}. NONMEM Project Group, University of California, San Francisco.

Davidian, M. and Giltinan, D. M. (1995). @cite{Nonlinear Models for Repeated
Measurement Data}. London: Chapman & Hall. (section 5.5, p. 145 and section 6.6, p. 176)

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models in
S and S-PLUS}. New York: Springer. (Appendix A.29)

@subsubheading Examples

@example
t = tblish.dataset.Theoph;

# TODO: Coplot
# TODO: Yet another linear model to port to Octave

@end example


@end deftypefn

@node tblish.dataset.Titanic
@subsubsection tblish.dataset.Titanic

@deftypefn {Static Method} {@var{out} =} Titanic ()

Survival of passengers on the Titanic

@subsubheading Description

This data set provides information on the fate of passengers on the fatal
maiden voyage of the ocean liner ‘Titanic’, summarized according to
economic status (class), sex, age and survival.

@subsubheading Format

@code{n} is a 4-dimensional array resulting from cross-tabulating 2201 observations
on 4 variables. The dimensions of the array correspond to the following variables:

@table @code
@item Class
1st, 2nd, 3rd, Cre.
@item Sex
Male, Female.
@item Age
Child, Adult.
@item Survived
No, Yes.
@end table

@subsubheading Details

The sinking of the Titanic is a famous event, and new books are still being
published about it. Many well-known facts—from the proportions of first-class
passengers to the ‘women and children first’ policy, and the fact that that
policy was not entirely successful in saving the women and children in the
third class—are reflected in the survival rates for various classes of
passenger.

These data were originally collected by the British Board of Trade in their
investigation of the sinking. Note that there is not complete agreement among
primary sources as to the exact numbers on board, rescued, or lost.

Due in particular to the very successful film ‘Titanic’, the last years saw a
rise in public interest in the Titanic. Very detailed data about the passengers
is now available on the Internet, at sites such as Encyclopedia Titanica
(@url{https://www.encyclopedia-titanica.org/}).

@subsubheading Source

Dawson, Robert J. MacG. (1995). The ‘Unusual Episode’ Data Revisited.
@cite{Journal of Statistics Education}, 3.

The source provides a data set recording class, sex, age, and survival status
for each person on board of the Titanic, and is based on data originally
collected by the British Board of Trade and reprinted in:

British Board of Trade (1990). @cite{Report on the Loss of the ‘Titanic’
(S.S.)}. British Board of Trade Inquiry Report (reprint). Gloucester,
UK: Allan Sutton Publishing.

@subsubheading Examples

@example
tblish.dataset.Titanic;

# TODO: Port mosaic plot to Octave

# TODO: Check for higher survival rates in children and females

@end example


@end deftypefn

@node tblish.dataset.ToothGrowth
@subsubsection tblish.dataset.ToothGrowth

@deftypefn {Static Method} {@var{out} =} ToothGrowth ()

The Effect of Vitamin C on Tooth Growth in Guinea Pigs

@subsubheading Description

The response is the length of odontoblasts (cells responsible for tooth growth)
in 60 guinea pigs. Each animal received one of three dose levels of vitamin C
(0.5, 1, and 2 mg/day) by one of two delivery methods, orange juice or
ascorbic acid (a form of vitamin C and coded as @code{VC}).

@subsubheading Format

@table @code
@item supp
Supplement type.
@item dose
Dose (mg/day).
@item len
Tooth length.
@end table

@subsubheading Source

C. I. Bliss (1952). @cite{The Statistics of Bioassay}. Academic Press.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

Crampton, E. W. (1947). The growth of the odontoblast of the incisor
teeth as a criterion of vitamin C intake of the guinea pig. @cite{The
Journal of Nutrition}, 33(5), 491–504.

@subsubheading Examples

@example
t = tblish.dataset.ToothGrowth;

tblish.examples.coplot (t, "dose", "len", "supp");

# TODO: Port Lowess smoothing to Octave

@end example


@end deftypefn

@node tblish.dataset.treering
@subsubsection tblish.dataset.treering

@deftypefn {Static Method} {@var{out} =} treering ()

Yearly Treering Data, -6000-1979

@subsubheading Description

Contains normalized tree-ring widths in dimensionless units.

@subsubheading Format

A univariate time series with 7981 observations.

Each tree ring corresponds to one year.

@subsubheading Details

The data were recorded by Donald A. Graybill, 1980, from Gt Basin
Bristlecone Pine 2805M, 3726-11810 in Methuselah Walk, California.

@subsubheading Source

Time Series Data Library: @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/},
series ‘CA535.DAT’.

@subsubheading References

For some photos of Methuselah Walk see
@url{https://web.archive.org/web/20110523225828/http://www.ltrr.arizona.edu/~hallman/sitephotos/meth.html}.

@subsubheading Examples

@example
t = tblish.dataset.treering;

@end example


@end deftypefn

@node tblish.dataset.trees
@subsubsection tblish.dataset.trees

@deftypefn {Static Method} {@var{out} =} trees ()

Diameter, Height and Volume for Black Cherry Trees

@subsubheading Description

This data set provides measurements of the diameter, height and volume of
timber in 31 felled black cherry trees. Note that the diameter (in inches)
is erroneously labelled Girth in the data. It is measured at 4 ft 6 in
above the ground.

@subsubheading Format

@table @code
@item Girth
Tree diameter (rather than girth, actually) in inches.
@item Height
Height in ft.
@item Volume
Volume of timber in cubic feet.
@end table

@subsubheading Source

Ryan, T. A., Joiner, B. L. and Ryan, B. F. (1976). @cite{The Minitab
Student Handbook}. Duxbury Press.

@subsubheading References

Atkinson, A. C. (1985). @cite{Plots, Transformations and Regression}.
Oxford: Oxford University Press.

@subsubheading Examples

@example
t = tblish.dataset.trees;

figure
tblish.examples.plot_pairs (t);

figure
loglog (t.Girth, t.Volume)
xlabel ("Girth")
ylabel ("Volume")

# TODO: Transform to log space for the coplot

# TODO: Linear model

@end example


@end deftypefn

@node tblish.dataset.UCBAdmissions
@subsubsection tblish.dataset.UCBAdmissions

@deftypefn {Static Method} {@var{out} =} UCBAdmissions ()

Student Admissions at UC Berkeley

@subsubheading Description

Aggregate data on applicants to graduate school at Berkeley for the six
largest departments in 1973 classified by admission and sex.

@subsubheading Format

A 3-dimensional array resulting from cross-tabulating 4526 observations on
3 variables. The variables and their levels are as follows:

@table @code
@item Admit
Admitted, Rejected.
@item Gender
Male, Female.
@item Dept
A, B, C, D, E, F.
@end table

@subsubheading Details

This data set is frequently used for illustrating Simpson's paradox, see
Bickel et al (1975). At issue is whether the data show evidence of sex bias
in admission practices. There were 2691 male applicants, of whom 1198 (44.5%)
were admitted, compared with 1835 female applicants of whom 557 (30.4%) were
admitted. This gives a sample odds ratio of 1.83, indicating that males were
almost twice as likely to be admitted. In fact, graphical methods (as in the
example below) or log-linear modelling show that the apparent association
between admission and sex stems from differences in the tendency of males
and females to apply to the individual departments (females used to apply
more to departments with higher rejection rates).

@subsubheading Source

The data are given in Box & Jenkins (1976). Obtained from the Time Series Data
Library at @url{http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/}.

@subsubheading References

Bickel, P. J., Hammel, E. A., and O'Connell, J. W. (1975). Sex bias in
graduate admissions: Data from Berkeley. @cite{Science}, 187, 398–403.
@url{http://www.jstor.org/stable/1739581}.

@subsubheading Examples

@example
tblish.dataset.UCBAdmissions;

# TODO: Port mosaic plot to Octave

@end example


@end deftypefn

@node tblish.dataset.UKDriverDeaths
@subsubsection tblish.dataset.UKDriverDeaths

@deftypefn {Static Method} {@var{out} =} UKDriverDeaths ()

Road Casualties in Great Britain 1969-84

@subsubheading Description

@code{UKDriverDeaths} is a time series giving the monthly totals of car drivers in Great Britain killed
or seriously injured Jan 1969 to Dec 1984. Compulsory wearing of seat belts
was introduced on 31 Jan 1983.

@code{Seatbelts} is more information on the same problem.

@subsubheading Format

@code{UKDriverDeaths} is a table with the following variables:

@table @code
@item month
Month of the observation.
@item deaths
Number of deaths.
@end table

@code{Seatbelts} is a table with the following variables:

@table @code
@item month
Month of the observation.
@item DriversKilled
Car drivers killed.
@item drivers
Same as @code{UKDriverDeaths} @code{deaths} count.
@item front
Front-seat passengers killed or seriously injured.
@item rear
Rear-seat passengers killed or seriously injured.
@item kms
Distance driven.
@item PetrolPrice
Petrol price.
@item VanKilled
Number of van (“light goods vehicle”) drivers killed.
@item law
0/1: was the seatbelt law in effect that month?
@end table

@subsubheading Source

Harvey, A.C. (1989). @cite{Forecasting, Structural Time Series Models and
the Kalman Filter}. Cambridge: Cambridge University Press. pp. 519–523.

Durbin, J. and Koopman, S. J. (2001). @cite{Time Series Analysis by State
Space Methods}. Oxford: Oxford University Press. @url{http://www.ssfpack.com/dkbook/}

@subsubheading References

Harvey, A. C. and Durbin, J. (1986). The effects of seat belt legislation
on British road casualties: A case study in structural time series
modelling. @cite{Journal of the Royal Statistical Society} series A, 149, 187–227.

@subsubheading Examples

@example
tblish.dataset.UKDriverDeaths;
d = UKDriverDeaths;
s = Seatbelts;

# TODO: Port the model and plots to Octave

@end example


@end deftypefn

@node tblish.dataset.UKgas
@subsubsection tblish.dataset.UKgas

@deftypefn {Static Method} {@var{out} =} UKgas ()

UK Quarterly Gas Consumption

@subsubheading Description

Quarterly UK gas consumption from 1960Q1 to 1986Q4, in millions of therms.

@subsubheading Format

@table @code
@item date
Quarter of the observation
@item gas
Gas consumption (MM therms).
@end table

@subsubheading Source

Durbin, J. and Koopman, S. J. (2001). @cite{Time Series Analysis by State
Space Methods}. Oxford: Oxford University Press. @url{http://www.ssfpack.com/dkbook/}.

@subsubheading Examples

@example
t = tblish.dataset.UKgas;

plot (datenum (t.date), t.gas);
datetick ("x")
xlabel ("Month")
ylabel ("Gas consumption (MM therms)")

@end example


@end deftypefn

@node tblish.dataset.UKLungDeaths
@subsubsection tblish.dataset.UKLungDeaths

@deftypefn {Static Method} {@var{out} =} UKLungDeaths ()

Monthly Deaths from Lung Diseases in the UK

@subsubheading Description

Three time series giving the monthly deaths from bronchitis, emphysema and
asthma in the UK, 1974–1979.

@subsubheading Format

@table @code
@item date
Month of the observation.
@item ldeaths
Total lung deaths.
@item fdeaths
Lung deaths among females.
@item mdeaths
Lung deaths among males.
@end table

@subsubheading Source

P. J. Diggle (1990). @cite{Time Series: A Biostatistical Introduction}. Oxford. table A.3

@subsubheading Examples

@example
t = tblish.dataset.UKLungDeaths;

figure
plot (datenum (t.date), t.ldeaths);
title ("Total UK Lung Deaths")
xlabel ("Month")
ylabel ("Deaths")

figure
plot (datenum (t.date), [t.fdeaths t.mdeaths]);
title ("UK Lung Deaths buy sex")
legend (@{"Female", "Male"@})
xlabel ("Month")
ylabel ("Deaths")

@end example


@end deftypefn

@node tblish.dataset.USAccDeaths
@subsubsection tblish.dataset.USAccDeaths

@deftypefn {Static Method} {@var{out} =} USAccDeaths ()

Accidental Deaths in the US 1973-1978

@subsubheading Description

A time series giving the monthly totals of accidental deaths in the USA.

@subsubheading Format

@table @code
@item month
Month of the observation.
@item deaths
Accidental deaths.
@end table

@subsubheading Source

Brockwell, P. J. and Davis, R. A. (1991). @cite{Time Series: Theory and Methods}.
New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.USAccDeaths;

@end example


@end deftypefn

@node tblish.dataset.USArrests
@subsubsection tblish.dataset.USArrests

@deftypefn {Static Method} {@var{out} =} USArrests ()

Violent Crime Rates by US State

@subsubheading Description

This data set contains statistics, in arrests per 100,000 residents for
assault, murder, and rape in each of the 50 US states in 1973. Also given
is the percent of the population living in urban areas.

@subsubheading Format

@table @code
@item State
State name.
@item Murder
Murder arrests (per 100,000).
@item Assault
Assault arrests (per 100,000).
@item UrbanPop
Percent urban population.
@item Rape
Rape arrests (per 100,000).
@end table

@subsubheading Note

@code{USArrests} contains the data as in McNeil's monograph. For the
@code{UrbanPop} percentages, a review of the table (No. 21) in the
Statistical Abstracts 1975 reveals a transcription error for Maryland
(and that McNeil used the same “round to even” rule), as found by
Daniel S Coven (Arizona).

See the example below on how to correct the error and improve accuracy
for the ‘<n>.5’ percentages.

@subsubheading Source

@cite{World Almanac and Book of Facts 1975}. (Crime rates).

@cite{Statistical Abstracts of the United States 1975}, p.20, (Urban rates),
possibly available as @url{https://books.google.ch/books?id=zl9qAAAAMAAJ&pg=PA20}.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.USArrests;

summary (t);

tblish.examples.plot_pairs (t(:,2:end));

# TODO: Difference between USArrests and its correction

# TODO: +/- 0.5 to restore the original <n>.5 percentages

@end example


@end deftypefn

@node tblish.dataset.USJudgeRatings
@subsubsection tblish.dataset.USJudgeRatings

@deftypefn {Static Method} {@var{out} =} USJudgeRatings ()

Lawyers’ Ratings of State Judges in the US Superior Court

@subsubheading Description

Lawyers’ ratings of state judges in the US Superior Court.

@subsubheading Format

@table @code
@item CONT
Number of contacts of lawyer with judge.
@item INTG
Judicial integrity.
@item DMNR
Demeanor.
@item DILG
Diligence.
@item CFMG
Case flow managing.
@item DECI
Prompt decisions.
@item PREP
Preparation for trial.
@item FAMI
Familiarity with law.
@item ORAL
Sound oral rulings.
@item WRIT
Sound written rulings.
@item PHYS
Physical ability.
@item RTEN
Worthy of retention.
@end table

@subsubheading Source

New Haven Register, 14 January, 1977 (from John Hartigan).

@subsubheading Examples

@example
t = tblish.dataset.USJudgeRatings;

figure
tblish.examples.plot_pairs (t(:,2:end));
title ("USJudgeRatings data")

@end example


@end deftypefn

@node tblish.dataset.USPersonalExpenditure
@subsubsection tblish.dataset.USPersonalExpenditure

@deftypefn {Static Method} {@var{out} =} USPersonalExpenditure ()

Personal Expenditure Data

@subsubheading Description

This data set consists of United States personal expenditures (in billions
of dollars) in the categories: food and tobacco, household operation,
medical and health, personal care, and private education for the years 1940,
1945, 1950, 1955 and 1960.

@subsubheading Format

A 2-dimensional matrix @code{x} with Category along dimension 1 and Year along dimension 2.

@subsubheading Source

@cite{The World Almanac and Book of Facts}, 1962, page 756.

@subsubheading References

Tukey, J. W. (1977). @cite{Exploratory Data Analysis}. Reading, Mass: Addison-Wesley.

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
tblish.dataset.USPersonalExpenditure;

# TODO: Port medpolish() from R, whatever that is.

@end example


@end deftypefn

@node tblish.dataset.uspop
@subsubsection tblish.dataset.uspop

@deftypefn {Static Method} {@var{out} =} uspop ()

Populations Recorded by the US Census

@subsubheading Description

This data set gives the population of the United States
(in millions) as recorded by the decennial census for the period 1790–1970.

@subsubheading Format

@table @code
@item year
Year of the census.
@item population
Population, in millions.
@end table

@subsubheading Source

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.uspop;

figure
semilogy (t.year, t.population)
xlabel ("Year")
ylabel ("U.S. Population (millions)")

@end example


@end deftypefn

@node tblish.dataset.VADeaths
@subsubsection tblish.dataset.VADeaths

@deftypefn {Static Method} {@var{out} =} VADeaths ()

Death Rates in Virginia (1940)

@subsubheading Description

Death rates per 1000 in Virginia in 1940.

@subsubheading Format

A 2-dimensional matrix @code{deaths}, with age group along dimension 1 and
demographic group along dimension 2.

@subsubheading Details

The death rates are measured per 1000 population per year. They are
cross-classified by age group (rows) and population group (columns). The
age groups are: 50–54, 55–59, 60–64, 65–69, 70–74 and the population groups
are Rural/Male, Rural/Female, Urban/Male and Urban/Female.

This provides a rather nice 3-way analysis of variance example.

@subsubheading Source

Molyneaux, L., Gilliam, S. K., and Florant, L. C.(1947) Differences
in Virginia death rates by color, sex, age, and rural or urban
residence. @cite{American Sociological Review}, 12, 525–535.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
tblish.dataset.VADeaths;

# TODO: Port to Octave

@end example


@end deftypefn

@node tblish.dataset.volcano
@subsubsection tblish.dataset.volcano

@deftypefn {Static Method} {@var{out} =} volcano ()

Topographic Information on Auckland’s Maunga Whau Volcano

@subsubheading Description

Maunga Whau (Mt Eden) is one of about 50 volcanos in the Auckland volcanic
field. This data set gives topographic information for Maunga Whau on a
10m by 10m grid.

@subsubheading Format

A matrix @code{volcano} with 87 rows and 61 columns, rows corresponding
to grid lines running east to west and columns to grid lines running south
to north.

@subsubheading Source

Digitized from a topographic map by Ross Ihaka. These data should not be regarded as accurate.

@subsubheading References

Box, G. E. P. and Jenkins, G. M. (1976). @cite{Time Series Analysis, Forecasting and
Control}. San Francisco: Holden-Day. p. 537.

Brockwell, P. J. and Davis, R. A. (1991). @cite{Time Series: Theory and Methods}.
Second edition. New York: Springer-Verlag. p. 414.

@subsubheading Examples

@example
tblish.dataset.volcano;

# TODO: Figure out how to do a topo map in Octave. Just a gridded color plot
# should be fine. And then maybe do a 3-d mesh plot.

@end example


@end deftypefn

@node tblish.dataset.warpbreaks
@subsubsection tblish.dataset.warpbreaks

@deftypefn {Static Method} {@var{out} =} warpbreaks ()

The Number of Breaks in Yarn during Weaving

@subsubheading Description

This data set gives the number of warp breaks per loom, where a loom
corresponds to a fixed length of yarn.

@subsubheading Format

@table @code
@item wool
Type of wool (A or B).
@item tension
The level of tension (L, M, H).
@item breaks
Number of breaks.
@end table

There are measurements on 9 looms for each of the six types of warp (AL, AM, AH, BL, BM, BH).

@subsubheading Source

Tippett, L. H. C. (1950). @cite{Technological Applications of Statistics}.
New York: Wiley. Page 106.

@subsubheading References

Tukey, J. W. (1977). @cite{Exploratory Data Analysis}. Reading, Mass: Addison-Wesley.

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.warpbreaks;

summary (t)

# TODO: Port the plotting code and OPAR to Octave

@end example


@end deftypefn

@node tblish.dataset.women
@subsubsection tblish.dataset.women

@deftypefn {Static Method} {@var{out} =} women ()

Average Heights and Weights for American Women

@subsubheading Description

This data set gives the average heights and weights for American women aged 30–39.

@subsubheading Format

@table @code
@item height
Height (in).
@item weight
Weight (lbs).
@end table

@subsubheading Details

The data set appears to have been taken from the American Society of Actuaries
Build and Blood Pressure Study for some (unknown to us) earlier year.

The World Almanac notes: “The figures represent weights in ordinary indoor
clothing and shoes, and heights with shoes”.

@subsubheading Source

@cite{The World Almanac and Book of Facts}, 1975.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
t = tblish.dataset.women;

figure
scatter (t.height, t.weight)
xlabel ("Height (in)")
ylabel ("Weight (lb")
title ("women data: American women aged 30-39")

@end example


@end deftypefn

@node tblish.dataset.WorldPhones
@subsubsection tblish.dataset.WorldPhones

@deftypefn {Static Method} {@var{out} =} WorldPhones ()

The World’s Telephones

@subsubheading Description

The number of telephones in various regions of the world (in thousands).

@subsubheading Format

A matrix with 7 rows and 8 columns. The columns of the matrix give the
figures for a given region, and the rows the figures for a year.

The regions are: North America, Europe, Asia, South America, Oceania,
Africa, Central America.

The years are: 1951, 1956, 1957, 1958, 1959, 1960, 1961.

@subsubheading Source

AT&T (1961) @cite{The World’s Telephones}.

@subsubheading References

McNeil, D. R. (1977). @cite{Interactive Data Analysis}. New York: Wiley.

@subsubheading Examples

@example
tblish.dataset.WorldPhones;

# TODO: Port matplot() to Octave

@end example


@end deftypefn

@node tblish.dataset.WWWusage
@subsubsection tblish.dataset.WWWusage

@deftypefn {Static Method} {@var{out} =} WWWusage ()

WWWusage

@subsubheading Description

A time series of the numbers of users connected to the Internet through
a server every minute.

@subsubheading Format

A time series of length 100.

@subsubheading Source

Durbin, J. and Koopman, S. J. (2001). @cite{Time Series Analysis by State
Space Methods}. Oxford: Oxford University Press. @url{http://www.ssfpack.com/dkbook/}

@subsubheading References

Makridakis, S., Wheelwright, S. C. and Hyndman, R. J. (1998). @cite{Forecasting:
Methods and Applications}. New York: Wiley.

@subsubheading Examples

@example
# TODO: Come up with example code here

@end example


@end deftypefn

@node tblish.dataset.zCO2
@subsubsection tblish.dataset.zCO2

@deftypefn {Static Method} {@var{out} =} zCO2 ()

Carbon Dioxide Uptake in Grass Plants

@subsubheading Description

The @code{CO2} data set has 84 rows and 5 columns of data from an experiment
on the cold tolerance of the grass species Echinochloa crus-galli.

@subsubheading Format

@subsubheading Details

The CO2 uptake of six plants from Quebec and six plants from Mississippi was
measured at several levels of ambient CO2 concentration. Half the plants of
each type were chilled overnight before the experiment was conducted.

@subsubheading Source

Potvin, C., Lechowicz, M. J. and Tardif, S. (1990). The statistical
analysis of ecophysiological response curves obtained from experiments
involving repeated measures. @cite{Ecology}, 71, 1389–1400.

Pinheiro, J. C. and Bates, D. M. (2000). @cite{Mixed-effects Models
in S and S-PLUS}. New York: Springer.

@subsubheading Examples

@example
t = tblish.dataset.zCO2;

# TODO: Coplot
# TODO: Port the linear model to Octave

@end example


@end deftypefn

@node tblish.datasets
@subsection tblish.datasets
@deftp {Class} tblish.datasets

Example dataset collection.

@code{tblish.datasets} is a collection of example datasets to go with the
Tablicious package.

The @code{tblish.datasets} class provides methods for listing and loading
the example datasets.

@end deftp


@node datasets.description
@subsubsection datasets.description

@deftypefn {Static Method} description (@var{datasetName})
@deftypefnx {Static Method} {@var{out} =} description (@var{datasetName})

Get or display the description for a dataset.

Gets the description for the named dataset. If the output is captured,
it is returned as a charvec containing plain text suitable for human display.
If the output is not captured, displays the description to the console.

@end deftypefn

@node datasets.list
@subsubsection datasets.list

@deftypefn {Static Method} {} list ()
@deftypefnx {Static Method} {@var{out} =} list ()

List all datasets.

Lists all the example datasets known to this class. If the output is
captured, returns the list as a table. If the output is not captured,
displays the list.

Returns a table with variables Name, Description, and possibly more.

@end deftypefn

@node datasets.load
@subsubsection datasets.load

@deftypefn {Static Method} load (@var{datasetName})
@deftypefnx {Static Method} {@var{out} =} load (@var{datasetName})

Load a specified dataset.

@var{datasetName} is the name of the dataset to load, as found in the
@code{Name} column of the dataset list.

@end deftypefn

@node tblish.evalWithTableVars
@subsection tblish.evalWithTableVars
@deftypefn {Function} {@var{out} =} tblish.evalWithTableVars (@var{tbl}, @var{expr})

Evaluate an expression against a table array’s variables.

Evaluates the M-code expression @var{expr} in a workspace where all of @var{tbl}’s
variables have been assigned to workspace variables.

@var{expr} is a charvec containing an Octave expression.

As an implementation detail, the workspace will also contain some variables
that are prefixed and suffixed with "__". So try to avoid those in your
table variable names.

Returns the result of the evaluation.

Examples:

@example
[s,p,sp] = tblish.examples.SpDb
tmp = join (sp, p);
shipment_weight = tblish.evalWithTableVars (tmp, "Qty .* Weight")
@end example

See also: @ref{table.restrict}

@end deftypefn


@node tblish.examples.coplot
@subsection tblish.examples.coplot
@deftypefn {Function} {[@var{fig}, @var{hax}] =} tblish.examples.coplot (@var{tbl}, @var{xvar}, @var{yvar}, @var{gvar})
@deftypefnx {Function} {[@var{fig}, @var{hax}] =} tblish.examples.coplot (@var{fig}, @var{tbl}, @var{xvar}, @var{yvar}, @var{gvar})
@deftypefnx {Function} {[@var{fig}, @var{hax}] =} tblish.examples.coplot (@dots{}, @var{OptionName}, @var{OptionValue}, @dots{})

Conditioning plot.

@code{tblish.examples.coplot} produces conditioning plots. This is a kind of plot that breaks up the
data into groups based on one or two grouping variables, and plots each group of data
in a separate subplot.

@var{tbl} is a @code{table} containing the data to plot.

@var{xvar} is the name of the table variable within @var{tbl} to use as the X values.
May be a variable name or index.

@var{yvar} is the name of the table variable within @var{tbl} to use as the Y values.
May be a variable name or index.

@var{gvar} is the name of the table variable or variables within @var{tbl} to use as
the grouping variable(s). The grouping variables split the data into groups based on
the distinct values in those variables. @var{gvar} may specify either one or two
grouping variables (but not more). It can be provided as a charvec, cellstr, or index
array. Records with a missing value for their grouping variable(s) are ignored.

@var{fig} is the figure handle to plot into. If @var{fig} is not provided, a new figure
is created.

Name/Value options:

@table @code
@item PlotFcn
The plotting function to use, supplied as a function handle. Defaults to @code{@@plot}.
It must be a function that provides the signature @code{fcn(hax, X, Y, @dots{})}.
@item PlotArgs
A cell array of arguments to pass in to the plotting function, following the @var{hax},
@var{x}, and @var{y} arguments.
@end table

Returns:
  @var{fig} – the figure handle it plotted into
  @var{hax} – array of axes handles to all the axes for the subplots

@end deftypefn


@node tblish.examples.plot_pairs
@subsection tblish.examples.plot_pairs
@deftypefn {Function} {@var{out} =} tblish.examples.plot_pairs (@var{data})
@deftypefnx {Function} {@var{out} =} tblish.examples.plot_pairs (@var{data}, @var{plot_type})
@deftypefnx {Function} {@var{out} =} tblish.examples.plot_pairs (@var{fig}, @dots{})

Plot pairs of variables against each other.

@var{data} is the data holding the variables to plot. It may be either a
@code{table} or a struct. Each variable or field in the @code{table}
or struct is considered to be one variable. Each must hold a vector, and
all the vectors of all the variables must be the same size.

@var{plot_type} is a charvec indicating what plot type to do in each subplot.
(@code{"scatter"} is the default.) Valid @var{plot_type} values are:

@table @code
@item "scatter"
A plain scatter plot.
@item "smooth"
A scatter plot + fitted line, like R's @code{panel.smooth} does.
@end table

@var{fig} is an optional figure handle to plot into. If omitted, a new
figure is created.

Returns the created figure, if the output is captured.

@end deftypefn


@node tblish.examples.SpDb
@subsection tblish.examples.SpDb
@deftypefn {Function} {@var{spdb} =} tblish.examples.SpDb ()
@deftypefnx {Function} {[@var{s}, @var{p}, @var{sp}] =} tblish.examples.SpDb ()

The classic Suppliers-Parts example database.

Constructs the classic C. J. Date Suppliers-Parts ("SP") example database as tables.
This database is the one used as an example throughout Date's "An Introduction to
Database Systems" textbook.

Returns the database as a set of three table arrays. If one argout is captured, the
tables are returned in the fields of a single struct. If multiple argouts are captured, the
tables are returned as three argouts with a single table in each, in the order (@var{s},
@var{p}, @var{sp}).

@end deftypefn


@node tblish.sizeof2
@subsection tblish.sizeof2
@deftypefn {Function} {@var{out} =} tblish.sizeof2 (@var{x})

Approximate size of an array in bytes, with object support.

This is an alternative to Octave's @code{sizeof} function that tries to provide
meaningful support for objects, including the classes defined in Tablicious. It is
named "sizeof2" instead of "sizeof" to avoid a "shadowing core function" warning
when loading Tablicious, because it seems that Octave does not consider packages
(namespaces) when detecting shadowed functions.

This may be supplemented or replaced by @code{sizeof} override methods on Tablicious's
classes. I'm not sure whether Octave's @code{sizeof} supports extension by method
overrides, so I'm not doing that yet. If that happens, this @code{sizeof2} function
will stick around in a deprecated state for a while, and it will respect those override
methods.

For tables, this returns the sum of @code{sizeof} for all of its variables’
arrays, plus the size of the VariableNames and any other metadata stored in @var{obj}.

This is currently broken for some types, because its implementation is in transition
from overridden methods on Tablicious's objects to a separate function.

This is not supported, fully or at all, for all input types, but it has support
for the types defined in Tablicious, plus some Octave built-in types, and makes a
best effort at figuring out user-defined classdef objects. It currently does not
have extensibility support for customization by classdef classes, but that may be
added in the future, in which case its output may change significantly for classdef
objects in future releases.

@var{x} is an array of any type.

Returns a scalar numeric. Returns NaN for types that are known to not be supported,
instead of raising an error. Raises an error if it fails to determine the size of an
input of a type that it thought was supported.

See also: sizeof

@end deftypefn


@node tblish.table.grpstats
@subsection tblish.table.grpstats
@deftypefn {Function} {[@var{out}] =} tblish.table.grpstats (@var{tbl}, @var{groupvar})
@deftypefnx {Function} {[@var{out}] =} tblish.table.grpstats (@dots{}, @code{'DataVars'}, @var{DataVars})

Statistics by group for a table array.

This is a table-specific implementation of @code{grpstats} that works on table arrays.
It is supplied as a function in the @var{+tblish} package to avoid colliding with
the global @code{grpstats} function supplied by the Statistics Octave Forge package.
Depending on which version of the Statistics OF package you are using, it may or may
not support table inputs to its @code{grpstats} function. This function is supplied
as an alternative you can use in an environment where @code{table} arrays are not
supported by the @code{grpstats} that you have, though you need to make code changes
and call it as @code{tblish.table.grpstats(tbl)} instead of with a plain
@code{grpstats(tbl)}.

See also: table.groupby, table.findgroups, table.splitapply

@end deftypefn


@node timezones
@subsection timezones
@deftypefn {Function} {@var{out} =} timezones ()
@deftypefnx {Function} {@var{out} =} timezones (@var{area})

List all the time zones defined on this system.

This lists all the time zones that are defined in the IANA time zone database
used by this Octave. (On Linux and macOS, that will generally be the system
time zone database from @file{/usr/share/zoneinfo}. On Windows, it will be
the database redistributed with the Tablicious package.

If the return is captured, the output is returned as a table if your Octave
has table support, or a struct if it does not. It will have fields/variables
containing column vectors:

@table @code
@item Name
The IANA zone name, as cellstr.
@item Area
The geographical area the zone is in, as cellstr.
@end table

Compatibility note: Matlab also includes UTCOffset and DSTOffset fields in
the output; these are currently unimplemented.

@end deftypefn


@node todatetime
@subsection todatetime
@deftypefn {Function} {@var{out} =} todatetime (@var{x})

Convert input to a Tablicious datetime array, with convenient interface.

This is an alternative to the regular datetime constructor, with a signature
and conversion logic that Tablicious's author likes better.

This mainly exists because datetime's constructor signature does not accept
datenums, and instead treats one-arg numeric inputs as datevecs. (For compatibility
with Matlab's interface.) I think that's less convenient: datenums seem to be
more common than datevecs in M-code, and it returns an object array that's not the
same size as the input.

Returns a datetime array whose size depends on the size and type of the input
array, but will generally be the same size as the array of strings or numerics
the input array "represents".

@end deftypefn


@node vartype
@subsection vartype
@deftypefn {Function} {@var{out} =} vartype (@var{type})

Filter by variable type for use in suscripting.

Creates an object that can be used for subscripting into the variables
dimension of a table and filtering on variable type.

@var{type} is the name of a type as charvec. This may be anything that
the @code{isa} function accepts, or @code{'cellstr'} to select cellstrs,
as determined by @code{iscellstr}.

Returns an object of an opaque type. Don’t worry about what type it is;
just pass it into the second argument of a subscript into a @code{table}
object.

@end deftypefn


@node vecfun
@subsection vecfun
@deftypefn {Function} {@var{out} =} vecfun (@var{fcn}, @var{x}, @var{dim})

Apply function to vectors in array along arbitrary dimension.

This function is not implemented yet.

Applies a given function to the vector slices of an N-dimensional array, where
those slices are along a given dimension.

@var{fcn} is a function handle to apply.

@var{x} is an array of arbitrary type which is to be sliced and passed
in to @var{fcn}.

@var{dim} is the dimension along which the vector slices lay.

Returns the collected output of the @var{fcn} calls, which will be
the same size as @var{x}, but not necessarily the same type.

@end deftypefn


@node years
@subsection years
@deftypefn {Function File} {@var{out} =} years (@var{x})
Create a @code{duration} @var{x} years long, or get the years in a @code{duration}
@var{x}.

If input is numeric, returns a @code{duration} array in units of fixed-length
years of 365.2425 days each.

If input is a @code{duration}, converts the @code{duration} to a number of fixed-length
years as double.

Note: @code{years} creates fixed-length years, which may not be what you want.
To create a duration of calendar years (which account for actual leap days),
use @code{calyears}.

@xref{calyears}.
@end deftypefn





@node Copying
@chapter Copying


@section Package Copyright

Tablicious for GNU Octave is covered by the GNU GPLv3 and other Free and Open Source Software licenses.

The main code of Tablicious is licensed under the GNU GPL version 3 or later.

Certain files in the build tools are licensed under the GNU GPL version 2 or later. This includes the @code{mktexi.pl} and @code{OctTexiDoc.pm} files in the @code{doc/} directory.

The tzinfo database file is Public Domain.

The date/time portion of Tablicious includes some Unicode data files licensed under the Unicode License Agreement - Data Files and Software license.

The Tablicious test suite contains some files, specifically some table-related tests using MP-Test like @code{t/t_01_table.m}, which are BSD 3-Clause licensed, and are adapted from MATPOWER written by Ray Zimmerman.

The Fisher Iris dataset is Public Domain.

@section Manual Copyright

@insertcopying

@bye
