codevariability 0.2.0__py3-none-any.whl

codevariability/interop.py

@@ -0,0 +1,94 @@
+"""Interoperability helpers for language-specific analysis adapters."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from .exceptions import AnalysisError
+from .validation import metric_name, similarity_matrix
+
+
+def _unique_keys(items):
+    result = {}
+    for key, value in items:
+        if key in result:
+            raise AnalysisError(f"Chave JSON duplicada: {key}.")
+        result[key] = value
+    return result
+
+
+def load_matrix_json(path: str | Path) -> tuple[str, pd.DataFrame]:
+    """Load the JSON matrix schema emitted by a codevariability language adapter."""
+    try:
+        payload = json.loads(
+            Path(path).read_text(encoding="utf-8"), object_pairs_hook=_unique_keys
+        )
+    except (OSError, UnicodeError, ValueError, RecursionError, TypeError) as exc:
+        raise AnalysisError(
+            f"Não foi possível ler o JSON de métrica externa: {exc}."
+        ) from exc
+    if not isinstance(payload, dict):
+        raise AnalysisError(
+            "JSON de métrica externa inválido ou versão de esquema não suportada."
+        )
+    required = {"schema_version", "metric", "files", "matrix"}
+    missing = required - set(payload)
+    if missing or payload.get("schema_version") != "codevariability.matrix.v1":
+        raise AnalysisError(
+            "JSON de métrica externa inválido ou versão de esquema não suportada."
+        )
+    files = payload["files"]
+    if (
+        not isinstance(files, list)
+        or not files
+        or not all(isinstance(name, str) and name for name in files)
+        or len(files) != len(set(files))
+    ):
+        raise AnalysisError(
+            "O JSON de métrica externa deve declarar nomes de arquivo únicos."
+        )
+    metric = metric_name(payload["metric"])
+    matrix = payload["matrix"]
+    if (
+        not isinstance(metric, str)
+        or not metric
+        or not isinstance(matrix, list)
+        or len(matrix) != len(files)
+        or any(not isinstance(row, list) or len(row) != len(files) for row in matrix)
+    ):
+        raise AnalysisError(
+            "O JSON de métrica externa deve conter uma métrica e uma matriz quadrada compatível com os arquivos."
+        )
+    try:
+        frame = similarity_matrix(
+            pd.DataFrame(matrix, index=files, columns=files, dtype=object), files
+        )
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise AnalysisError(
+            "A matriz externa deve conter somente números reais finitos."
+        ) from exc
+    frame.attrs["metric_id"] = payload.get("metric_id")
+    adapter_metadata = payload.get("metadata")
+    if adapter_metadata is not None and not isinstance(adapter_metadata, dict):
+        raise AnalysisError("Os metadados do adaptador devem ser um objeto JSON.")
+    if frame.attrs["metric_id"] is not None and (
+        not isinstance(frame.attrs["metric_id"], str)
+        or not frame.attrs["metric_id"].strip()
+    ):
+        raise AnalysisError("metric_id deve ser texto não vazio.")
+    if isinstance(adapter_metadata, dict):
+        frame.attrs["adapter_metadata"] = adapter_metadata
+        frame.attrs["normalization"] = adapter_metadata.get("normalization")
+        dimensions = adapter_metadata.get("metric_dimensions")
+        if isinstance(dimensions, dict):
+            frame.attrs["dimension"] = dimensions.get(metric)
+        elif dimensions is not None:
+            raise AnalysisError("metric_dimensions deve ser um objeto JSON.")
+        for attribute in ("normalization", "dimension"):
+            value = frame.attrs.get(attribute)
+            if value is not None and (not isinstance(value, str) or not value.strip()):
+                raise AnalysisError(f"{attribute} deve ser texto não vazio.")
+    return metric, frame

codevariability/metrics.py

@@ -0,0 +1,89 @@
+"""Normalized pairwise similarity metrics."""
+
+from __future__ import annotations
+
+from itertools import combinations
+from typing import Callable, Mapping, Sequence
+
+import pandas as pd
+from rapidfuzz.distance import LCSseq, Levenshtein
+from sklearn.feature_extraction.text import CountVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+from .ast_tree_edit import (
+    AST_TREE_EDIT_METRIC,
+    AST_TREE_EDIT_METRIC_ID,
+    ast_tree_edit_similarity,
+)
+from .normalization import code_tokens, text_tokens
+
+DEFAULT_METRICS = ("cosine", "jaccard", "lcs", "levenshtein")
+METRICS = (*DEFAULT_METRICS, AST_TREE_EDIT_METRIC)
+METRIC_IDS = {
+    "cosine": "cosine_bag_of_words_text_v1",
+    "jaccard": "jaccard_word_set_text_v1",
+    "lcs": "lcs_code_tokens_v1",
+    "levenshtein": "levenshtein_code_tokens_v1",
+    AST_TREE_EDIT_METRIC: AST_TREE_EDIT_METRIC_ID,
+}
+METRIC_DIMENSIONS = {
+    "cosine": "textual",
+    "jaccard": "textual",
+    "lcs": "syntactic_token_sequence",
+    "levenshtein": "syntactic_token_sequence",
+    AST_TREE_EDIT_METRIC: "structural_ast",
+}
+def _empty_matrix(names: Sequence[str]) -> pd.DataFrame:
+    matrix = pd.DataFrame(0.0, index=names, columns=names, dtype=float)
+    for name in names:
+        matrix.loc[name, name] = 1.0
+    return matrix
+
+
+def cosine(sources: Mapping[str, str]) -> pd.DataFrame:
+    names = list(sources)
+    corpus = [" ".join(text_tokens(sources[name])) for name in names]
+    if not any(corpus):
+        return _empty_matrix(names)
+    vectors = CountVectorizer(token_pattern=r"(?u)\b\w+\b").fit_transform(corpus)
+    return pd.DataFrame(cosine_similarity(vectors), index=names, columns=names)
+
+
+def jaccard(sources: Mapping[str, str]) -> pd.DataFrame:
+    names = list(sources)
+    sets = {name: set(text_tokens(text)) for name, text in sources.items()}
+    matrix = _empty_matrix(names)
+    for left, right in combinations(names, 2):
+        union = sets[left] | sets[right]
+        value = len(sets[left] & sets[right]) / len(union) if union else 1.0
+        matrix.loc[left, right] = matrix.loc[right, left] = value
+    return matrix
+
+
+def lcs(sources: Mapping[str, str]) -> pd.DataFrame:
+    names = list(sources)
+    processed = {name: code_tokens(text, name) for name, text in sources.items()}
+    matrix = _empty_matrix(names)
+    for left, right in combinations(names, 2):
+        value = LCSseq.normalized_similarity(processed[left], processed[right])
+        matrix.loc[left, right] = matrix.loc[right, left] = value
+    return matrix
+
+
+def levenshtein(sources: Mapping[str, str]) -> pd.DataFrame:
+    names = list(sources)
+    processed = {name: code_tokens(text, name) for name, text in sources.items()}
+    matrix = _empty_matrix(names)
+    for left, right in combinations(names, 2):
+        value = Levenshtein.normalized_similarity(processed[left], processed[right])
+        matrix.loc[left, right] = matrix.loc[right, left] = value
+    return matrix
+
+
+CALCULATORS: dict[str, Callable[..., pd.DataFrame]] = {
+    "cosine": cosine,
+    "jaccard": jaccard,
+    "lcs": lcs,
+    "levenshtein": levenshtein,
+    AST_TREE_EDIT_METRIC: ast_tree_edit_similarity,
+}

codevariability/normalization.py

@@ -0,0 +1,257 @@
+"""Reproducible preprocessing for textual and code-token analyses."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+
+from pygments import lex
+from pygments.lexers import get_lexer_by_name, get_lexer_for_filename
+from pygments.token import Comment, Operator, Text
+from pygments.util import ClassNotFound
+
+TEXT_NORMALIZATION = "unicode_words_casefold_v1"
+CODE_TOKENIZATION = "pygments_lexemes_with_generic_fallback_v2"
+
+_WORD = re.compile(r"(?u)\b\w+\b")
+_GENERIC_CODE_TOKEN = re.compile(
+    r"""(?x)
+    (?:0[xX][0-9a-fA-F]+|0[bB][01]+|0[oO][0-7]+|\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)
+    |(?:[^\W\d]\w*)
+    |(?:===|!==|>>>|<<=|>>=|\*\*=|//=|\?\?=|\*\*|//|==|!=|<=|>=|&&|\|\||\?\?|\?\.|=>|->|::|\.\.\.|\+\+|--|\+=|-=|\*=|/=|%=|&=|\|=|\^=|:=|<<|>>)
+    |(?:[^\s\w])
+    """,
+    flags=re.UNICODE,
+)
+_COMPOUND_OPERATORS = {
+    "===",
+    "!==",
+    ">>>",
+    "<<=",
+    ">>=",
+    "**",
+    "//",
+    "==",
+    "!=",
+    "<=",
+    ">=",
+    "**=",
+    "//=",
+    "??=",
+    "&&",
+    "||",
+    "??",
+    "?.",
+    "=>",
+    "->",
+    "::",
+    "...",
+    "++",
+    "--",
+    "+=",
+    "-=",
+    "*=",
+    "/=",
+    "%=",
+    "&=",
+    "|=",
+    "^=",
+    ":=",
+    "<<",
+    ">>",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class CodeSegment:
+    """A code segment and its optional Markdown language identifier."""
+
+    code: str
+    language: str | None = None
+    start_line: int = 1
+
+
+def normalize_text(text: str) -> str:
+    """Apply only language-independent textual normalization."""
+
+    normalized = (
+        unicodedata.normalize("NFC", text).replace("\r\n", "\n").replace("\r", "\n")
+    )
+    return " ".join(normalized.casefold().split())
+
+
+def text_tokens(text: str) -> list[str]:
+    """Return case-folded Unicode words from the complete response."""
+
+    return _WORD.findall(normalize_text(text))
+
+
+def fenced_code_segments(text: str) -> tuple[CodeSegment, ...]:
+    """Scan closed backtick/tilde fences once, preserving code and line numbers.
+
+    Only a complete delimiter line closes a fence. Unterminated fences are
+    rejected, so malformed Markdown cannot silently become an empty program.
+    """
+    from .exceptions import AnalysisError
+
+    result: list[CodeSegment] = []
+    delimiter: str | None = None
+    width = 0
+    language: str | None = None
+    start_line = 1
+    code: list[str] = []
+    for number, line in enumerate(text.splitlines(keepends=True), 1):
+        stripped = line.strip(" \t\r\n")
+        if delimiter is not None:
+            if (
+                stripped
+                and stripped[0] == delimiter
+                and len(stripped) >= width
+                and not stripped.strip(delimiter)
+            ):
+                result.append(CodeSegment("".join(code), language, start_line))
+                delimiter = None
+                code = []
+            else:
+                code.append(line)
+            continue
+        candidate = line.lstrip(" \t")
+        if not candidate or candidate[0] not in {"`", "~"}:
+            continue
+        marker = candidate[0]
+        count = len(candidate) - len(candidate.lstrip(marker))
+        if count < 3:
+            continue
+        info = candidate[count:].strip()
+        if marker == "`" and "`" in info:
+            continue
+        delimiter, width = marker, count
+        language = info.split(maxsplit=1)[0] if info else None
+        start_line = number + 1
+    if delimiter is not None:
+        raise AnalysisError(f"Fence Markdown sem fechamento (linha {start_line - 1}).")
+    return tuple(result)
+
+
+def code_segments(text: str) -> tuple[CodeSegment, ...]:
+    """Extract closed fences, or retain the complete unmodified source."""
+    segments = fenced_code_segments(text)
+    return segments or (CodeSegment(text),)
+
+
+def _lexer(filename: str, language: str | None):
+    try:
+        if language:
+            return get_lexer_by_name(language, stripnl=False, ensurenl=False)
+        return get_lexer_for_filename(filename, stripnl=False, ensurenl=False)
+    except ClassNotFound:
+        return None
+
+
+def _generic_tokens(code: str) -> list[str]:
+    # Resolve closing quotes once, backwards. Repeated failed searches from
+    # escaped quotes in an unterminated string must not rescan every suffix.
+    # next_end[q] is the first legal closing q from the next character;
+    # after_next[q] handles the two-character escape branch of the old grammar.
+    quotes = ('"', "'", '`')
+    next_end = [-1, -1, -1]
+    after_next = next_end
+    endings: dict[int, int] = {}
+    for index in range(len(code) - 1, -1, -1):
+        character = code[index]
+        current = []
+        for position, quote in enumerate(quotes):
+            if character == quote:
+                endings[index] = next_end[position]
+                current.append(index)
+            elif character == "\\":
+                current.append(after_next[position] if index + 1 < len(code) and code[index + 1] != "\n" else -1)
+            else:
+                current.append(next_end[position])
+        after_next, next_end = next_end, current
+    tokens = []
+    index = 0
+    while index < len(code):
+        end = endings.get(index, -1)
+        if end >= 0:
+            tokens.append(code[index:end + 1])
+            index = end + 1
+        else:
+            match = _GENERIC_CODE_TOKEN.match(code, index)
+            if match is None:
+                index += 1
+            else:
+                tokens.append(match.group(0))
+                index = match.end()
+    return tokens
+
+
+def _pygments_tokens(code: str, lexer) -> list[str]:
+    result: list[str] = []
+    adjacent_operator = False
+    for token_type, value in lex(code, lexer):
+        if token_type in Comment or not value:
+            adjacent_operator = False
+            continue
+        if value.isspace():
+            adjacent_operator = False
+            continue
+        if token_type in Operator:
+            candidate = f"{result[-1]}{value}" if adjacent_operator else value
+            if adjacent_operator and candidate in _COMPOUND_OPERATORS:
+                result[-1] = candidate
+            else:
+                result.append(value)
+            adjacent_operator = True
+            continue
+        adjacent_operator = False
+        if token_type in Text:
+            result.extend(_generic_tokens(value))
+        else:
+            result.append(value.replace("\r\n", "\n").replace("\r", "\n"))
+    return result
+
+
+def code_tokens(text: str, filename: str) -> list[str]:
+    """Return ordered code lexemes, excluding comments and whitespace.
+
+    Pygments supplies language lexers when the filename or Markdown fence has
+    a known language. Unknown languages use the documented generic tokenizer;
+    this fallback is deterministic but is not presented as a compiler lexer.
+    Fragment boundary markers prevent matches from crossing code blocks.
+    """
+
+    segments = (
+        fenced_code_segments(text)
+        if Path(filename).suffix.lower() in {".md", ".markdown"}
+        else (CodeSegment(text),)
+    )
+    result: list[str] = []
+    for segment in segments:
+        lexer = _lexer(filename, segment.language)
+        tokens = (
+            _pygments_tokens(segment.code, lexer)
+            if lexer
+            else _generic_tokens(segment.code)
+        )
+        if not tokens:
+            continue
+        if result:
+            result.append("<CODE_FRAGMENT_BOUNDARY>")
+        result.extend(tokens)
+    return result
+
+
+def uses_python_code(text: str, filename: str) -> bool:
+    """Route .py source or explicitly Python Markdown fences to the parser."""
+    suffix = Path(filename).suffix.lower()
+    if suffix == ".py":
+        return True
+    if suffix not in {".md", ".markdown"}:
+        return False
+    segments = fenced_code_segments(text)
+    return bool(segments) and all(
+        (segment.language or "").casefold() in {"py", "python"} for segment in segments
+    )

codevariability/output.py

@@ -0,0 +1,76 @@
+"""Atomic output files: never follow an existing destination symlink."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from contextlib import contextmanager, suppress
+from pathlib import Path
+
+import pandas as pd
+
+from .exceptions import AnalysisError
+
+
+@contextmanager
+def atomic_target(path: str | Path):
+    target = Path(path)
+    if target.is_symlink():
+        raise AnalysisError(
+            f"O destino de exportação não pode ser um link simbólico: {target}."
+        )
+    target.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(
+        prefix=".codevariability-", suffix=target.suffix, dir=target.parent
+    )
+    os.close(descriptor)
+    temporary = Path(name)
+    try:
+        yield temporary
+        if target.is_symlink():
+            raise AnalysisError(
+                f"O destino de exportação tornou-se um link simbólico: {target}."
+            )
+        os.replace(temporary, target)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def frame_json(frame: pd.DataFrame, orient: str) -> object:
+    """Preserve pandas' null conventions, reporting serialization errors uniformly."""
+    try:
+        return json.loads(frame.to_json(orient=orient))
+    except (TypeError, ValueError, OverflowError, RecursionError) as exc:
+        raise AnalysisError(
+            f"A tabela não pode ser serializada como JSON: {exc}."
+        ) from exc
+
+
+def write_json(payload: object, path: str | Path) -> None:
+    try:
+        content = json.dumps(
+            payload, ensure_ascii=False, indent=2, allow_nan=False
+        ).encode("utf-8")
+    except (TypeError, ValueError, OverflowError, RecursionError) as exc:
+        raise AnalysisError(
+            f"O resultado não pode ser serializado como JSON: {exc}."
+        ) from exc
+    with atomic_target(path) as temporary:
+        temporary.write_bytes(content)
+
+
+@contextmanager
+def excel_writer(path: str | Path):
+    with atomic_target(path) as temporary:
+        # The outer handle closes even if openpyxl cannot save a failed workbook.
+        with temporary.open("w+b") as handle:
+            writer = pd.ExcelWriter(handle, engine="openpyxl")
+            try:
+                yield writer
+            except BaseException:
+                with suppress(Exception):
+                    writer.close()
+                raise
+            else:
+                writer.close()

codevariability/spreadsheet.py

@@ -0,0 +1,68 @@
+"""Escape untrusted labels when exporting tables opened by spreadsheet apps."""
+
+from __future__ import annotations
+
+import csv
+import re
+from pathlib import Path
+
+import pandas as pd
+
+from .exceptions import AnalysisError
+from .output import atomic_target
+
+
+def _safe_cell(value: object, prefix: str) -> object:
+    if (
+        prefix == "'"
+        and isinstance(value, str)
+        and re.search(r"[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]", value)
+    ):
+        raise AnalysisError(
+            "O texto exportado contém caracteres incompatíveis com XML do Excel."
+        )
+    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
+        return prefix + value
+    return value
+
+
+def _safe_index(index: pd.Index, prefix: str) -> pd.Index:
+    if isinstance(index, pd.MultiIndex):
+        return pd.MultiIndex.from_tuples(
+            [tuple(_safe_cell(part, prefix) for part in label) for label in index],
+            names=[_safe_cell(name, prefix) for name in index.names],
+        )
+    return pd.Index(
+        [_safe_cell(label, prefix) for label in index],
+        name=_safe_cell(index.name, prefix),
+    )
+
+
+def _safe_frame(frame: pd.DataFrame, prefix: str) -> pd.DataFrame:
+    safe = frame.copy()
+    for column in safe.columns:
+        if safe[column].dtype == object or pd.api.types.is_string_dtype(
+            safe[column].dtype
+        ):
+            safe[column] = safe[column].map(lambda value: _safe_cell(value, prefix))
+    safe.index = _safe_index(safe.index, prefix)
+    safe.columns = _safe_index(safe.columns, prefix)
+    return safe
+
+
+def safe_to_csv(frame: pd.DataFrame, path: str | Path, **kwargs: object) -> None:
+    kwargs.setdefault("quoting", csv.QUOTE_ALL)
+    safe = _safe_frame(frame, "\t")
+    with atomic_target(path) as temporary:
+        try:
+            safe.to_csv(temporary, **kwargs)
+        except UnicodeError as exc:
+            raise AnalysisError(
+                "O texto exportado como CSV deve ser representável em UTF-8."
+            ) from exc
+
+
+def safe_to_excel(
+    frame: pd.DataFrame, writer: pd.ExcelWriter, **kwargs: object
+) -> None:
+    _safe_frame(frame, "'").to_excel(writer, **kwargs)

codevariability/validation.py

@@ -0,0 +1,115 @@
+"""Shared validation for public analysis and adapter inputs."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from copy import deepcopy
+from numbers import Real
+
+import numpy as np
+import pandas as pd
+
+from .exceptions import AnalysisError
+
+DIMENSION_SCORE_COLUMNS = {
+    "textual": "textual_score",
+    "syntactic_token_sequence": "syntactic_score",
+    "structural_ast": "structural_score",
+}
+RESERVED_COLUMNS = {
+    "file",
+    "rank",
+    "score",
+    "overall_score",
+    "overall_dispersion",
+    *DIMENSION_SCORE_COLUMNS.values(),
+}
+
+
+def metric_name(value: object) -> str:
+    if not isinstance(value, str) or not value.strip() or value in RESERVED_COLUMNS:
+        raise AnalysisError(
+            "O nome da métrica deve ser texto não vazio e não pode ser uma coluna reservada."
+        )
+    try:
+        value.encode("utf-8")
+    except UnicodeError as exc:
+        raise AnalysisError(
+            "O nome da métrica deve ser representável em UTF-8."
+        ) from exc
+    return value
+
+
+def dimensions(metrics: Sequence[str], metadata: Mapping[str, object]) -> None:
+    for field in ("metric_ids", "metric_normalizations"):
+        values = metadata.get(field, {})
+        if not isinstance(values, Mapping) or any(
+            not isinstance(value, str) or not value.strip() for value in values.values()
+        ):
+            raise AnalysisError(
+                f"{field} deve mapear métricas para strings não vazias."
+            )
+    if not isinstance(metadata.get("external_adapters", {}), Mapping):
+        raise AnalysisError("external_adapters deve ser um mapeamento.")
+    declared = metadata.get("metric_dimensions", {})
+    if not isinstance(declared, Mapping):
+        raise AnalysisError("metric_dimensions deve ser um mapeamento.")
+    columns: dict[str, str] = {}
+    for metric in metrics:
+        dimension = declared.get(metric, metric)
+        if not isinstance(dimension, str) or not dimension.strip():
+            raise AnalysisError("A dimensão de cada métrica deve ser texto não vazio.")
+        column = DIMENSION_SCORE_COLUMNS.get(dimension, f"{dimension}_score")
+        if (
+            column in {"file", "rank", "score", "overall_score", "overall_dispersion"}
+            or column in metrics
+        ):
+            raise AnalysisError(
+                f"A dimensão '{dimension}' colide com uma coluna reservada ou métrica."
+            )
+        if column in columns and columns[column] != dimension:
+            raise AnalysisError(
+                "Dimensões distintas não podem gerar a mesma coluna de score."
+            )
+        columns[column] = dimension
+
+
+def similarity_matrix(matrix: object, files: Sequence[str]) -> pd.DataFrame:
+    if not isinstance(matrix, pd.DataFrame):
+        raise AnalysisError("A matriz de similaridade deve ser um pandas.DataFrame.")
+    if not matrix.index.is_unique or not matrix.columns.is_unique:
+        raise AnalysisError(
+            "Índices e colunas da matriz externa não podem conter nomes duplicados."
+        )
+    if (
+        list(matrix.shape) != [len(files), len(files)]
+        or set(matrix.index) != set(files)
+        or set(matrix.columns) != set(files)
+    ):
+        raise AnalysisError(
+            "Índices e colunas da matriz externa devem corresponder exatamente aos arquivos analisados."
+        )
+    if any(
+        not isinstance(value, Real) or isinstance(value, (bool, np.bool_))
+        for value in matrix.to_numpy().flat
+    ):
+        raise AnalysisError(
+            "A matriz externa deve conter somente números reais, sem booleanos ou strings."
+        )
+    try:
+        aligned = matrix.loc[list(files), list(files)].astype(float).copy(deep=True)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise AnalysisError(
+            "A matriz externa deve conter somente valores numéricos finitos."
+        ) from exc
+    values = aligned.to_numpy()
+    if not np.isfinite(values).all() or ((values < 0) | (values > 1)).any():
+        raise AnalysisError(
+            "A matriz externa deve conter somente similaridades numéricas entre 0 e 1."
+        )
+    if not (values.diagonal() == 1).all():
+        raise AnalysisError("A diagonal da matriz externa deve ser igual a 1.")
+    if not aligned.equals(aligned.T):
+        raise AnalysisError("A matriz externa deve ser simétrica.")
+    aligned.attrs = deepcopy(matrix.attrs)
+    return aligned