octave_packages/dataframe-0.9.1/@dataframe/sort.m

   1 function [resu, idx] = sort(df, varargin)
   2
   3   %# -*- texinfo -*-
   4   %# @deftypefn  {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x})
   5   %# @deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim})
   6   %# @deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{mode})
   7   %# @deftypefnx {Loadable Function} {[@var{s}, @var{i}] =} sort (@var{x}, @var{dim},  @var{mode})
   8   %# Return a copy of @var{x} with the elements arranged in increasing
   9   %# order.  For matrices, @code{sort} orders the elements in each column.
  10   %#
  11   %# For example:
  12   %#
  13   %# @example
  14   %# @group
  15   %# sort ([1, 2; 2, 3; 3, 1])
  16   %#      @result{}  1  1
  17   %#          2  2
  18   %#          3  3
  19   %#
  20   %# @end group
  21   %# @end example
  22   %#
  23   %# The @code{sort} function may also be used to produce a matrix
  24   %# containing the original row indices of the elements in the sorted
  25   %# matrix.  For example:
  26   %#
  27   %# @example
  28   %# @group
  29   %# [s, i] = sort ([1, 2; 2, 3; 3, 1])
  30   %#      @result{} s = 1  1
  31   %#             2  2
  32   %#             3  3
  33   %#      @result{} i = 1  3
  34   %#             2  1
  35   %#             3  2
  36   %# @end group
  37   %# @end example
  38   %#
  39   %# If the optional argument @var{dim} is given, then the matrix is sorted
  40   %# along the dimension defined by @var{dim}.  The optional argument @code{mode}
  41   %# defines the order in which the values will be sorted.  Valid values of
  42   %# @code{mode} are `ascend' or `descend'.
  43   %#
  44   %# For equal elements, the indices are such that the equal elements are listed
  45   %# in the order that appeared in the original list.
  46   %#
  47   %# The @code{sort} function may also be used to sort strings and cell arrays
  48   %# of strings, in which case the dictionary order of the strings is used.
  49   %#
  50   %# The algorithm used in @code{sort} is optimized for the sorting of partially
  51   %# ordered lists.
  52   %# @end deftypefn
  53
  54   %% Copyright (C) 2009-2012 Pascal Dupuis <Pascal.Dupuis@uclouvain.be>
  55   %%
  56   %% This file is part of Octave.
  57   %%
  58   %% Octave is free software; you can redistribute it and/or
  59   %% modify it under the terms of the GNU General Public
  60   %% License as published by the Free Software Foundation;
  61   %% either version 2, or (at your option) any later version.
  62   %%
  63   %% Octave is distributed in the hope that it will be useful,
  64   %% but WITHOUT ANY WARRANTY; without even the implied
  65   %% warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  66   %% PURPOSE.  See the GNU General Public License for more
  67   %% details.
  68   %%
  69   %% You should have received a copy of the GNU General Public
  70   %% License along with Octave; see the file COPYING.  If not,
  71   %% write to the Free Software Foundation, 51 Franklin Street -
  72   %% Fifth Floor, Boston, MA 02110-1301, USA.
  73
  74   %#
  75   %# $Id: sort.m 9585 2012-02-05 15:32:46Z cdemills $
  76   %#
  77
  78   if !isa(df, 'dataframe'),
  79     resu = []; return;
  80   endif
  81
  82   dim = []; mode = [];
  83   vout= varargin;
  84
  85   indi = 1; while indi <= length(varargin)
  86     if isnumeric(varargin{indi}),
  87       if !isempty(dim),
  88         print_usage('@dataframe/sort');
  89         resu = [];
  90         return
  91       else
  92         dim = varargin{indi};
  93         if 3 == dim, vout(indi) = 2; endif
  94       endif
  95     else
  96       if !isempty(mode),
  97         print_usage('@dataframe/sort');
  98         resu = [];
  99         return
 100       else
 101         sort = varargin{indi};
 102       endif
 103     endif
 104     indi = indi + 1;
 105   endwhile;
 106
 107   if isempty(dim), dim = 1; endif;
 108
 109   %# pre-assignation
 110   resu = struct(df);
 111
 112   switch(dim)
 113     case {1},
 114       for indi = 1:resu._cnt(2),
 115         [resu._data{indi}, idx(:, indi, :)] = sort\
 116             (resu._data{indi}(:, resu._rep{indi}), varargin{:});
 117         resu._data{indi} = squeeze(resu._data{indi});
 118         resu._rep{indi} = 1:size(resu._data{indi}, 2);
 119       endfor
 120       if (all([1 == size(idx, 2) 1 == size(idx, 3)])),
 121         if (size(resu._ridx, 1) == resu._cnt(1)),
 122           resu._ridx = resu._ridx(idx, :);
 123         endif
 124         if (!isempty(resu._name{1, 1})),
 125           resu._name{1, 1} = resu._name{1, 1}(idx);
 126           resu._over{1, 1} = resu._over{1, 1}(idx);
 127         endif
 128       else
 129         %# data where mixed
 130         resu._ridx = idx;
 131         resu._name{1, 1} = []; resu._over{1, 1} = [];
 132       endif
 133
 134     case {2},
 135       error('Operation not implemented');
 136     case {3},
 137       for indi = 1:resu._cnt(2),
 138         [resu._data{1, indi}, idx(:, indi)] = sort(resu._data{1, indi}, vout(:));
 139       endfor
 140      otherwise
 141       error("Invalid dimension %d", dim);
 142   endswitch
 143
 144   dummy = dbstack();
 145   if (any(strmatch('quantile', {dummy.name}))),
 146     resu = df_whole(resu);
 147   else
 148     resu = dataframe(resu);
 149   endif
 150
 151 endfunction