04 mayo, 2015

Guía de estilo para MATLAB: Documentación

La usabilidad de un programa depende de su documentación. Si el programa está bien documentado, será posible usarlo fácilmente. De lo contrario, el programa será inútil. Aquí propongo el contenido mínimo en el texto de ayuda de funciones escritas en MATLAB.

Supongamos que creamos una función para sumar dos números

function y = add(a,b)
switch nargin
    case 2
        c = a + b;
    case 1
        c = a + a;
    otherwise
        c = NaN;
end

Se deberán incluir al menos las siguientes secciones en el texto de ayuda:

Contenido

Cabecera

La primer línea del texto de ayuda (llamada H1) inicia con el nombre de la función y una breve descripción de la función. Esta línea es importante porque lookfor busca en ella una palabra clave dada. Además, Contents despliegan esta línea para cada archivo .m en el directorio de trabajo.

% ADD  Suma dos números.
%

Descripción

En esta sección se presenta una descripción detallada de la función en el contexto del problema general o el área temática a la que pertenece. Se puede plantear el problema que la función atiende, describir las variables ambientales, proporcionar antecedentes, explicar la metodología y análisis matemáticos usados.

% Descripción:
%     Suma dos números usando la suma de los números reales. Esta suma,
%     junto con los números reales, cumplen con los cuatro axiomas de
%     grupo: cerradura, asociatividad, existencia de elemento neutro y
%     existencia de elementos inversos. Además, la suma es conmutativa, por
%     lo que los reales con esta suma son un grupo abeliano.
%

Autores

Admás del nombre de los autores, es importante incluir algún medio de contacto, por ejemplo, dirección de correo electrónico.

% Autor:
%     Evaristo Rojas <evaristo.rojas@islas.org.mx>
%

Referencias

Debemos incluir las referencias en las que se encuentran los antecedentes de nuestra descripción y las referencias en las que basamos los métodos y análisis matemáticos. También podemos usar esta sección para referir al lector a las definiciones de los términos usados.

% Referencias:
%     - <a href="http://es.wikipedia.org/wiki/Grupo_abeliano">Grupo abeliano</a>
%     - <a href="http://es.wikipedia.org/wiki/Suma">Suma</a>
%

Sintaxis

Enlistamos todas las posibles maneras en las que se puede invocar la función.

% Sintaxis:
%     Y = add(A) suma A a sí mismo.
%     Y = add(A,B) suma A mas B.
%

Entrada

Enlistamos todos los posibles argumentos de entrada de la función, los cuales se mostraron en la sección de Sintaxis. Indicamos su clase y dominio. Debe quedar claro cual es la relación entre estos parámetros y las variables del problema general.

% Entrada:
%     A  (double)  Número real que será sumado.
%     B  (double)  Número real que será sumado.
%

Salida

Enlistamos todos los valores de salida de la función, los cuales se mostraron en la sección de Sintaxis. Indicamos su clase y dominio.

% Salida:
%     Y  (double)  Total de la suma.
%

Ejemplos

Incluiremos ejeplos que sean autónomos, es decir, que se puedan copiar y pegar en la ventana de comandos para ser ejecutados. Se deberá incluir un ejemplo por cada manera mostrada en la sección de Sintaxis.

% Ejemplos:
%     Y = add(1); % devuelve Y = 2
%     Y = add(2,3); % devuelve Y = 5
%     Y = add(); % devuelve Y = NaN
%

See also

Al incluir nombres de funciones al final del texto de ayuda en una línea que inicie con % See also se crearán enlaces hacia dichas funciones.

% See also:
%     sum, cumsum, diff.
%

Resultado

Escribiendo el texto de ayuda de esta manera, obtendremos ayuda completa que nos permitirar usar la función fácilmente.

help add
  ADD  Suma dos números.
 
  Descripción:
      Suma dos números usando la suma de los números reales. Esta suma,
      junto con los números reales, cumplen con los cuatro axiomas de
      grupo: cerradura, asociatividad, existencia de elemento neutro y
      existencia de elementos inversos. Además, la suma es conmutativa, por
      lo que los reales con esta suma son un grupo abeliano.
 
  Autor:
      Evaristo Rojas <evaristo.rojas@islas.org.mx>
 
  Referencias:
      - Grupo abeliano
      - Suma
 
  Sintaxis:
      Y = add(A) suma A a sí mismo.
      Y = add(A,B) suma A mas B.
 
  Entrada:
      A  (double)  Número real que será sumado.
      B  (double)  Número real que será sumado.
 
  Salida:
      Y  (double)  Total de la suma.
 
  Ejemplos:
      Y = add(1); % devuelve Y = 2
      Y = add(2,3); % devuelve Y = 5
      Y = add(1,2,3); % devuelve Y = NaN 
 
  See also:
      sum, cumsum, diff.

Referencias

07 marzo, 2015

Guía de estilo para MATLAB: Metadatos

Cuando proceso datos en MATLAB uso estructuras para manejar los metadatos. El uso de estructuras hace engorroso el acceso a los datos pero me facilita el manejo de los metadatos porque me permite tenerlos en la misma variable. Para cada variable creo una estructura con el campo data donde almaceno el valor de la variable; el resto de los campos de la estructura contienen los metadatos de la variable.

Contents

Variables individuales

Supongamos que queremos graficar una serie de tiempo de la marea. Usaremos las estructuras Tiempo y Altura.

% Inicializar
clear, close all

% Se define la variable independiente
Tiempo.data = linspace(0,24);
Tiempo.units = 'hr';
Tiempo.long_name = 'Tiempo';
Tiempo.standard_name = 'time';
Tiempo.axis = 'T';

% Se define la variable dependiente
Altura.data = sin(Tiempo.data/24*2*pi);
Altura.units = 'm';
Altura.long_name = 'Altura del Nivel del Mar';
Altura.standard_name = 'sea_surface_height';

Atributos globales

Conviene incluir las estructuras de ambas variables en una estructura que contenga los atributos globales de la serie de tiempo.

% Incluir ambas variables
Marea.Tiempo=Tiempo;
Marea.Altura=Altura;

% Definir atributos globales
Marea.Metadata.title = 'Serie de tiempo de la marea';
Marea.Metadata.institution = 'GECI';
Marea.Metadata.source = 'Datos sintéticos';
Marea.Metadata.history = [datestr(now,30) ' Versión inicial'];
Marea.Metadata.references = 'http://evaristor.blogspot.com/search/label/MATLAB';
Marea.Metadata.comment = 'Guía de estilo para MATLAB: Metadatos';

% Graficado
plot(Marea.Tiempo.data,Marea.Altura.data)
xlabel([Marea.Tiempo.long_name ' (' Marea.Tiempo.units ')']);
ylabel([Marea.Altura.long_name ' (' Marea.Altura.units ')']);
title(Marea.Metadata.title)

19 junio, 2013

Definiciones sobre datos ambientales georreferenciados

Se define punto, serie de tiempo, perfil, trayectoria, mapa, campo y sección en el contexto de datos ambientales georreferenciados.

En las siguientes definiciones \(x,y\in\mathbb{R}\) son coordenadas horizontales, \(z\in\mathbb{R}\) es la posición vertical, \(t\in\mathbb{R}^+\) es el tiempo y \(u\) es el valor de la variable ambiental. El subíndice \(0\) se usa para denotar un elemento fijo, \(\left\{a_k\right\}_{k=1}^n\) representa un vector de dimensión \(n\) y \(A_{l,m}\) es una matriz \(l \times m\).

Definiciones

Punto es una quíntupla de la forma \[\left(t_0,x_0,y_0,z_0,u_0\right).\]

Serie de tiempo es una quíntupla de la forma \[\left(\left\{t_k\right\}_{k=1}^n,x_0,y_0,z_0,\left\{u_k\right\}_{k=1}^n\right).\]

Perfil es una quíntupla de la forma \[\left(t_0,\left\{x_k\right\}_{k=1}^n,\left\{y_k\right\}_{k=1}^n,\left\{z_k\right\}_{k=1}^n,\left\{u_k\right\}_{k=1}^n\right).\]

Perfil vertical es una quíntupla de la forma \[\left(t_0,x_0,y_0,\left\{z_k\right\}_{k=1}^n,\left\{u_k\right\}_{k=1}^n\right).\]

Perfil horizontal es una quíntupla de la forma \[\left(t_0,\left\{x_k\right\}_{k=1}^n,\left\{y_k\right\}_{k=1}^n,z_0,\left\{u_k\right\}_{k=1}^n\right).\]

Perfil zonal es una quíntupla de la forma \[\left(t_0,\left\{x_k\right\}_{k=1}^n,y_0,z_0,\left\{u_k\right\}_{k=1}^n\right).\]

Perfil meridional es una quíntupla de la forma \[\left(t_0,x_0,\left\{y_k\right\}_{k=1}^n,z_0,\left\{u_k\right\}_{k=1}^n\right).\]

Trayectoria es una quíntupla de la forma \[\left(\left\{t_k\right\}_{k=1}^n,\left\{x_k\right\}_{k=1}^n,\left\{y_k\right\}_{k=1}^n,\left\{z_k\right\}_{k=1}^n,\left\{u_k\right\}_{k=1}^n\right).\]

Mapa es una quíntupla de la forma \[\left(t_0,X_{l,m},Y_{l,m},z_0,U_{l,m}\right).\]

Campo es una quíntupla de la forma \[\left(\left\{t_k\right\}_{k=1}^n,X_{l,m},Y_{l,m},z_0,\left\{U_{k,l,m}\right\}_{k=1}^n\right).\]

Sección es una quíntupla de la forma \[\left(t_0,\left\{x_j\right\}_{j=1}^m,\left\{y_j\right\}_{j=1}^m,\left\{z_k\right\}_{k=1}^n,U_{m,n}\right).\]