MINAS - Machine-learning INtegrated analysis with photometric Astronomical Surveys

English

MINAS was developed to assist and facilitate the complete Machine Learning workflow for astronomical photometric surveys. The package integrates all stages of the process, from preprocessing to final model application.

Fun fact: MINAS is also the name of a Brazilian state (Minas Gerais), the home state of Icaro Meidem, the package creator. As a proud "mineiro" (someone from Minas Gerais), the name represents both the astronomical focus and personal heritage.

Main Features

• Complete workflow: Integrates preprocessing, feature selection, hyperparameter tuning, and model application in a single package.
• Random Forest and XGBoost integrated: Optimized pipelines for classification and regression with the main ML libraries, easily extensible to other algorithms.
• Intelligent feature selection: Uses Permutation Importance to automatically identify the most relevant features.
• Hyperparameter tuning: Built-in tools for model optimization with grid search and random search.
• Monte Carlo application: Photometric error propagation using Monte Carlo simulations during prediction.
• Automatic filter recognition: Native support for filters from major photometric surveys such as J-PAS, J-PLUS, S-PLUS, GAIA, WISE, GALEX.
• Bolometric correction: Pre-trained models for bolometric correction calculation based on Teff, log g, and [Fe/H].
• Modular structure: Easy to adapt, extend, and integrate new methods or databases.

Folder Structure

• evaluation/
  Tools for model evaluation, metrics, plots, and feature selection (e.g., permutation importance).
• models/
  Implementation of Random Forest, XGBoost models, and utilities for ML pipelines.
• preprocess/
  Functions for data preprocessing, catalog manipulation, normalization, missing value handling, etc.
• tuning/
  Methods for hyperparameter search (grid search, random search) and pipeline integration.
• bolometric/
  Modules for classification and bolometric correction calculation with pre-trained models.
• __init__.py
  Package initialization, filter definitions, parameter aliases, and submodule integration.
• setup.py and pyproject.toml
  Configuration files for modern package installation (PEP 517/518).

How to Use

Install the package (recommended):

pip install /path/to/minas

Note: In modern Python environments, editable mode (-e) may not work due to pip/setuptools changes. Prefer standard installation unless you really need live code editing.

Import in your code:

import minas as mg

Usage example:

from minas.models import create_model
model = create_model('RF-REG')

Examples

The examples/ folder contains complete Jupyter notebooks demonstrating the full ML workflow:

• data/: Data preparation and catalog creation

  • data_creation.ipynb: Creating training datasets from spectroscopic surveys
  • apply/data/data_prepare.ipynb: Preprocessing data for model application

• tuning/: Hyperparameter optimization and feature selection

  • tuning_RF.ipynb / tuning_XGB.ipynb: Grid search for optimal hyperparameters
  • feature_import_RF.ipynb / feature_import_XGB.ipynb: Permutation importance analysis
  • pipeline/: Custom pipeline configurations

• training/: Model training and evaluation

  • predict_RF_all.ipynb / predict_XGB_all.ipynb: Training models for Teff, log g, and [Fe/H]
  • graphs_XGB_all.ipynb: Visualization of results and performance metrics
  • models/: Saved trained models (XGB, RF)
  • predicts/: Prediction metrics and validation results
  • graphs_results/: Performance plots per parameter
  • graphs_matrix/: Confusion matrices and correlation plots

• apply/: Applying trained models to new data

  • apply_models_XGB.ipynb / apply_models_RF.ipynb: Model application with Monte Carlo error propagation
  • pred_results/: Final predictions with uncertainties

These notebooks provide a complete template for stellar parameter estimation from photometric data.

Bolometric Correction

MINAS includes pre-trained models for calculating bolometric correction (BC) based on the corrections presented by Jordi et al. (2010), which provides BC data for Gaia-observed stars based on Teff, log g, and [Fe/H].

Available Models

Two Machine Learning algorithms were trained to predict bolometric correction:

Model	R²	MAD	Standard Deviation
Random Forest	0.9970	0.0067 mag	0.0573 mag
XGBoost	0.9983	0.0062 mag	0.0430 mag

Performance Plots

Figure: Performance of XGBoost (left) and Random Forest (right) models for bolometric correction prediction.

How to Use

import minas as mg

# Apply bolometric correction with XGBoost
df = mg.bolometric.apply_bc(
    data='your_catalog.csv',
    teff_col='Teff',
    logg_col='logg',
    feh_col='[M/H]',
    model_type='XGB',  # or 'RF'
    sigma_multiplier=3.0,  # Standard deviation multiplier for uncertainty
    output_file='catalog_with_bc.csv'
)

Uncertainties

BC uncertainty is calculated as σ_BC = multiplier × standard_deviation, where the multiplier is user-defined (default: 3.0). Statistics are automatically validated based on the validation sample included in the package, showing the percentage of objects within specified error limits.

Reference

Jordi, C., Gebran, M., Carrasco, J. M., et al. (2010). Gaia broad band photometry. Astronomy & Astrophysics, 523, A48. DOI: 10.1051/0004-6361/200913234

Extensibility

• You can add new ML algorithms by creating modules in models/ and integrating them into the pipeline.
• New filters or surveys can be added by editing the FILTERS dictionary in __init__.py.

Contribution

Pull requests and suggestions are welcome! Please follow the package's modularity and documentation standards.

Author

• Icaro Meidem
• Contact: [email protected]

---

This package is distributed under the MIT license. For questions, open an issue in the repository.

Português

MINAS foi desenvolvido para auxiliar e facilitar o fluxo de trabalho completo de análises de Machine Learning em levantamentos fotométricos astronômicos. O pacote integra todas as etapas do processo, desde o pré-processamento até a aplicação final dos modelos.

Curiosidade: MINAS também é o nome de um estado brasileiro (Minas Gerais), terra natal de Icaro Meidem, criador do pacote. Como um orgulhoso mineiro, o nome representa tanto o foco astronômico quanto a herança pessoal.

Principais Características

• Fluxo de trabalho completo: Integra pré-processamento, seleção de features, busca de hiperparâmetros e aplicação de modelos em um único pacote.
• Random Forest e XGBoost integrados: Pipelines otimizados para classificação e regressão com as principais bibliotecas de ML, facilmente extensível para outros algoritmos.
• Seleção inteligente de features: Utiliza Permutation Importance para identificar as características mais relevantes automaticamente.
• Busca de hiperparâmetros: Ferramentas integradas para otimização de modelos com grid search e random search.
• Aplicação com Monte Carlo: Propagação de erros fotométricos usando simulações de Monte Carlo durante a predição.
• Reconhecimento automático de filtros: Suporte nativo aos filtros dos principais levantamentos fotométricos, como J-PAS, J-PLUS, S-PLUS, GAIA, WISE, GALEX.
• Correção bolométrica: Modelos pré-treinados para cálculo de correção bolométrica baseados em Teff, log g e [Fe/H].
• Estrutura modular: Fácil de adaptar, estender e integrar novos métodos ou bancos de dados.

Estrutura das Pastas

• evaluation/
  Ferramentas para avaliação de modelos, métricas, gráficos e seleção de features (ex: permutation importance).
• models/
  Implementação dos modelos Random Forest, XGBoost e utilitários para pipeline de machine learning.
• preprocess/
  Funções para pré-processamento de dados, manipulação de catálogos, normalização, tratamento de valores ausentes, etc.
• tuning/
  Métodos para busca de hiperparâmetros (grid search, random search) e integração com pipelines.
• bolometric/
  Módulos para cálculo de correção bolométrica com modelos pré-treinados.
• __init__.py
  Inicialização do pacote, definição de filtros reconhecidos, aliases de parâmetros e integração dos submódulos.
• setup.py e pyproject.toml
  Arquivos de configuração para instalação do pacote no modo moderno (PEP 517/518).

Como Usar

Instale o pacote normalmente:

pip install /caminho/para/minas

Nota: Para ambientes modernos, a instalação editável (-e) pode não funcionar devido a mudanças no pip/setuptools. Prefira a instalação padrão, a menos que você realmente precise editar o código frequentemente.

Importe no seu código:

import minas as mg

Exemplo de uso:

from minas.models import create_model
model = create_model('RF')

Exemplos

A pasta examples/ contém notebooks Jupyter completos demonstrando todo o fluxo de trabalho de ML:

• data/: Preparação de dados e criação de catálogos

  • data_creation.ipynb: Criação de datasets de treinamento a partir de levantamentos espectroscópicos
  • apply/data/data_prepare.ipynb: Pré-processamento de dados para aplicação de modelos

• tuning/: Otimização de hiperparâmetros e seleção de features

  • tuning_RF.ipynb / tuning_XGB.ipynb: Busca em grade para hiperparâmetros ótimos
  • feature_import_RF.ipynb / feature_import_XGB.ipynb: Análise de permutation importance
  • pipeline/: Configurações personalizadas de pipeline

• training/: Treinamento e avaliação de modelos

  • predict_RF_all.ipynb / predict_XGB_all.ipynb: Treinamento de modelos para Teff, log g e [Fe/H]
  • graphs_XGB_all.ipynb: Visualização de resultados e métricas de desempenho
  • models/: Modelos treinados salvos (XGB, RF)
  • predicts/: Métricas de predição e resultados de validação
  • graphs_results/: Gráficos de desempenho por parâmetro
  • graphs_matrix/: Matrizes de confusão e gráficos de correlação

• apply/: Aplicação de modelos treinados em novos dados

  • apply_models_XGB.ipynb / apply_models_RF.ipynb: Aplicação de modelos com propagação de erros via Monte Carlo
  • pred_results/: Predições finais com incertezas

Esses notebooks fornecem um template completo para estimativa de parâmetros estelares a partir de dados fotométricos.

Correção Bolométrica

O MINAS inclui modelos pré-treinados para cálculo de correção bolométrica (BC) baseados nas correções apresentadas por Jordi et al. (2010), que fornece dados de BC para estrelas observadas pelo Gaia com base em Teff, log g e [Fe/H].

Modelos Disponíveis

Dois algoritmos de Machine Learning foram treinados para prever a correção bolométrica:

Modelo	R² Score	MAD	Desvio Padrão
Random Forest	0.9970	0.0067 mag	0.0573 mag
XGBoost	0.9983	0.0062 mag	0.0430 mag

Gráficos de Desempenho

Figura: Desempenho dos modelos XGBoost (esquerda) e Random Forest (direita) para predição de correção bolométrica.

Como Usar

import minas as mg

# Aplicar correção bolométrica com XGBoost
df = mg.bolometric.apply_bc(
    data='your_catalog.csv',
    teff_col='Teff',
    logg_col='logg',
    feh_col='[M/H]',
    model_type='XGB',  # ou 'RF'
    sigma_multiplier=3.0,  # Multiplicador do desvio padrão para incerteza
    output_file='catalog_with_bc.csv'
)

Incertezas

A incerteza da BC é calculada como σ_BC = multiplicador × desvio_padrão, onde o multiplicador é escolhido pelo usuário (padrão: 3.0). As estatísticas são validadas automaticamente com base na amostra de validação incluída no pacote, mostrando a porcentagem de objetos dentro dos limites de erro especificados.

Referência

Jordi, C., Gebran, M., Carrasco, J. M., et al. (2010). Gaia broad band photometry. Astronomy & Astrophysics, 523, A48. DOI: 10.1051/0004-6361/200913234

Extensibilidade

• Você pode adicionar novos algoritmos de ML criando módulos em models/ e integrando ao pipeline.
• Novos filtros ou levantamentos podem ser adicionados editando o dicionário FILTERS no __init__.py.

Contribuição

Pull requests e sugestões são bem-vindos! Siga o padrão de modularidade e documentação do pacote.

Autor

• Icaro Meidem
• Contato: [email protected]

---

Este pacote é distribuído sob a licença MIT. Para dúvidas, abra uma issue no repositório.