Документирование функций Matlab

Материал из MachineLearning.

(Различия между версиями)
Перейти к: навигация, поиск
(Новая: Документирование функций Matlab {{stub}} Категория: Вычислительный эксперимент)
Текущая версия (10:23, 27 декабря 2009) (править) (отменить)
м (орфография)
 
(12 промежуточных версий не показаны.)
Строка 1: Строка 1:
-
Документирование функций Matlab
+
'''Документирование функций Matlab''' — способ передачи кода программ,
 +
написанных на языке Matlab коллегам или в общественное пользование.
 +
Система [[Matlab]] имеет ряд инструментов для работы с
 +
документированными функциями. В частности:
 +
# заголовок функции показывается в поле «Description» окна «Current Directory»;
 +
# заголовок функции и ссылка на файл, содержащий функцию показываются при генерации содержания «View->Directory Reports->Contents Report»;
 +
# документация функции «help myfunc» показывается в окне «Command Window»;
 +
# документация функции «doc myfunc» показывается в окне «Help»;
 +
# список незавершенных работ и работ, требующих пересмотра показывается при генерации отчета «View->Directory Reports->TODO/FIXME Report».
-
{{stub}}
+
== Заголовок функции ==
-
[[Категория: Вычислительный эксперимент]]
+
М-файл содержит необязательное ключевое слово function начала тела функции
 +
<source lang="matlab">
 +
function [argOut1 {, argOut}] = myfunc(argIn {, arginN})
 +
</source>
 +
 
 +
Заголовок функции ставится в комментарии первой строкой до строки function, например,
 +
<source lang="matlab">
 +
% NLINFIT Nonlinear least-squares regression
 +
function [beta,r,J,Sigma,mse] = nlinfit(X,y,model,beta,options)
 +
</source>
 +
или второй строкой:
 +
<source lang="matlab">
 +
function [beta,r,J,Sigma,mse] = nlinfit(X,y,model,beta,options)
 +
% NLINFIT Nonlinear least-squares regression
 +
</source>
 +
 
 +
== Описание функции ==
 +
Описание содержит следующие необязательные секции: Description, Syntax, Arguments, Examples, See also.
 +
Например:
 +
<source lang="matlab">
 +
function hist = histmake(x, n, w)
 +
% make histogram using data sample, number of segments or their width
 +
%
 +
% hist = histmake(x, n, w)
 +
%
 +
% Arguments
 +
% x [N, 1] the input sample
 +
% n [int] optional number of segments to divide (xmin xmax) uniformly
 +
% w [scalar] optional width of a segment to divide (xmin xmax) uniformly
 +
% w [W,1] the edges of the histogram, assigned directly
 +
% if w is given, n will be ignored
 +
% if neither n nor w are given, the optimal value of n will be chosen
 +
%
 +
% hist [structure] to use in the toolbox with the following fields
 +
% .dom = [min(x), max(x)] the input domain
 +
% .edges = edges (start points) of the segments
 +
% .p = probabilities, non-cumulative
 +
% .N = length(x)
 +
%
 +
% Example
 +
% hist = histmake(randn(100,1), 5)
 +
% h = histplot(hist);
 +
%
 +
% See also
 +
% histnorm histprob histplot histc
 +
%
 +
% Revisions
 +
% Author: Paul Fleury, Date: 12/03/2005
 +
% Supervisor: Vadim Strijov, Date: 24/03/2005
 +
% Author: (Next revision author), Date: (Next revision date)
 +
%
 +
</source>
 +
 
 +
Общие требования:
 +
# желательно указывать размерность векторов и матриц, особенно, если используются несколько матриц связанной размерности;
 +
# желательно для каждой функции подготовить примеры использования, чтобы иметь возможность проиллюстрировать или протестировать ее работу;
 +
# если функция является частью системы, указать, какие функции могут использоваться совместно с данной.
 +
 
 +
== Язык документирования ==
 +
Можно документировать как по-русски, так и по-английски.
 +
При этом нужно помнить, что Matlab не поддерживает русский язык полностью.
 +
В ранних версиях при отображении русских комментариев в окне редактора могут появляться вопросы.
 +
В поздних версиях при создании отчета например, на языке TeX, русский язык может отображаться в некорректной кодировке.
 +
 
 +
== Тело функции ==
 +
Рекомендуется при создании черновых версий алгоритмов использовать ключевые слова
 +
<source lang="matlab">
 +
% TODO
 +
% FIXIT
 +
% NOTE
 +
</source>
 +
Эти слова могут быть использованы для планирования дальнейшей работы; см.
 +
генератор отчетов "View->Directory Reports->TODO/FIXME Report".
 +
 
 +
== Соглашение об именах переменных==
 +
 
 +
Рекомендуется давать переменным «говорящие» имена в формате Camel. Например:
 +
* LogicRule — логическое правило (без префикса),
 +
* strPatientName — имя пациента (строка),
 +
* idxFeature — номер признака (целочисленный индекс),
 +
* tsElConsumption — временной ряд потребления электроэнергии (структура типа ts — time series).
 +
 
 +
Так как типов в Матлабе в строгом смысле этого слова нет, то эти необязательные префиксы несут смысловую нагрузку. Часто используемые обозначения:
 +
* idx — индекс элемента вектора,
 +
* fea — признак,
 +
* obj — объект,
 +
* cls — класс,
 +
* str — строка,
 +
* vec — вектор,
 +
* mat — матрица.
 +
 
 +
Имена функций обычно даются без префикса, за исключением
 +
* demoAlgorithmName — демонстрационный файл или отчет о вычислительном эксперименте,
 +
* loadDataName — файл порождения модельных данных или загрузки реальных данных.
 +
Имена файлов специального назначение, которые будут работать в составе некоторой системы, даются в формате Camel. Файлы общего назначения получают краткое название с маленькой буквы.
 +
 
 +
== Создание отчетов о вычислительных экспериментах ==
 +
M-файлы, не использующие ключевое слово function, называются скриптами.
 +
Matlab предлагает язык разметки скриптов, удобный для автоматической генерации отчета о
 +
вычислительном эксперименте.
 +
<source lang="matlab">
 +
%% Название отчета
 +
% Описание отчета, начинается на следующей строке после названия.
 +
% После этого описания автоматически будет вставлено содержание отчета.
 +
 
 +
%%
 +
% Ячейки с пустым названием в содержание не вставляются.
 +
% После описания отчета удобно вставлять технические комментарии, например:
 +
% "Этот отчет содержит формулы, смотри вариант отчета в файле
 +
% <report_example.pdf report_example.pdf>".
 +
 
 +
% this file: report_example.m
 +
% data file:
 +
 
 +
%% Теория
 +
% Для того, чтобы вставить тег LaTex, необходимо начать новую ячейку.
 +
%%
 +
% <latex>
 +
% Будет рассмотрена задача вычисления значений функции $y = sin(x)$ и
 +
% доказано, что
 +
% $$\int\limits_{-\infty}^{\infty} sin(x) dx = 0.$$
 +
% </latex>
 +
 
 +
%% Вычислительный эксперимент
 +
% Здесь будет описание эксперимента, его цели и методы. Комментарии к
 +
% программам желательно писать по-английски.
 +
 
 +
% If the section begins with comments, please separate the comments by
 +
% empty line.
 +
N = 182;
 +
x = linspace(...
 +
datenum('1/1/2007 00:00:00'),...
 +
datenum('6/1/2007 00:00:00'),N);
 +
y = cos(x*2*pi/N);
 +
h = figure; hold on
 +
plot(x,y,'r-');
 +
plot(x,y,'r.');
 +
datetick('x','m');
 +
axis tight
 +
legend('solar histoty');
 +
xlabel('date');
 +
ylabel('altitude');
 +
% please insert the break line here to correct the plot manually
 +
% create the folder 'html/img/' in necessary
 +
saveas(h,'html/img/solar','png'); % to the html report
 +
saveas(h,'html/img/solar','psc2'); % to the LaTeX report
 +
% please comment the 'saveas' lines to keep corrected plots unchanged
 +
close(h);
 +
%%
 +
% <<img/solar.png>>
 +
%%
 +
% Вывод: очевидно, что на графике показана синусоида.
 +
 
 +
%%
 +
% Для того, чтобы вставить график в отчет LaTeX, нужно заменить расширение
 +
% .png на .ps в .tex-файле.
 +
</source>
 +
 
 +
Для генерации отчета нужно выполнить команду publish, например,
 +
<source lang="matlab">
 +
publish('report_example','html')
 +
</source>
 +
или выбрать "File->Publish to HTML".
 +
 
 +
* Пример отчета на языке HTML: [[Медиа:report_example_ru.pdf]].
 +
* Пример отчета на языке LaTeX: [[Медиа:report_example.pdf]].
 +
 
 +
== Смотри также ==
 +
* [[Matlab]]
 +
* [[MVR Composer]]
 +
* [[SourceForge]]
 +
 
 +
[[Категория:Вычислительный эксперимент]]
 +
[[Категория:Регрессионный анализ]]
 +
[[Категория:Учебные материалы]]
 +
[[Категория:Matlab]]

Текущая версия

Документирование функций Matlab — способ передачи кода программ, написанных на языке Matlab коллегам или в общественное пользование. Система Matlab имеет ряд инструментов для работы с документированными функциями. В частности:

  1. заголовок функции показывается в поле «Description» окна «Current Directory»;
  2. заголовок функции и ссылка на файл, содержащий функцию показываются при генерации содержания «View->Directory Reports->Contents Report»;
  3. документация функции «help myfunc» показывается в окне «Command Window»;
  4. документация функции «doc myfunc» показывается в окне «Help»;
  5. список незавершенных работ и работ, требующих пересмотра показывается при генерации отчета «View->Directory Reports->TODO/FIXME Report».

Содержание

Заголовок функции

М-файл содержит необязательное ключевое слово function начала тела функции 

function [argOut1 {, argOut}] = myfunc(argIn {, arginN})

Заголовок функции ставится в комментарии первой строкой до строки function, например, 

% NLINFIT Nonlinear least-squares regression
function [beta,r,J,Sigma,mse] = nlinfit(X,y,model,beta,options)

или второй строкой: 

function [beta,r,J,Sigma,mse] = nlinfit(X,y,model,beta,options)
% NLINFIT Nonlinear least-squares regression

Описание функции

Описание содержит следующие необязательные секции: Description, Syntax, Arguments, Examples, See also. Например: 

function hist = histmake(x, n, w)
% make histogram using data sample, number of segments or their width
%
% hist = histmake(x, n, w)
%
% Arguments
% x [N, 1] the input sample
% n [int] optional number of segments to divide (xmin xmax) uniformly
% w [scalar] optional width of a segment to divide (xmin xmax) uniformly
% w [W,1] the edges of the histogram, assigned directly
% if w is given, n will be ignored
% if neither n nor w are given, the optimal value of n will be chosen
%
% hist [structure] to use in the toolbox with the following fields
%   .dom = [min(x), max(x)] the input domain
%   .edges = edges (start points) of the segments
%   .p = probabilities, non-cumulative
%   .N = length(x)
%
% Example
% hist = histmake(randn(100,1), 5)
% h = histplot(hist);
%
% See also
% histnorm histprob histplot histc
% 
% Revisions
% Author: Paul Fleury, Date: 12/03/2005
% Supervisor: Vadim Strijov, Date: 24/03/2005
% Author: (Next revision author), Date: (Next revision date)
%

Общие требования:

  1. желательно указывать размерность векторов и матриц, особенно, если используются несколько матриц связанной размерности;
  2. желательно для каждой функции подготовить примеры использования, чтобы иметь возможность проиллюстрировать или протестировать ее работу;
  3. если функция является частью системы, указать, какие функции могут использоваться совместно с данной.

Язык документирования

Можно документировать как по-русски, так и по-английски. При этом нужно помнить, что Matlab не поддерживает русский язык полностью. В ранних версиях при отображении русских комментариев в окне редактора могут появляться вопросы. В поздних версиях при создании отчета например, на языке TeX, русский язык может отображаться в некорректной кодировке.

Тело функции

Рекомендуется при создании черновых версий алгоритмов использовать ключевые слова 

% TODO
% FIXIT
% NOTE

Эти слова могут быть использованы для планирования дальнейшей работы; см. генератор отчетов "View->Directory Reports->TODO/FIXME Report".

Соглашение об именах переменных

Рекомендуется давать переменным «говорящие» имена в формате Camel. Например:

  • LogicRule — логическое правило (без префикса),
  • strPatientName — имя пациента (строка),
  • idxFeature — номер признака (целочисленный индекс),
  • tsElConsumption — временной ряд потребления электроэнергии (структура типа ts — time series).

Так как типов в Матлабе в строгом смысле этого слова нет, то эти необязательные префиксы несут смысловую нагрузку. Часто используемые обозначения:

  • idx — индекс элемента вектора,
  • fea — признак,
  • obj — объект,
  • cls — класс,
  • str — строка,
  • vec — вектор,
  • mat — матрица.

Имена функций обычно даются без префикса, за исключением

  • demoAlgorithmName — демонстрационный файл или отчет о вычислительном эксперименте,
  • loadDataName — файл порождения модельных данных или загрузки реальных данных.

Имена файлов специального назначение, которые будут работать в составе некоторой системы, даются в формате Camel. Файлы общего назначения получают краткое название с маленькой буквы.

Создание отчетов о вычислительных экспериментах

M-файлы, не использующие ключевое слово function, называются скриптами. Matlab предлагает язык разметки скриптов, удобный для автоматической генерации отчета о вычислительном эксперименте. 

%% Название отчета
% Описание отчета, начинается на следующей строке после названия.
% После этого описания автоматически будет вставлено содержание отчета.
 
%%
% Ячейки с пустым названием в содержание не вставляются.
% После описания отчета удобно вставлять технические комментарии, например:
% "Этот отчет содержит формулы, смотри вариант отчета в файле
% <report_example.pdf report_example.pdf>".
 
% this file: report_example.m
% data file:
 
%% Теория
% Для того, чтобы вставить тег LaTex, необходимо начать новую ячейку.
%%
% <latex>
% Будет рассмотрена задача вычисления значений функции $y = sin(x)$ и
% доказано, что
% $$\int\limits_{-\infty}^{\infty} sin(x) dx = 0.$$
% </latex>
 
%% Вычислительный эксперимент
% Здесь будет описание эксперимента, его цели и методы. Комментарии к
% программам желательно писать по-английски.
 
% If the section begins with comments, please separate the comments by
% empty line.
N = 182;
x = linspace(...
    datenum('1/1/2007 00:00:00'),...
    datenum('6/1/2007 00:00:00'),N);
y = cos(x*2*pi/N);
h = figure; hold on
plot(x,y,'r-');
plot(x,y,'r.');
datetick('x','m');
axis tight
legend('solar histoty');
xlabel('date');
ylabel('altitude');
% please insert the break line here to correct the plot manually
% create the folder 'html/img/' in necessary
saveas(h,'html/img/solar','png'); % to the html report
saveas(h,'html/img/solar','psc2'); % to the LaTeX report
% please comment the 'saveas' lines to keep corrected plots unchanged
close(h);
%%
% <<img/solar.png>>
%%
% Вывод: очевидно, что на графике показана синусоида.
 
%%
% Для того, чтобы вставить график в отчет LaTeX, нужно заменить расширение
% .png на .ps в .tex-файле.

Для генерации отчета нужно выполнить команду publish, например, 

publish('report_example','html')

или выбрать "File->Publish to HTML".

Смотри также

Источник — «http://machinelearning.ru/wiki/index.php?title=%D0%94%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_%D1%84%D1%83%D0%BD%D0%BA%D1%86%D0%B8%D0%B9_Matlab»
Личные инструменты