This is tablicious.info, produced by makeinfo version 7.1 from
tablicious.texi.

This manual is for Tablicious, version 0.4.2.

   Copyright © 2019, 2023, 2024 Andrew Janke

     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.


File: tablicious.info,  Node: Top,  Next: Introduction,  Up: (dir)

Tablicious for GNU Octave
*************************

This manual is for Tablicious, version 0.4.2.

* Menu:

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


File: tablicious.info,  Node: Introduction,  Next: Getting Started,  Up: Top

1 Introduction
**************

     Time is an illusion.  Lunchtime doubly so.

                          -- _Douglas Adams_

   This is the manual for the Tablicious package version 0.4.2 for GNU
Octave.

   Tablicious provides somewhat-Matlab-compatible tabular data and
date/time support for GNU Octave.  This includes a ‘table’ class with
support for filtering and join operations; ‘datetime’, ‘duration’, and
related classes; Missing Data support; ‘string’ and ‘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 <<floss@apjanke.net>>.
Support can be found on the Tablicious project GitHub page
(https://github.com/apjanke/octave-tablicious).


File: tablicious.info,  Node: Getting Started,  Next: Table Representation,  Prev: Introduction,  Up: Top

2 Getting Started
*****************

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

     pkg install https://github.com/apjanke/octave-tablicious/releases/download/v0.4.2/tablicious-0.4.2.tar.gz

   (Check the releases page at
<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
<https://github.com/apjanke/octave-tablicious>.  Make a local clone of
the repo.  Then add the ‘inst’ directory in the repo to your Octave
path.


File: tablicious.info,  Node: Table Representation,  Next: Date and Time Representation,  Prev: Getting Started,  Up: Top

3 Table Representation
**********************

Tablicious provides the ‘table’ class for representing tabular data.

   A ‘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 ‘table’ is composed of multiple “variables”, each with a name,
which all have the same number of rows.  (A ‘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 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 ‘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 ‘table’ arrays.  It’s like
having your own in-memory SQL engine.

* Menu:

* Table Construction::
* Tables vs SQL::


File: tablicious.info,  Node: Table Construction,  Next: Tables vs SQL,  Up: Table Representation

3.1 Table Construction
======================

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

   To build an array from multiple variables, use the ‘table(...)’
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 ‘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 ‘'VariableNames'’ option.

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


File: tablicious.info,  Node: Tables vs SQL,  Prev: Table Construction,  Up: Table Representation

3.2 Tables vs SQL
=================

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

   In this table, ‘t’ is a variable holding a ‘table’ array, and ‘ix’ is
some indexing expression.

SQL                      Relational               Octave ‘table’
---------------------------------------------------------------------------
SELECT                   PROJECT                  ‘subsetvars’,
                                                  ‘t(:,ix)’
WHERE                    RESTRICT                 ‘subsetrows’,
                                                  ‘t(ix,:)’
INNER JOIN               JOIN                     ‘innerjoin’
OUTER JOIN               OUTER JOIN               ‘outerjoin’
FROM ‘TABLE1, TABLE2,    Cartesian product        ‘cartesian’
...’
GROUP BY                 SUMMARIZE                ‘groupby’
DISTINCT                 (automatic)              ‘unique(t)’

   Note that there is one big difference between relational algebra and
SQL & Octave ‘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
‘DISTINCT’/‘unique()’ on its results, and there‘s no ‘ORDER
BY’/‘sort()’.  This is not the case in SQL or Octave ‘table’.

   Note for users coming from Matlab: Matlab does not provide a general
‘groupby’ function.  Instead, you have to variously use ‘rowfun’,
‘grpstats’, ‘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


File: tablicious.info,  Node: Date and Time Representation,  Next: Validation Functions,  Prev: Table Representation,  Up: Top

4 Date and Time Representation
******************************

Tablicious provides the ‘datetime’ class for representing points in
time.

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

* Menu:

* datetime Class::
* Time Zones::
* Durations::


File: tablicious.info,  Node: datetime Class,  Next: Time Zones,  Up: Date and Time Representation

4.1 ‘datetime’ Class
====================

A ‘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
‘datetime’.  It also contains some Octave-specific extensions.

   The underlying representation is that of a datenum (a ‘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 ‘datetime’ inclues an
optional ‘TimeZone’ property indicating what time zone the datetimes are
in.

   So, basically, a ‘datetime’ is an object wrapper around a datenum
array, plus time zone support.

* Menu:

* Datenum Compatibility::


File: tablicious.info,  Node: Datenum Compatibility,  Up: datetime Class

4.1.1 Datenum Compatibility
---------------------------

While the underlying data representation of ‘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 ‘datetime’ constructor.  When
combining objects and primitive types like ‘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 ‘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 ‘datetime’s with datenums, you can convert the datenums to
‘datetime’s by calling ‘datetime.ofDatenum’ or ‘datetime(x,
'ConvertFrom', 'datenum')’, or you can convert the ‘datetime’s to
datenums by accessing its ‘dnums’ field with ‘x.dnums’.

   Examples:

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

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


File: tablicious.info,  Node: Time Zones,  Next: Durations,  Prev: datetime Class,  Up: Date and Time Representation

4.2 Time Zones
==============

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

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

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

   By default, the ‘datetime’ constructor creates unzoned ‘datetime’s.
To make a zoned ‘datetime’, either pass the ‘'TimeZone'’ option to the
constructor, or set the ‘TimeZone’ property after object creation.
Setting the ‘TimeZone’ property on a zoneless ‘datetime’ declares that
it's a local time in that time zone.  Setting the ‘TimeZone’ property on
a zoned ‘datetime’ turns it back into a zoneless ‘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 ‘datetime’s.

     % Create an unzoned datetime
     d = datetime('2011-03-04 06:00:00')
         ⇒  04-Mar-2011 06:00:00

     % Create a zoned datetime
     d_ny = datetime('2011-03-04 06:00:00', 'TimeZone', 'America/New_York')
         ⇒  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'
         ⇒  04-Mar-2011 06:00:00 America/New_York

     % Convert it to Chicago time
     d_chi.TimeZone = 'America/Chicago'
         ⇒  04-Mar-2011 05:00:00 America/Chicago

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

     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
         ⇒ 03:00:00

   You cannot combine a zoned and an unzoned ‘datetime’.  This results
in an error being raised.

     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.

* Menu:

* Defined Time Zones::


File: tablicious.info,  Node: Defined Time Zones,  Up: Time Zones

4.2.1 Defined Time Zones
------------------------

Tablicious's time zone data is drawn from the IANA Time Zone Database
(https://www.iana.org/time-zones), 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 ‘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).

     Note: The IANA Time Zone Database only covers dates from about the
     year 1880 to 2038.  Converting time zones for ‘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.)


File: tablicious.info,  Node: Durations,  Prev: Time Zones,  Up: Date and Time Representation

4.3 Durations
=============

* Menu:

* duration Class::
* calendarDuration Class::


File: tablicious.info,  Node: duration Class,  Next: calendarDuration Class,  Up: Durations

4.3.1 ‘duration’ Class
----------------------

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

   A ‘duration’ has a resolution of about a nanosecond for typical
dates.  The underlying representation is a ‘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 ‘duration’ to a ‘datetime’ to get another
‘datetime’.  You can also add or subtract ‘durations’ to each other.


File: tablicious.info,  Node: calendarDuration Class,  Prev: duration Class,  Up: Durations

4.3.2 ‘calendarDuration’ Class
------------------------------

A ‘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 ‘calendarDuration’ does arithmetic with
"whole" calendar periods.

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

     d = datetime('2011-03-04 00:00:00')
         ⇒ 04-Mar-2011
     cdur = calendarDuration(1, 3, 0)
         ⇒ 1y 3mo
     d2 = d + cdur
         ⇒ 04-Jun-2012


File: tablicious.info,  Node: Validation Functions,  Next: Example Data Sets,  Prev: Date and Time Representation,  Up: Top

5 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
‘mustBeXxx’, where ‘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 ‘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.

     % 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');


File: tablicious.info,  Node: Example Data Sets,  Next: Missing Functionality,  Prev: Validation Functions,  Up: Top

6 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 ‘tblish.datasets’ and ‘tblish.dataset’ classes.

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

     tblish.datasets.list
     t = tblish.datasets.load('cupcake')

   You can also load it by calling ‘tblish.dataset.<name>’.  This does
the same thing.  For example:

     t = tblish.dataset.cupcake

   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 ‘doc’ command on ‘tblish.dataset.<name>’, where <NAME> is the
name of the data set.

   For example:

     doc tblish.dataset.cupcake

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

* Menu:

* Data Sets from R::


File: tablicious.info,  Node: Data Sets from R,  Next: Missing Functionality,  Prev: Example Data Sets,  Up: Example Data Sets

6.1 Data Sets from R
====================

Many of Tablicious’ example data sets are based on the example datasets
found in R’s ‘datasets’ package.  R can be found at
<https://www.r-project.org/>, and documentation for its ‘datasets’ is at
<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.


File: tablicious.info,  Node: Missing Functionality,  Next: API Reference,  Prev: Example Data Sets,  Up: Top

7 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:

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

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

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


File: tablicious.info,  Node: API Reference,  Next: Copying,  Prev: Missing Functionality,  Up: Top

8 API Reference
***************

* Menu:

* API by Category::
* API Alphabetically::


File: tablicious.info,  Node: API by Category,  Next: API Alphabetically,  Up: API Reference

8.1 API by Category
===================

8.1.1 Tables
------------

table
     Tabular data array containing multiple columnar variables.

     *Note table::.
array2table
     Convert an array to a table.

     *Note array2table::.
cell2table
     Convert a cell array to a table.

     *Note cell2table::.
struct2table
     Convert struct to a table.

     *Note struct2table::.
tableOuterFillValue

     *Note tableOuterFillValue::.
vartype
     Filter by variable type for use in suscripting.

     *Note vartype::.
istable
     True if input is a ‘table’ array or other table-like type, false
     otherwise.

     *Note istable::.
istimetable
     True if input is a ‘timetable’ array or other timetable-like type,
     false otherwise.

     *Note istimetable::.
istabular
     True if input is eitehr a ‘table’ or ‘timetable’ array, or an
     object like them.

     *Note istabular::.
tblish.evalWithTableVars
     Evaluate an expression against a table array’s variables.

     *Note tblish.evalWithTableVars::.
tblish.table.grpstats
     Statistics by group for a table array.

     *Note tblish.table.grpstats::.

8.1.2 Strings and Categoricals
------------------------------

string
     A string array of Unicode strings.

     *Note string::.
NaS
     “Not-a-String".

     *Note NaS::.
contains
     Test if strings contain a pattern.

     *Note contains::.
dispstrs
     Display strings for array.

     *Note dispstrs::.
categorical
     Categorical variable array.

     *Note categorical::.
iscategorical
     True if input is a ‘categorical’ array, false otherwise.

     *Note iscategorical::.
NaC
     “Not-a-Categorical".

     *Note NaC::.
discretize
     Group data into discrete bins or categories.

     *Note discretize::.

8.1.3 Dates and Times
---------------------

datetime
     Represents points in time using the Gregorian calendar.

     *Note datetime::.
NaT
     “Not-a-Time”.

     *Note NaT::.
todatetime
     Convert input to a Tablicious datetime array, with convenient
     interface.

     *Note todatetime::.
localdate
     Represents a complete day using the Gregorian calendar.

     *Note localdate::.
isdatetime
     True if input is a ‘datetime’ array, false otherwise.

     *Note isdatetime::.
calendarDuration
     Durations of time using variable-length calendar periods, such as
     days, months, and years, which may vary in length over time.

     *Note calendarDuration::.
iscalendarduration
     True if input is a ‘calendarDuration’ array, false otherwise.

     *Note iscalendarduration::.
calmonths
     Create a ‘calendarDuration’ that is a given number of calendar
     months long.

     *Note calmonths::.
calyears
     Construct a ‘calendarDuration’ a given number of years long.

     *Note calyears::.
days
     Duration in days.

     *Note days::.
duration
     Represents durations or periods of time as an amount of
     fixed-length time (i.e.

     *Note duration::.
hours
     Create a ‘duration’ X hours long, or get the hours in a ‘duration’
     X.

     *Note hours::.
isduration
     True if input is a ‘duration’ array, false otherwise.

     *Note isduration::.
milliseconds
     Create a ‘duration’ X milliseconds long, or get the milliseconds in
     a ‘duration’ X.

     *Note milliseconds::.
minutes
     Create a ‘duration’ X hours long, or get the hours in a ‘duration’
     X.

     *Note minutes::.
seconds
     Create a ‘duration’ X seconds long, or get the seconds in a
     ‘duration’ X.

     *Note seconds::.
timezones
     List all the time zones defined on this system.

     *Note timezones::.
years
     Create a ‘duration’ X years long, or get the years in a ‘duration’
     X.

     *Note years::.

8.1.4 Missing Data
------------------

missing
     Generic auto-converting missing value.

     *Note missing::.
isnanny
     Test if elements are NaN or NaN-like

     *Note isnanny::.
eqn
     Determine element-wise equality, treating NaNs as equal

     *Note eqn::.

8.1.5 Validation Functions
--------------------------

mustBeA

     *Note mustBeA::.
mustBeCellstr

     *Note mustBeCellstr::.
mustBeCharvec

     *Note mustBeCharvec::.
mustBeFinite

     *Note mustBeFinite::.
mustBeInteger

     *Note mustBeInteger::.
mustBeMember

     *Note mustBeMember::.
mustBeNonempty

     *Note mustBeNonempty::.
mustBeNumeric

     *Note mustBeNumeric::.
mustBeReal

     *Note mustBeReal::.
mustBeSameSize

     *Note mustBeSameSize::.
mustBeScalar

     *Note mustBeScalar::.
mustBeScalarLogical

     *Note mustBeScalarLogical::.
mustBeVector

     *Note mustBeVector::.

8.1.6 Miscellaneous
-------------------

colvecfun
     Apply a function to column vectors in array.

     *Note colvecfun::.
dispstrs
     Display strings for array.

     *Note dispstrs::.
head
     Get first K rows of an array.

     *Note head::.
isfile

     *Note isfile::.
isfolder

     *Note isfolder::.
pp
     Alias for prettyprint, for interactive use.

     *Note pp::.
scalarexpand
     Expand scalar inputs to match size of non-scalar inputs.

     *Note scalarexpand::.
size2str
     Format an array size for display.

     *Note size2str::.
splitapply
     Split data into groups and apply function.

     *Note splitapply::.
tail
     Get last K rows of an array.

     *Note tail::.
vecfun
     Apply function to vectors in array along arbitrary dimension.

     *Note vecfun::.
tblish.sizeof2
     Approximate size of an array in bytes, with object support.

     *Note tblish.sizeof2::.

8.1.7 Example Datasets
----------------------

tblish.datasets
     Example dataset collection.

     *Note tblish.datasets::.
tblish.dataset
     The ‘tblish.dataset’ class provides convenient access to the
     various datasets included with Tablicious.

     *Note tblish.dataset::.

8.1.8 Example Code
------------------

tblish.examples.coplot
     Conditioning plot.

     *Note tblish.examples.coplot::.
tblish.examples.plot_pairs
     Plot pairs of variables against each other.

     *Note tblish.examples.plot_pairs::.
tblish.examples.SpDb
     The classic Suppliers-Parts example database.

     *Note tblish.examples.SpDb::.


File: tablicious.info,  Node: API Alphabetically,  Prev: API by Category,  Up: API Reference

8.2 API Alphabetically
======================

* Menu:

* array2table:: Convert an array to a table.
* 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.


File: tablicious.info,  Node: array2table,  Next: calendarDuration,  Up: API Alphabetically

8.2.1 array2table
-----------------

 -- Function: OUT = array2table (C)
 -- Function: OUT = array2table (..., 'VariableNames', VARIABLENAMES)
 -- Function: OUT = array2table (..., 'RowNames', 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 ‘cell2table’ instead, columns of the cell array which
     can be condensed into primitive arrays will be.  With
     ‘array2table’, they won't be.

     See also: *note cell2table::, *note table::, *note struct2table::


File: tablicious.info,  Node: calendarDuration,  Next: calmonths,  Prev: array2table,  Up: API Alphabetically

8.2.2 calendarDuration
----------------------

 -- 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.)

 -- Instance Variable of calendarDuration: char Sign

     The sign (1 or -1) of this duration, which indicates whether it is
     a positive or negative span of time.

 -- Instance Variable of calendarDuration: char Years

     The number of whole calendar years in this duration.  Must be
     integer-valued.

 -- Instance Variable of calendarDuration: char Months

     The number of whole calendar months in this duration.  Must be
     integer-valued.

 -- Instance Variable of calendarDuration: char Days

     The number of whole calendar days in this duration.  Must be
     integer-valued.

 -- Instance Variable of calendarDuration: char Hours

     The number of whole hours in this duration.  Must be
     integer-valued.

 -- Instance Variable of calendarDuration: char Minutes

     The number of whole minutes in this duration.  Must be
     integer-valued.

 -- Instance Variable of calendarDuration: char Seconds

     The number of seconds in this duration.  May contain fractional
     values.

 -- Instance Variable of calendarDuration: char Format

     The format to display this ‘calendarDuration’ in.  Currently
     unsupported.

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

* Menu:

* calendarDuration.calendarDuration::
* calendarDuration.dispstrs::
* calendarDuration.ismissing::
* calendarDuration.isnan::
* calendarDuration.minus::
* calendarDuration.plus::
* calendarDuration.times::
* calendarDuration.uminus::


File: tablicious.info,  Node: calendarDuration.calendarDuration,  Next: calendarDuration.dispstrs,  Up: calendarDuration

8.2.2.1 calendarDuration.calendarDuration
.........................................

 -- Constructor: OBJ = calendarDuration ()

     Constructs a new scalar ‘calendarDuration’ of zero elapsed time.

 -- Constructor: OBJ = calendarDuration (Y, M, D)
 -- Constructor: OBJ = calendarDuration (Y, M, D, H, MI, S)

     Constructs new ‘calendarDuration’ arrays based on input values.


File: tablicious.info,  Node: calendarDuration.dispstrs,  Next: calendarDuration.ismissing,  Prev: calendarDuration.calendarDuration,  Up: calendarDuration

8.2.2.2 calendarDuration.dispstrs
.................................

 -- Method: OUT = dispstrs (OBJ)

     Get display strings for each element of OBJ.

     Returns a cellstr the same size as OBJ.


File: tablicious.info,  Node: calendarDuration.ismissing,  Next: calendarDuration.isnan,  Prev: calendarDuration.dispstrs,  Up: calendarDuration

8.2.2.3 calendarDuration.ismissing
..................................

 -- Method: OUT = ismissing (OBJ)

     True if input elements are missing.

     This is equivalent to ‘ismissing’.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: calendarDuration.isnan,  Next: calendarDuration.minus,  Prev: calendarDuration.ismissing,  Up: calendarDuration

8.2.2.4 calendarDuration.isnan
..............................

 -- Method: OUT = isnan (OBJ)

     True if input elements are NaN.

     This is equivalent to ‘ismissing’, and is provided for
     compatibility and polymorphic programming purposes.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: calendarDuration.minus,  Next: calendarDuration.plus,  Prev: calendarDuration.isnan,  Up: calendarDuration

8.2.2.5 calendarDuration.minus
..............................

 -- Method: OUT = times (A, B)

     Subtraction: Subtracts one ‘calendarDuration’ from another.

     Returns a ‘calendarDuration’.


File: tablicious.info,  Node: calendarDuration.plus,  Next: calendarDuration.times,  Prev: calendarDuration.minus,  Up: calendarDuration

8.2.2.6 calendarDuration.plus
.............................

 -- Method: OUT = plus (A, B)

     Addition: add two ‘calendarDuration’s.

     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.

     If B is numeric, it is converted to a ‘calendarDuration’ using
     ‘calendarDuration.ofDays’.

     Returns a ‘calendarDuration’.


File: tablicious.info,  Node: calendarDuration.times,  Next: calendarDuration.uminus,  Prev: calendarDuration.plus,  Up: calendarDuration

8.2.2.7 calendarDuration.times
..............................

 -- Method: OUT = times (OBJ, B)

     Multiplication: Multiplies a ‘calendarDuration’ by a numeric
     factor.

     Returns a ‘calendarDuration’.


File: tablicious.info,  Node: calendarDuration.uminus,  Prev: calendarDuration.times,  Up: calendarDuration

8.2.2.8 calendarDuration.uminus
...............................

 -- Method: OUT = uminus (OBJ)

     Unary minus.  Negates the sign of OBJ.


File: tablicious.info,  Node: calmonths,  Next: calyears,  Prev: calendarDuration,  Up: API Alphabetically

8.2.3 calmonths
---------------

 -- Function File: OUT = calmonths (X)
     Create a ‘calendarDuration’ that is a given number of calendar
     months long.

     Input X is a numeric array specifying the number of calendar
     months.

     This is a shorthand alternative to calling the ‘calendarDuration’
     constructor with ‘calendarDuration(0, x, 0)’.

     Returns a new ‘calendarDuration’ object of the same size as X.

     *Note calendarDuration::.


File: tablicious.info,  Node: calyears,  Next: categorical,  Prev: calmonths,  Up: API Alphabetically

8.2.4 calyears
--------------

 -- Function: OUT = calyears (X)

     Construct a ‘calendarDuration’ a given number of years long.

     This is a shorthand for calling ‘calendarDuration(X, 0, 0)’.

     *Note calendarDuration::.


File: tablicious.info,  Node: categorical,  Next: cell2table,  Prev: calyears,  Up: API Alphabetically

8.2.5 categorical
-----------------

 -- Class: categorical

     Categorical variable array.

     A ‘categorical’ array represents an array of values of a
     categorical variable.  Each ‘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 ‘NaN’ value.

     This class is not fully implemented yet.  Missing stuff:

        • gt, ge, lt, le
        • Ordinal support in general
        • countcats
        • summary

 -- Instance Variable of categorical: uint16 code

     The numeric codes of the array element values.  These are indexes
     into the ‘cats’ category list.

     This is a planar property.

 -- Instance Variable of categorical: logical tfMissing

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

     This is a planar property.

 -- Instance Variable of categorical: cellstr cats

     The names of the categories in this array.  This is the list into
     which the ‘code’ values are indexes.

 -- Instance Variable of categorical: scalar_logical isOrdinal

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

* Menu:

* categorical.addcats::
* categorical.categorical::
* categorical.categories::
* categorical.cellstr::
* categorical.dispstrs::
* categorical.iscategory::
* categorical.ismissing::
* categorical.isnanny::
* categorical.isordinal::
* categorical.isundefined::
* categorical.mergecats::
* categorical.missing::
* categorical.removecats::
* categorical.renamecats::
* categorical.reordercats::
* categorical.setcats::
* categorical.squeezecats::
* categorical.string::
* categorical.summary::
* categorical.undefined::


File: tablicious.info,  Node: categorical.addcats,  Next: categorical.categorical,  Up: categorical

8.2.5.1 categorical.addcats
...........................

 -- Method: OUT = addcats (OBJ, NEWCATS)

     Add categories to categorical array.

     Adds the specified categories to OBJ, without changing any of its
     values.

     NEWCATS is a cellstr listing the category names to add to OBJ.


File: tablicious.info,  Node: categorical.categorical,  Next: categorical.categories,  Prev: categorical.addcats,  Up: categorical

8.2.5.2 categorical.categorical
...............................

 -- Constructor: OBJ = categorical ()

     Constructs a new scalar categorical whose value is undefined.

 -- Constructor: OBJ = categorical (VALS)
 -- Constructor: OBJ = categorical (VALS, VALUESET)
 -- Constructor: OBJ = categorical (VALS, VALUESET, CATEGORY_NAMES)
 -- Constructor: OBJ = categorical (..., 'Ordinal', ORDINAL)
 -- Constructor: OBJ = categorical (..., 'Protected', PROTECTED)

     Constructs a new categorical array from the given values.

     VALS is the array of values to convert to categoricals.

     VALUESET is the set of all values from which VALS is drawn.  If
     omitted, it defaults to the unique values in VALS.

     CATEGORY_NAMES is a list of category names corresponding to
     VALUESET.  If omitted, it defaults to VALUESET, converted to
     strings.

     ORDINAL is a logical indicating whether the category values in OBJ
     have a numeric ordering relationship.  Defaults to false.

     PROTECTED indicates whether OBJ should be protected, which prevents
     the addition of new categories to the array.  Defaults to false.


File: tablicious.info,  Node: categorical.categories,  Next: categorical.cellstr,  Prev: categorical.categorical,  Up: categorical

8.2.5.3 categorical.categories
..............................

 -- Method: OUT = categories (OBJ)

     Get a list of the categories in OBJ.

     Gets a list of the categories in OBJ, identified by their category
     names.

     Returns a cellstr column vector.


File: tablicious.info,  Node: categorical.cellstr,  Next: categorical.dispstrs,  Prev: categorical.categories,  Up: categorical

8.2.5.4 categorical.cellstr
...........................

 -- Method: OUT = cellstr (OBJ)

     Convert to cellstr.

     Converts OBJ to a cellstr array.  The strings will be the category
     names for corresponding values, or ‘''’ for undefined values.

     Returns a cellstr array the same size as OBJ.


File: tablicious.info,  Node: categorical.dispstrs,  Next: categorical.iscategory,  Prev: categorical.cellstr,  Up: categorical

8.2.5.5 categorical.dispstrs
............................

 -- Method: OUT = dispstrs (OBJ)

     Display strings.

     Gets display strings for each element in OBJ.  The display strings
     are either the category string, or ‘'<undefined>'’ for undefined
     values.

     Returns a cellstr array the same size as OBJ.


File: tablicious.info,  Node: categorical.iscategory,  Next: categorical.ismissing,  Prev: categorical.dispstrs,  Up: categorical

8.2.5.6 categorical.iscategory
..............................

 -- Method: OUT = iscategory (OBJ, CATNAMES)

     Test whether input is a category on a categorical array.

     CATNAMES is a cellstr listing the category names to check against
     OBJ.

     Returns a logical array the same size as CATNAMES.


File: tablicious.info,  Node: categorical.ismissing,  Next: categorical.isnanny,  Prev: categorical.iscategory,  Up: categorical

8.2.5.7 categorical.ismissing
.............................

 -- Method: OUT = ismissing (OBJ)

     Test whether elements are missing.

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

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: categorical.isnanny,  Next: categorical.isordinal,  Prev: categorical.ismissing,  Up: categorical

8.2.5.8 categorical.isnanny
...........................

 -- Method: OUT = isnanny (OBJ)

     Test whethere elements are NaN-ish.

     Checks where each element in 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 OBJ.


File: tablicious.info,  Node: categorical.isordinal,  Next: categorical.isundefined,  Prev: categorical.isnanny,  Up: categorical

8.2.5.9 categorical.isordinal
.............................

 -- Method: OUT = isordinal (OBJ)

     Whether OBJ is ordinal.

     Returns true if OBJ is ordinal (as determined by its ‘IsOrdinal’
     property), and false otherwise.


File: tablicious.info,  Node: categorical.isundefined,  Next: categorical.mergecats,  Prev: categorical.isordinal,  Up: categorical

8.2.5.10 categorical.isundefined
................................

 -- Method: OUT = isundefined (OBJ)

     Test whether elements are undefined.

     Checks whether each element in OBJ is undefined.  "Undefined" is a
     special value defined by ‘categorical’.  It is equivalent to a
     ‘NaN’ or a ‘missing’ value.

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: categorical.mergecats,  Next: categorical.missing,  Prev: categorical.isundefined,  Up: categorical

8.2.5.11 categorical.mergecats
..............................

 -- Method: OUT = mergecats (OBJ, OLDCATS)
 -- Method: OUT = mergecats (OBJ, OLDCATS, NEWCAT)

     Merge multiple categories.

     Merges the categories OLDCATS into a single category.  If NEWCAT is
     specified, that new category is added if necessary, and all of
     OLDCATS are merged into it.  NEWCAT must be an existing category in
     OBJ if OBJ is ordinal.

     If NEWCAT is not provided, all of ODCATS are merged into
     ‘oldcats{1}’.


File: tablicious.info,  Node: categorical.missing,  Next: categorical.removecats,  Prev: categorical.mergecats,  Up: categorical

8.2.5.12 categorical.missing
............................

 -- Static Method: OUT = categorical.missing ()
 -- Static Method: 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 *note categorical.undefined::, so
     you can call it generically.  It returns strictly the same results
     as calling *note categorical.undefined:: with the same arguments.

     Returns a categorical array.

     See also: categorical.undefined


File: tablicious.info,  Node: categorical.removecats,  Next: categorical.renamecats,  Prev: categorical.missing,  Up: categorical

8.2.5.13 categorical.removecats
...............................

 -- Method: OUT = removecats (OBJ)

     Removes all unused categories from OBJ.  This is equivalent to ‘out
     = squeezecats (obj)’.

 -- Method: OUT = removecats (OBJ, OLDCATS)

     Remove categories from categorical array.

     Removes the specified categories from OBJ.  Elements of OBJ whose
     values belonged to those categories are replaced with undefined.

     NEWCATS is a cellstr listing the category names to add to OBJ.


File: tablicious.info,  Node: categorical.renamecats,  Next: categorical.reordercats,  Prev: categorical.removecats,  Up: categorical

8.2.5.14 categorical.renamecats
...............................

 -- Method: OUT = renamecats (OBJ, NEWCATS)
 -- Method: OUT = renamecats (OBJ, OLDCATS, NEWCATS)

     Rename categories.

     Renames some or all of the categories in OBJ, without changing any
     of its values.


File: tablicious.info,  Node: categorical.reordercats,  Next: categorical.setcats,  Prev: categorical.renamecats,  Up: categorical

8.2.5.15 categorical.reordercats
................................

 -- Method: OUT = reordercats (OBJ)
 -- Method: OUT = reordercats (OBJ, NEWCATS)

     Reorder categories.

     Reorders the categories in OBJ to match NEWCATS.

     NEWCATS is a cellstr that must be a reordering of OBJ’s existing
     category list.  If NEWCATS is not supplied, sorts the categories in
     alphabetical order.


File: tablicious.info,  Node: categorical.setcats,  Next: categorical.squeezecats,  Prev: categorical.reordercats,  Up: categorical

8.2.5.16 categorical.setcats
............................

 -- Method: OUT = setcats (OBJ, NEWCATS)

     Set categories for categorical array.

     Sets the categories to use for OBJ.  If any current categories are
     absent from the NEWCATS list, current values of those categories
     become undefined.


File: tablicious.info,  Node: categorical.squeezecats,  Next: categorical.string,  Prev: categorical.setcats,  Up: categorical

8.2.5.17 categorical.squeezecats
................................

 -- Method: OUT = squeezecats (OBJ)

     Remove unused categories.

     Removes all categories which have no corresponding values in OBJ’s
     elements.

     This is currently unimplemented.


File: tablicious.info,  Node: categorical.string,  Next: categorical.summary,  Prev: categorical.squeezecats,  Up: categorical

8.2.5.18 categorical.string
...........................

 -- Method: OUT = string (OBJ)

     Convert to string array.

     Converts OBJ to a string array.  The strings will be the category
     names for corresponding values, or <missing> for undefined values.

     Returns a ‘string’ array the same size as OBJ.


File: tablicious.info,  Node: categorical.summary,  Next: categorical.undefined,  Prev: categorical.string,  Up: categorical

8.2.5.19 categorical.summary
............................

 -- Method: summary (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.


File: tablicious.info,  Node: categorical.undefined,  Prev: categorical.summary,  Up: categorical

8.2.5.20 categorical.undefined
..............................

 -- Static Method: OUT = categorical.undefined ()
 -- Static Method: OUT = categorical.undefined (sz)

     Create an array of undefined categoricals.

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

     SZ is the size of the array to create.  If omitted or empty,
     creates a scalar.

     Returns a categorical array.

     See also: categorical.missing


File: tablicious.info,  Node: cell2table,  Next: colvecfun,  Prev: categorical,  Up: API Alphabetically

8.2.6 cell2table
----------------

 -- Function: OUT = cell2table (C)
 -- Function: OUT = cell2table (..., 'VariableNames', VARIABLENAMES)
 -- Function: OUT = cell2table (..., 'RowNames', ROWNAMES)

     Convert a cell array to a table.

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

     See also: *note array2table::, *note table::, *note struct2table::


File: tablicious.info,  Node: colvecfun,  Next: contains,  Prev: cell2table,  Up: API Alphabetically

8.2.7 colvecfun
---------------

 -- Function: OUT = colvecfun (FCN, X)

     Apply a function to column vectors in array.

     Applies the given function FCN to each column vector in the array
     X, by iterating over the indexes along all dimensions except
     dimension 1.  Collects the function return values in an output
     array.

     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 X.

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


File: tablicious.info,  Node: contains,  Next: datetime,  Prev: colvecfun,  Up: API Alphabetically

8.2.8 contains
--------------

 -- Function: OUT = colvecfun (STR, PATTERN)
 -- Function: OUT = colvecfun (..., 'IgnoreCase', IGNORECASE)

     Test if strings contain a pattern.

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

     STR (char, cellstr, or string) is a list of strings to compare
     against pattern.

     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 STR.

     See also: startsWith, endsWith


File: tablicious.info,  Node: datetime,  Next: days,  Prev: contains,  Up: API Alphabetically

8.2.9 datetime
--------------

 -- 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 ‘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
     ‘datetime’.  It also contains some Octave-specific extensions.

 -- Instance Variable of datetime: double dnums

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

     This is a planar property: the size of ‘dnums’ is the same size as
     the containing ‘datetime’ array object.

 -- Instance Variable of datetime: char TimeZone

     The time zone this ‘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 ‘TimeZone’ of a ‘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.

 -- Instance Variable of datetime: char Format

     The format to display this ‘datetime’ in.  Currently unsupported.

* Menu:

* datetime.convertDatenumTimeZone::
* datetime.datenum::
* datetime.datenum2posix::
* datetime.datestr::
* datetime.datestrs::
* datetime.datestruct::
* datetime.datetime::
* datetime.diff::
* datetime.dispstrs::
* datetime.eq::
* datetime.ge::
* datetime.gmtime::
* datetime.gt::
* datetime.hms::
* datetime.isbetween::
* datetime.isnan::
* datetime.isnat::
* datetime.le::
* datetime.linspace::
* datetime.localtime::
* datetime.lt::
* datetime.minus::
* datetime.NaT::
* datetime.ne::
* datetime.ofDatenum::
* datetime.ofDatestruct::
* datetime.plus::
* datetime.posix2datenum::
* datetime.posixtime::
* datetime.proxyKeys::
* datetime.timeofday::
* datetime.week::
* datetime.ymd::
* datetime.ymdhms::


File: tablicious.info,  Node: datetime.convertDatenumTimeZone,  Next: datetime.datenum,  Up: datetime

8.2.9.1 datetime.convertDatenumTimeZone
.......................................

 -- Static Method: OUT = datetime.convertDatenumTimeZone (DNUM,
          FROMZONEID, TOZONEID)

     Convert a datenum from one time zone to another.

     DNUM is a datenum array to convert.

     FROMZONEID is a charvec containing the IANA Time Zone identifier
     for the time zone to convert from.

     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 DNUM.


File: tablicious.info,  Node: datetime.datenum,  Next: datetime.datenum2posix,  Prev: datetime.convertDatenumTimeZone,  Up: datetime

8.2.9.2 datetime.datenum
........................

 -- Method: OUT = datenum (OBJ)

     Convert this to datenums that represent the same local time

     Returns double array of same size as this.


File: tablicious.info,  Node: datetime.datenum2posix,  Next: datetime.datestr,  Prev: datetime.datenum,  Up: datetime

8.2.9.3 datetime.datenum2posix
..............................

 -- Static Method: OUT = datetime.datenum2posix (DNUMS)

     Converts Octave datenums to Unix dates.

     The input datenums are assumed to be in UTC.

     Returns a double, which may have fractional seconds.


File: tablicious.info,  Node: datetime.datestr,  Next: datetime.datestrs,  Prev: datetime.datenum2posix,  Up: datetime

8.2.9.4 datetime.datestr
........................

 -- Method: OUT = datestr (OBJ)
 -- Method: OUT = datestr (OBJ, ...)

     Format OBJ as date strings.  Supports all arguments that core
     Octave's ‘datestr’ does.

     Returns date strings as a 2-D char array.


File: tablicious.info,  Node: datetime.datestrs,  Next: datetime.datestruct,  Prev: datetime.datestr,  Up: datetime

8.2.9.5 datetime.datestrs
.........................

 -- Method: OUT = datestrs (OBJ)
 -- Method: OUT = datestrs (OBJ, ...)

     Format OBJ as date strings, returning cellstr.  Supports all
     arguments that core Octave's ‘datestr’ does.

     Returns a cellstr array the same size as OBJ.


File: tablicious.info,  Node: datetime.datestruct,  Next: datetime.datetime,  Prev: datetime.datestrs,  Up: datetime

8.2.9.6 datetime.datestruct
...........................

 -- Method: OUT = datestruct (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.


File: tablicious.info,  Node: datetime.datetime,  Next: datetime.diff,  Prev: datetime.datestruct,  Up: datetime

8.2.9.7 datetime.datetime
.........................

 -- Constructor: OBJ = datetime ()

     Constructs a new scalar ‘datetime’ containing the current local
     time, with no time zone attached.

 -- Constructor: OBJ = datetime (DATEVEC)
 -- Constructor: OBJ = datetime (DATESTRS)
 -- Constructor: OBJ = datetime (IN, 'ConvertFrom', INTYPE)
 -- Constructor: OBJ = datetime (Y, M, D, H, MI, S)
 -- Constructor: OBJ = datetime (Y, M, D, H, MI, MS)
 -- Constructor: OBJ = datetime (..., 'Format', FORMAT, 'InputFormat',
          INPUTFORMAT, 'Locale', INPUTLOCALE, 'PivotYear', PIVOTYEAR,
          'TimeZone', TIMEZONE)

     Constructs a new ‘datetime’ array based on input values.


File: tablicious.info,  Node: datetime.diff,  Next: datetime.dispstrs,  Prev: datetime.datetime,  Up: datetime

8.2.9.8 datetime.diff
.....................

 -- Method: OUT = diff (OBJ)

     Differences between elements.

     Computes the difference between each successive element in OBJ, as
     a ‘duration’.

     Returns a ‘duration’ array the same size as OBJ.


File: tablicious.info,  Node: datetime.dispstrs,  Next: datetime.eq,  Prev: datetime.diff,  Up: datetime

8.2.9.9 datetime.dispstrs
.........................

 -- Method: OUT = dispstrs (OBJ)

     Get display strings for each element of OBJ.

     Returns a cellstr the same size as OBJ.


File: tablicious.info,  Node: datetime.eq,  Next: datetime.ge,  Prev: datetime.dispstrs,  Up: datetime

8.2.9.10 datetime.eq
....................

 -- Method: OUT = eq (A, B)

     True if A is equal to B.  This defines the ‘==’ operator for
     ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.ge,  Next: datetime.gmtime,  Prev: datetime.eq,  Up: datetime

8.2.9.11 datetime.ge
....................

 -- Method: OUT = ge (A, B)

     True if A is greater than or equal to B.  This defines the ‘>=’
     operator for ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.gmtime,  Next: datetime.gt,  Prev: datetime.ge,  Up: datetime

8.2.9.12 datetime.gmtime
........................

 -- Method: OUT = gmtime (OBJ)

     Convert to TM_STRUCT structure in UTC time.

     Converts OBJ to a TM_STRUCT style structure array.  The result is
     in UTC time.  If OBJ is unzoned, it is assumed to be in UTC time.

     Returns a struct array in TM_STRUCT style.


File: tablicious.info,  Node: datetime.gt,  Next: datetime.hms,  Prev: datetime.gmtime,  Up: datetime

8.2.9.13 datetime.gt
....................

 -- Method: OUT = gt (A, B)

     True if A is greater than B.  This defines the ‘>’ operator for
     ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.hms,  Next: datetime.isbetween,  Prev: datetime.gt,  Up: datetime

8.2.9.14 datetime.hms
.....................

 -- Method: [H, M, S] = hms (OBJ)

     Get the Hour, Minute, and Second components of a OBJ.

     For zoned ‘datetime’s, these will be local times in the associated
     time zone.

     Returns double arrays the same size as ‘obj’.


File: tablicious.info,  Node: datetime.isbetween,  Next: datetime.isnan,  Prev: datetime.hms,  Up: datetime

8.2.9.15 datetime.isbetween
...........................

 -- Method: OUT = isbetween (OBJ, LOWER, UPPER)

     Tests whether the elements of OBJ are between LOWER and UPPER.

     All inputs are implicitly converted to ‘datetime’ arrays, and are
     subject to scalar expansion.

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


File: tablicious.info,  Node: datetime.isnan,  Next: datetime.isnat,  Prev: datetime.isbetween,  Up: datetime

8.2.9.16 datetime.isnan
.......................

 -- Method: OUT = isnan (OBJ)

     True if input elements are NaT. This is an alias for ‘isnat’ to
     support type compatibility and polymorphic programming.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.isnat,  Next: datetime.le,  Prev: datetime.isnan,  Up: datetime

8.2.9.17 datetime.isnat
.......................

 -- Method: OUT = isnat (OBJ)

     True if input elements are NaT.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.le,  Next: datetime.linspace,  Prev: datetime.isnat,  Up: datetime

8.2.9.18 datetime.le
....................

 -- Method: OUT = le (A, B)

     True if A is less than or equal toB.  This defines the ‘<=’
     operator for ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.linspace,  Next: datetime.localtime,  Prev: datetime.le,  Up: datetime

8.2.9.19 datetime.linspace
..........................

 -- Method: OUT = linspace (FROM, TO, N)

     Linearly-spaced values in date/time space.

     Constructs a vector of ‘datetime’s that represent linearly spaced
     points starting at FROM and going up to TO, with N points in the
     vector.

     FROM and TO are implicitly converted to ‘datetime’s.

     N is how many points to use.  If omitted, defaults to 100.

     Returns an N-long ‘datetime’ vector.


File: tablicious.info,  Node: datetime.localtime,  Next: datetime.lt,  Prev: datetime.linspace,  Up: datetime

8.2.9.20 datetime.localtime
...........................

 -- Method: OUT = localtime (OBJ)

     Convert to TM_STRUCT structure in UTC time.

     Converts 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 OBJ.

     If OBJ is unzoned, it is assumed to be in UTC time.

     Returns a struct array in TM_STRUCT style.

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


File: tablicious.info,  Node: datetime.lt,  Next: datetime.minus,  Prev: datetime.localtime,  Up: datetime

8.2.9.21 datetime.lt
....................

 -- Method: OUT = lt (A, B)

     True if A is less than B.  This defines the ‘<’ operator for
     ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.minus,  Next: datetime.NaT,  Prev: datetime.lt,  Up: datetime

8.2.9.22 datetime.minus
.......................

 -- Method: OUT = minus (A, B)

     Subtraction (‘-’ operator).  Subtracts a ‘duration’,
     ‘calendarDuration’ or numeric B from a ‘datetime’ A, or subtracts
     two ‘datetime’s from each other.

     If both inputs are ‘datetime’, then the output is a ‘duration’.
     Otherwise, the output is a ‘datetime’.

     Numeric B inputs are implicitly converted to ‘duration’ using
     ‘duration.ofDays’.

     Returns an array the same size as A.


File: tablicious.info,  Node: datetime.NaT,  Next: datetime.ne,  Prev: datetime.minus,  Up: datetime

8.2.9.23 datetime.NaT
.....................

 -- Static Method: OUT = datetime.NaT ()
 -- Static Method: OUT = datetime.NaT (SZ)

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

     Constructs a new ‘datetime’ array of all ‘NaT’ values of the given
     size.  If no input SZ is given, the result is a scalar ‘NaT’.

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


File: tablicious.info,  Node: datetime.ne,  Next: datetime.ofDatenum,  Prev: datetime.NaT,  Up: datetime

8.2.9.24 datetime.ne
....................

 -- Method: OUT = ne (A, B)

     True if A is not equal to B.  This defines the ‘!=’ operator for
     ‘datetime’s.

     Inputs are implicitly converted to ‘datetime’ using the one-arg
     constructor or conversion method.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: datetime.ofDatenum,  Next: datetime.ofDatestruct,  Prev: datetime.ne,  Up: datetime

8.2.9.25 datetime.ofDatenum
...........................

 -- Static Method: OBJ = datetime.ofDatenum (DNUMS)

     Converts a datenum array to a datetime array.

     Returns an unzoned ‘datetime’ array of the same size as the input.


File: tablicious.info,  Node: datetime.ofDatestruct,  Next: datetime.plus,  Prev: datetime.ofDatenum,  Up: datetime

8.2.9.26 datetime.ofDatestruct
..............................

 -- Static Method: OBJ = datetime.ofDatestruct (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 ‘datetime’ array.


File: tablicious.info,  Node: datetime.plus,  Next: datetime.posix2datenum,  Prev: datetime.ofDatestruct,  Up: datetime

8.2.9.27 datetime.plus
......................

 -- Method: OUT = plus (A, B)

     Addition (‘+’ operator).  Adds a ‘duration’, ‘calendarDuration’, or
     numeric B to a ‘datetime’ A.

     A must be a ‘datetime’.

     Numeric B inputs are implicitly converted to ‘duration’ using
     ‘duration.ofDays’.

     Returns ‘datetime’ array the same size as A.


File: tablicious.info,  Node: datetime.posix2datenum,  Next: datetime.posixtime,  Prev: datetime.plus,  Up: datetime

8.2.9.28 datetime.posix2datenum
...............................

 -- Static Method: DNUMS = datetime.posix2datenum (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.


File: tablicious.info,  Node: datetime.posixtime,  Next: datetime.proxyKeys,  Prev: datetime.posix2datenum,  Up: datetime

8.2.9.29 datetime.posixtime
...........................

 -- Method: OUT = posixtime (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.


File: tablicious.info,  Node: datetime.proxyKeys,  Next: datetime.timeofday,  Prev: datetime.posixtime,  Up: datetime

8.2.9.30 datetime.proxyKeys
...........................

 -- Method: [KEYSA, KEYSB] = proxyKeys (A, 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.


File: tablicious.info,  Node: datetime.timeofday,  Next: datetime.week,  Prev: datetime.proxyKeys,  Up: datetime

8.2.9.31 datetime.timeofday
...........................

 -- Method: OUT = timeofday (OBJ)

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

     For zoned ‘datetime’s, these will be local times in the associated
     time zone.

     Returns a ‘duration’ array the same size as ‘obj’.


File: tablicious.info,  Node: datetime.week,  Next: datetime.ymd,  Prev: datetime.timeofday,  Up: datetime

8.2.9.32 datetime.week
......................

 -- Method: OUT = week (OBJ)

     Get the week of the year.

     This method is unimplemented.


File: tablicious.info,  Node: datetime.ymd,  Next: datetime.ymdhms,  Prev: datetime.week,  Up: datetime

8.2.9.33 datetime.ymd
.....................

 -- Method: [Y, M, D] = ymd (OBJ)

     Get the Year, Month, and Day components of OBJ.

     For zoned ‘datetime’s, these will be local times in the associated
     time zone.

     Returns double arrays the same size as ‘obj’.


File: tablicious.info,  Node: datetime.ymdhms,  Prev: datetime.ymd,  Up: datetime

8.2.9.34 datetime.ymdhms
........................

 -- Method: [Y, M, D, H, MI, S] = ymdhms (OBJ)

     Get the Year, Month, Day, Hour, Minute, and Second components of a
     OBJ.

     For zoned ‘datetime’s, these will be local times in the associated
     time zone.

     Returns double arrays the same size as ‘obj’.


File: tablicious.info,  Node: days,  Next: discretize,  Prev: datetime,  Up: API Alphabetically

8.2.10 days
-----------

 -- Function: OUT = days (X)

     Duration in days.

     If X is numeric, then OUT is a ‘duration’ array in units of
     fixed-length 24-hour days, with the same size as X.

     If X is a ‘duration’, then returns a ‘double’ array the same size
     as X indicating the number of fixed-length days that each duration
     is.


File: tablicious.info,  Node: discretize,  Next: dispstrs,  Prev: days,  Up: API Alphabetically

8.2.11 discretize
-----------------

 -- Function: [Y, E] = discretize (X, N)
 -- Function: [Y, E] = discretize (X, EDGES)
 -- Function: [Y, E] = discretize (X, DUR)
 -- Function: [Y, E] = discretize (..., 'categorical')
 -- Function: [Y, E] = discretize (..., 'IncludedEdge', INCLUDEDEDGE)

     Group data into discrete bins or categories.

     N is the number of bins to group the values into.

     EDGES is an array of edge values defining the bins.

     DUR is a ‘duration’ value indicating the length of time of each
     bin.

     If ‘'categorical'’ is specified, the resulting values are a
     ‘categorical’ array instead of a numeric array of bin indexes.

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


File: tablicious.info,  Node: dispstrs,  Next: duration,  Prev: discretize,  Up: API Alphabetically

8.2.12 dispstrs
---------------

 -- Function: OUT = dispstrs (X)

     Display strings for array.

     Gets the display strings for each element of X.  The display
     strings should be short, one-line, human-presentable strings
     describing the value of that element.

     The default implementation of ‘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 X.


File: tablicious.info,  Node: duration,  Next: eqn,  Prev: dispstrs,  Up: API Alphabetically

8.2.13 duration
---------------

 -- 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
     ‘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.

 -- Instance Variable of duration: 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 ‘days’ is the same size as
     the containing ‘duration’ array object.

 -- Instance Variable of duration: char Format

     The format to display this ‘duration’ in.  Currently unsupported.

* Menu:

* duration.char::
* duration.dispstrs::
* duration.hours::
* duration.linspace::
* duration.milliseconds::
* duration.minutes::
* duration.ofDays::
* duration.seconds::
* duration.years::


File: tablicious.info,  Node: duration.char,  Next: duration.dispstrs,  Up: duration

8.2.13.1 duration.char
......................

 -- Method: OUT = char (OBJ)

     Convert to char.  The contents of the strings will be the same as
     returned by ‘dispstrs’.

     This is primarily a convenience method for use on scalar OBJs.

     Returns a 2-D char array with one row per element in OBJ.


File: tablicious.info,  Node: duration.dispstrs,  Next: duration.hours,  Prev: duration.char,  Up: duration

8.2.13.2 duration.dispstrs
..........................

 -- Method: OUT = duration (OBJ)

     Get display strings for each element of OBJ.

     Returns a cellstr the same size as OBJ.


File: tablicious.info,  Node: duration.hours,  Next: duration.linspace,  Prev: duration.dispstrs,  Up: duration

8.2.13.3 duration.hours
.......................

 -- Method: OUT = hours (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 OBJ.


File: tablicious.info,  Node: duration.linspace,  Next: duration.milliseconds,  Prev: duration.hours,  Up: duration

8.2.13.4 duration.linspace
..........................

 -- Method: OUT = linspace (FROM, TO, N)

     Linearly-spaced values in time duration space.

     Constructs a vector of ‘duration’s that represent linearly spaced
     points starting at FROM and going up to TO, with N points in the
     vector.

     FROM and TO are implicitly converted to ‘duration’s.

     N is how many points to use.  If omitted, defaults to 100.

     Returns an N-long ‘datetime’ vector.


File: tablicious.info,  Node: duration.milliseconds,  Next: duration.minutes,  Prev: duration.linspace,  Up: duration

8.2.13.5 duration.milliseconds
..............................

 -- Method: OUT = milliseconds (OBJ)

     Equivalent number of milliseconds.

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

     Returns double array the same size as OBJ.


File: tablicious.info,  Node: duration.minutes,  Next: duration.ofDays,  Prev: duration.milliseconds,  Up: duration

8.2.13.6 duration.minutes
.........................

 -- Method: OUT = minutes (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 OBJ.


File: tablicious.info,  Node: duration.ofDays,  Next: duration.seconds,  Prev: duration.minutes,  Up: duration

8.2.13.7 duration.ofDays
........................

 -- Static Method: OBJ = duration.ofDays (DNUMS)

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

     Returns a ‘duration’ array of the same size as the input.


File: tablicious.info,  Node: duration.seconds,  Next: duration.years,  Prev: duration.ofDays,  Up: duration

8.2.13.8 duration.seconds
.........................

 -- Method: OUT = seconds (OBJ)

     Equivalent number of seconds.

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

     Returns double array the same size as OBJ.


File: tablicious.info,  Node: duration.years,  Prev: duration.seconds,  Up: duration

8.2.13.9 duration.years
.......................

 -- Method: OUT = years (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 OBJ.


File: tablicious.info,  Node: eqn,  Next: head,  Prev: duration,  Up: API Alphabetically

8.2.14 eqn
----------

 -- Function: OUT = eqn (A, B)

     Determine element-wise equality, treating NaNs as equal

     out = eqn (A, B)

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

     ‘eqn’ uses ‘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 “‘eqn’” is a little unfortunate, because
     “eqn” could also be an abbreviation for “equation”.  But this name
     follows the ‘isequaln’ pattern of appending an “n” to the
     corresponding non-NaN-equivocating function.

     See also: ‘eq’, ‘isequaln’, *note isnanny::


File: tablicious.info,  Node: head,  Next: hours,  Prev: eqn,  Up: API Alphabetically

8.2.15 head
-----------

 -- Function: OUT = head (A)
 -- Function: OUT = head (A, K)

     Get first K rows of an array.

     Returns the array A, subsetted to its first K rows.  This means
     subsetting it to the first ‘(min (k, size (A, 1)))’ elements along
     dimension 1, and leaving all other dimensions unrestricted.

     A is the array to subset.

     K is the number of rows to get.  K defaults to 8 if it is omitted
     or empty.

     If there are less than K rows in A, returns all rows.

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

     See also: tail


File: tablicious.info,  Node: hours,  Next: iscalendarduration,  Prev: head,  Up: API Alphabetically

8.2.16 hours
------------

 -- Function File: OUT = hours (X)
     Create a ‘duration’ X hours long, or get the hours in a ‘duration’
     X.

     If input is numeric, returns a ‘duration’ array that is that many
     hours in time.

     If input is a ‘duration’, converts the ‘duration’ to a number of
     hours.

     Returns an array the same size as X.


File: tablicious.info,  Node: iscalendarduration,  Next: iscategorical,  Prev: hours,  Up: API Alphabetically

8.2.17 iscalendarduration
-------------------------

 -- Function: OUT = iscalendarduration (X)

     True if input is a ‘calendarDuration’ array, false otherwise.

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

     Returns a scalar logical.


File: tablicious.info,  Node: iscategorical,  Next: isdatetime,  Prev: iscalendarduration,  Up: API Alphabetically

8.2.18 iscategorical
--------------------

 -- Function: OUT = iscategorical (X)

     True if input is a ‘categorical’ array, false otherwise.

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

     Returns a scalar logical.


File: tablicious.info,  Node: isdatetime,  Next: isduration,  Prev: iscategorical,  Up: API Alphabetically

8.2.19 isdatetime
-----------------

 -- Function: OUT = isdatetime (X)

     True if input is a ‘datetime’ array, false otherwise.

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

     Returns a scalar logical.


File: tablicious.info,  Node: isduration,  Next: isfile,  Prev: isdatetime,  Up: API Alphabetically

8.2.20 isduration
-----------------

 -- Function: OUT = isduration (X)

     True if input is a ‘duration’ array, false otherwise.

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

     Returns a scalar logical.


File: tablicious.info,  Node: isfile,  Next: isfolder,  Prev: isduration,  Up: API Alphabetically

8.2.21 isfile
-------------

_Not documented_


File: tablicious.info,  Node: isfolder,  Next: isnanny,  Prev: isfile,  Up: API Alphabetically

8.2.22 isfolder
---------------

_Not documented_


File: tablicious.info,  Node: isnanny,  Next: istable,  Prev: isfolder,  Up: API Alphabetically

8.2.23 isnanny
--------------

 -- Function: OUT = isnanny (X)

     Test if elements are NaN or NaN-like

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

     This function only exists because:

       a. Matlab decided to call their NaN values for datetime “NaT”
          instead, and test for them with a different “isnat()”
          function, and
       b. isnan() errors out for some types that do not support isnan(),
          like cells.

     ‘isnanny()’ smooths over those differences so you can call it
     polymorphically on any input type.  Hopefully.

     Under normal operation, ‘isnanny()’ should not throw an error for
     any type or value of input.

     See also: ismissing, ‘isnan’, ‘isnat’, *note eqn::, ‘isequaln’


File: tablicious.info,  Node: istable,  Next: istabular,  Prev: isnanny,  Up: API Alphabetically

8.2.24 istable
--------------

 -- Function: OUT = istable (X)

     True if input is a ‘table’ array or other table-like type, false
     otherwise.

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

     User-defined classes should only override ‘istable’ to return true
     if they conform to the ‘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.


File: tablicious.info,  Node: istabular,  Next: istimetable,  Prev: istable,  Up: API Alphabetically

8.2.25 istabular
----------------

 -- Function: OUT = istabular (X)

     True if input is eitehr a ‘table’ or ‘timetable’ array, or an
     object like them.

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

     Returns a scalar logical.


File: tablicious.info,  Node: istimetable,  Next: localdate,  Prev: istabular,  Up: API Alphabetically

8.2.26 istimetable
------------------

 -- Function: OUT = istimetable (X)

     True if input is a ‘timetable’ array or other timetable-like type,
     false otherwise.

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

     User-defined classes should only override ‘istimetable’ to return
     true if they conform to the ‘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.


File: tablicious.info,  Node: localdate,  Next: milliseconds,  Prev: istimetable,  Up: API Alphabetically

8.2.27 localdate
----------------

 -- 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.

 -- Instance Variable of localdate: 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.

 -- Instance Variable of localdate: char Format

     The format to display this ‘localdate’ in.  Currently unsupported.

* Menu:

* localdate.datenum::
* localdate.datestr::
* localdate.datestrs::
* localdate.datestruct::
* localdate.dispstrs::
* localdate.isnan::
* localdate.isnat::
* localdate.localdate::
* localdate.NaT::
* localdate.posixtime::
* localdate.ymd::


File: tablicious.info,  Node: localdate.datenum,  Next: localdate.datestr,  Up: localdate

8.2.27.1 localdate.datenum
..........................

 -- Method: OUT = datenum (OBJ)

     Convert this to datenums that represent midnight on OBJ’s days.

     Returns double array of same size as this.


File: tablicious.info,  Node: localdate.datestr,  Next: localdate.datestrs,  Prev: localdate.datenum,  Up: localdate

8.2.27.2 localdate.datestr
..........................

 -- Method: OUT = datestr (OBJ)
 -- Method: OUT = datestr (OBJ, ...)

     Format OBJ as date strings.  Supports all arguments that core
     Octave's ‘datestr’ does.

     Returns date strings as a 2-D char array.


File: tablicious.info,  Node: localdate.datestrs,  Next: localdate.datestruct,  Prev: localdate.datestr,  Up: localdate

8.2.27.3 localdate.datestrs
...........................

 -- Method: OUT = datestrs (OBJ)
 -- Method: OUT = datestrs (OBJ, ...)

     Format OBJ as date strings, returning cellstr.  Supports all
     arguments that core Octave's ‘datestr’ does.

     Returns a cellstr array the same size as OBJ.


File: tablicious.info,  Node: localdate.datestruct,  Next: localdate.dispstrs,  Prev: localdate.datestrs,  Up: localdate

8.2.27.4 localdate.datestruct
.............................

 -- Method: OUT = datestruct (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
     ‘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 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.


File: tablicious.info,  Node: localdate.dispstrs,  Next: localdate.isnan,  Prev: localdate.datestruct,  Up: localdate

8.2.27.5 localdate.dispstrs
...........................

 -- Method: OUT = dispstrs (OBJ)

     Get display strings for each element of OBJ.

     Returns a cellstr the same size as OBJ.


File: tablicious.info,  Node: localdate.isnan,  Next: localdate.isnat,  Prev: localdate.dispstrs,  Up: localdate

8.2.27.6 localdate.isnan
........................

 -- Method: OUT = isnan (OBJ)

     True if input elements are NaT. This is an alias for ‘isnat’ to
     support type compatibility and polymorphic programming.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: localdate.isnat,  Next: localdate.localdate,  Prev: localdate.isnan,  Up: localdate

8.2.27.7 localdate.isnat
........................

 -- Method: OUT = isnat (OBJ)

     True if input elements are NaT.

     Returns logical array the same size as OBJ.


File: tablicious.info,  Node: localdate.localdate,  Next: localdate.NaT,  Prev: localdate.isnat,  Up: localdate

8.2.27.8 localdate.localdate
............................

 -- Constructor: OBJ = localdate ()

     Constructs a new scalar ‘localdate’ containing the current local
     date.

 -- Constructor: OBJ = localdate (DATENUMS)
 -- Constructor: OBJ = localdate (DATESTRS)
 -- Constructor: OBJ = localdate (Y, M, D)
 -- Constructor: OBJ = localdate (..., 'Format', FORMAT)

     Constructs a new ‘localdate’ array based on input values.


File: tablicious.info,  Node: localdate.NaT,  Next: localdate.posixtime,  Prev: localdate.localdate,  Up: localdate

8.2.27.9 localdate.NaT
......................

 -- Static Method: OUT = localdate.NaT ()
 -- Static Method: OUT = localdate.NaT (SZ)

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

     Constructs a new ‘datetime’ array of all ‘NaT’ values of the given
     size.  If no input SZ is given, the result is a scalar ‘NaT’.

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

     This static method is provided because the global ‘NaT’ function
     creates ‘datetime’s, not ‘localdate’s


File: tablicious.info,  Node: localdate.posixtime,  Next: localdate.ymd,  Prev: localdate.NaT,  Up: localdate

8.2.27.10 localdate.posixtime
.............................

 -- Method: OUT = posixtime (OBJ)

     Converts this to POSIX time values for midnight of 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 OBJ’s days.

     Returns double array of same size as this.


File: tablicious.info,  Node: localdate.ymd,  Prev: localdate.posixtime,  Up: localdate

8.2.27.11 localdate.ymd
.......................

 -- Method: [Y, M, D] = ymd (OBJ)

     Get the Year, Month, and Day components of OBJ.

     Returns double arrays the same size as ‘obj’.


File: tablicious.info,  Node: milliseconds,  Next: minutes,  Prev: localdate,  Up: API Alphabetically

8.2.28 milliseconds
-------------------

 -- Function File: OUT = milliseconds (X)
     Create a ‘duration’ X milliseconds long, or get the milliseconds in
     a ‘duration’ X.

     If input is numeric, returns a ‘duration’ array that is that many
     milliseconds in time.

     If input is a ‘duration’, converts the ‘duration’ to a number of
     milliseconds.

     Returns an array the same size as X.


File: tablicious.info,  Node: minutes,  Next: missing,  Prev: milliseconds,  Up: API Alphabetically

8.2.29 minutes
--------------

 -- Function File: OUT = hours (X)
     Create a ‘duration’ X hours long, or get the hours in a ‘duration’
     X.


File: tablicious.info,  Node: missing,  Next: mustBeA,  Prev: minutes,  Up: API Alphabetically

8.2.30 missing
--------------

 -- Class: missing

     Generic auto-converting missing value.

     ‘missing’ is a generic missing value that auto-converts to other
     types.

     A ‘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:

            x = 1:5
            x(3) = missing

     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.

* Menu:

* missing.dispstrs::
* missing.ismissing::
* missing.isnan::
* missing.isnanny::
* missing.missing::


File: tablicious.info,  Node: missing.dispstrs,  Next: missing.ismissing,  Up: missing

8.2.30.1 missing.dispstrs
.........................

 -- Method: OUT = dispstrs (OBJ)

     Display strings.

     Gets display strings for each element in OBJ.

     For ‘missing’, the display strings are always ‘'<missing>'’.

     Returns a cellstr the same size as OBJ.


File: tablicious.info,  Node: missing.ismissing,  Next: missing.isnan,  Prev: missing.dispstrs,  Up: missing

8.2.30.2 missing.ismissing
..........................

 -- Method: OUT = ismissing (OBJ)

     Test whether elements are missing values.

     ‘ismissing’ is always true for ‘missing’ arrays.

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: missing.isnan,  Next: missing.isnanny,  Prev: missing.ismissing,  Up: missing

8.2.30.3 missing.isnan
......................

 -- Method: OUT = isnan (OBJ)

     Test whether elements are NaN.

     ‘isnan’ is always true for ‘missing’ arrays.

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: missing.isnanny,  Next: missing.missing,  Prev: missing.isnan,  Up: missing

8.2.30.4 missing.isnanny
........................

 -- Method: OUT = isnanny (OBJ)

     Test whether elements are NaN-like.

     ‘isnanny’ is always true for ‘missing’ arrays.

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: missing.missing,  Prev: missing.isnanny,  Up: missing

8.2.30.5 missing.missing
........................

 -- Constructor: OBJ = missing ()

     Constructs a scalar ‘missing’ array.

     The constructor takes no arguments, since there’s only one
     ‘missing’ value.


File: tablicious.info,  Node: mustBeA,  Next: mustBeCellstr,  Prev: missing,  Up: API Alphabetically

8.2.31 mustBeA
--------------

_Not documented_


File: tablicious.info,  Node: mustBeCellstr,  Next: mustBeCharvec,  Prev: mustBeA,  Up: API Alphabetically

8.2.32 mustBeCellstr
--------------------

_Not documented_


File: tablicious.info,  Node: mustBeCharvec,  Next: mustBeFinite,  Prev: mustBeCellstr,  Up: API Alphabetically

8.2.33 mustBeCharvec
--------------------

_Not documented_


File: tablicious.info,  Node: mustBeFinite,  Next: mustBeInteger,  Prev: mustBeCharvec,  Up: API Alphabetically

8.2.34 mustBeFinite
-------------------

_Not documented_


File: tablicious.info,  Node: mustBeInteger,  Next: mustBeMember,  Prev: mustBeFinite,  Up: API Alphabetically

8.2.35 mustBeInteger
--------------------

_Not documented_


File: tablicious.info,  Node: mustBeMember,  Next: mustBeNonempty,  Prev: mustBeInteger,  Up: API Alphabetically

8.2.36 mustBeMember
-------------------

_Not documented_


File: tablicious.info,  Node: mustBeNonempty,  Next: mustBeNumeric,  Prev: mustBeMember,  Up: API Alphabetically

8.2.37 mustBeNonempty
---------------------

_Not documented_


File: tablicious.info,  Node: mustBeNumeric,  Next: mustBeReal,  Prev: mustBeNonempty,  Up: API Alphabetically

8.2.38 mustBeNumeric
--------------------

_Not documented_


File: tablicious.info,  Node: mustBeReal,  Next: mustBeSameSize,  Prev: mustBeNumeric,  Up: API Alphabetically

8.2.39 mustBeReal
-----------------

_Not documented_


File: tablicious.info,  Node: mustBeSameSize,  Next: mustBeScalar,  Prev: mustBeReal,  Up: API Alphabetically

8.2.40 mustBeSameSize
---------------------

_Not documented_


File: tablicious.info,  Node: mustBeScalar,  Next: mustBeScalarLogical,  Prev: mustBeSameSize,  Up: API Alphabetically

8.2.41 mustBeScalar
-------------------

_Not documented_


File: tablicious.info,  Node: mustBeScalarLogical,  Next: mustBeVector,  Prev: mustBeScalar,  Up: API Alphabetically

8.2.42 mustBeScalarLogical
--------------------------

_Not documented_


File: tablicious.info,  Node: mustBeVector,  Next: NaC,  Prev: mustBeScalarLogical,  Up: API Alphabetically

8.2.43 mustBeVector
-------------------

_Not documented_


File: tablicious.info,  Node: NaC,  Next: NaS,  Prev: mustBeVector,  Up: API Alphabetically

8.2.44 NaC
----------

 -- Function: OUT = NaC ()
 -- Function: OUT = NaC (SZ)

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

     Returns a new ‘categorical’ array of all missing values of the
     given size.  If no input SZ is given, the result is a scalar
     missing categorical.

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

     ‘NaC’ is a convenience function which is strictly a wrapper around
     ‘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


File: tablicious.info,  Node: NaS,  Next: NaT,  Prev: NaC,  Up: API Alphabetically

8.2.45 NaS
----------

 -- Function: OUT = NaS ()
 -- Function: OUT = NaS (SZ)

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

     Returns a new ‘string’ array of all missing values of the given
     size.  If no input SZ is given, the result is a scalar missing
     string.

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

     ‘NaS’ is a convenience function which is strictly a wrapper around
     ‘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


File: tablicious.info,  Node: NaT,  Next: pp,  Prev: NaS,  Up: API Alphabetically

8.2.46 NaT
----------

 -- Function: OUT = NaT ()
 -- Function: OUT = NaT (SZ)

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

     Constructs a new ‘datetime’ array of all ‘NaT’ values of the given
     size.  If no input SZ is given, the result is a scalar ‘NaT’.

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

     ‘NaT’ currently cannot create NaT arrays of type ‘localdate’.  To
     do that, use *note localdate.NaT:: instead.


File: tablicious.info,  Node: pp,  Next: scalarexpand,  Prev: NaT,  Up: API Alphabetically

8.2.47 pp
---------

 -- Function: pp (X)
 -- Function: pp (A, B, C, ...)
 -- Function: pp ('A', 'B', 'C', ...)
 -- Function: pp A B C ...

     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.


File: tablicious.info,  Node: scalarexpand,  Next: seconds,  Prev: pp,  Up: API Alphabetically

8.2.48 scalarexpand
-------------------

 -- Function: [OUT1, OUT2, ..., OUTN] = scalarexpand (X1, X2, ..., 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.  ‘repmat’ is used to do the
     expansion.

     Works on any input types that support ‘size’, ‘isscalar’, and
     ‘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:

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


File: tablicious.info,  Node: seconds,  Next: size2str,  Prev: scalarexpand,  Up: API Alphabetically

8.2.49 seconds
--------------

 -- Function File: OUT = seconds (X)
     Create a ‘duration’ X seconds long, or get the seconds in a
     ‘duration’ X.

     If input is numeric, returns a ‘duration’ array that is that many
     seconds in time.

     If input is a ‘duration’, converts the ‘duration’ to a number of
     seconds.

     Returns an array the same size as X.


File: tablicious.info,  Node: size2str,  Next: splitapply,  Prev: seconds,  Up: API Alphabetically

8.2.50 size2str
---------------

 -- Function: OUT = size2str (SZ)

     Format an array size for display.

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

     SZ is an array of dimension sizes, in the format returned by the
     ‘size’ function.

     Returns a charvec.

     Examples:
          str = size2str (size (magic (4)))
              ⇒ str = 4-by-4


File: tablicious.info,  Node: splitapply,  Next: string,  Prev: size2str,  Up: API Alphabetically

8.2.51 splitapply
-----------------

 -- Function: OUT = splitapply (FUNC, X, G)
 -- Function: OUT = splitapply (FUNC, X1, ..., XN, G)
 -- Function: [Y1, ..., YM] = splitapply (...)

     Split data into groups and apply function.

     FUNC is a function handle to call on each group of inputs in turn.

     X, X1, ..., XN are the input variables that are split into groups
     for the function calls.  If X is a ‘table’, then its contained
     variables are “popped out” and considered to be the X1 ... XN input
     variables.

     G is the grouping variable vector.  It contains a list of integers
     that identify which group each element of the X input variables
     belongs to.  NaNs in 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 FUNC to each group.

     See also: *note table.groupby::, *note table.splitapply::


File: tablicious.info,  Node: string,  Next: struct2table,  Prev: splitapply,  Up: API Alphabetically

8.2.52 string
-------------

 -- 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:
        • Each element of a string array is a single string

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

        • Those characters are encoded in UTF-8

             • This last bit depends on the fact that Octave chars are
               UTF-8 now

     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:

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

       2. It adds ismissing() semantics.

       3. And it introduces Unicode support.

     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.

* Menu:

* string.cell::
* string.cellstr::
* string.char::
* string.cmp::
* string.decode::
* string.dispstrs::
* string.empty::
* string.encode::
* string.erase::
* string.ismissing::
* string.isnanny::
* string.isstring::
* string.lower::
* string.missing::
* string.plus::
* string.regexprep::
* string.reverse::
* string.reverse_bytes::
* string.strcat::
* string.strcmp::
* string.strfind::
* string.string::
* string.strlength::
* string.strlength_bytes::
* string.strrep::
* string.upper::


File: tablicious.info,  Node: string.cell,  Next: string.cellstr,  Up: string

8.2.52.1 string.cell
....................

 -- Method: OUT = cell (OBJ)

     Convert to cell array.

     Converts this to a cell, which will be a cellstr.  Missing values
     are converted to ‘''’.

     This method returns the same values as ‘cellstr(obj)’; it is just
     provided for interface compatibility purposes.

     Returns a cell array of the same size as OBJ.


File: tablicious.info,  Node: string.cellstr,  Next: string.char,  Prev: string.cell,  Up: string

8.2.52.2 string.cellstr
.......................

 -- Method: OUT = cellstr (OBJ)

     Convert to cellstr.

     Converts OBJ to a cellstr.  Missing values are converted to ‘''’.

     Returns a cellstr array of the same size as OBJ.


File: tablicious.info,  Node: string.char,  Next: string.cmp,  Prev: string.cellstr,  Up: string

8.2.52.3 string.char
....................

 -- Method: OUT = char (OBJ)

     Convert to char array.

     Converts OBJ to a 2-D char array.  It will have as many rows as OBJ
     has elements.

     It is an error to convert missing-valued ‘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.


File: tablicious.info,  Node: string.cmp,  Next: string.decode,  Prev: string.char,  Up: string

8.2.52.4 string.cmp
...................

 -- Method: [OUT, OUTA, OUTB] = cmp (A, B)

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

     Compares each element of A and B, returning for each element ‘i’
     whether ‘A(i)’ was less than (-1), equal to (0), or greater than
     (1) the corresponding ‘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 OUT of the same size as the scalar
     expansion of A and B.  Each value in it will be -1, 0, or 1.

     Also returns scalar-expanded copies of A and B as OUTA and OUTB, as
     a programming convenience.


File: tablicious.info,  Node: string.decode,  Next: string.dispstrs,  Prev: string.cmp,  Up: string

8.2.52.5 string.decode
......................

 -- Static Method: OUT = string.decode (BYTES, CHARSETNAME)

     Decode encoded text from bytes.

     Decodes the given encoded text in BYTES according to the specified
     encoding, given by CHARSETNAME.

     Returns a scalar string.

     See also: *note string.encode::


File: tablicious.info,  Node: string.dispstrs,  Next: string.empty,  Prev: string.decode,  Up: string

8.2.52.6 string.dispstrs
........................

 -- Method: OUT = dispstrs (OBJ)

     Display strings for array elements.

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

     Returns a cellstr of the same size as OBJ.


File: tablicious.info,  Node: string.empty,  Next: string.encode,  Prev: string.dispstrs,  Up: string

8.2.52.7 string.empty
.....................

 -- Function: OUT = empty (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.


File: tablicious.info,  Node: string.encode,  Next: string.erase,  Prev: string.empty,  Up: string

8.2.52.8 string.encode
......................

 -- Method: OUT = encode (OBJ, CHARSETNAME)

     Encode string in a given character encoding.

     OBJ must be scalar.

     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 ‘uint8’ vector.

     See also: *note string.decode::.


File: tablicious.info,  Node: string.erase,  Next: string.ismissing,  Prev: string.encode,  Up: string

8.2.52.9 string.erase
.....................

 -- Method: OUT = erase (OBJ, MATCH)

     Erase matching substring.

     Erases the substrings in OBJ which match the MATCH input.

     Returns a string array of the same size as OBJ.


File: tablicious.info,  Node: string.ismissing,  Next: string.isnanny,  Prev: string.erase,  Up: string

8.2.52.10 string.ismissing
..........................

 -- Method: OUT = ismissing (OBJ)

     Test whether array elements are missing.

     For ‘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 ‘obj’.


File: tablicious.info,  Node: string.isnanny,  Next: string.isstring,  Prev: string.ismissing,  Up: string

8.2.52.11 string.isnanny
........................

 -- Method: OUT = isnanny (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 OBJ.


File: tablicious.info,  Node: string.isstring,  Next: string.lower,  Prev: string.isnanny,  Up: string

8.2.52.12 string.isstring
.........................

 -- Method: OUT = isstring (OBJ)

     Test if input is a string array.

     ‘isstring’ is always true for ‘string’ inputs.

     Returns a scalar logical.


File: tablicious.info,  Node: string.lower,  Next: string.missing,  Prev: string.isstring,  Up: string

8.2.52.13 string.lower
......................

 -- Method: OUT = lower (OBJ)

     Convert to lower case.

     Converts all the characters in all the strings in OBJ to lower
     case.

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

     Returns a string array of the same size as OBJ.


File: tablicious.info,  Node: string.missing,  Next: string.plus,  Prev: string.lower,  Up: string

8.2.52.14 string.missing
........................

 -- Static Method: OUT = string.missing (SZ)

     Missing string value.

     Creates a string array of all-missing values of the specified size
     SZ.  If SZ is omitted, creates a scalar missing string.

     Returns a string array of size SZ or [1 1].

     See also: NaS


File: tablicious.info,  Node: string.plus,  Next: string.regexprep,  Prev: string.missing,  Up: string

8.2.52.15 string.plus
.....................

 -- Method: OUT = plus (A, 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


File: tablicious.info,  Node: string.regexprep,  Next: string.reverse,  Prev: string.plus,  Up: string

8.2.52.16 string.regexprep
..........................

 -- Method: OUT = regexprep (OBJ, PAT, REPSTR)
 -- Method: OUT = regexprep (..., VARARGIN)

     Replace based on regular expression matching.

     Replaces all the substrings matching a given regexp pattern PAT
     with the given replacement text REPSTR.

     Returns a string array of the same size as OBJ.


File: tablicious.info,  Node: string.reverse,  Next: string.reverse_bytes,  Prev: string.regexprep,  Up: string

8.2.52.17 string.reverse
........................

 -- Method: OUT = reverse (OBJ)

     Reverse string, character-wise.

     Reverses the characters in each string in 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 OBJ.


File: tablicious.info,  Node: string.reverse_bytes,  Next: string.strcat,  Prev: string.reverse,  Up: string

8.2.52.18 string.reverse_bytes
..............................

 -- Method: OUT = reverse_bytes (OBJ)

     Reverse string, byte-wise.

     Reverses the bytes in each string in 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 ‘string.reverse’ instead.

     Returns a string array the same size as OBJ.

     See also: *note string.reverse::


File: tablicious.info,  Node: string.strcat,  Next: string.strcmp,  Prev: string.reverse_bytes,  Up: string

8.2.52.19 string.strcat
.......................

 -- Method: OUT = strcat (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.


File: tablicious.info,  Node: string.strcmp,  Next: string.strfind,  Prev: string.strcat,  Up: string

8.2.52.20 string.strcmp
.......................

 -- Method: OUT = strcmp (A, 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 ‘A == B’, but is not polymorphic.
     Generally, there is no reason to use ‘strcmp’ instead of ‘==’ or
     ‘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.


File: tablicious.info,  Node: string.strfind,  Next: string.string,  Prev: string.strcmp,  Up: string

8.2.52.21 string.strfind
........................

 -- Method: OUT = strfind (OBJ, PATTERN)
 -- Method: OUT = strfind (..., VARARGIN)

     Find pattern in string.

     Finds the locations where PATTERN occurs in the strings of 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.


File: tablicious.info,  Node: string.string,  Next: string.strlength,  Prev: string.strfind,  Up: string

8.2.52.22 string.string
.......................

 -- Constructor: OBJ = string ()
 -- Constructor: OBJ = string (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.

        • chars and cellstrs are converted via cellstr()
        • numerics are converted via num2str()
        • datetimes are converted via datestr()


File: tablicious.info,  Node: string.strlength,  Next: string.strlength_bytes,  Prev: string.string,  Up: string

8.2.52.23 string.strlength
..........................

 -- Method: OUT = strlength (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
     ‘strlength_bytes’.

     Returns double array of the same size as OBJ.  Returns NaNs for
     missing strings.

     See also: *note string.strlength_bytes::


File: tablicious.info,  Node: string.strlength_bytes,  Next: string.strrep,  Prev: string.strlength,  Up: string

8.2.52.24 string.strlength_bytes
................................

 -- Method: OUT = strlength_bytes (OBJ)

     String length in bytes.

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

     Returns double array of the same size as OBJ.  Returns NaNs for
     missing strings.

     See also: *note string.strlength::


File: tablicious.info,  Node: string.strrep,  Next: string.upper,  Prev: string.strlength_bytes,  Up: string

8.2.52.25 string.strrep
.......................

 -- Method: OUT = strrep (OBJ, MATCH, REPLACEMENT)
 -- Method: OUT = strrep (..., VARARGIN)

     Replace occurrences of pattern with other string.

     Replaces matching substrings in OBJ with a given replacement
     string.

     VARARGIN is passed along to the core Octave ‘strrep’ function.
     This supports whatever options it does.  TODO: Maybe document what
     those options are.

     Returns a string array of the same size as OBJ.


File: tablicious.info,  Node: string.upper,  Prev: string.strrep,  Up: string

8.2.52.26 string.upper
......................

 -- Method: OUT = upper (OBJ)

     Convert to upper case.

     Converts all the characters in all the strings in OBJ to upper
     case.

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

     Returns a string array of the same size as OBJ.


File: tablicious.info,  Node: struct2table,  Next: table,  Prev: string,  Up: API Alphabetically

8.2.53 struct2table
-------------------

 -- Function: OUT = struct2table (S)
 -- Function: OUT = struct2table (..., 'AsArray', ASARRAY)

     Convert struct to a table.

     Converts the input struct S to a ‘table’.

     S may be a scalar struct or a nonscalar struct array.

     The ASARRAY option is not implemented yet.

     Returns a ‘table’.


File: tablicious.info,  Node: table,  Next: tableOuterFillValue,  Prev: struct2table,  Up: API Alphabetically

8.2.54 table
------------

 -- Class: table

     Tabular data array containing multiple columnar variables.

     A ‘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 NROWS-by-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 ‘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 ‘t.Properties.<property>’ for a table ‘t’.  That will give you a
     property instead of a variable.  (And due to this mechanism, it
     will cause problems if you have a ‘table’ with a variable named
     ‘Properties’.  Try to avoid that.)

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

 -- Instance Variable of table: cellstr VariableNames

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

 -- Instance Variable of table: cell VariableValues

     A cell vector containing the values for each of the variables.
     ‘VariableValues(i)’ corresponds to ‘VariableNames(i)’.

 -- Instance Variable of table: cellstr RowNames

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

* Menu:

* table.addvars::
* table.antijoin::
* table.cartesian::
* table.convertvars::
* table.findgroups::
* table.getvar::
* table.getvars::
* table.groupby::
* table.height::
* table.horzcat::
* table.innerjoin::
* table.intersect::
* table.isempty::
* table.ismember::
* table.ismissing::
* table.istable::
* table.join::
* table.mergevars::
* table.movevars::
* table.ndims::
* table.numel::
* table.outerfillvals::
* table.outerjoin::
* table.prettyprint::
* table.realjoin::
* table.removevars::
* table.renamevars::
* table.repelem::
* table.repmat::
* table.restrict::
* table.rowfun::
* table.rows2vars::
* table.semijoin::
* table.setdiff::
* table.setDimensionNames::
* table.setRowNames::
* table.setvar::
* table.setVariableNames::
* table.setxor::
* table.size::
* table.splitapply::
* table.splitvars::
* table.squeeze::
* table.stack::
* table.summary::
* table.table::
* table.table2array::
* table.table2cell::
* table.table2struct::
* table.union::
* table.varfun::
* table.varnames::
* table.vertcat::
* table.width::


File: tablicious.info,  Node: table.addvars,  Next: table.antijoin,  Up: table

8.2.54.1 table.addvars
......................

 -- Method: OUT = addvars (OBJ, VAR1, ..., VARN)
 -- Method: OUT = addvars (..., 'Before', BEFORE)
 -- Method: OUT = addvars (..., 'After', AFTER)
 -- Method: OUT = addvars (..., 'NewVariableNames', NEWVARIABLENAMES)

     Add variables to table.

     Adds the specified variables to a table.


File: tablicious.info,  Node: table.antijoin,  Next: table.cartesian,  Prev: table.addvars,  Up: table

8.2.54.2 table.antijoin
.......................

 -- Method: [OUTA, IXA, OUTB, IXB] = antijoin (A, 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: OUTA - all the rows in A with no matching row in B IXA -
     the row indexes into A which produced OUTA OUTB - all the rows in B
     with no matching row in A IXB - the row indexes into B which
     produced OUTB

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


File: tablicious.info,  Node: table.cartesian,  Next: table.convertvars,  Prev: table.antijoin,  Up: table

8.2.54.3 table.cartesian
........................

 -- Method: [OUT, IXS] = cartesian (A, 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.


File: tablicious.info,  Node: table.convertvars,  Next: table.findgroups,  Prev: table.cartesian,  Up: table

8.2.54.4 table.convertvars
..........................

 -- Method: OUT = convertvars (OBJ, VARS, DATATYPE)

     Convert variables to specified data type.

     Converts the variables in OBJ specified by VARS to the specified
     data type.

     VARS is a cellstr or numeric vector specifying which variables to
     convert.

     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 OBJ, but with
     converted types.


File: tablicious.info,  Node: table.findgroups,  Next: table.getvar,  Prev: table.convertvars,  Up: table

8.2.54.5 table.findgroups
.........................

 -- Method: [G, TID] = findgroups (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: G - A double column vector of group numbers created from
     OBJ.  TID - A table containing the row values corresponding to the
     group numbers.


File: tablicious.info,  Node: table.getvar,  Next: table.getvars,  Prev: table.findgroups,  Up: table

8.2.54.6 table.getvar
.....................

 -- Method: [OUT, NAME] = getvar (OBJ, VARREF)

     Get value and name for single table variable.

     VARREF is a variable reference.  It may be a name or an index.  It
     may only specify a single table variable.

     Returns: OUT – the value of the referenced table variable NAME –
     the name of the referenced table variable


File: tablicious.info,  Node: table.getvars,  Next: table.groupby,  Prev: table.getvar,  Up: table

8.2.54.7 table.getvars
......................

 -- Method: [OUT1, ...] = getvars (OBJ, VARREF)

     Get values for one ore more table variables.

     VARREF is a variable reference in the form of variable names or
     indexes.

     Returns as many outputs as VARREF referenced variables.  Each
     output contains the contents of the corresponding table variable.


File: tablicious.info,  Node: table.groupby,  Next: table.height,  Prev: table.getvars,  Up: table

8.2.54.8 table.groupby
......................

 -- Method: [OUT] = groupby (OBJ, GROUPVARS, AGGCALCS)

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

     This works like an SQL ‘"SELECT ... GROUP BY ..."’ statement.

     GROUPVARS (cellstr, numeric) is a list of the grouping variables,
     identified by name or index.

     AGGCALCS is a specification of the aggregate calculations to
     perform on them, in the form ‘{’OUT_VAR‘,’ FCN‘,’ IN_VARS‘; ...}’,
     where: OUT_VAR (char) is the name of the output variable FCN
     (function handle) is the function to apply to produce it 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.


File: tablicious.info,  Node: table.height,  Next: table.horzcat,  Prev: table.groupby,  Up: table

8.2.54.9 table.height
.....................

 -- Method: OUT = height (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.


File: tablicious.info,  Node: table.horzcat,  Next: table.innerjoin,  Prev: table.height,  Up: table

8.2.54.10 table.horzcat
.......................

 -- Method: OUT = horzcat (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 ‘varargin{1}’.  The variable names
     and values are the result of the concatenation of the variable
     names and values lists from the inputs.


File: tablicious.info,  Node: table.innerjoin,  Next: table.intersect,  Prev: table.horzcat,  Up: table

8.2.54.11 table.innerjoin
.........................

 -- Method: [OUT, IXA, IXB] = innerjoin (A, B)
 -- Method: [...] = innerjoin (A, B, ...)

     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: OUT - A table that is the result of joining A and B IX -
     Indexes into A for each row in out IXB - Indexes into B for each
     row in out


File: tablicious.info,  Node: table.intersect,  Next: table.isempty,  Prev: table.innerjoin,  Up: table

8.2.54.12 table.intersect
.........................

 -- Method: [C, IA, IB] = intersect (A, 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: C - A table containing all the unique row values present
     in both A and B. IA - Row indexes into A of the rows from A
     included in C. IB - Row indexes into B of the rows from B included
     in C.


File: tablicious.info,  Node: table.isempty,  Next: table.ismember,  Prev: table.intersect,  Up: table

8.2.54.13 table.isempty
.......................

 -- Method: OUT = isempty (OBJ)

     Test whether array is empty.

     For tables, ‘isempty’ is true if the number of rows is 0 or the
     number of variables is 0.


File: tablicious.info,  Node: table.ismember,  Next: table.ismissing,  Prev: table.isempty,  Up: table

8.2.54.14 table.ismember
........................

 -- Method: [TF, LOC] = ismember (A, B)

     Set membership.

     Finds rows in A that are members of B.

     Returns: TF - A logical vector indicating whether each A(i,:) was
     present in B. LOC - Indexes into B of rows that were found.


File: tablicious.info,  Node: table.ismissing,  Next: table.istable,  Prev: table.ismember,  Up: table

8.2.54.15 table.ismissing
.........................

 -- Method: OUT = ismissing (OBJ)
 -- Method: OUT = ismissing (OBJ, INDICATOR)

     Find missing values.

     Finds missing values in 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 ‘size(out) == size(obj)’.)

     Returns a logical array the same size as OBJ.


File: tablicious.info,  Node: table.istable,  Next: table.join,  Prev: table.ismissing,  Up: table

8.2.54.16 table.istable
.......................

 -- Method: TF = istable (OBJ)

     True if input is a table.


File: tablicious.info,  Node: table.join,  Next: table.mergevars,  Prev: table.istable,  Up: table

8.2.54.17 table.join
....................

 -- Method: [C, IB] = join (A, B)
 -- Method: [C, IB] = join (A, B, ...)

     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: *note table.innerjoin::, *note table.outerjoin::


File: tablicious.info,  Node: table.mergevars,  Next: table.movevars,  Prev: table.join,  Up: table

8.2.54.18 table.mergevars
.........................

 -- Method: OUT = mergevars (OBJ, VARS)
 -- Method: OUT = mergevars (..., 'NewVariableName', NEWVARIABLENAME)
 -- Method: OUT = mergevars (..., 'MergeAsTable', MERGEASTABLE)

     Merge table variables into a single variable.


File: tablicious.info,  Node: table.movevars,  Next: table.ndims,  Prev: table.mergevars,  Up: table

8.2.54.19 table.movevars
........................

 -- Method: OUT = movevars (OBJ, VARS, RELLOCATION, LOCATION)

     Move around variables in a table.

     VARS is a list of variables to move, specified by name or index.

     RELLOCATION is ‘'Before'’ or ‘'After'’.

     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 OBJ, not the
     original full list of variables in OBJ.

     Returns a table with the same variables as OBJ, but in a different
     order.


File: tablicious.info,  Node: table.ndims,  Next: table.numel,  Prev: table.movevars,  Up: table

8.2.54.20 table.ndims
.....................

 -- Method: OUT = ndims (OBJ)

     Number of dimensions

     For tables, ‘ndims(obj)’ is always 2, because table arrays are
     always 2-D (rows-by-columns).


File: tablicious.info,  Node: table.numel,  Next: table.outerfillvals,  Prev: table.ndims,  Up: table

8.2.54.21 table.numel
.....................

 -- Method: OUT = numel (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.


File: tablicious.info,  Node: table.outerfillvals,  Next: table.outerjoin,  Prev: table.numel,  Up: table

8.2.54.22 table.outerfillvals
.............................

 -- Method: OUT = outerfillvals (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.


File: tablicious.info,  Node: table.outerjoin,  Next: table.prettyprint,  Prev: table.outerfillvals,  Up: table

8.2.54.23 table.outerjoin
.........................

 -- Method: [OUT, IXA, IXB] = outerjoin (A, B)
 -- Method: [...] = outerjoin (A, B, ...)

     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: OUT - A table that is the result of the outer join of A
     and B IXA - indexes into A for each row in out IXB - indexes into B
     for each row in out


File: tablicious.info,  Node: table.prettyprint,  Next: table.realjoin,  Prev: table.outerjoin,  Up: table

8.2.54.24 table.prettyprint
...........................

 -- Method: prettyprint (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 ‘dispstrs’ method, if they define one.


File: tablicious.info,  Node: table.realjoin,  Next: table.removevars,  Prev: table.prettyprint,  Up: table

8.2.54.25 table.realjoin
........................

 -- Method: [OUT, IXS] = realjoin (A, B)
 -- Method: [...] = realjoin (A, B, ...)

     "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: KEYS, LEFTKEYS, RIGHTKEYS,
     LEFTVARIABLES, RIGHTVARIABLES.

     FIXME: Document those options.

     Returns: OUT - A table that is the result of joining A and B IXS -
     Indexes into A for each row in out


File: tablicious.info,  Node: table.removevars,  Next: table.renamevars,  Prev: table.realjoin,  Up: table

8.2.54.26 table.removevars
..........................

 -- Method: OUT = removevars (OBJ, VARS)

     Remove variables from table.

     Deletes the variables specified by VARS from OBJ.

     VARS may be a char, cellstr, numeric index vector, or logical index
     vector.


File: tablicious.info,  Node: table.renamevars,  Next: table.repelem,  Prev: table.removevars,  Up: table

8.2.54.27 table.renamevars
..........................

 -- Method: OUT = renamevars (OBJ, RENAMEMAP)

     Rename variables in a table.

     Renames selected variables in the table OBJ based on the mapping
     provided in RENAMEMAP.

     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 RENAMEMAP are not modified.

     It is an error if any variables named in the first column of
     RENAMEMAP are not present in OBJ.

     Renames


File: tablicious.info,  Node: table.repelem,  Next: table.repmat,  Prev: table.renamevars,  Up: table

8.2.54.28 table.repelem
.......................

 -- Method: OUT = repelem (OBJ, R)
 -- Method: OUT = repelem (OBJ, R_1, 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 ‘repelem’ on tables.


File: tablicious.info,  Node: table.repmat,  Next: table.restrict,  Prev: table.repelem,  Up: table

8.2.54.29 table.repmat
......................

 -- Method: OUT = repmat (OBJ, 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.


File: tablicious.info,  Node: table.restrict,  Next: table.rowfun,  Prev: table.repmat,  Up: table

8.2.54.30 table.restrict
........................

 -- Method: OUT = restrict (OBJ, EXPR)
 -- Method: OUT = restrict (OBJ, IX)

     Subset rows using variable expression or index.

     Subsets a table row-wise, using either an index vector or an
     expression involving 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 ‘tblish.evalWithTableVars’.  The output of expr
     must be a numeric or logical index vector (This form is a shorthand
     for ‘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:
          [s,p,sp] = tblish.examples.SpDb;
          prettyprint (restrict (p, 'Weight >= 14 & strcmp(Color, "Red")'))

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

     See also: tblish.evalWithTableVars


File: tablicious.info,  Node: table.rowfun,  Next: table.rows2vars,  Prev: table.restrict,  Up: table

8.2.54.31 table.rowfun
......................

 -- Method: OUT = varfun (FUNC, OBJ)
 -- Method: OUT = varfun (..., 'OptionName', OPTIONVALUE, ...)

     Apply function to rows in table and collect outputs.

     This applies the function FUNC to the elements of each row of OBJ’s
     variables, and collects the concatenated output(s) into the
     variable(s) of a new table.

     FUNC is a function handle.  It should take as many inputs as there
     are variables in OBJ.  Or, it can take a single input, and you must
     specify ‘'SeparateInputs', false’ to have the input variables
     concatenated before being passed to FUNC.  It may return multiple
     argouts, but to capture those past the first one, you must
     explicitly specify the ‘'NumOutputs'’ or ‘'OutputVariableNames'’
     options.

     Supported name/value options:
     ‘'OutputVariableNames'’
          Names of table variables to store combined function output
          arguments in.
     ‘'NumOutputs'’
          Number of output arguments to call function with.  If omitted,
          defaults to number of items in OUTPUTVARIABLENAMES if it is
          supplied, otherwise defaults to 1.
     ‘'SeparateInputs'’
          If true, input variables are passed as separate input
          arguments to FUNC.  If false, they are concatenated together
          into a row vector and passed as a single argument.  Defaults
          to true.
     ‘'ErrorHandler'’
          A function to call as a fallback when calling FUNC results in
          an error.  It is passed the caught exception, along with the
          original inputs passed to 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.
     ‘'ExtractCellContents'’
          Whether to “pop out” the contents of the elements of cell
          variables in OBJ, or to leave them as cells.  True/false;
          default is false.  If you specify this option, then OBJ may
          not have any multi-column cell-valued variables.
     ‘'InputVariables'’
          If specified, only these variables from OBJ are used as the
          function inputs, instead of using all variables.
     ‘'GroupingVariables'’
          Not yet implemented.
     ‘'OutputFormat'’
          The format of the output.  May be ‘'table'’ (the default),
          ‘'uniform'’, or ‘'cell'’.  If it is ‘'uniform'’ or ‘'cell'’,
          the output variables are returned in multiple output arguments
          from ‘'rowfun'’.

     Returns a ‘table’ whose variables are the collected output
     arguments of FUNC if OUTPUTFORMAT is ‘'table'’.  Otherwise, returns
     multiple output arguments of whatever type FUNC returned (if
     OUTPUTFORMAT is ‘'uniform'’) or cells (if OUTPUTFORMAT is
     ‘'cell'’).


File: tablicious.info,  Node: table.rows2vars,  Next: table.semijoin,  Prev: table.rowfun,  Up: table

8.2.54.32 table.rows2vars
.........................

 -- Method: OUT = rows2vars (OBJ)
 -- Method: OUT = rows2vars (OBJ, 'VariableNamesSource',
          VARIABLENAMESSOURCE)
 -- Method: OUT = rows2vars (..., 'DataVariables', DATAVARIABLES)

     Reorient table, swapping rows and variables dimensions.

     This flips the dimensions of the given table 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 VARIABLENAMESSOURCE if it
     is specified.  Otherwise, if OBJ has row names, they are used.
     Otherwise, new variable names in the form “VarN” are generated.

     If all the variables in 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.


File: tablicious.info,  Node: table.semijoin,  Next: table.setdiff,  Prev: table.rows2vars,  Up: table

8.2.54.33 table.semijoin
........................

 -- Method: [OUTA, IXA, OUTB, IXB] = semijoin (A, 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: OUTA - all the rows in A with matching row(s) in B IXA -
     the row indexes into A which produced OUTA OUTB - all the rows in B
     with matching row(s) in A IXB - the row indexes into B which
     produced OUTB

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


File: tablicious.info,  Node: table.setdiff,  Next: table.setDimensionNames,  Prev: table.semijoin,  Up: table

8.2.54.34 table.setdiff
.......................

 -- Method: [C, IA] = setdiff (A, 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: C - A table containing the unique row values in A that
     were not in B. IA - Row indexes into A of the rows from A included
     in C.


File: tablicious.info,  Node: table.setDimensionNames,  Next: table.setRowNames,  Prev: table.setdiff,  Up: table

8.2.54.35 table.setDimensionNames
.................................

 -- Method: OUT = setDimensionNames (OBJ, NAMES)
 -- Method: OUT = setDimensionNames (OBJ, IX, NAMES)

     Set dimension names.

     Sets the ‘DimensionNames’ for this table to a new list of names.

     NAMES is a char or cellstr vector.  It must have the same number of
     elements as the number of dimension names being assigned.

     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 IX may never be higher than 2.

     This method exists because the ‘obj.Properties.DimensionNames =
     ...’ assignment form does not work, possibly due to an Octave bug.


File: tablicious.info,  Node: table.setRowNames,  Next: table.setvar,  Prev: table.setDimensionNames,  Up: table

8.2.54.36 table.setRowNames
...........................

 -- Method: OUT = setRowNames (OBJ, NAMES)

     Set row names.

     Sets the row names on OBJ to NAMES.

     NAMES is a cellstr column vector, with the same number of rows as
     OBJ has.


File: tablicious.info,  Node: table.setvar,  Next: table.setVariableNames,  Prev: table.setRowNames,  Up: table

8.2.54.37 table.setvar
......................

 -- Method: OUT = setvar (OBJ, VARREF, VALUE)

     Set value for a variable in table.

     This sets (adds or replaces) the value for a variable in 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 ‘obj.foo = value’
     to work, apparently due to an issue with Octave's subsasgn support.

     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.

     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 OBJ.


File: tablicious.info,  Node: table.setVariableNames,  Next: table.setxor,  Prev: table.setvar,  Up: table

8.2.54.38 table.setVariableNames
................................

 -- Method: OUT = setVariableNames (OBJ, NAMES)
 -- Method: OUT = setVariableNames (OBJ, IX, NAMES)

     Set variable names.

     Sets the ‘VariableNames’ for this table to a new list of names.

     NAMES is a char or cellstr vector.  It must have the same number of
     elements as the number of variable names being assigned.

     IX is an index vector indicating which variable names to set.  If
     omitted, it sets all of them present in OBJ.

     This method exists because the ‘obj.Properties.VariableNames = ...’
     assignment form does not work, possibly due to an Octave bug.


File: tablicious.info,  Node: table.setxor,  Next: table.size,  Prev: table.setVariableNames,  Up: table

8.2.54.39 table.setxor
......................

 -- Method: [C, IA, IB] = setxor (A, 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: C - A table containing all the unique row values in the
     set XOR of A and B. IA - Row indexes into A of the rows from A
     included in C. IB - Row indexes into B of the rows from B included
     in C.


File: tablicious.info,  Node: table.size,  Next: table.splitapply,  Prev: table.setxor,  Up: table

8.2.54.40 table.size
....................

 -- Method: SZ = size (OBJ)
 -- Method: [NR, NV] = size (OBJ)
 -- Method: [NR, NV, ...] = size (OBJ)

     Gets the size of a table.

     For tables, the size is [number-of-rows x number-of-variables].
     This is the same as ‘[height(obj), width(obj)]’.


File: tablicious.info,  Node: table.splitapply,  Next: table.splitvars,  Prev: table.size,  Up: table

8.2.54.41 table.splitapply
..........................

 -- Method: OUT = splitapply (FUNC, OBJ, G)
 -- Method: [Y1, ..., YM] = splitapply (FUNC, OBJ, G)

     Split table data into groups and apply function.

     Performs a splitapply, using the variables in OBJ as the input X
     variables to the ‘splitapply’ function call.

     See also: splitapply, table.groupby, tblish.table.grpstats


File: tablicious.info,  Node: table.splitvars,  Next: table.squeeze,  Prev: table.splitapply,  Up: table

8.2.54.42 table.splitvars
.........................

 -- Method: OUT = splitvars (OBJ)
 -- Method: OUT = splitvars (OBJ, VARS)
 -- Method: OUT = splitvars (..., 'NewVariableNames', NEWVARIABLENAMES)

     Split multicolumn table variables.

     Splits multicolumn table variables into new single-column
     variables.  If VARS is supplied, splits only those variables.  If
     VARS is not supplied, splits all multicolumn variables.


File: tablicious.info,  Node: table.squeeze,  Next: table.stack,  Prev: table.splitvars,  Up: table

8.2.54.43 table.squeeze
.......................

 -- Method: OBJ = squeeze (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.


File: tablicious.info,  Node: table.stack,  Next: table.summary,  Prev: table.squeeze,  Up: table

8.2.54.44 table.stack
.....................

 -- Method: OUT = stack (OBJ, VARS)
 -- Method: OUT = stack (..., 'NewDataVariableName',
          NEWDATAVARIABLENAME)
 -- Method: OUT = stack (..., 'IndexVariableName', INDEXVARIABLENAME)

     Stack multiple table variables into a single variable.


File: tablicious.info,  Node: table.summary,  Next: table.table,  Prev: table.stack,  Up: table

8.2.54.45 table.summary
.......................

 -- Method: summary (OBJ)

     Summary of table's data.

     Displays a summary of data in the input table.  This will contain
     some statistical information on each of its variables.


File: tablicious.info,  Node: table.table,  Next: table.table2array,  Prev: table.summary,  Up: table

8.2.54.46 table.table
.....................

 -- Constructor: OBJ = table ()

     Constructs a new empty (0 rows by 0 variables) table.

 -- Constructor: OBJ = table (VAR1, VAR2, ..., 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.

 -- Constructor: OBJ = table ('Size', SZ, 'VariableTypes', 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.

 -- Constructor: OBJ = table (..., 'VariableNames', VARNAMES)
 -- Constructor: OBJ = table (..., 'RowNames', ROWNAMES)

     Specifies the variable names or row names to use in the constructed
     table.  Overrides the implicit names garnered from the input
     variable names.


File: tablicious.info,  Node: table.table2array,  Next: table.table2cell,  Prev: table.table,  Up: table

8.2.54.47 table.table2array
...........................

 -- Method: S = table2struct (OBJ)

     Converts OBJ to a homogeneous array.


File: tablicious.info,  Node: table.table2cell,  Next: table.table2struct,  Prev: table.table2array,  Up: table

8.2.54.48 table.table2cell
..........................

 -- Method: C = table2cell (OBJ)

     Converts table to a cell array.  Each variable in 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 OBJ, and with
     as many or more columns as OBJ has variables.


File: tablicious.info,  Node: table.table2struct,  Next: table.union,  Prev: table.table2cell,  Up: table

8.2.54.49 table.table2struct
............................

 -- Method: S = table2struct (OBJ)
 -- Method: S = table2struct (..., 'ToScalar', TRUEORFALSE)

     Converts 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 ‘ToScalar’ option.


File: tablicious.info,  Node: table.union,  Next: table.varfun,  Prev: table.table2struct,  Up: table

8.2.54.50 table.union
.....................

 -- Method: [C, IA, IB] = union (A, 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: C - A table containing all the unique row values present
     in A or B. IA - Row indexes into A of the rows from A included in
     C. IB - Row indexes into B of the rows from B included in C.


File: tablicious.info,  Node: table.varfun,  Next: table.varnames,  Prev: table.union,  Up: table

8.2.54.51 table.varfun
......................

 -- Method: OUT = varfun (FCN, OBJ)
 -- Method: OUT = varfun (..., 'OutputFormat', OUTPUTFORMAT)
 -- Method: OUT = varfun (..., 'InputVariables', VARS)
 -- Method: OUT = varfun (..., 'ErrorHandler', ERRORFCN)

     Apply function to table variables.

     Applies the given function FCN to each variable in OBJ, collecting
     the output in a table, cell array, or array of another type.


File: tablicious.info,  Node: table.varnames,  Next: table.vertcat,  Prev: table.varfun,  Up: table

8.2.54.52 table.varnames
........................

 -- Method: OUT = varnames (OBJ)
 -- Method: OUT = varnames (OBJ, VARNAMES)

     Get or set variable names for a table.

     Returns cellstr in the getter form.  Returns an updated datetime in
     the setter form.


File: tablicious.info,  Node: table.vertcat,  Next: table.width,  Prev: table.varnames,  Up: table

8.2.54.53 table.vertcat
.......................

 -- Method: OUT = vertcat (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.


File: tablicious.info,  Node: table.width,  Prev: table.vertcat,  Up: table

8.2.54.54 table.width
.....................

 -- Method: OUT = width (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.


File: tablicious.info,  Node: tableOuterFillValue,  Next: tail,  Prev: table,  Up: API Alphabetically

8.2.55 tableOuterFillValue
--------------------------

_Not documented_


File: tablicious.info,  Node: tail,  Next: tblish.dataset,  Prev: tableOuterFillValue,  Up: API Alphabetically

8.2.56 tail
-----------

 -- Function: OUT = tail (A)
 -- Function: OUT = tail (A, K)

     Get last K rows of an array.

     Returns the array A, subsetted to its last K rows.  This means
     subsetting it to the last ‘(min (k, size (A, 1)))’ elements along
     dimension 1, and leaving all other dimensions unrestricted.

     A is the array to subset.

     K is the number of rows to get.  K defaults to 8 if it is omitted
     or empty.

     If there are less than K rows in A, returns all rows.

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

     See also: head


File: tablicious.info,  Node: tblish.dataset,  Next: tblish.datasets,  Prev: tail,  Up: API Alphabetically

8.2.57 tblish.dataset
---------------------

 -- Class: tblish.dataset

     The ‘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.

* Menu:

* tblish.dataset.airmiles::
* tblish.dataset.AirPassengers::
* tblish.dataset.airquality::
* tblish.dataset.anscombe::
* tblish.dataset.attenu::
* tblish.dataset.attitude::
* tblish.dataset.austres::
* tblish.dataset.beavers::
* tblish.dataset.BJsales::
* tblish.dataset.BOD::
* tblish.dataset.cars::
* tblish.dataset.ChickWeight::
* tblish.dataset.chickwts::
* tblish.dataset.co2::
* tblish.dataset.crimtab::
* tblish.dataset.cupcake::
* tblish.dataset.discoveries::
* tblish.dataset.DNase::
* tblish.dataset.esoph::
* tblish.dataset.euro::
* tblish.dataset.eurodist::
* tblish.dataset.EuStockMarkets::
* tblish.dataset.faithful::
* tblish.dataset.Formaldehyde::
* tblish.dataset.freeny::
* tblish.dataset.HairEyeColor::
* tblish.dataset.Harman23cor::
* tblish.dataset.Harman74cor::
* tblish.dataset.Indometh::
* tblish.dataset.infert::
* tblish.dataset.InsectSprays::
* tblish.dataset.iris::
* tblish.dataset.islands::
* tblish.dataset.JohnsonJohnson::
* tblish.dataset.LakeHuron::
* tblish.dataset.lh::
* tblish.dataset.LifeCycleSavings::
* tblish.dataset.Loblolly::
* tblish.dataset.longley::
* tblish.dataset.lynx::
* tblish.dataset.morley::
* tblish.dataset.mtcars::
* tblish.dataset.nhtemp::
* tblish.dataset.Nile::
* tblish.dataset.nottem::
* tblish.dataset.npk::
* tblish.dataset.occupationalStatus::
* tblish.dataset.Orange::
* tblish.dataset.OrchardSprays::
* tblish.dataset.PlantGrowth::
* tblish.dataset.precip::
* tblish.dataset.presidents::
* tblish.dataset.pressure::
* tblish.dataset.Puromycin::
* tblish.dataset.quakes::
* tblish.dataset.randu::
* tblish.dataset.rivers::
* tblish.dataset.rock::
* tblish.dataset.sleep::
* tblish.dataset.stackloss::
* tblish.dataset.state::
* tblish.dataset.sunspot_month::
* tblish.dataset.sunspot_year::
* tblish.dataset.sunspots::
* tblish.dataset.swiss::
* tblish.dataset.Theoph::
* tblish.dataset.Titanic::
* tblish.dataset.ToothGrowth::
* tblish.dataset.treering::
* tblish.dataset.trees::
* tblish.dataset.UCBAdmissions::
* tblish.dataset.UKDriverDeaths::
* tblish.dataset.UKgas::
* tblish.dataset.UKLungDeaths::
* tblish.dataset.USAccDeaths::
* tblish.dataset.USArrests::
* tblish.dataset.USJudgeRatings::
* tblish.dataset.USPersonalExpenditure::
* tblish.dataset.uspop::
* tblish.dataset.VADeaths::
* tblish.dataset.volcano::
* tblish.dataset.warpbreaks::
* tblish.dataset.women::
* tblish.dataset.WorldPhones::
* tblish.dataset.WWWusage::
* tblish.dataset.zCO2::


File: tablicious.info,  Node: tblish.dataset.airmiles,  Next: tblish.dataset.AirPassengers,  Up: tblish.dataset

8.2.57.1 tblish.dataset.airmiles
................................

 -- Static Method: OUT = airmiles ()

     Passenger Miles on Commercial US Airlines, 1937-1960

     Description
     ...........

     The revenue passenger miles flown by commercial airlines in the
     United States for each year from 1937 to 1960.

     Source
     ......

     ‘F.A.A. Statistical Handbook of Aviation’.

     Examples
     ........

          t = tblish.dataset.airmiles;
          plot (t.year, t.miles);
          title ("airmiles data");
          xlabel ("Passenger-miles flown by U.S. commercial airlines")
          ylabel ("airmiles");



File: tablicious.info,  Node: tblish.dataset.AirPassengers,  Next: tblish.dataset.airquality,  Prev: tblish.dataset.airmiles,  Up: tblish.dataset

8.2.57.2 tblish.dataset.AirPassengers
.....................................

 -- Static Method: OUT = AirPassengers ()

     Monthly Airline Passenger Numbers 1949-1960

     Description
     ...........

     The classic Box & Jenkins airline data.  Monthly totals of
     international airline passengers, 1949 to 1960.

     Source
     ......

     Box, G. E. P., Jenkins, G. M. and Reinsel, G. C. (1976).  ‘Time
     Series Analysis, Forecasting and Control’.  Third Edition.  San
     Francisco: Holden-Day.  Series G.

     Examples
     ........

          ## TODO: This example needs to be ported from R.



File: tablicious.info,  Node: tblish.dataset.airquality,  Next: tblish.dataset.anscombe,  Prev: tblish.dataset.AirPassengers,  Up: tblish.dataset

8.2.57.3 tblish.dataset.airquality
..................................

 -- Static Method: OUT = airquality ()

     New York Air Quality Measurements from 1973

     Description
     ...........

     Daily air quality measurements in New York, May to September 1973.

     Format
     ......

     ‘Ozone’
          Ozone concentration (ppb)
     ‘SolarR’
          Solar R (lang)
     ‘Wind’
          Wind (mph)
     ‘Temp’
          Temperature (degrees F)
     ‘Month’
          Month (1-12)
     ‘Day’
          Day of month (1-31)

     Source
     ......

     New York State Department of Conservation (ozone data) and the
     National Weather Service (meteorological data).

     References
     ..........

     Chambers, J. M., Cleveland, W. S., Kleiner, B. and Tukey, P. A.
     (1983).  ‘Graphical Methods for Data Analysis’.  Belmont, CA:
     Wadsworth.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.anscombe,  Next: tblish.dataset.attenu,  Prev: tblish.dataset.airquality,  Up: tblish.dataset

8.2.57.4 tblish.dataset.anscombe
................................

 -- Static Method: OUT = anscombe ()

     Anscombe’s Quartet of “Identical” Simple Linear Regressions

     Description
     ...........

     Four sets of x/y pairs which have the same statistical properties,
     but are very different.

     Format
     ......

     The data comes in an array of 4 structs, each with fields as
     follows:

     ‘x’
          The X values for this pair.
     ‘y’
          The Y values for this pair.

     Source
     ......

     Tufte, Edward R. (1989).  ‘The Visual Display of Quantitative
     Information’.  13–14.  Cheshire, CT: Graphics Press.

     References
     ..........

     Anscombe, Francis J. (1973).  Graphs in statistical analysis.  ‘The
     American Statistician’, 27, 17–21.

     Examples
     ........

          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);



File: tablicious.info,  Node: tblish.dataset.attenu,  Next: tblish.dataset.attitude,  Prev: tblish.dataset.anscombe,  Up: tblish.dataset

8.2.57.5 tblish.dataset.attenu
..............................

 -- Static Method: OUT = attenu ()

     Joyner-Boore Earthquake Attenuation Data

     Description
     ...........

     Event data for 23 earthquakes in California, showing peak
     accelerations.

     Format
     ......

     ‘event’
          Event number
     ‘mag’
          Moment magnitude
     ‘station’
          Station identifier
     ‘dist’
          Station-hypocenter distance (km)
     ‘accel’
          Peak acceleration (g)

     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.

     References
     ..........

     Boore, D. M. and Joyner, W. B. (1982).  The empirical prediction of
     ground motion.  ‘Bulletin of the Seismological Society of America’,
     72, S269–S268.

     Examples
     ........

          # 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.


File: tablicious.info,  Node: tblish.dataset.attitude,  Next: tblish.dataset.austres,  Prev: tblish.dataset.attenu,  Up: tblish.dataset

8.2.57.6 tblish.dataset.attitude
................................

 -- Static Method: OUT = attitude ()

     The Chatterjee-Price Attitude Data

     Description
     ...........

     Aggregated data from a survey of clerical employees at a large
     financial organization.

     Format
     ......

     ‘rating’
          Overall rating.
     ‘complaints’
          Handling of employee complaints.
     ‘privileges’
          Does not allow special privileges.
     ‘learning’
          Opportunity to learn.
     ‘raises’
          Raises based on performance.
     ‘critical’
          Too critical.
     ‘advance’
          Advancement.

     Source
     ......

     Chatterjee, S. and Price, B. (1977).  ‘Regression Analysis by
     Example’.  New York: Wiley.  (Section 3.7, p.68ff of 2nd
     ed.(1991).)

     Examples
     ........

          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




File: tablicious.info,  Node: tblish.dataset.austres,  Next: tblish.dataset.beavers,  Prev: tblish.dataset.attitude,  Up: tblish.dataset

8.2.57.7 tblish.dataset.austres
...............................

 -- Static Method: OUT = austres ()

     Australian Population

     Description
     ...........

     Numbers of Australian residents measured quarterly from March 1971
     to March 1994.

     Format
     ......

     ‘date’
          The month of the observation.
     ‘residents’
          The number of residents.

     Source
     ......

     Brockwell, P. J. and Davis, R. A. (1996).  ‘Introduction to Time
     Series and Forecasting’.  New York: Springer-Verlag.

     Examples
     ........

          t = tblish.dataset.austres

          plot (datenum (t.date), t.residents);
          datetick x
          xlabel ("Month"); ylabel ("Residents"); title ("Australian Residents");



File: tablicious.info,  Node: tblish.dataset.beavers,  Next: tblish.dataset.BJsales,  Prev: tblish.dataset.austres,  Up: tblish.dataset

8.2.57.8 tblish.dataset.beavers
...............................

 -- Static Method: OUT = beavers ()

     Body Temperature Series of Two Beavers

     Description
     ...........

     Body temperature readings for two beavers.

     Format
     ......

     ‘day’
          Day of observation (in days since the beginning of 1990),
          December 12–13 (beaver1) and November 3–4 (beaver2).
     ‘time’
          Time of observation, in the form 0330 for 3:30am
     ‘temp’
          Measured body temperature in degrees Celsius.
     ‘activ’
          Indicator of activity outside the retreat.

     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)
     ‘Case Studies in Biometry’.  New York: John Wiley and Sons.

     Examples
     ........

          # TODO: This example needs to be ported from R.


File: tablicious.info,  Node: tblish.dataset.BJsales,  Next: tblish.dataset.BOD,  Prev: tblish.dataset.beavers,  Up: tblish.dataset

8.2.57.9 tblish.dataset.BJsales
...............................

 -- Static Method: OUT = BJsales ()

     Sales Data with Leading Indicator

     Description
     ...........

     Sales Data with Leading Indicator

     Format
     ......

     ‘record’
          Index of the record.
     ‘lead’
          Leading indicator.
     ‘sales’
          Sales volume.

     Source
     ......

     The data are given in Box & Jenkins (1976).  Obtained from the Time
     Series Data Library at
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>.

     References
     ..........

     Box, G. E. P. and Jenkins, G. M. (1976).  ‘Time Series Analysis,
     Forecasting and Control’.  San Francisco: Holden-Day.  p.  537.

     Brockwell, P. J. and Davis, R. A. (1991).  ‘Time Series: Theory and
     Methods’, Second edition.  New York: Springer-Verlag.  p.  414.

     Examples
     ........

          # TODO: Come up with example code here



File: tablicious.info,  Node: tblish.dataset.BOD,  Next: tblish.dataset.cars,  Prev: tblish.dataset.BJsales,  Up: tblish.dataset

8.2.57.10 tblish.dataset.BOD
............................

 -- Static Method: OUT = BOD ()

     Biochemical Oxygen Demand

     Description
     ...........

     Contains biochemical oxygen demand versus time in an evaluation of
     water quality.

     Format
     ......

     ‘Time’
          Time of the measurement (in days).
     ‘demand’
          Biochemical oxygen demand (mg/l).

     Source
     ......

     Bates, D.M. and Watts, D.G. (1988).  ‘Nonlinear Regression Analysis
     and Its Applications’.  New York: John Wiley & Sons.  Appendix
     A1.4.

     Originally from: Marske (1967).  ‘Biochemical Oxygen Demand Data
     Interpretation Using Sum of Squares Surface’, M.Sc.  Thesis,
     University of Wisconsin – Madison.

     Examples
     ........

          # TODO: Port this example from R



File: tablicious.info,  Node: tblish.dataset.cars,  Next: tblish.dataset.ChickWeight,  Prev: tblish.dataset.BOD,  Up: tblish.dataset

8.2.57.11 tblish.dataset.cars
.............................

 -- Static Method: OUT = cars ()

     Speed and Stopping Distances of Cars

     Description
     ...........

     Speed of cars and distances taken to stop.  Note that the data were
     recorded in the 1920s.

     Format
     ......

     ‘speed’
          Speed (mph).
     ‘dist’
          Stopping distance (ft).

     Source
     ......

     Ezekiel, M. (1930).  ‘Methods of Correlation Analysis’.  New York:
     Wiley.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........


          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




File: tablicious.info,  Node: tblish.dataset.ChickWeight,  Next: tblish.dataset.chickwts,  Prev: tblish.dataset.cars,  Up: tblish.dataset

8.2.57.12 tblish.dataset.ChickWeight
....................................

 -- Static Method: OUT = ChickWeight ()

     Weight versus age of chicks on different diets

     Format
     ......

     ‘weight’
          a numeric vector giving the body weight of the chick (gm).
     ‘Time’
          a numeric vector giving the number of days since birth when
          the measurement was made.
     ‘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.
     ‘Diet’
          a factor with levels 1, ..., 4 indicating which experimental
          diet the chick received.

     Source
     ......

     Crowder, M. and Hand, D. (1990).  ‘Analysis of Repeated Measures’.
     London: Chapman and Hall.  (example 5.3)

     Hand, D. and Crowder, M. (1996), ‘Practical Longitudinal Data
     Analysis’.  London: Chapman and Hall.  (table A.2)

     Pinheiro, J. C. and Bates, D. M. (2000) ‘Mixed-effects Models in S
     and S-PLUS’. New York: Springer.

     Examples
     ........

          t = tblish.dataset.ChickWeight

          tblish.examples.coplot (t, "Time", "weight", "Chick");



File: tablicious.info,  Node: tblish.dataset.chickwts,  Next: tblish.dataset.co2,  Prev: tblish.dataset.ChickWeight,  Up: tblish.dataset

8.2.57.13 tblish.dataset.chickwts
.................................

 -- Static Method: OUT = chickwts ()

     Chicken Weights by Feed Type

     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.

     Format
     ......

     ‘weight’
          Chick weight at six weeks (gm).
     ‘feed’
          Feed type.

     Source
     ......

     Anonymous (1948) ‘Biometrika’, 35, 214.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          # 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



File: tablicious.info,  Node: tblish.dataset.co2,  Next: tblish.dataset.crimtab,  Prev: tblish.dataset.chickwts,  Up: tblish.dataset

8.2.57.14 tblish.dataset.co2
............................

 -- Static Method: OUT = co2 ()

     Mauna Loa Atmospheric CO2 Concentration

     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.

     Format
     ......

     ‘date’
          Date of the month of the observation, as datetime.
     ‘co2’
          CO2 concentration (ppm).

     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.

     Source
     ......

     Keeling, C. D. and Whorf, T. P., Scripps Institution of
     Oceanography (SIO), University of California, La Jolla, California
     USA 92093-0220.

     <ftp://cdiac.esd.ornl.gov/pub/maunaloa-co2/maunaloa.co2>.

     References
     ..........

     Cleveland, W. S. (1993).  ‘Visualizing Data’.  New Jersey: Summit
     Press.

     Examples
     ........

          t = tblish.dataset.co2;

          plot (datenum (t.date), t.co2);
          datetick ("x");
          xlabel ("Time"); ylabel ("Atmospheric concentration of CO2");
          title ("co2 data set");



File: tablicious.info,  Node: tblish.dataset.crimtab,  Next: tblish.dataset.cupcake,  Prev: tblish.dataset.co2,  Up: tblish.dataset

8.2.57.15 tblish.dataset.crimtab
................................

 -- Static Method: OUT = crimtab ()

     Student’s 3000 Criminals Data

     Description
     ...........

     Data of 3000 male criminals over 20 years old undergoing their
     sentences in the chief prisons of England and Wales.

     Format
     ......

     This dataset contains three separate variables.  The
     ‘finger_length’ and ‘body_height’ variables correspond to the rows
     and columns of the ‘count’ matrix.

     ‘finger_length’
          Midpoints of intervals of finger lengths (cm).
     ‘body_height’
          Body heights (cm).
     ‘count’
          Number of prisoners in this bin.

     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.”

     Source
     ......

     <http://pbil.univ-lyon1.fr/R/donnees/criminals1902.txt> thanks to
     Jean R. Lobry and Anne-Béatrice Dufour.

     References
     ..........

     Garson, J.G. (1900).  The metric system of identification of
     criminals, as used in in Great Britain and Ireland.  ‘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.  ‘Biometrika’, 1(2), 177–227.

     Student (1908).  The probable error of a mean.  ‘Biometrika’, 6,
     1–25.

     Examples
     ........

          # TODO: Port this from R



File: tablicious.info,  Node: tblish.dataset.cupcake,  Next: tblish.dataset.discoveries,  Prev: tblish.dataset.crimtab,  Up: tblish.dataset

8.2.57.16 tblish.dataset.cupcake
................................

 -- Static Method: OUT = cupcake ()

     Google Search popularity for "cupcake", 2004-2019

     Description
     ...........

     Monthly popularity of worldwide Google search results for
     "cupcake", 2004-2019.

     Format
     ......

     ‘Month’
          Month when searches took place
     ‘Cupcake’
          An indicator of search volume, in unknown units

     Source
     ......

     Google Trends,
     <https://trends.google.com/trends/explore?q=%2Fm%2F03p1r4&date=all>,
     retrieved 2019-05-04 by Andrew Janke.

     Examples
     ........

          t = tblish.dataset.cupcake
          plot (datenum (t.Month), t.Cupcake)
          title ('“Cupcake” Google Searches'); xlabel ("Year"); ylabel ("Unknown popularity metric");



File: tablicious.info,  Node: tblish.dataset.discoveries,  Next: tblish.dataset.DNase,  Prev: tblish.dataset.cupcake,  Up: tblish.dataset

8.2.57.17 tblish.dataset.discoveries
....................................

 -- Static Method: OUT = discoveries ()

     Yearly Numbers of Important Discoveries

     Description
     ...........

     The numbers of “great” inventions and scientific discoveries in
     each year from 1860 to 1959.

     Format
     ......

     ‘year’
          Year.
     ‘discoveries’
          Number of “great” discoveries that year.

     Source
     ......

     ‘The World Almanac and Book of Facts’, 1975 Edition, pages 315–318.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.discoveries;

          plot (t.year, t.discoveries);
          xlabel ("Time"); ylabel ("Number of important discoveries");
          title ("discoveries data set");



File: tablicious.info,  Node: tblish.dataset.DNase,  Next: tblish.dataset.esoph,  Prev: tblish.dataset.discoveries,  Up: tblish.dataset

8.2.57.18 tblish.dataset.DNase
..............................

 -- Static Method: OUT = DNase ()

     Elisa assay of DNase

     Description
     ...........

     Data obtained during development of an ELISA assay for the
     recombinant protein DNase in rat serum.

     Format
     ......

     ‘Run’
          Ordered ‘categorical’ indicating the assay run.
     ‘conc’
          Known concentration of the protein (ng/ml).
     ‘density’
          Measured optical density in the assay (dimensionless).

     Source
     ......

     Davidian, M. and Giltinan, D. M. (1995).  ‘Nonlinear Models for
     Repeated Measurement Data’.  London: Chapman & Hall.  (section
     5.2.4, p.  134)

     Pinheiro, J. C. and Bates, D. M. (2000).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.

     Examples
     ........

          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"});



File: tablicious.info,  Node: tblish.dataset.esoph,  Next: tblish.dataset.euro,  Prev: tblish.dataset.DNase,  Up: tblish.dataset

8.2.57.19 tblish.dataset.esoph
..............................

 -- Static Method: OUT = esoph ()

     Smoking, Alcohol and Esophageal Cancer

     Description
     ...........

     Data from a case-control study of (o)esophageal cancer in
     Ille-et-Vilaine, France.

     Format
     ......

     ‘item’
          Age group (years).
     ‘alcgp’
          Alcohol consumption (gm/day).
     ‘tobgp’
          Tobacco consumption (gm/day).
     ‘ncases’
          Number of cases.
     ‘ncontrols’
          Number of controls

     Source
     ......

     Breslow, N. E. and Day, N. E. (1980) ‘Statistical Methods in Cancer
     Research. Volume 1: The Analysis of Case-Control Studies’.  Oxford:
     IARC Lyon / Oxford University Press.

     Examples
     ........

          # 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.



File: tablicious.info,  Node: tblish.dataset.euro,  Next: tblish.dataset.eurodist,  Prev: tblish.dataset.esoph,  Up: tblish.dataset

8.2.57.20 tblish.dataset.euro
.............................

 -- Static Method: OUT = euro ()

     Conversion Rates of Euro Currencies

     Description
     ...........

     Conversion rates between the various Euro currencies.

     Format
     ......

     This data comes in two separate variables.

     ‘euro’
          An 11-long vector of the value of 1 Euro in all participating
          currencies.
     ‘euro_cross’
          An 11-by-11 matrix of conversion rates between various Euro
          currencies.
     ‘euro_date’
          The date upon which these Euro conversion rates were fixed.

     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.

     Source
     ......

     Unknown.

     This example data set was derived from the R 3.6.0 example
     datasets, and they do not specify a source.

     Examples
     ........

          # TODO: Port this from R

          # TODO: Example conversion

          # TODO: "dot chart" showing euro-to-whatever conversion rates and vice versa



File: tablicious.info,  Node: tblish.dataset.eurodist,  Next: tblish.dataset.EuStockMarkets,  Prev: tblish.dataset.euro,  Up: tblish.dataset

8.2.57.21 tblish.dataset.eurodist
.................................

 -- Static Method: OUT = eurodist ()

     Distances Between European Cities and Between US Cities

     Description
     ...........

     ‘eurodist’ gives road distances (in km) between 21 cities in
     Europe.  The data are taken from a table in The Cambridge
     Encyclopaedia.

     ‘UScitiesD’ gives “straight line” distances between 10 cities in
     the US.

     Format
     ......

     ‘eurodist’
          ?????

     TODO: Finish this.

     Source
     ......

     Crystal, D. Ed.  (1990).  ‘The Cambridge Encyclopaedia’.
     Cambridge: Cambridge University Press.

     The US cities distances were provided by Pierre Legendre.

     Examples
     ........


File: tablicious.info,  Node: tblish.dataset.EuStockMarkets,  Next: tblish.dataset.faithful,  Prev: tblish.dataset.eurodist,  Up: tblish.dataset

8.2.57.22 tblish.dataset.EuStockMarkets
.......................................

 -- Static Method: OUT = EuStockMarkets ()

     Daily Closing Prices of Major European Stock Indices

     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.

     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.

     Source
     ......

     The data were kindly provided by Erste Bank AG, Vienna, Austria.

     Examples
     ........


          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");





File: tablicious.info,  Node: tblish.dataset.faithful,  Next: tblish.dataset.Formaldehyde,  Prev: tblish.dataset.EuStockMarkets,  Up: tblish.dataset

8.2.57.23 tblish.dataset.faithful
.................................

 -- Static Method: OUT = faithful ()

     Old Faithful Geyser Data

     Description
     ...........

     Waiting time between eruptions and the duration of the eruption for
     the Old Faithful geyser in Yellowstone National Park, Wyoming, USA.

     Format
     ......

     ‘eruptions’
          Eruption time (mins).
     ‘waiting’
          Waiting time to next eruption (mins).

     Source
     ......

     W. Härdle.

     References
     ..........

     Härdle, W. (1991).  ‘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.  ‘Applied Statistics’, 39, 357–365.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.Formaldehyde,  Next: tblish.dataset.freeny,  Prev: tblish.dataset.faithful,  Up: tblish.dataset

8.2.57.24 tblish.dataset.Formaldehyde
.....................................

 -- Static Method: OUT = Formaldehyde ()

     Determination of Formaldehyde

     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.

     Format
     ......

     ‘record’
          Observation record number.
     ‘carb’
          Carbohydrate (ml).
     ‘optden’
          Optical Density

     Source
     ......

     Bennett, N. A. and N. L. Franklin (1954).  ‘Statistical Analysis in
     Chemistry and the Chemical Industry’.  New York: Wiley.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.freeny,  Next: tblish.dataset.HairEyeColor,  Prev: tblish.dataset.Formaldehyde,  Up: tblish.dataset

8.2.57.25 tblish.dataset.freeny
...............................

 -- Static Method: OUT = freeny ()

     Freeny's Revenue Data

     Description
     ...........

     Freeny’s data on quarterly revenue and explanatory variables.

     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).

     ‘date’
          Start date of the quarter for the observation.
     ‘y’
          Observed quarterly revenue.  TODO: Determine units (probably
          millions of USD?)
     ‘lag_quarterly_revenue’
          Quarterly revenue (‘y’), lagged 1 quarter.
     ‘price_index’
          A price index
     ‘income_level’
          ???  TODO: Fill this in
     ‘market_potential’
          ???  TODO: Fill this in

     Source
     ......

     Freeny, A. E. (1977).  ‘A Portable Linear Regression Package with
     Test Programs’.  Bell Laboratories memorandum.

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘The New S
     Language’.  Monterey: Wadsworth & Brooks/Cole.

     Examples
     ........

          t = tblish.dataset.freeny;

          summary (t)

          tblish.examples.plot_pairs (removevars (t, "date"))

          # TODO: Create linear model and print summary

          # TODO: Linear model plot



File: tablicious.info,  Node: tblish.dataset.HairEyeColor,  Next: tblish.dataset.Harman23cor,  Prev: tblish.dataset.freeny,  Up: tblish.dataset

8.2.57.26 tblish.dataset.HairEyeColor
.....................................

 -- Static Method: OUT = HairEyeColor ()

     Hair and Eye Color of Statistics Students

     Description
     ...........

     Distribution of hair and eye color and sex in 592 statistics
     students.

     Format
     ......

     This data set comes in multiple variables

     ‘n’
          A 3-dimensional array containing the counts of students in
          each bucket.  It is arranged as hair-by-eye-by-sex.
     ‘hair’
          Hair colors for the indexes along dimension 1.
     ‘eye’
          Eye colors for the indexes along dimension 2.
     ‘sex’
          Sexes for the indexes along dimension 3.

     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.

     Source
     ......

     <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).

     References
     ..........

     Snee, R. D. (1974).  Graphical display of two-way contingency
     tables.  ‘The American Statistician’, 28, 9–12.

     Friendly, M. (1992a).  Graphical methods for categorical data.
     ‘SAS User Group International Conference Proceedings’, 17, 190–200.
     <http://www.math.yorku.ca/SCS/sugi/sugi17-paper.html>

     Friendly, M. (1992b).  Mosaic displays for loglinear models.
     ‘Proceedings of the Statistical Graphics Section’, American
     Statistical Association, pp.  61–68.
     <http://www.math.yorku.ca/SCS/Papers/asa92.html>

     Friendly, M. (2000).  ‘Visualizing Categorical Data’.  SAS
     Institute, ISBN 1-58025-660-0.

     Examples
     ........

          tblish.dataset.HairEyeColor

          # TODO: Aggregate over sex and display a table of counts

          # TODO: Port mosaic plot to Octave



File: tablicious.info,  Node: tblish.dataset.Harman23cor,  Next: tblish.dataset.Harman74cor,  Prev: tblish.dataset.HairEyeColor,  Up: tblish.dataset

8.2.57.27 tblish.dataset.Harman23cor
....................................

 -- Static Method: OUT = Harman23cor ()

     Harman Example 2.3

     Description
     ...........

     A correlation matrix of eight physical measurements on 305 girls
     between ages seven and seventeen.

     Format
     ......

     ‘cov’
          An 8-by-8 correlation matrix.
     ‘names’
          Names of the variables corresponding to the indexes of the
          correlation matrix’s dimensions.

     Source
     ......

     Harman, H. H. (1976).  ‘Modern Factor Analysis’, Third Edition
     Revised.  Chicago: University of Chicago Press.  Table 2.3.

     Examples
     ........

          tblish.dataset.Harman23cor;

          # TODO: Port factanal to Octave



File: tablicious.info,  Node: tblish.dataset.Harman74cor,  Next: tblish.dataset.Indometh,  Prev: tblish.dataset.Harman23cor,  Up: tblish.dataset

8.2.57.28 tblish.dataset.Harman74cor
....................................

 -- Static Method: OUT = Harman74cor ()

     Harman Example 7.4

     Description
     ...........

     A correlation matrix of 24 psychological tests given to 145 seventh
     and eighth-grade children in a Chicago suburb by Holzinger and
     Swineford.

     Format
     ......

     ‘cov’
          A 2-dimensional correlation matrix.
     ‘vars’
          Names of the variables corresponding to the indexes along the
          dimensions of ‘cov’.

     Source
     ......

     Harman, H. H. (1976).  ‘Modern Factor Analysis’, Third Edition
     Revised.  Chicago: University of Chicago Press.  Table 7.4.

     Examples
     ........

          tblish.dataset.Harman74cor;

          # TODO: Port factanal to Octave



File: tablicious.info,  Node: tblish.dataset.Indometh,  Next: tblish.dataset.infert,  Prev: tblish.dataset.Harman74cor,  Up: tblish.dataset

8.2.57.29 tblish.dataset.Indometh
.................................

 -- Static Method: OUT = Indometh ()

     Pharmacokinetics of Indomethacin

     Description
     ...........

     Data on the pharmacokinetics of indometacin (or, older spelling,
     ‘indomethacin’).

     Format
     ......

     ‘Subject’
          Subject identifier.
     ‘time’
          Time since drug administration at which samples were drawn
          (hours).
     ‘conc’
          Plasma concentration of indomethacin (mcg/ml).

     Details
     .......

     Each of the six subjects were given an intravenous injection of
     indometacin.

     Source
     ......

     Kwan, Breault, Umbenhauer, McMahon and Duggan (1976).  Kinetics of
     Indomethacin absorption, elimination, and enterohepatic circulation
     in man.  ‘Journal of Pharmacokinetics and Biopharmaceutics’ 4,
     255–280.

     Davidian, M. and Giltinan, D. M. (1995).  ‘Nonlinear Models for
     Repeated Measurement Data’.  London: Chapman & Hall.  (section
     5.2.4, p.  129)

     Pinheiro, J. C. and Bates, D. M. (2000).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.


File: tablicious.info,  Node: tblish.dataset.infert,  Next: tblish.dataset.InsectSprays,  Prev: tblish.dataset.Indometh,  Up: tblish.dataset

8.2.57.30 tblish.dataset.infert
...............................

 -- Static Method: OUT = infert ()

     Infertility after Spontaneous and Induced Abortion

     Description
     ...........

     This is a matched case-control study dating from before the
     availability of conditional logistic regression.

     Format
     ......

     ‘education’
          Index of the record.
     ‘age’
          Age in years of case.
     ‘parity’
          Count.
     ‘induced’
          Number of prior induced abortions, grouped into “0”, “1”, or
          “2 or more”.
     ‘case_status’
          0 = control, 1 = case.
     ‘spontaneous’
          Number of prior spontaneous abortions, grouped into “0”, “1”,
          or “2 or more”.
     ‘stratum’
          Matched set number.
     ‘pooled_stratum’
          Stratum number.

     Note
     ....

     One case with two prior spontaneous abortions and two prior induced
     abortions is omitted.

     Source
     ......

     Trichopoulos et al (1976).  ‘Br. J. of Obst. and Gynaec.’ 83,
     645–650.

     Examples
     ........

          t = tblish.dataset.infert;

          # TODO: Port glm() (generalized linear model) stuff to Octave



File: tablicious.info,  Node: tblish.dataset.InsectSprays,  Next: tblish.dataset.iris,  Prev: tblish.dataset.infert,  Up: tblish.dataset

8.2.57.31 tblish.dataset.InsectSprays
.....................................

 -- Static Method: OUT = InsectSprays ()

     Effectiveness of Insect Sprays

     Description
     ...........

     The counts of insects in agricultural experimental units treated
     with different insecticides.

     Format
     ......

     ‘spray’
          The type of spray.
     ‘count’
          Insect count.

     Source
     ......

     Beall, G., (1942).  The Transformation of data from entomological
     field experiments.  ‘Biometrika’, 29, 243–262.

     References
     ..........

     McNeil, D. (1977).  ‘Interactive Data Analysis’.  New York: Wiley.

     Examples
     ........

          t = tblish.dataset.InsectSprays;

          # TODO: boxplot

          # TODO: AOV plots



File: tablicious.info,  Node: tblish.dataset.iris,  Next: tblish.dataset.islands,  Prev: tblish.dataset.InsectSprays,  Up: tblish.dataset

8.2.57.32 tblish.dataset.iris
.............................

 -- Static Method: OUT = iris ()

     The Fisher Iris dataset: measurements of various flowers

     Description
     ...........

     This is the classic Fisher Iris dataset.

     Format
     ......

     ‘Species’
          The species of flower being measured.
     ‘SepalLength’
          Length of sepals, in centimeters.
     ‘SepalWidth’
          Width of sepals, in centimeters.
     ‘PetalLength’
          Length of petals, in centimeters.
     ‘PetalWidth’
          Width of petals, in centimeters.

     Source
     ......

     <http://archive.ics.uci.edu/ml/datasets/Iris>

     References
     ..........

     <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 ‘Contributions to Mathematical Statistics’ (John Wiley, NY,
     1950).

     Duda, R.O., & Hart, P.E. (1973).  ‘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.  ‘Bulletin of the American Iris Society’, 59,
     2–5.

     Examples
     ........

          # TODO: Port this example from R



File: tablicious.info,  Node: tblish.dataset.islands,  Next: tblish.dataset.JohnsonJohnson,  Prev: tblish.dataset.iris,  Up: tblish.dataset

8.2.57.33 tblish.dataset.islands
................................

 -- Static Method: OUT = islands ()

     Areas of the World's Major Landmasses

     Description
     ...........

     The areas in thousands of square miles of the landmasses which
     exceed 10,000 square miles.

     Format
     ......

     ‘name’
          The name of the island.
     ‘area’
          The area, in thousands of square miles.

     Source
     ......

     ‘The World Almanac and Book of Facts’, 1975, page 406.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.islands;

          # TODO: Port dot chart to Octave



File: tablicious.info,  Node: tblish.dataset.JohnsonJohnson,  Next: tblish.dataset.LakeHuron,  Prev: tblish.dataset.islands,  Up: tblish.dataset

8.2.57.34 tblish.dataset.JohnsonJohnson
.......................................

 -- Static Method: OUT = JohnsonJohnson ()

     Quarterly Earnings per Johnson & Johnson Share

     Description
     ...........

     Quarterly earnings (dollars) per Johnson & Johnson share 1960–80.

     Format
     ......

     ‘date’
          Start date of the quarter.
     ‘earnings’
          Earnings per share (USD).

     Source
     ......

     Shumway, R. H. and Stoffer, D. S. (2000).  ‘Time Series Analysis
     and its Applications’.  Second Edition.  New York: Springer.
     Example 1.1.

     Examples
     ........

          t = tblish.dataset.JohnsonJohnson

          # TODO: Yikes, look at all those plots. Port them to Octave.



File: tablicious.info,  Node: tblish.dataset.LakeHuron,  Next: tblish.dataset.lh,  Prev: tblish.dataset.JohnsonJohnson,  Up: tblish.dataset

8.2.57.35 tblish.dataset.LakeHuron
..................................

 -- Static Method: OUT = LakeHuron ()

     Level of Lake Huron 1875-1972

     Description
     ...........

     Annual measurements of the level, in feet, of Lake Huron 1875–1972.

     Format
     ......

     ‘year’
          Year of the measurement
     ‘level’
          Lake level (ft).

     Source
     ......

     Brockwell, P. J. and Davis, R. A. (1991).  ‘Time Series and
     Forecasting Methods’.  Second edition.  New York: Springer.  Series
     A, page 555.

     Brockwell, P. J. and Davis, R. A. (1996).  ‘Introduction to Time
     Series and Forecasting’.  New York: Springer.  Sections 5.1 and
     7.6.

     Examples
     ........

          t = tblish.dataset.LakeHuron;

          plot (t.year, t.level)
          xlabel ("Year")
          ylabel ("Lake level (ft)")
          title ("Level of Lake Huron")



File: tablicious.info,  Node: tblish.dataset.lh,  Next: tblish.dataset.LifeCycleSavings,  Prev: tblish.dataset.LakeHuron,  Up: tblish.dataset

8.2.57.36 tblish.dataset.lh
...........................

 -- Static Method: OUT = lh ()

     Luteinizing Hormone in Blood Samples

     Description
     ...........

     A regular time series giving the luteinizing hormone in blood
     samples at 10 minute intervals from a human female, 48 samples.

     Format
     ......

     ‘sample’
          The number of the observation.
     ‘lh’
          Level of luteinizing hormone.

     Source
     ......

     P.J. Diggle (1990).  ‘Time Series: A Biostatistical Introduction’.
     Oxford.  Table A.1, series 3.

     Examples
     ........

          t = tblish.dataset.lh;

          plot (t.sample, t.lh);
          xlabel ("Sample Number");
          ylabel ("lh level");



File: tablicious.info,  Node: tblish.dataset.LifeCycleSavings,  Next: tblish.dataset.Loblolly,  Prev: tblish.dataset.lh,  Up: tblish.dataset

8.2.57.37 tblish.dataset.LifeCycleSavings
.........................................

 -- Static Method: OUT = LifeCycleSavings ()

     Intercountry Life-Cycle Savings Data

     Description
     ...........

     Data on the savings ratio 1960–1970.

     Format
     ......

     ‘country’
          Name of the country.
     ‘sr’
          Aggregate personal savings.
     ‘pop15’
          Percentage of population under 15.
     ‘pop75’
          Percentage of population over 75.
     ‘dpi’
          Real per-capita disposable income.
     ‘ddpi’
          Percent growth rate of dpi.

     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.

     Source
     ......

     The data were obtained from Belsley, Kuh and Welsch (1980).  They
     in turn obtained the data from Sterling (1977).

     References
     ..........

     Sterling, Arnie (1977).  Unpublished BS Thesis.  Massachusetts
     Institute of Technology.

     Belsley, D. A., Kuh.  E. and Welsch, R. E. (1980).  ‘Regression
     Diagnostics’.  New York: Wiley.

     Examples
     ........

          t = tblish.dataset.LifeCycleSavings;

          # TODO: linear model

          # TODO: pairs plot with Lowess smoothed line



File: tablicious.info,  Node: tblish.dataset.Loblolly,  Next: tblish.dataset.longley,  Prev: tblish.dataset.LifeCycleSavings,  Up: tblish.dataset

8.2.57.38 tblish.dataset.Loblolly
.................................

 -- Static Method: OUT = Loblolly ()

     Growth of Loblolly pine trees

     Description
     ...........

     Records of the growth of Loblolly pine trees.

     Format
     ......

     ‘height’
          Tree height (ft).
     ‘age’
          Tree age (years).
     ‘Seed’
          Seed source for the tree.  Ordering is according to increasing
          maximum height.

     Source
     ......

     Kung, F. H. (1986).  Fitting logistic growth curve with
     predetermined carrying capacity.  ‘Proceedings of the Statistical
     Computing Section’, American Statistical Association, 340–343.

     Pinheiro, J. C. and Bates, D. M. (2000).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.longley,  Next: tblish.dataset.lynx,  Prev: tblish.dataset.Loblolly,  Up: tblish.dataset

8.2.57.39 tblish.dataset.longley
................................

 -- Static Method: OUT = longley ()

     Longley’s Economic Regression Data

     Description
     ...........

     A macroeconomic data set which provides a well-known example for a
     highly collinear regression.

     Format
     ......

     ‘Year’
          The year.
     ‘GNP_deflator’
          GNP implicit price deflator (1954=100).
     ‘GNP’
          Gross National Product.
     ‘Unemployed’
          Number of unemployed.
     ‘Armed_Forces’
          Number of people in the armed forces.
     ‘Population’
          “Noninstitutionalized” population ≥ 14 years of age.
     ‘Employed’
          Number of people employed.

     Source
     ......

     J. W. Longley (1967).  An appraisal of least-squares programs from
     the point of view of the user.  ‘Journal of the American
     Statistical Association’, 62, 819–841.

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘The New S
     Language’.  Monterey: Wadsworth & Brooks/Cole.

     Examples
     ........

          t = tblish.dataset.longley;

          # TODO: Linear model
          # TODO: opar plot



File: tablicious.info,  Node: tblish.dataset.lynx,  Next: tblish.dataset.morley,  Prev: tblish.dataset.longley,  Up: tblish.dataset

8.2.57.40 tblish.dataset.lynx
.............................

 -- Static Method: OUT = lynx ()

     Annual Canadian Lynx trappings 1821-1934

     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).

     Format
     ......

     ‘year’
          Year of the record.
     ‘lynx’
          Number of lynx trapped.

     Source
     ......

     Brockwell, P. J. and Davis, R. A. (1991).  ‘Time Series and
     Forecasting Methods’.  Second edition.  New York: Springer.  Series
     G (page 557).

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘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.  ‘Journal of
     the Royal Statistical Society series A’, 140, 411–431.

     Examples
     ........

          t = tblish.dataset.lynx;

          plot (t.year, t.lynx);
          xlabel ("Year");
          ylabel ("Lynx Trapped");



File: tablicious.info,  Node: tblish.dataset.morley,  Next: tblish.dataset.mtcars,  Prev: tblish.dataset.lynx,  Up: tblish.dataset

8.2.57.41 tblish.dataset.morley
...............................

 -- Static Method: OUT = morley ()

     Michelson Speed of Light Data

     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).

     Format
     ......

     ‘Expt’
          The experiment number, from 1 to 5.
     ‘Run’
          The run number within each experiment.
     ‘Speed’
          Speed-of-light measurement.

     Details
     .......

     The data is here viewed as a randomized block experiment with
     ‘experiment’ and ‘run’ as the factors.  ‘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.

     Source
     ......

     A. J. Weekes (1986).  ‘A Genstat Primer’.  London: Edward Arnold.

     S. M. Stigler (1977).  Do robust estimators work with real data?
     ‘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.
     ‘Astronomic Papers’, 1, 135–8.  U.S. Nautical Almanac Office.  (See
     Table 24.).

     Examples
     ........

          t = tblish.dataset.morley;

          # TODO: Port to Octave



File: tablicious.info,  Node: tblish.dataset.mtcars,  Next: tblish.dataset.nhtemp,  Prev: tblish.dataset.morley,  Up: tblish.dataset

8.2.57.42 tblish.dataset.mtcars
...............................

 -- Static Method: OUT = mtcars ()

     Motor Trend 1974 Car Road Tests

     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).

     Format
     ......

     ‘mpg’
          Fuel efficiency in miles/gallon
     ‘cyl’
          Number of cylinders
     ‘disp’
          Displacement (cu.  in.)
     ‘hp’
          Gross horsepower
     ‘drat’
          Rear axle ratio
     ‘wt’
          Weight (1,000 lbs)
     ‘qsec’
          1/4 mile time
     ‘vs’
          Engine type (0 = V-shaped, 1 = straight)
     ‘am’
          Transmission type (0 = automatic, 1 = manual)
     ‘gear’
          Number of forward gears
     ‘carb’
          Number of carburetors

     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.”

     Source
     ......

     Henderson and Velleman (1981).  Building multiple regression models
     interactively.  ‘Biometrics’, 37, 391–411.

     Examples
     ........

          # TODO: Port this example from R


File: tablicious.info,  Node: tblish.dataset.nhtemp,  Next: tblish.dataset.Nile,  Prev: tblish.dataset.mtcars,  Up: tblish.dataset

8.2.57.43 tblish.dataset.nhtemp
...............................

 -- Static Method: OUT = nhtemp ()

     Average Yearly Temperatures in New Haven

     Description
     ...........

     The mean annual temperature in degrees Fahrenheit in New Haven,
     Connecticut, from 1912 to 1971.

     Format
     ......

     ‘year’
          Year of the observation.
     ‘temp’
          Mean annual temperature (degrees F).

     Source
     ......

     Vaux, J. E. and Brinker, N. B. (1972) ‘Cycles’, 1972, 117–121.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.nhtemp;

          plot (t.year, t.temp);
          title ("nhtemp data");
          xlabel ("Mean annual temperature in New Haven, CT (deg. F)");



File: tablicious.info,  Node: tblish.dataset.Nile,  Next: tblish.dataset.nottem,  Prev: tblish.dataset.nhtemp,  Up: tblish.dataset

8.2.57.44 tblish.dataset.Nile
.............................

 -- Static Method: OUT = Nile ()

     Flow of the River Nile

     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).

     Format
     ......

     ‘year’
          Year of the record.
     ‘flow’
          Annual flow (cubic meters).

     Source
     ......

     Durbin, J. and Koopman, S. J. (2001).  ‘Time Series Analysis by
     State Space Methods’.  Oxford: Oxford University Press.
     <http://www.ssfpack.com/DKbook.html>

     References
     ..........

     Balke, N. S. (1993).  Detecting level shifts in time series.
     ‘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.  ‘Biometrika’ 65, 243–51.

     Examples
     ........

          t = tblish.dataset.Nile;

          figure
          plot (t.year, t.flow);

          # TODO: Port the rest of the example to Octave



File: tablicious.info,  Node: tblish.dataset.nottem,  Next: tblish.dataset.npk,  Prev: tblish.dataset.Nile,  Up: tblish.dataset

8.2.57.45 tblish.dataset.nottem
...............................

 -- Static Method: OUT = nottem ()

     Average Monthly Temperatures at Nottingham, 1920-1939

     Description
     ...........

     A time series object containing average air temperatures at
     Nottingham Castle in degrees Fahrenheit for 20 years.

     Format
     ......

     ‘record’
          Index of the record.
     ‘lead’
          Leading indicator.
     ‘sales’
          Sales volume.

     Source
     ......

     Anderson, O. D. (1976).  ‘Time Series Analysis and Forecasting: The
     Box-Jenkins approach’.  London: Butterworths.  Series R.

     Examples
     ........

          # TODO: Come up with example code here



File: tablicious.info,  Node: tblish.dataset.npk,  Next: tblish.dataset.occupationalStatus,  Prev: tblish.dataset.nottem,  Up: tblish.dataset

8.2.57.46 tblish.dataset.npk
............................

 -- Static Method: OUT = npk ()

     Classical N, P, K Factorial Experiment

     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.

     Format
     ......

     ‘block’
          Which block (1 to 6).
     ‘N’
          Indicator (0/1) for the application of nitrogen.
     ‘P’
          Indicator (0/1) for the application of phosphate.
     ‘K’
          Indicator (0/1) for the application of potassium.
     ‘yield’
          Yield of peas, in pounds/plot.  Plots were 1/70 acre.

     Source
     ......

     Imperial College, London, M.Sc.  exercise sheet.

     References
     ..........

     Venables, W. N. and Ripley, B. D. (2002).  ‘Modern Applied
     Statistics with S’. Fourth edition.  New York: Springer.

     Examples
     ........

          t = tblish.dataset.npk;

          # TODO: Port aov() and LM to Octave



File: tablicious.info,  Node: tblish.dataset.occupationalStatus,  Next: tblish.dataset.Orange,  Prev: tblish.dataset.npk,  Up: tblish.dataset

8.2.57.47 tblish.dataset.occupationalStatus
...........................................

 -- Static Method: OUT = occupationalStatus ()

     Occupational Status of Fathers and their Sons

     Description
     ...........

     Cross-classification of a sample of British males according to each
     subject’s occupational status and his father’s occupational status.

     Format
     ......

     An 8-by-8 matrix of counts, with classifying fators ‘origin’
     (father’s occupational status, levels 1:8) and ‘destination’ (son’s
     occupational status, levels 1:8).

     Source
     ......

     Goodman, L. A. (1979).  Simple Models for the Analysis of
     Association in Cross-Classifications having Ordered Categories.
     ‘J. Am. Stat. Assoc.’, 74 (367), 537–552.

     Examples
     ........

          # TODO: Come up with example code here



File: tablicious.info,  Node: tblish.dataset.Orange,  Next: tblish.dataset.OrchardSprays,  Prev: tblish.dataset.occupationalStatus,  Up: tblish.dataset

8.2.57.48 tblish.dataset.Orange
...............................

 -- Static Method: OUT = Orange ()

     Growth of Orange Trees

     Description
     ...........

     Records of the growth of orange trees.

     Format
     ......

     ‘Tree’
          A categorical indicating on which tree the measurement is
          made.  Ordering is according to increasing maximum diameter.
     ‘age’
          Age of the tree (days since 1968-12-31).
     ‘circumference’
          Trunk circumference (mm).  This is probably “circumference at
          breast height”, a standard measurement in forestry.

     Source
     ......

     The data are given in Box & Jenkins (1976).  Obtained from the Time
     Series Data Library at
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>.

     References
     ..........

     Draper, N. R. and Smith, H. (1998).  ‘Applied Regression Analysis
     (3rd ed)’.  New York: Wiley.  (exercise 24.N).

     Pinheiro, J. C. and Bates, D. M. (2000).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.

     Examples
     ........

          t = tblish.dataset.Orange;

          # TODO: Port coplot to Octave

          # TODO: Linear model



File: tablicious.info,  Node: tblish.dataset.OrchardSprays,  Next: tblish.dataset.PlantGrowth,  Prev: tblish.dataset.Orange,  Up: tblish.dataset

8.2.57.49 tblish.dataset.OrchardSprays
......................................

 -- Static Method: OUT = OrchardSprays ()

     Potency of Orchard Sprays

     Description
     ...........

     An experiment was conducted to assess the potency of various
     constituents of orchard sprays in repelling honeybees, using a
     Latin square design.

     Format
     ......

     ‘rowpos’
          Row of the design.
     ‘colpos’
          Column of the design
     ‘treatment’
          Treatment level.
     ‘decrease’
          Response.

     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 ... G – lowest level of lime sulphur H – no lime sulphur

     Source
     ......

     Finney, D. J. (1947).  ‘Probit Analysis’.  Cambridge.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.OrchardSprays;

          tblish.examples.plot_pairs (t);



File: tablicious.info,  Node: tblish.dataset.PlantGrowth,  Next: tblish.dataset.precip,  Prev: tblish.dataset.OrchardSprays,  Up: tblish.dataset

8.2.57.50 tblish.dataset.PlantGrowth
....................................

 -- Static Method: OUT = PlantGrowth ()

     Results from an Experiment on Plant Growth

     Description
     ...........

     Results from an experiment to compare yields (as measured by dried
     weight of plants) obtained under a control and two different
     treatment conditions.

     Format
     ......

     ‘group’
          Treatment condition group.
     ‘weight’
          Weight of plants.

     Source
     ......

     Dobson, A. J. (1983).  ‘An Introduction to Statistical Modelling’.
     London: Chapman and Hall.

     Examples
     ........

          t = tblish.dataset.PlantGrowth;

          # TODO: Port anova to Octave



File: tablicious.info,  Node: tblish.dataset.precip,  Next: tblish.dataset.presidents,  Prev: tblish.dataset.PlantGrowth,  Up: tblish.dataset

8.2.57.51 tblish.dataset.precip
...............................

 -- Static Method: OUT = precip ()

     Annual Precipitation in US Cities

     Description
     ...........

     The average amount of precipitation (rainfall) in inches for each
     of 70 United States (and Puerto Rico) cities.

     Format
     ......

     ‘city’
          City observed.
     ‘precip’
          Annual precipitation (in).

     Source
     ......

     ‘Statistical Abstracts of the United States’, 1975.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.precip;

          # TODO: Port dot plot to Octave



File: tablicious.info,  Node: tblish.dataset.presidents,  Next: tblish.dataset.pressure,  Prev: tblish.dataset.precip,  Up: tblish.dataset

8.2.57.52 tblish.dataset.presidents
...................................

 -- Static Method: OUT = presidents ()

     Quarterly Approval Ratings of US Presidents

     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.

     Format
     ......

     ‘date’
          Approximate date of the observation.
     ‘approval’
          Approval rating (%).

     Details
     .......

     The data are actually a fudged version of the approval ratings.
     See McNeil’s book for details.

     Source
     ......

     The Gallup Organisation.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.presidents;

          figure
          plot (datenum (t.date), t.approval)
          datetick ("x")
          xlabel ("Date")
          ylabel ("Approval rating (%)")
          title ("presidents data")



File: tablicious.info,  Node: tblish.dataset.pressure,  Next: tblish.dataset.Puromycin,  Prev: tblish.dataset.presidents,  Up: tblish.dataset

8.2.57.53 tblish.dataset.pressure
.................................

 -- Static Method: OUT = pressure ()

     Vapor Pressure of Mercury as a Function of Temperature

     Description
     ...........

     Data on the relation between temperature in degrees Celsius and
     vapor pressure of mercury in millimeters (of mercury).

     Format
     ......

     ‘temperature’
          Temperature (deg C).
     ‘pressure’
          Pressure (mm Hg).

     Source
     ......

     Weast, R. C., ed.  (1973).  ‘Handbook of Chemistry and Physics’.
     Cleveland: CRC Press.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          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")




File: tablicious.info,  Node: tblish.dataset.Puromycin,  Next: tblish.dataset.quakes,  Prev: tblish.dataset.pressure,  Up: tblish.dataset

8.2.57.54 tblish.dataset.Puromycin
..................................

 -- Static Method: OUT = Puromycin ()

     Reaction Velocity of an Enzymatic Reaction

     Description
     ...........

     Reaction velocity versus substrate concentration in an enzymatic
     reaction involving untreated cells or cells treated with Puromycin.

     Format
     ......

     ‘state’
          Whether the cell was treated.
     ‘conc’
          Substrate concentrations (ppm).
     ‘rate’
          Instantaneous reaction rates (counts/min/min).

     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.

     Source
     ......

     The data are given in Box & Jenkins (1976).  Obtained from the Time
     Series Data Library at
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>.

     References
     ..........

     Bates, D.M. and Watts, D.G. (1988).  ‘Nonlinear Regression Analysis
     and Its Applications’.  New York: Wiley.  Appendix A1.3.

     Treloar, M. A. (1974).  ‘Effects of Puromycin on
     Galactosyltransferase in Golgi Membranes’.  M.Sc.  Thesis, U. of
     Toronto.

     Examples
     ........

          t = tblish.dataset.Puromycin;

          # TODO: Port example to Octave



File: tablicious.info,  Node: tblish.dataset.quakes,  Next: tblish.dataset.randu,  Prev: tblish.dataset.Puromycin,  Up: tblish.dataset

8.2.57.55 tblish.dataset.quakes
...............................

 -- Static Method: OUT = quakes ()

     Locations of Earthquakes off Fiji

     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.

     Format
     ......

     ‘lat’
          Latitude of event.
     ‘long’
          Longitude of event.
     ‘depth’
          Depth (km).
     ‘mag’
          Richter magnitude.
     ‘stations’
          Number of stations reporting.

     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.

     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.

     References
     ..........

     G. E. P. Box and G. M. Jenkins (1976).  ‘Time Series Analysis,
     Forecasting and Control’.  San Francisco: Holden-Day.  p.  537.

     P. J. Brockwell and R. A. Davis (1991).  ‘Time Series: Theory and
     Methods’.  Second edition.  New York: Springer-Verlag.  p.  414.

     Examples
     ........

          # TODO: Come up with example code here



File: tablicious.info,  Node: tblish.dataset.randu,  Next: tblish.dataset.rivers,  Prev: tblish.dataset.quakes,  Up: tblish.dataset

8.2.57.56 tblish.dataset.randu
..............................

 -- Static Method: OUT = randu ()

     Random Numbers from Congruential Generator RANDU

     Description
     ...........

     400 triples of successive random numbers were taken from the VAX
     FORTRAN function RANDU running under VMS 1.5.

     Format
     ......

     ‘record’
          Index of the record.
     ‘x’
          X value of the triple.
     ‘y’
          Y value of the triple.
     ‘z’
          Z value of the triple.

     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.

     Source
     ......

     David Donoho

     Examples
     ........

          t = tblish.dataset.randu;




File: tablicious.info,  Node: tblish.dataset.rivers,  Next: tblish.dataset.rock,  Prev: tblish.dataset.randu,  Up: tblish.dataset

8.2.57.57 tblish.dataset.rivers
...............................

 -- Static Method: OUT = rivers ()

     Lengths of Major North American Rivers

     Description
     ...........

     This data set gives the lengths (in miles) of 141 “major” rivers in
     North America, as compiled by the US Geological Survey.

     Format
     ......

     ‘rivers’
          A vector containing 141 observations.

     Source
     ......

     ‘World Almanac and Book of Facts’, 1975, page 406.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          tblish.dataset.rivers;

          longest_river = max (rivers)
          shortest_river = min (rivers)



File: tablicious.info,  Node: tblish.dataset.rock,  Next: tblish.dataset.sleep,  Prev: tblish.dataset.rivers,  Up: tblish.dataset

8.2.57.58 tblish.dataset.rock
.............................

 -- Static Method: OUT = rock ()

     Measurements on Petroleum Rock Samples

     Description
     ...........

     Measurements on 48 rock samples from a petroleum reservoir.

     Format
     ......

     ‘area’
          Area of pores space, in pixels out of 256 by 256.
     ‘peri’
          Perimeter in pixels.
     ‘shape’
          Perimeter/sqrt(area).
     ‘perm’
          Permeability in milli-Darcies.

     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.

     Source
     ......

     Data from BP Research, image analysis by Ronit Katz, U. Oxford.

     Examples
     ........

          t = tblish.dataset.rock;

          figure
          scatter (t.area, t.perm)
          xlabel ("Area of pores space (pixels out of 256x256)")
          ylabel ("Permeability (milli-Darcies)")



File: tablicious.info,  Node: tblish.dataset.sleep,  Next: tblish.dataset.stackloss,  Prev: tblish.dataset.rock,  Up: tblish.dataset

8.2.57.59 tblish.dataset.sleep
..............................

 -- Static Method: OUT = sleep ()

     Student’s Sleep Data

     Description
     ...........

     Data which show the effect of two soporific drugs (increase in
     hours of sleep compared to control) on 10 patients.

     Format
     ......

     ‘id’
          Patient ID.
     ‘group’
          Drug given.
     ‘extra’
          Increase in hours of sleep.

     Details
     .......

     The ‘group’ variable name may be misleading about the data: They
     represent measurements on 10 persons, not in groups.

     Source
     ......

     Cushny, A. R. and Peebles, A. R. (1905).  The action of optical
     isomers: II hyoscines.  ‘The Journal of Physiology’, 32, 501–510.

     Student (1908).  The probable error of the mean.  ‘Biometrika’, 6,
     20.

     References
     ..........

     Scheffé, Henry (1959).  ‘The Analysis of Variance’.  New York, NY:
     Wiley.

     Examples
     ........

          t = tblish.dataset.sleep;

          # TODO: Port to Octave



File: tablicious.info,  Node: tblish.dataset.stackloss,  Next: tblish.dataset.state,  Prev: tblish.dataset.sleep,  Up: tblish.dataset

8.2.57.60 tblish.dataset.stackloss
..................................

 -- Static Method: OUT = stackloss ()

     Brownlee's Stack Loss Plant Data

     Description
     ...........

     Operational data of a plant for the oxidation of ammonia to nitric
     acid.

     Format
     ......

     ‘AirFlow’
          Flow of cooling air.
     ‘WaterTemp’
          Cooling Water Inlet temperature.
     ‘AcidConc’
          Concentration of acid (per 1000, minus 500).
     ‘StackLoss’
          Stack loss

     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.)

     ‘AirFlow’ represents the rate of operation of the plant.
     ‘WaterTemp’ is the temperature of cooling water circulated through
     coils in the absorption tower.  ‘AcidConc’ is the concentration of
     the acid circulating, minus 50, times 10: that is, 89 corresponds
     to 58.9 per cent acid.  ‘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.

     Source
     ......

     Brownlee, K. A. (1960, 2nd ed.  1965).  ‘Statistical Theory and
     Methodology in Science and Engineering’.  New York: Wiley.  pp.
     491–500.

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘The New S
     Language’.  Monterey: Wadsworth & Brooks/Cole.

     Dodge, Y. (1996).  The guinea pig of multiple regression.  In:
     ‘Robust Statistics, Data Analysis, and Computer Intensive Methods;
     In Honor of Peter Huber’s 60th Birthday’, 1996, ‘Lecture Notes in
     Statistics’ 109, Springer-Verlag, New York.

     Examples
     ........

          t = tblish.dataset.stackloss;

          # TODO: Create linear model and print summary



File: tablicious.info,  Node: tblish.dataset.state,  Next: tblish.dataset.sunspot_month,  Prev: tblish.dataset.stackloss,  Up: tblish.dataset

8.2.57.61 tblish.dataset.state
..............................

 -- Static Method: OUT = state ()

     US State Facts and Figures

     Description
     ...........

     Data related to the 50 states of the United States of America.

     Format
     ......

     ‘abb’
          State abbreviation.
     ‘name’
          State name.
     ‘area’
          Area (sq mi).
     ‘lat’
          Approximate center (latitude).
     ‘lon’
          Approximate center (longitude).
     ‘division’
          State division.
     ‘revion’
          State region.
     ‘Population’
          Population estimate as of July 1, 1975.
     ‘Income’
          Per capita income (1974).
     ‘Illiteracy’
          Illiteracy as of 1970 (percent of population).
     ‘LifeExp’
          Lfe expectancy in years (1969-71).
     ‘Murder’
          Murder and non-negligent manslaughter rate per 100,000
          population (1976).
     ‘HSGrad’
          Percent high-school graduates (1970).
     ‘Frost’
          Mean number of days with minimum temperature below freezing
          (1931-1960) in capital or large city.

     Source
     ......

     U.S. Department of Commerce, Bureau of the Census (1977)
     ‘Statistical Abstract of the United States’.

     U.S. Department of Commerce, Bureau of the Census (1977) ‘County
     and City Data Book’.

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘The New S
     Language’.  Monterey: Wadsworth & Brooks/Cole.

     Examples
     ........

          t = tblish.dataset.state;



File: tablicious.info,  Node: tblish.dataset.sunspot_month,  Next: tblish.dataset.sunspot_year,  Prev: tblish.dataset.state,  Up: tblish.dataset

8.2.57.62 tblish.dataset.sunspot_month
......................................

 -- Static Method: OUT = sunspot_month ()

     Monthly Sunspot Data, from 1749 to “Present”

     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.

     Format
     ......

     ‘month’
          Month of the observation.
     ‘sunspots’
          Number of sunspots.

     Source
     ......

     WDC-SILSO, Solar Influences Data Analysis Center (SIDC), Royal
     Observatory of Belgium, Av.  Circulaire, 3, B-1180 BRUSSELS.
     Currently at <http://www.sidc.be/silso/datafiles>.

     Examples
     ........

          t = tblish.dataset.sunspot_month;




File: tablicious.info,  Node: tblish.dataset.sunspot_year,  Next: tblish.dataset.sunspots,  Prev: tblish.dataset.sunspot_month,  Up: tblish.dataset

8.2.57.63 tblish.dataset.sunspot_year
.....................................

 -- Static Method: OUT = sunspot_year ()

     Yearly Sunspot Data, 1700-1988

     Description
     ...........

     Yearly numbers of sunspots from 1700 to 1988 (rounded to one
     digit).

     Format
     ......

     ‘year’
          Year of the observation.
     ‘sunspots’
          Number of sunspots.

     Source
     ......

     H. Tong (1996) ‘Non-Linear Time Series’.  Clarendon Press, Oxford,
     p.  471.

     Examples
     ........

          t = tblish.dataset.sunspot_year;

          figure
          plot (t.year, t.sunspots)
          xlabel ("Year")
          ylabel ("Sunspots")



File: tablicious.info,  Node: tblish.dataset.sunspots,  Next: tblish.dataset.swiss,  Prev: tblish.dataset.sunspot_year,  Up: tblish.dataset

8.2.57.64 tblish.dataset.sunspots
.................................

 -- Static Method: OUT = sunspots ()

     Monthly Sunspot Numbers, 1749-1983

     Description
     ...........

     Monthly mean relative sunspot numbers from 1749 to 1983.  Collected
     at Swiss Federal Observatory, Zurich until 1960, then Tokyo
     Astronomical Observatory.

     Format
     ......

     ‘month’
          Month of the observation.
     ‘sunspots’
          Number of observed sunspots.

     Source
     ......

     Andrews, D. F. and Herzberg, A. M. (1985) ‘Data: A Collection of
     Problems from Many Fields for the Student and Research Worker’.
     New York: Springer-Verlag.

     Examples
     ........

          t = tblish.dataset.sunspots;

          figure
          plot (datenum (t.month), t.sunspots)
          datetick ("x")
          xlabel ("Date")
          ylabel ("Monthly sunspot numbers")
          title ("sunspots data")




File: tablicious.info,  Node: tblish.dataset.swiss,  Next: tblish.dataset.Theoph,  Prev: tblish.dataset.sunspots,  Up: tblish.dataset

8.2.57.65 tblish.dataset.swiss
..............................

 -- Static Method: OUT = swiss ()

     Swiss Fertility and Socioeconomic Indicators (1888) Data

     Description
     ...........

     Standardized fertility measure and socio-economic indicators for
     each of 47 French-speaking provinces of Switzerland at about 1888.

     Format
     ......

     ‘Fertility’
          Ig, ‘common standardized fertility measure’.
     ‘Agriculture’
          % of males involved in agriculture as occupation.
     ‘Examination’
          % draftees receiving highest mark on army examination.
     ‘Education’
          % education beyond primary school for draftees.
     ‘Catholic’
          % ‘Catholic’ (as opposed to ‘Protestant’).
     ‘InfantMortality’
          Live births who live less than 1 year.

     All variables but ‘Fertility’ give proportions of the population.

     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 ‘Catholic’ were scaled to [0, 1].

     Note
     ....

     Files for all 182 districts in 1888 and other years have been
     available at <https://opr.princeton.edu/archive/pefp/switz.aspx>.

     They state that variables ‘Examination’ and ‘Education’ are
     averages for 1887, 1888 and 1889.

     References
     ..........

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988).  ‘The New S
     Language’.  Monterey: Wadsworth & Brooks/Cole.

     Examples
     ........

          t = tblish.dataset.swiss;

          # TODO: Port linear model to Octave



File: tablicious.info,  Node: tblish.dataset.Theoph,  Next: tblish.dataset.Titanic,  Prev: tblish.dataset.swiss,  Up: tblish.dataset

8.2.57.66 tblish.dataset.Theoph
...............................

 -- Static Method: OUT = Theoph ()

     Pharmacokinetics of Theophylline

     Description
     ...........

     An experiment on the pharmacokinetics of theophylline.

     Format
     ......

     ‘Subject’
          Categorical identifying the subject on whom the observation
          was made.  The ordering is by increasing maximum concentration
          of theophylline observed.
     ‘Wt’
          Weight of the subject (kg).
     ‘Dose’
          Dose of theophylline administerred orally to the subject
          (mg/kg).
     ‘Time’
          Time since drug administration when the sample was drawn (hr).
     ‘conc’
          Theophylline concentration in the sample (mg/L).

     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.

     Source
     ......

     The data are given in Box & Jenkins (1976).  Obtained from the Time
     Series Data Library at
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>.

     References
     ..........

     Boeckmann, A. J., Sheiner, L. B. and Beal, S. L. (1994).  ‘NONMEM
     Users Guide: Part V’. NONMEM Project Group, University of
     California, San Francisco.

     Davidian, M. and Giltinan, D. M. (1995).  ‘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).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.  (Appendix A.29)

     Examples
     ........

          t = tblish.dataset.Theoph;

          # TODO: Coplot
          # TODO: Yet another linear model to port to Octave



File: tablicious.info,  Node: tblish.dataset.Titanic,  Next: tblish.dataset.ToothGrowth,  Prev: tblish.dataset.Theoph,  Up: tblish.dataset

8.2.57.67 tblish.dataset.Titanic
................................

 -- Static Method: OUT = Titanic ()

     Survival of passengers on the Titanic

     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.

     Format
     ......

     ‘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:

     ‘Class’
          1st, 2nd, 3rd, Cre.
     ‘Sex’
          Male, Female.
     ‘Age’
          Child, Adult.
     ‘Survived’
          No, Yes.

     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
     (<https://www.encyclopedia-titanica.org/>).

     Source
     ......

     Dawson, Robert J. MacG. (1995).  The ‘Unusual Episode’ Data
     Revisited.  ‘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).  ‘Report on the Loss of the
     ‘Titanic’ (S.S.)’. British Board of Trade Inquiry Report (reprint).
     Gloucester, UK: Allan Sutton Publishing.

     Examples
     ........

          tblish.dataset.Titanic;

          # TODO: Port mosaic plot to Octave

          # TODO: Check for higher survival rates in children and females



File: tablicious.info,  Node: tblish.dataset.ToothGrowth,  Next: tblish.dataset.treering,  Prev: tblish.dataset.Titanic,  Up: tblish.dataset

8.2.57.68 tblish.dataset.ToothGrowth
....................................

 -- Static Method: OUT = ToothGrowth ()

     The Effect of Vitamin C on Tooth Growth in Guinea Pigs

     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 ‘VC’).

     Format
     ......

     ‘supp’
          Supplement type.
     ‘dose’
          Dose (mg/day).
     ‘len’
          Tooth length.

     Source
     ......

     C. I. Bliss (1952).  ‘The Statistics of Bioassay’.  Academic Press.

     References
     ..........

     McNeil, D. R. (1977).  ‘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.
     ‘The Journal of Nutrition’, 33(5), 491–504.

     Examples
     ........

          t = tblish.dataset.ToothGrowth;

          tblish.examples.coplot (t, "dose", "len", "supp");

          # TODO: Port Lowess smoothing to Octave



File: tablicious.info,  Node: tblish.dataset.treering,  Next: tblish.dataset.trees,  Prev: tblish.dataset.ToothGrowth,  Up: tblish.dataset

8.2.57.69 tblish.dataset.treering
.................................

 -- Static Method: OUT = treering ()

     Yearly Treering Data, -6000-1979

     Description
     ...........

     Contains normalized tree-ring widths in dimensionless units.

     Format
     ......

     A univariate time series with 7981 observations.

     Each tree ring corresponds to one year.

     Details
     .......

     The data were recorded by Donald A. Graybill, 1980, from Gt Basin
     Bristlecone Pine 2805M, 3726-11810 in Methuselah Walk, California.

     Source
     ......

     Time Series Data Library:
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>, series
     ‘CA535.DAT’.

     References
     ..........

     For some photos of Methuselah Walk see
     <https://web.archive.org/web/20110523225828/http://www.ltrr.arizona.edu/~hallman/sitephotos/meth.html>.

     Examples
     ........

          t = tblish.dataset.treering;



File: tablicious.info,  Node: tblish.dataset.trees,  Next: tblish.dataset.UCBAdmissions,  Prev: tblish.dataset.treering,  Up: tblish.dataset

8.2.57.70 tblish.dataset.trees
..............................

 -- Static Method: OUT = trees ()

     Diameter, Height and Volume for Black Cherry Trees

     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.

     Format
     ......

     ‘Girth’
          Tree diameter (rather than girth, actually) in inches.
     ‘Height’
          Height in ft.
     ‘Volume’
          Volume of timber in cubic feet.

     Source
     ......

     Ryan, T. A., Joiner, B. L. and Ryan, B. F. (1976).  ‘The Minitab
     Student Handbook’.  Duxbury Press.

     References
     ..........

     Atkinson, A. C. (1985).  ‘Plots, Transformations and Regression’.
     Oxford: Oxford University Press.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.UCBAdmissions,  Next: tblish.dataset.UKDriverDeaths,  Prev: tblish.dataset.trees,  Up: tblish.dataset

8.2.57.71 tblish.dataset.UCBAdmissions
......................................

 -- Static Method: OUT = UCBAdmissions ()

     Student Admissions at UC Berkeley

     Description
     ...........

     Aggregate data on applicants to graduate school at Berkeley for the
     six largest departments in 1973 classified by admission and sex.

     Format
     ......

     A 3-dimensional array resulting from cross-tabulating 4526
     observations on 3 variables.  The variables and their levels are as
     follows:

     ‘Admit’
          Admitted, Rejected.
     ‘Gender’
          Male, Female.
     ‘Dept’
          A, B, C, D, E, F.

     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).

     Source
     ......

     The data are given in Box & Jenkins (1976).  Obtained from the Time
     Series Data Library at
     <http://www-personal.buseco.monash.edu.au/~hyndman/TSDL/>.

     References
     ..........

     Bickel, P. J., Hammel, E. A., and O'Connell, J. W. (1975).  Sex
     bias in graduate admissions: Data from Berkeley.  ‘Science’, 187,
     398–403.  <http://www.jstor.org/stable/1739581>.

     Examples
     ........

          tblish.dataset.UCBAdmissions;

          # TODO: Port mosaic plot to Octave



File: tablicious.info,  Node: tblish.dataset.UKDriverDeaths,  Next: tblish.dataset.UKgas,  Prev: tblish.dataset.UCBAdmissions,  Up: tblish.dataset

8.2.57.72 tblish.dataset.UKDriverDeaths
.......................................

 -- Static Method: OUT = UKDriverDeaths ()

     Road Casualties in Great Britain 1969-84

     Description
     ...........

     ‘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.

     ‘Seatbelts’ is more information on the same problem.

     Format
     ......

     ‘UKDriverDeaths’ is a table with the following variables:

     ‘month’
          Month of the observation.
     ‘deaths’
          Number of deaths.

     ‘Seatbelts’ is a table with the following variables:

     ‘month’
          Month of the observation.
     ‘DriversKilled’
          Car drivers killed.
     ‘drivers’
          Same as ‘UKDriverDeaths’ ‘deaths’ count.
     ‘front’
          Front-seat passengers killed or seriously injured.
     ‘rear’
          Rear-seat passengers killed or seriously injured.
     ‘kms’
          Distance driven.
     ‘PetrolPrice’
          Petrol price.
     ‘VanKilled’
          Number of van (“light goods vehicle”) drivers killed.
     ‘law’
          0/1: was the seatbelt law in effect that month?

     Source
     ......

     Harvey, A.C. (1989).  ‘Forecasting, Structural Time Series Models
     and the Kalman Filter’.  Cambridge: Cambridge University Press.
     pp.  519–523.

     Durbin, J. and Koopman, S. J. (2001).  ‘Time Series Analysis by
     State Space Methods’.  Oxford: Oxford University Press.
     <http://www.ssfpack.com/dkbook/>

     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.  ‘Journal of the Royal Statistical Society’
     series A, 149, 187–227.

     Examples
     ........

          tblish.dataset.UKDriverDeaths;
          d = UKDriverDeaths;
          s = Seatbelts;

          # TODO: Port the model and plots to Octave



File: tablicious.info,  Node: tblish.dataset.UKgas,  Next: tblish.dataset.UKLungDeaths,  Prev: tblish.dataset.UKDriverDeaths,  Up: tblish.dataset

8.2.57.73 tblish.dataset.UKgas
..............................

 -- Static Method: OUT = UKgas ()

     UK Quarterly Gas Consumption

     Description
     ...........

     Quarterly UK gas consumption from 1960Q1 to 1986Q4, in millions of
     therms.

     Format
     ......

     ‘date’
          Quarter of the observation
     ‘gas’
          Gas consumption (MM therms).

     Source
     ......

     Durbin, J. and Koopman, S. J. (2001).  ‘Time Series Analysis by
     State Space Methods’.  Oxford: Oxford University Press.
     <http://www.ssfpack.com/dkbook/>.

     Examples
     ........

          t = tblish.dataset.UKgas;

          plot (datenum (t.date), t.gas);
          datetick ("x")
          xlabel ("Month")
          ylabel ("Gas consumption (MM therms)")



File: tablicious.info,  Node: tblish.dataset.UKLungDeaths,  Next: tblish.dataset.USAccDeaths,  Prev: tblish.dataset.UKgas,  Up: tblish.dataset

8.2.57.74 tblish.dataset.UKLungDeaths
.....................................

 -- Static Method: OUT = UKLungDeaths ()

     Monthly Deaths from Lung Diseases in the UK

     Description
     ...........

     Three time series giving the monthly deaths from bronchitis,
     emphysema and asthma in the UK, 1974–1979.

     Format
     ......

     ‘date’
          Month of the observation.
     ‘ldeaths’
          Total lung deaths.
     ‘fdeaths’
          Lung deaths among females.
     ‘mdeaths’
          Lung deaths among males.

     Source
     ......

     P. J. Diggle (1990).  ‘Time Series: A Biostatistical Introduction’.
     Oxford.  table A.3

     Examples
     ........

          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")



File: tablicious.info,  Node: tblish.dataset.USAccDeaths,  Next: tblish.dataset.USArrests,  Prev: tblish.dataset.UKLungDeaths,  Up: tblish.dataset

8.2.57.75 tblish.dataset.USAccDeaths
....................................

 -- Static Method: OUT = USAccDeaths ()

     Accidental Deaths in the US 1973-1978

     Description
     ...........

     A time series giving the monthly totals of accidental deaths in the
     USA.

     Format
     ......

     ‘month’
          Month of the observation.
     ‘deaths’
          Accidental deaths.

     Source
     ......

     Brockwell, P. J. and Davis, R. A. (1991).  ‘Time Series: Theory and
     Methods’.  New York: Springer.

     Examples
     ........

          t = tblish.dataset.USAccDeaths;



File: tablicious.info,  Node: tblish.dataset.USArrests,  Next: tblish.dataset.USJudgeRatings,  Prev: tblish.dataset.USAccDeaths,  Up: tblish.dataset

8.2.57.76 tblish.dataset.USArrests
..................................

 -- Static Method: OUT = USArrests ()

     Violent Crime Rates by US State

     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.

     Format
     ......

     ‘State’
          State name.
     ‘Murder’
          Murder arrests (per 100,000).
     ‘Assault’
          Assault arrests (per 100,000).
     ‘UrbanPop’
          Percent urban population.
     ‘Rape’
          Rape arrests (per 100,000).

     Note
     ....

     ‘USArrests’ contains the data as in McNeil's monograph.  For the
     ‘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.

     Source
     ......

     ‘World Almanac and Book of Facts 1975’.  (Crime rates).

     ‘Statistical Abstracts of the United States 1975’, p.20, (Urban
     rates), possibly available as
     <https://books.google.ch/books?id=zl9qAAAAMAAJ&pg=PA20>.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          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



File: tablicious.info,  Node: tblish.dataset.USJudgeRatings,  Next: tblish.dataset.USPersonalExpenditure,  Prev: tblish.dataset.USArrests,  Up: tblish.dataset

8.2.57.77 tblish.dataset.USJudgeRatings
.......................................

 -- Static Method: OUT = USJudgeRatings ()

     Lawyers’ Ratings of State Judges in the US Superior Court

     Description
     ...........

     Lawyers’ ratings of state judges in the US Superior Court.

     Format
     ......

     ‘CONT’
          Number of contacts of lawyer with judge.
     ‘INTG’
          Judicial integrity.
     ‘DMNR’
          Demeanor.
     ‘DILG’
          Diligence.
     ‘CFMG’
          Case flow managing.
     ‘DECI’
          Prompt decisions.
     ‘PREP’
          Preparation for trial.
     ‘FAMI’
          Familiarity with law.
     ‘ORAL’
          Sound oral rulings.
     ‘WRIT’
          Sound written rulings.
     ‘PHYS’
          Physical ability.
     ‘RTEN’
          Worthy of retention.

     Source
     ......

     New Haven Register, 14 January, 1977 (from John Hartigan).

     Examples
     ........

          t = tblish.dataset.USJudgeRatings;

          figure
          tblish.examples.plot_pairs (t(:,2:end));
          title ("USJudgeRatings data")



File: tablicious.info,  Node: tblish.dataset.USPersonalExpenditure,  Next: tblish.dataset.uspop,  Prev: tblish.dataset.USJudgeRatings,  Up: tblish.dataset

8.2.57.78 tblish.dataset.USPersonalExpenditure
..............................................

 -- Static Method: OUT = USPersonalExpenditure ()

     Personal Expenditure Data

     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.

     Format
     ......

     A 2-dimensional matrix ‘x’ with Category along dimension 1 and Year
     along dimension 2.

     Source
     ......

     ‘The World Almanac and Book of Facts’, 1962, page 756.

     References
     ..........

     Tukey, J. W. (1977).  ‘Exploratory Data Analysis’.  Reading, Mass:
     Addison-Wesley.

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          tblish.dataset.USPersonalExpenditure;

          # TODO: Port medpolish() from R, whatever that is.



File: tablicious.info,  Node: tblish.dataset.uspop,  Next: tblish.dataset.VADeaths,  Prev: tblish.dataset.USPersonalExpenditure,  Up: tblish.dataset

8.2.57.79 tblish.dataset.uspop
..............................

 -- Static Method: OUT = uspop ()

     Populations Recorded by the US Census

     Description
     ...........

     This data set gives the population of the United States (in
     millions) as recorded by the decennial census for the period
     1790–1970.

     Format
     ......

     ‘year’
          Year of the census.
     ‘population’
          Population, in millions.

     Source
     ......

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.uspop;

          figure
          semilogy (t.year, t.population)
          xlabel ("Year")
          ylabel ("U.S. Population (millions)")



File: tablicious.info,  Node: tblish.dataset.VADeaths,  Next: tblish.dataset.volcano,  Prev: tblish.dataset.uspop,  Up: tblish.dataset

8.2.57.80 tblish.dataset.VADeaths
.................................

 -- Static Method: OUT = VADeaths ()

     Death Rates in Virginia (1940)

     Description
     ...........

     Death rates per 1000 in Virginia in 1940.

     Format
     ......

     A 2-dimensional matrix ‘deaths’, with age group along dimension 1
     and demographic group along dimension 2.

     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.

     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.  ‘American Sociological Review’, 12, 525–535.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          tblish.dataset.VADeaths;

          # TODO: Port to Octave



File: tablicious.info,  Node: tblish.dataset.volcano,  Next: tblish.dataset.warpbreaks,  Prev: tblish.dataset.VADeaths,  Up: tblish.dataset

8.2.57.81 tblish.dataset.volcano
................................

 -- Static Method: OUT = volcano ()

     Topographic Information on Auckland’s Maunga Whau Volcano

     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.

     Format
     ......

     A matrix ‘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.

     Source
     ......

     Digitized from a topographic map by Ross Ihaka.  These data should
     not be regarded as accurate.

     References
     ..........

     Box, G. E. P. and Jenkins, G. M. (1976).  ‘Time Series Analysis,
     Forecasting and Control’.  San Francisco: Holden-Day.  p.  537.

     Brockwell, P. J. and Davis, R. A. (1991).  ‘Time Series: Theory and
     Methods’.  Second edition.  New York: Springer-Verlag.  p.  414.

     Examples
     ........

          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.



File: tablicious.info,  Node: tblish.dataset.warpbreaks,  Next: tblish.dataset.women,  Prev: tblish.dataset.volcano,  Up: tblish.dataset

8.2.57.82 tblish.dataset.warpbreaks
...................................

 -- Static Method: OUT = warpbreaks ()

     The Number of Breaks in Yarn during Weaving

     Description
     ...........

     This data set gives the number of warp breaks per loom, where a
     loom corresponds to a fixed length of yarn.

     Format
     ......

     ‘wool’
          Type of wool (A or B).
     ‘tension’
          The level of tension (L, M, H).
     ‘breaks’
          Number of breaks.

     There are measurements on 9 looms for each of the six types of warp
     (AL, AM, AH, BL, BM, BH).

     Source
     ......

     Tippett, L. H. C. (1950).  ‘Technological Applications of
     Statistics’.  New York: Wiley.  Page 106.

     References
     ..........

     Tukey, J. W. (1977).  ‘Exploratory Data Analysis’.  Reading, Mass:
     Addison-Wesley.

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.warpbreaks;

          summary (t)

          # TODO: Port the plotting code and OPAR to Octave



File: tablicious.info,  Node: tblish.dataset.women,  Next: tblish.dataset.WorldPhones,  Prev: tblish.dataset.warpbreaks,  Up: tblish.dataset

8.2.57.83 tblish.dataset.women
..............................

 -- Static Method: OUT = women ()

     Average Heights and Weights for American Women

     Description
     ...........

     This data set gives the average heights and weights for American
     women aged 30–39.

     Format
     ......

     ‘height’
          Height (in).
     ‘weight’
          Weight (lbs).

     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”.

     Source
     ......

     ‘The World Almanac and Book of Facts’, 1975.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          t = tblish.dataset.women;

          figure
          scatter (t.height, t.weight)
          xlabel ("Height (in)")
          ylabel ("Weight (lb")
          title ("women data: American women aged 30-39")



File: tablicious.info,  Node: tblish.dataset.WorldPhones,  Next: tblish.dataset.WWWusage,  Prev: tblish.dataset.women,  Up: tblish.dataset

8.2.57.84 tblish.dataset.WorldPhones
....................................

 -- Static Method: OUT = WorldPhones ()

     The World’s Telephones

     Description
     ...........

     The number of telephones in various regions of the world (in
     thousands).

     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.

     Source
     ......

     AT&T (1961) ‘The World’s Telephones’.

     References
     ..........

     McNeil, D. R. (1977).  ‘Interactive Data Analysis’.  New York:
     Wiley.

     Examples
     ........

          tblish.dataset.WorldPhones;

          # TODO: Port matplot() to Octave



File: tablicious.info,  Node: tblish.dataset.WWWusage,  Next: tblish.dataset.zCO2,  Prev: tblish.dataset.WorldPhones,  Up: tblish.dataset

8.2.57.85 tblish.dataset.WWWusage
.................................

 -- Static Method: OUT = WWWusage ()

     WWWusage

     Description
     ...........

     A time series of the numbers of users connected to the Internet
     through a server every minute.

     Format
     ......

     A time series of length 100.

     Source
     ......

     Durbin, J. and Koopman, S. J. (2001).  ‘Time Series Analysis by
     State Space Methods’.  Oxford: Oxford University Press.
     <http://www.ssfpack.com/dkbook/>

     References
     ..........

     Makridakis, S., Wheelwright, S. C. and Hyndman, R. J. (1998).
     ‘Forecasting: Methods and Applications’.  New York: Wiley.

     Examples
     ........

          # TODO: Come up with example code here



File: tablicious.info,  Node: tblish.dataset.zCO2,  Prev: tblish.dataset.WWWusage,  Up: tblish.dataset

8.2.57.86 tblish.dataset.zCO2
.............................

 -- Static Method: OUT = zCO2 ()

     Carbon Dioxide Uptake in Grass Plants

     Description
     ...........

     The ‘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.

     Format
     ......

     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.

     Source
     ......

     Potvin, C., Lechowicz, M. J. and Tardif, S. (1990).  The
     statistical analysis of ecophysiological response curves obtained
     from experiments involving repeated measures.  ‘Ecology’, 71,
     1389–1400.

     Pinheiro, J. C. and Bates, D. M. (2000).  ‘Mixed-effects Models in
     S and S-PLUS’. New York: Springer.

     Examples
     ........

          t = tblish.dataset.zCO2;

          # TODO: Coplot
          # TODO: Port the linear model to Octave



File: tablicious.info,  Node: tblish.datasets,  Next: tblish.evalWithTableVars,  Prev: tblish.dataset,  Up: API Alphabetically

8.2.58 tblish.datasets
----------------------

 -- Class: tblish.datasets

     Example dataset collection.

     ‘tblish.datasets’ is a collection of example datasets to go with
     the Tablicious package.

     The ‘tblish.datasets’ class provides methods for listing and
     loading the example datasets.

* Menu:

* datasets.description::
* datasets.list::
* datasets.load::


File: tablicious.info,  Node: datasets.description,  Next: datasets.list,  Up: tblish.datasets

8.2.58.1 datasets.description
.............................

 -- Static Method: description (DATASETNAME)
 -- Static Method: OUT = description (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.


File: tablicious.info,  Node: datasets.list,  Next: datasets.load,  Prev: datasets.description,  Up: tblish.datasets

8.2.58.2 datasets.list
......................

 -- Static Method: list ()
 -- Static Method: 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.


File: tablicious.info,  Node: datasets.load,  Prev: datasets.list,  Up: tblish.datasets

8.2.58.3 datasets.load
......................

 -- Static Method: load (DATASETNAME)
 -- Static Method: OUT = load (DATASETNAME)

     Load a specified dataset.

     DATASETNAME is the name of the dataset to load, as found in the
     ‘Name’ column of the dataset list.


File: tablicious.info,  Node: tblish.evalWithTableVars,  Next: tblish.examples.coplot,  Prev: tblish.datasets,  Up: API Alphabetically

8.2.59 tblish.evalWithTableVars
-------------------------------

 -- Function: OUT = tblish.evalWithTableVars (TBL, EXPR)

     Evaluate an expression against a table array’s variables.

     Evaluates the M-code expression EXPR in a workspace where all of
     TBL’s variables have been assigned to workspace variables.

     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:

          [s,p,sp] = tblish.examples.SpDb
          tmp = join (sp, p);
          shipment_weight = tblish.evalWithTableVars (tmp, "Qty .* Weight")

     See also: *note table.restrict::


File: tablicious.info,  Node: tblish.examples.coplot,  Next: tblish.examples.plot_pairs,  Prev: tblish.evalWithTableVars,  Up: API Alphabetically

8.2.60 tblish.examples.coplot
-----------------------------

 -- Function: [FIG, HAX] = tblish.examples.coplot (TBL, XVAR, YVAR,
          GVAR)
 -- Function: [FIG, HAX] = tblish.examples.coplot (FIG, TBL, XVAR, YVAR,
          GVAR)
 -- Function: [FIG, HAX] = tblish.examples.coplot (..., OPTIONNAME,
          OPTIONVALUE, ...)

     Conditioning plot.

     ‘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.

     TBL is a ‘table’ containing the data to plot.

     XVAR is the name of the table variable within TBL to use as the X
     values.  May be a variable name or index.

     YVAR is the name of the table variable within TBL to use as the Y
     values.  May be a variable name or index.

     GVAR is the name of the table variable or variables within TBL to
     use as the grouping variable(s).  The grouping variables split the
     data into groups based on the distinct values in those variables.
     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.

     FIG is the figure handle to plot into.  If FIG is not provided, a
     new figure is created.

     Name/Value options:

     ‘PlotFcn’
          The plotting function to use, supplied as a function handle.
          Defaults to ‘@plot’.  It must be a function that provides the
          signature ‘fcn(hax, X, Y, ...)’.
     ‘PlotArgs’
          A cell array of arguments to pass in to the plotting function,
          following the HAX, X, and Y arguments.

     Returns: FIG – the figure handle it plotted into HAX – array of
     axes handles to all the axes for the subplots


File: tablicious.info,  Node: tblish.examples.plot_pairs,  Next: tblish.examples.SpDb,  Prev: tblish.examples.coplot,  Up: API Alphabetically

8.2.61 tblish.examples.plot_pairs
---------------------------------

 -- Function: OUT = tblish.examples.plot_pairs (DATA)
 -- Function: OUT = tblish.examples.plot_pairs (DATA, PLOT_TYPE)
 -- Function: OUT = tblish.examples.plot_pairs (FIG, ...)

     Plot pairs of variables against each other.

     DATA is the data holding the variables to plot.  It may be either a
     ‘table’ or a struct.  Each variable or field in the ‘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.

     PLOT_TYPE is a charvec indicating what plot type to do in each
     subplot.  (‘"scatter"’ is the default.)  Valid PLOT_TYPE values
     are:

     ‘"scatter"’
          A plain scatter plot.
     ‘"smooth"’
          A scatter plot + fitted line, like R's ‘panel.smooth’ does.

     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.


File: tablicious.info,  Node: tblish.examples.SpDb,  Next: tblish.sizeof2,  Prev: tblish.examples.plot_pairs,  Up: API Alphabetically

8.2.62 tblish.examples.SpDb
---------------------------

 -- Function: SPDB = tblish.examples.SpDb ()
 -- Function: [S, P, 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 (S, P,
     SP).


File: tablicious.info,  Node: tblish.sizeof2,  Next: tblish.table.grpstats,  Prev: tblish.examples.SpDb,  Up: API Alphabetically

8.2.63 tblish.sizeof2
---------------------

 -- Function: OUT = tblish.sizeof2 (X)

     Approximate size of an array in bytes, with object support.

     This is an alternative to Octave's ‘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 ‘sizeof’ override methods
     on Tablicious's classes.  I'm not sure whether Octave's ‘sizeof’
     supports extension by method overrides, so I'm not doing that yet.
     If that happens, this ‘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 ‘sizeof’ for all of its
     variables’ arrays, plus the size of the VariableNames and any other
     metadata stored in 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.

     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


File: tablicious.info,  Node: tblish.table.grpstats,  Next: timezones,  Prev: tblish.sizeof2,  Up: API Alphabetically

8.2.64 tblish.table.grpstats
----------------------------

 -- Function: [OUT] = tblish.table.grpstats (TBL, GROUPVAR)
 -- Function: [OUT] = tblish.table.grpstats (..., 'DataVars', DATAVARS)

     Statistics by group for a table array.

     This is a table-specific implementation of ‘grpstats’ that works on
     table arrays.  It is supplied as a function in the +TBLISH package
     to avoid colliding with the global ‘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 ‘grpstats’ function.  This function is supplied
     as an alternative you can use in an environment where ‘table’
     arrays are not supported by the ‘grpstats’ that you have, though
     you need to make code changes and call it as
     ‘tblish.table.grpstats(tbl)’ instead of with a plain
     ‘grpstats(tbl)’.

     See also: table.groupby, table.findgroups, table.splitapply


File: tablicious.info,  Node: timezones,  Next: todatetime,  Prev: tblish.table.grpstats,  Up: API Alphabetically

8.2.65 timezones
----------------

 -- Function: OUT = timezones ()
 -- Function: OUT = timezones (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
     ‘/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:

     ‘Name’
          The IANA zone name, as cellstr.
     ‘Area’
          The geographical area the zone is in, as cellstr.

     Compatibility note: Matlab also includes UTCOffset and DSTOffset
     fields in the output; these are currently unimplemented.


File: tablicious.info,  Node: todatetime,  Next: vartype,  Prev: timezones,  Up: API Alphabetically

8.2.66 todatetime
-----------------

 -- Function: OUT = todatetime (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".


File: tablicious.info,  Node: vartype,  Next: vecfun,  Prev: todatetime,  Up: API Alphabetically

8.2.67 vartype
--------------

 -- Function: OUT = vartype (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.

     TYPE is the name of a type as charvec.  This may be anything that
     the ‘isa’ function accepts, or ‘'cellstr'’ to select cellstrs, as
     determined by ‘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
     ‘table’ object.


File: tablicious.info,  Node: vecfun,  Next: years,  Prev: vartype,  Up: API Alphabetically

8.2.68 vecfun
-------------

 -- Function: OUT = vecfun (FCN, X, 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.

     FCN is a function handle to apply.

     X is an array of arbitrary type which is to be sliced and passed in
     to FCN.

     DIM is the dimension along which the vector slices lay.

     Returns the collected output of the FCN calls, which will be the
     same size as X, but not necessarily the same type.


File: tablicious.info,  Node: years,  Prev: vecfun,  Up: API Alphabetically

8.2.69 years
------------

 -- Function File: OUT = years (X)
     Create a ‘duration’ X years long, or get the years in a ‘duration’
     X.

     If input is numeric, returns a ‘duration’ array in units of
     fixed-length years of 365.2425 days each.

     If input is a ‘duration’, converts the ‘duration’ to a number of
     fixed-length years as double.

     Note: ‘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 ‘calyears’.

     *Note calyears::.


File: tablicious.info,  Node: Copying,  Prev: API Reference,  Up: Top

9 Copying
*********

9.1 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.

   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 ‘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.

9.2 Manual Copyright
====================

This manual is for Tablicious, version 0.4.2.

   Copyright © 2019, 2023, 2024 Andrew Janke

     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.



Tag Table:
Node: Top784
Node: Introduction1183
Node: Getting Started2553
Node: Table Representation3365
Node: Table Construction4924
Node: Tables vs SQL6153
Node: Date and Time Representation8101
Node: datetime Class8648
Node: Datenum Compatibility9612
Node: Time Zones11144
Node: Defined Time Zones14005
Node: Durations15002
Node: duration Class15184
Node: calendarDuration Class15941
Node: Validation Functions16850
Node: Example Data Sets19161
Node: Data Sets from R20602
Node: Missing Functionality21511
Node: API Reference22997
Node: API by Category23186
Node: API Alphabetically29504
Node: array2table33578
Node: calendarDuration34500
Node: calendarDuration.calendarDuration36360
Node: calendarDuration.dispstrs36873
Node: calendarDuration.ismissing37232
Node: calendarDuration.isnan37623
Node: calendarDuration.minus38072
Node: calendarDuration.plus38417
Node: calendarDuration.times39025
Node: calendarDuration.uminus39387
Node: calmonths39640
Node: calyears40229
Node: categorical40573
Node: categorical.addcats42884
Node: categorical.categorical43283
Node: categorical.categories44556
Node: categorical.cellstr44956
Node: categorical.dispstrs45399
Node: categorical.iscategory45858
Node: categorical.ismissing46302
Node: categorical.isnanny46707
Node: categorical.isordinal47173
Node: categorical.isundefined47544
Node: categorical.mergecats48064
Node: categorical.missing48717
Node: categorical.removecats49439
Node: categorical.renamecats50082
Node: categorical.reordercats50500
Node: categorical.setcats51035
Node: categorical.squeezecats51481
Node: categorical.string51876
Node: categorical.summary52327
Node: categorical.undefined52780
Node: cell2table53327
Node: colvecfun54055
Node: contains54779
Node: datetime55597
Node: datetime.convertDatenumTimeZone57949
Node: datetime.datenum58600
Node: datetime.datenum2posix58935
Node: datetime.datestr59332
Node: datetime.datestrs59725
Node: datetime.datestruct60142
Node: datetime.datetime60942
Node: datetime.diff61751
Node: datetime.dispstrs62131
Node: datetime.eq62423
Node: datetime.ge62857
Node: datetime.gmtime63305
Node: datetime.gt63734
Node: datetime.hms64170
Node: datetime.isbetween64567
Node: datetime.isnan65051
Node: datetime.isnat65429
Node: datetime.le65703
Node: datetime.linspace66152
Node: datetime.localtime66745
Node: datetime.lt67466
Node: datetime.minus67904
Node: datetime.NaT68546
Node: datetime.ne69295
Node: datetime.ofDatenum69735
Node: datetime.ofDatestruct70091
Node: datetime.plus70601
Node: datetime.posix2datenum71115
Node: datetime.posixtime71591
Node: datetime.proxyKeys72130
Node: datetime.timeofday72780
Node: datetime.week73203
Node: datetime.ymd73458
Node: datetime.ymdhms73848
Node: days74264
Node: discretize74730
Node: dispstrs75615
Node: duration76399
Node: duration.char77826
Node: duration.dispstrs78229
Node: duration.hours78526
Node: duration.linspace78900
Node: duration.milliseconds79503
Node: duration.minutes79895
Node: duration.ofDays80283
Node: duration.seconds80769
Node: duration.years81122
Node: eqn81472
Node: head82547
Node: hours83322
Node: iscalendarduration83807
Node: iscategorical84316
Node: isdatetime84800
Node: isduration85258
Node: isfile85709
Node: isfolder85857
Node: isnanny86006
Node: istable87042
Node: istabular87742
Node: istimetable88242
Node: localdate88976
Node: localdate.datenum90289
Node: localdate.datestr90591
Node: localdate.datestrs90986
Node: localdate.datestruct91411
Node: localdate.dispstrs92343
Node: localdate.isnan92652
Node: localdate.isnat93035
Node: localdate.localdate93322
Node: localdate.NaT93876
Node: localdate.posixtime94770
Node: localdate.ymd95332
Node: milliseconds95617
Node: minutes96152
Node: missing96410
Node: missing.dispstrs97448
Node: missing.ismissing97821
Node: missing.isnan98186
Node: missing.isnanny98523
Node: missing.missing98871
Node: mustBeA99184
Node: mustBeCellstr99337
Node: mustBeCharvec99508
Node: mustBeFinite99684
Node: mustBeInteger99858
Node: mustBeMember100033
Node: mustBeNonempty100208
Node: mustBeNumeric100387
Node: mustBeReal100562
Node: mustBeSameSize100731
Node: mustBeScalar100907
Node: mustBeScalarLogical101088
Node: mustBeVector101281
Node: NaC101451
Node: NaS102381
Node: NaT103263
Node: pp104086
Node: scalarexpand104692
Node: seconds105609
Node: size2str106108
Node: splitapply106711
Node: string107822
Node: string.cell110970
Node: string.cellstr111437
Node: string.char111777
Node: string.cmp112302
Node: string.decode113276
Node: string.dispstrs113704
Node: string.empty114280
Node: string.encode114814
Node: string.erase115319
Node: string.ismissing115658
Node: string.isnanny116136
Node: string.isstring116514
Node: string.lower116839
Node: string.missing117345
Node: string.plus117776
Node: string.regexprep118346
Node: string.reverse118820
Node: string.reverse_bytes119295
Node: string.strcat120030
Node: string.strcmp120615
Node: string.strfind121309
Node: string.string121829
Node: string.strlength122460
Node: string.strlength_bytes123428
Node: string.strrep124101
Node: string.upper124714
Node: struct2table125195
Node: table125656
Node: table.addvars128524
Node: table.antijoin128948
Node: table.cartesian129690
Node: table.convertvars131053
Node: table.findgroups132038
Node: table.getvar132620
Node: table.getvars133112
Node: table.groupby133584
Node: table.height134522
Node: table.horzcat134937
Node: table.innerjoin135559
Node: table.intersect136223
Node: table.isempty136836
Node: table.ismember137164
Node: table.ismissing137566
Node: table.istable138248
Node: table.join138463
Node: table.mergevars139212
Node: table.movevars139595
Node: table.ndims140321
Node: table.numel140632
Node: table.outerfillvals141122
Node: table.outerjoin141552
Node: table.prettyprint142361
Node: table.realjoin142820
Node: table.removevars143698
Node: table.renamevars144083
Node: table.repelem144784
Node: table.repmat145225
Node: table.restrict145970
Node: table.rowfun147274
Node: table.rows2vars150355
Node: table.semijoin151460
Node: table.setdiff152317
Node: table.setDimensionNames152865
Node: table.setRowNames153741
Node: table.setvar154107
Node: table.setVariableNames154995
Node: table.setxor155776
Node: table.size156415
Node: table.splitapply156822
Node: table.splitvars157326
Node: table.squeeze157871
Node: table.stack158268
Node: table.summary158666
Node: table.table159004
Node: table.table2array160342
Node: table.table2cell160586
Node: table.table2struct161076
Node: table.union161697
Node: table.varfun162266
Node: table.varnames162804
Node: table.vertcat163176
Node: table.width163883
Node: tableOuterFillValue164195
Node: tail164373
Node: tblish.dataset165170
Node: tblish.dataset.airmiles168141
Node: tblish.dataset.AirPassengers168896
Node: tblish.dataset.airquality169665
Node: tblish.dataset.anscombe171766
Node: tblish.dataset.attenu173743
Node: tblish.dataset.attitude175182
Node: tblish.dataset.austres176412
Node: tblish.dataset.beavers177326
Node: tblish.dataset.BJsales178471
Node: tblish.dataset.BOD179579
Node: tblish.dataset.cars180551
Node: tblish.dataset.ChickWeight182283
Node: tblish.dataset.chickwts183775
Node: tblish.dataset.co2185265
Node: tblish.dataset.crimtab186753
Node: tblish.dataset.cupcake190228
Node: tblish.dataset.discoveries191201
Node: tblish.dataset.DNase192233
Node: tblish.dataset.esoph193512
Node: tblish.dataset.euro194678
Node: tblish.dataset.eurodist196350
Node: tblish.dataset.EuStockMarkets197260
Node: tblish.dataset.faithful198797
Node: tblish.dataset.Formaldehyde200633
Node: tblish.dataset.freeny202070
Node: tblish.dataset.HairEyeColor203680
Node: tblish.dataset.Harman23cor206209
Node: tblish.dataset.Harman74cor207134
Node: tblish.dataset.Indometh208101
Node: tblish.dataset.infert209428
Node: tblish.dataset.InsectSprays210836
Node: tblish.dataset.iris211780
Node: tblish.dataset.islands213319
Node: tblish.dataset.JohnsonJohnson214210
Node: tblish.dataset.LakeHuron215111
Node: tblish.dataset.lh216179
Node: tblish.dataset.LifeCycleSavings217069
Node: tblish.dataset.Loblolly218971
Node: tblish.dataset.longley220266
Node: tblish.dataset.lynx221653
Node: tblish.dataset.morley223060
Node: tblish.dataset.mtcars224794
Node: tblish.dataset.nhtemp226531
Node: tblish.dataset.Nile227520
Node: tblish.dataset.nottem228809
Node: tblish.dataset.npk229667
Node: tblish.dataset.occupationalStatus230958
Node: tblish.dataset.Orange231985
Node: tblish.dataset.OrchardSprays233370
Node: tblish.dataset.PlantGrowth235207
Node: tblish.dataset.precip236093
Node: tblish.dataset.presidents236975
Node: tblish.dataset.pressure238189
Node: tblish.dataset.Puromycin239523
Node: tblish.dataset.quakes241346
Node: tblish.dataset.randu242903
Node: tblish.dataset.rivers244154
Node: tblish.dataset.rock245047
Node: tblish.dataset.sleep246267
Node: tblish.dataset.stackloss247489
Node: tblish.dataset.state249752
Node: tblish.dataset.sunspot_month251537
Node: tblish.dataset.sunspot_year252503
Node: tblish.dataset.sunspots253352
Node: tblish.dataset.swiss254453
Node: tblish.dataset.Theoph256543
Node: tblish.dataset.Titanic258876
Node: tblish.dataset.ToothGrowth261550
Node: tblish.dataset.treering262973
Node: tblish.dataset.trees264067
Node: tblish.dataset.UCBAdmissions265485
Node: tblish.dataset.UKDriverDeaths267651
Node: tblish.dataset.UKgas269977
Node: tblish.dataset.UKLungDeaths270923
Node: tblish.dataset.USAccDeaths272199
Node: tblish.dataset.USArrests272966
Node: tblish.dataset.USJudgeRatings274939
Node: tblish.dataset.USPersonalExpenditure276254
Node: tblish.dataset.uspop277469
Node: tblish.dataset.VADeaths278388
Node: tblish.dataset.volcano279764
Node: tblish.dataset.warpbreaks281163
Node: tblish.dataset.women282419
Node: tblish.dataset.WorldPhones283726
Node: tblish.dataset.WWWusage284787
Node: tblish.dataset.zCO2285698
Node: tblish.datasets286941
Node: datasets.description287461
Node: datasets.list288013
Node: datasets.load288522
Node: tblish.evalWithTableVars288889
Node: tblish.examples.coplot289845
Node: tblish.examples.plot_pairs291919
Node: tblish.examples.SpDb293109
Node: tblish.sizeof2293959
Node: tblish.table.grpstats296141
Node: timezones297296
Node: todatetime298350
Node: vartype299344
Node: vecfun300058
Node: years300785
Node: Copying301462

End Tag Table


Local Variables:
coding: utf-8
End:
