evaristor

Cómo escribir un buen mensaje de consignación

2015-10-19T15:54:00.000-07:00

La siguiente es una lista de recomendaciones para escribir mensajes de consignación útiles.

El mensaje de consignación debe describir qué cambio se hizo y por qué
El mensaje debe comenzar con un verbo en modo imperativo para describir qué cambio se hizo
Describir por qué se hizo el cambio es más importante que describir qué cambio se hizo
Cada línea debe ser menor o igual a 80 caracteres
La primer línea debe ser una oración completa
El resto del mensaje se debe ser un texto formado por párrafos
El mensaje puede ser tan extenso como sea necesario para describir la consignación de forma detallada
Es más fácil redactar los mensajes cuando se hacen muchas consignaciones con pocos cambios en lugar de pocas consignaciones con muchos cambios

Gracias a Yutzil y David por compilar la primer versión de esta lista.

Guía de estilo para MATLAB: Documentación

2015-05-04T17:49:00.000-07:00

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:

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
%

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

Cómo guardar los datos y metadatos en una misma estructura de MATLAB

2015-03-07T15:00:00.000-08:00

Cuando proceso datos en MATLAB uso estructuras para manejar los datos y 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.

Variables individuales
Atributos globales

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)

Definiciones sobre datos ambientales georreferenciados

2013-06-19T13:32:00.000-07:00

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_{m,n}$ es una matriz $m \times n$.

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,\left\{x_k\right\}_{k=1}^n,\left\{y_k\right\}_{k=1}^m,z_0,U_{m,n}\right).\]

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

Sección vertical 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}^m,U_{m,n}\right).\]

Plantilla LaTeX

2013-03-11T09:30:00.000-07:00

Ésta es la plantilla que comúnmente uso al escribir en LaTeX.

\documentclass[12pt,letterpaper,onecolumn]{article}
\usepackage{amsfonts,amsmath,amssymb,amsthm,dsfont}
\usepackage[utf8]{inputenc}
\usepackage[spanish,mexico]{babel}
% Incluir figuras
\usepackage{graphicx}
% Formato de párrafos
\usepackage{parskip}
\setlength{\parindent}{20pt}
% Encabezado y pie de página
\usepackage{fancyhdr,lastpage}
\pagestyle{fancy}
\fancyhf{}
\lhead{\footnotesize{Instituci\'on}}
\rhead{\footnotesize{Proyecto}}
\rfoot{\scriptsize{\thepage\ de \pageref{LastPage}}}
% Info
\title{T\'itulo}
\author{Evaristo Rojas}
% Documento
\begin{document}
\maketitle
\input{documento.tex}
\end{document}

Guía de estilo para MATLAB: Nomenclatura

2013-02-01T08:27:00.000-08:00

En la nomenclatura de variables y funciones en MATLAB uso las siguientes convenciones

Contenido

Variables
Funciones
Referencia

Variables

Los nombres de las variables se escriben en español
Deben ser nombres descriptivos y sin abreviaturas; generalmente, serán nombres largos.
La primer letra de cada palabra en mayúsculas, excepto en la primer palabra (lowerCamelCase). Ejemplos: tiempo, distanciaHorizontal, perroGris
Si la variable es una estructura también la primer letra de la primer palabra es mayúscula (UpperCamelCase). Ejemplos: PerroGris.estatura, PerroGris.nombreCompleto, PerroGris.ComidaFavorita.desayuno
Si la variable representa el número total de elementos de un conjunto se usa el prefijo n. Ejemplos: nArchivos, nPerros
Si la variable se usa para iterar se utiliza el prefijo i. Ejemplo: for iPerro = 1:nPerros, ... , end
Para variables lógicas se usa el prefijo es. Ejemplos: esPerro, esGato
Si la variable es el índice de un arreglo se usa el prefijo ind. Ejemplo: indPerro = find(esPerro)
Se indican la unidades de las variables con un sufijo separado del nombre de la variable por un guion bajo. Ejemplos: distancia_m, peso_kg, tiempo_s

Funciones

Los nombres de las funciones se escriben en inglés
El nombre debe estar compuesto por un verbo seguido de un objeto. Ejemplos: processData(), petDog(). Si la función realiza tantas tareas que no sabes cual verbo escoger entonces tu función es incorrecta; cada función debe realizar una única acción y la debe hacer bien.
Si la función cambia el formato del argumento de entrada se usa la notación input2output. Ejemplos: jpg2bmp(), txt2pdf(), lbs2kg()
Las funciones que calculan un sólo dato de salida se pueden nombrar como ese dato (para evitar tener demasiadas funciones con el prefijo compute). Ejemplos: promedio = mean(datos), cuadrado = square(numero)
Si la función devuelve valores lógicos se usa el prefijo is. Ejemplos: esPerro = isDog(perroGris)

Referencia

MATLAB Programming Style Guidelines

Sumar un vector renglón a una matriz en MATLAB

2011-03-04T11:21:00.000-08:00

Supongamos que tenemos una matriz A con m renglones y n columnas y un vector b con n columnas. Queremos sumarle a cada columna de A el correspondiente elemento de b. Tal vez nuestro primer impulso es intentar A+b pero MATLAB nos dirá que Matrix dimensions must agree. Entonces se nos antojará un for de 1 a n, pero no debemos caer en la tentación. Una mejor opción es usar repmat.

m = 10; % Diez renglones
n = 5; % Cinco columnas
A = randi(9,m,n) % Matriz con números al azar del 1 al 9
b = randi(99,1,n) % Vector renglón con números al azar del 1 al 99


A =

     8     2     6     7     4
     9     9     1     1     4
     2     9     8     3     7
     9     5     9     1     8
     6     8     7     1     2
     1     2     7     8     5
     3     4     7     7     5
     5     9     4     3     6
     9     8     6     9     7
     9     9     2     1     7


b =

    28    68    65    17    12

Usando repmat podemos crear una nueva matriz B donde cada renglón sea el vector b.

B = repmat(b,m,1) % Creamos una matriz C


B =

    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12
    28    68    65    17    12

y ahora sí podemos sumar

suma = A+B


suma =

    36    70    71    24    16
    37    77    66    18    16
    30    77    73    20    19
    37    73    74    18    20
    34    76    72    18    14
    29    70    72    25    17
    31    72    72    24    17
    33    77    69    20    18
    37    76    71    26    19
    37    77    67    18    19

Ajustar una linea recta usando algoritmos genéticos en MATLAB

2008-06-29T06:00:00.000-07:00

Encuentra los parámetros $m$ y $b$ de la ecuación de la linea recta $y=mx+b$ que mejor se ajusta a los datos $\{(x_i,y_i)\}_{i=1}^{n}$ mediante un sencillo Algoritmo Genético (AG). Se compara el resultado obtenido con AG contra el obtenido con Mínimos Cuadrados.

Contenido

Definición del problema
Parámetros iniciales
Población inicial
Iteraciones
Orden aleatorio de parejas
Cruza
Mutacion
Cálculo de la aptitud (o viabilidad)
Seleccion
Resultados

Definición del problema

Se genera un conjunto de datos sintéticos $\{(x_i,y_i)\}_{i=1}^{n}$ donde la variable dependiente $y$ es un vector de números aleatorios en el intervalo de 0 a 1 por lo que se espera que la mejor solución sea cercana a $m=0$, $b=0.5$

x=linspace(1,100); % dominio de 1 a 100
y=rand(1,100);     % números aleatorios en el intervalo de 0 a 1

Parámetros iniciales

Se configua el Algoritmo definiendo parámetros análogos en la Genética

generaciones = 800; % iteraciones del algoritmo
n = 200;            % tamaño de la población de soluciones
probabilidad = 0.6; % probabilidad de que cada gen mute
mutacion = [1 1];   % máximo valor que puede mutar

Población inicial

Se genera aleatoriamente una población inicial de posibles soluciones. La primer columna representa el gen que define la pendiente $m$ de la recta. La segunda columna representa el gen que define la ordenada al origen $b$. Cada uno de los $n$ individuos (renglones) representa una posible solución.

poblacion = rand(n,2);

Iteraciones

La población de soluciones evoluciona mediante la cruza y mutación

s = n;
hw = waitbar(0,'Evolucionando...');
for i = 1:generaciones

Orden aleatorio de parejas

    poblacion(:,3) = rand(s,1);
    poblacion = sortrows(poblacion,+3);

Cruza

    poblacion=[poblacion; poblacion(1:2:end-1,1) poblacion(2:2:end,2) zeros(fix(s/2),1); poblacion(2:2:end,1) poblacion(1:2:end-1,2) zeros(fix(s/2),1)];

Mutacion

    s = size(poblacion,1);
    poblacion=[poblacion; poblacion+[(rand(s,3)<probabilidad).*(rand(s,3)*2-1).*repmat([mutacion 0],s,1)]];

Cálculo de la aptitud (o viabilidad)

La tercer columna de poblacion representa la aptitud (viabilidad) de la solución, menor es mejor.

    s = size(poblacion,1);
    m = repmat(poblacion(:,1),1,100);
    b = repmat(poblacion(:,2),1,100);
    X = repmat(x,s,1);
    Y = repmat(y,s,1);
    Y2=m.*X+b;
    poblacion(:,3)=sum(abs(Y-Y2),2);

Seleccion

    poblacion = unique(poblacion,'rows');
    poblacion = sortrows(poblacion,+3);
    s = min([size(poblacion,1),n]);
    poblacion = poblacion(1:s,:);
    waitbar(i/generaciones,hw)

end
close(hw)

Resultados

Se compara el resultado obtenido con AG contra el obtenido con mínimos cuadrados

error_ag = poblacion(1,3);
p = polyfit(x,y,1);
y3 = polyval(p,x);
error_mc = sum(abs(y3-y));
plot(x,y,'.',x,polyval(poblacion(1,1:2),x),x,y3,':')
axis([0 100 -0.5 1.5])
legend('Datos Sintéticos','Algoritmos Genéticos (AG)','Mínimos Cuadrados (MC)')
text(1,-.167,['AG: Error = ' num2str(error_ag) ', m = ' num2str(poblacion(1,1)) ', b = ' num2str(poblacion(1,2))])
text(1,-.333,['MC: Error = ' num2str(error_mc) ', m = ' num2str(p(1)) ', b = ' num2str(p(2))])