Документирование функций Matlab
Материал из MachineLearning.
(категория: "Инструменты и технологии" вместо "Прикладные исследования") |
|||
Строка 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». | ||
- | + | == Заголовок функции == | |
- | [[ | + | М-файл содержит необязательное ключевое слово 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 | ||
+ | </source> | ||
+ | |||
+ | Общие требования: | ||
+ | # желательно указывать размерность векторов и матриц, особенно, если используются несколько матриц связанной размерности; | ||
+ | # желательно для каждой функции подготовить примеры использования, чтобы иметь возможность проиллюстрировать или протестировать ее работу; | ||
+ | # если функция является частью системы, указать, какие функции могут использоваться совместно с данной. | ||
+ | |||
+ | == Язык документирования == | ||
+ | Можно документировать как по-русски, так и по-английски. | ||
+ | При этом нужно помнить, что Matlab не поддерживает русский язык полностью. | ||
+ | В ранних версиях при отображении русских комментариев в окне редактора могут появляться вопросы. | ||
+ | В поздних версиях при создании отчета например, на языке TeX, русский язык может отображаться в некорректной кодировке. | ||
+ | |||
+ | == Тело функции == | ||
+ | Рекомендуется при создании черновых версий алгоритмов использовать ключевые слова | ||
+ | <source lang="matlab"> | ||
+ | % TODO | ||
+ | % FIXIT | ||
+ | % NOTE | ||
+ | </source> | ||
+ | Эти слова могут быть использованы для планирования дальнейшей работы; см. | ||
+ | генератор отчетов "View->Directory Reports->TODO/FIXME Report". | ||
+ | |||
+ | == Создание отчетов о вычислительных экспериментах == | ||
+ | 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.pdf]]. | ||
+ | * Пример отчета на языке LaTeX: [[Медиа:report_example_ru.pdf]]. | ||
+ | |||
+ | == Смотри также == | ||
+ | [[Matlab]] | ||
+ | [[MVR Composer]] | ||
+ | [[SourceForge]] | ||
+ | |||
+ | [[Категория:Вычислительный эксперимент]] [[Категория:Регрессионный | ||
+ | анализ]] [[Категория:Учебные курсы]] [[Категория:Инструменты и | ||
+ | технологии]] |
Версия 13:08, 17 июля 2008
Документирование функций Matlab -- способ передачи кода программ, написанных на языке Matlab коллегам и в общественное пользование. Система Matlab имеет ряд инструментов для работы с документированными функциями. В частности:
- заголовок функции показывается в поле «Description» окна «Current Directory»;
- заголовок функции и ссылка на файл, содержащий функцию показываются при генерации содержания «View->Directory Reports->Contents Report»;
- документация функции «help myfunc» показывается в окне «Command Window»;
- документация функции «doc myfunc» показывается в окне «Help»;
- список незавершенных работ и работ, требующих пересмотра показывается при генерации отчета «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
Общие требования:
- желательно указывать размерность векторов и матриц, особенно, если используются несколько матриц связанной размерности;
- желательно для каждой функции подготовить примеры использования, чтобы иметь возможность проиллюстрировать или протестировать ее работу;
- если функция является частью системы, указать, какие функции могут использоваться совместно с данной.
Язык документирования
Можно документировать как по-русски, так и по-английски. При этом нужно помнить, что Matlab не поддерживает русский язык полностью. В ранних версиях при отображении русских комментариев в окне редактора могут появляться вопросы. В поздних версиях при создании отчета например, на языке TeX, русский язык может отображаться в некорректной кодировке.
Тело функции
Рекомендуется при создании черновых версий алгоритмов использовать ключевые слова
% TODO % FIXIT % NOTE
Эти слова могут быть использованы для планирования дальнейшей работы; см. генератор отчетов "View->Directory Reports->TODO/FIXME Report".
Создание отчетов о вычислительных экспериментах
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".
- Пример отчета на языке HTML: Медиа:report_example.pdf.
- Пример отчета на языке LaTeX: Медиа:report_example_ru.pdf.
Смотри также
Matlab MVR Composer SourceForge [[Категория:Регрессионный анализ]] [[Категория:Инструменты и технологии]]