# alexandrehsd/predicting-pulsar-stars architecture

> Architecture diagram of the GitHub repository alexandrehsd/predicting-pulsar-stars, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexandrehsd/predicting-pulsar-stars
- Repository: https://github.com/alexandrehsd/predicting-pulsar-stars

## Overview

1. This repository is a small, self-contained machine learning project rather than a multi-component application. Its architecture centers on a single Jupyter notebook, `predicting_pulsar_stars.ipynb`, backed by one tabular dataset, `pulsar_stars.csv`.

2. The dataset is the core input boundary. It contains 17,898 labeled examples from the HTRU2 pulsar-candidate survey: 8 continuous features and 1 binary class label. The label indicates whether a candidate is a real pulsar (`1`) or noise/RFI (`0`).

3. The notebook is the orchestration layer. It is where the data is loaded, explored, transformed, modeled, and evaluated. There is no separate service layer, API layer, or database layer in the repository as provided.

4. The feature set is domain-specific and already engineered. The first four columns summarize the integrated pulse profile, and the next four summarize the DM-SNR curve. This means the project works on structured features rather than raw radio waveforms.

5. The main data flow is straightforward: CSV input → notebook-based analysis → trained binary classifier(s) → evaluation results/plots inside the notebook. Any outputs are likely notebook cells, figures, and metrics rather than deployed artifacts.

6. A key architectural concern is class imbalance. The README states there are far more negative examples than positive ones, so the modeling workflow likely needs to account for skewed labels when evaluating performance.

7. The runtime boundary is local and interactive. Jupyter provides the execution environment, and the notebook likely depends on common Python data-science libraries for loading the CSV, preprocessing, visualization, and classification.

8. There is no evidence of persistence beyond the source CSV and notebook itself. The repository does not show model binaries, experiment tracking, or a production inference endpoint, so the project appears to be an exploratory or educational ML workflow.

9. From an architecture-diagram perspective, the important nodes are: the HTRU2 dataset source, the local CSV file, the notebook execution environment, and the resulting predictive model/evaluation outputs. Data flows one way from the CSV into the notebook, with results staying in the notebook context.

10. The external dependency worth noting is the original Kaggle/HTRU2 data source referenced in the README. It matters only as the provenance of the dataset; the repository itself does not integrate with live external services.

Main entry points: [`predicting_pulsar_stars.ipynb`](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/predicting_pulsar_stars.ipynb) (Prediction Notebook), [`pulsar_stars.csv`](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/pulsar_stars.csv) (Pulsar CSV), [`README.md`](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_notebook["Prediction Notebook<br/>jupyter notebook"]
  node_dataset[("Pulsar CSV<br/>tabular dataset<br/>[pulsar_stars.csv]")]
  node_features["Engineered Features<br/>feature space"]
  node_imbalance{{"Class Skew<br/>data characteristic"}}
  node_modeling["Classifier Training<br/>ml modeling"]
  node_evaluation["Evaluation Results<br/>metrics and plots"]
  node_htru2[("HTRU2 Source<br/>external data source")]
end

node_htru2 -.->|"provenance"| node_dataset
node_readme -->|"documents"| node_notebook
node_readme -->|"describes"| node_dataset
node_dataset -->|"contains"| node_features
node_dataset -->|"loaded by"| node_notebook
node_features -->|"analyzed in"| node_notebook
node_imbalance -.->|"affects"| node_modeling
node_notebook -->|"orchestrates"| node_modeling
node_modeling -->|"produces"| node_evaluation
node_notebook -->|"renders"| node_evaluation

click node_readme "https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/README.md"
click node_notebook "https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/predicting_pulsar_stars.ipynb"
click node_dataset "https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/pulsar_stars.csv"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_notebook,node_dataset,node_features,node_imbalance,node_modeling,node_evaluation,node_htru2 toneBlue
```

## Components

### Repository

Self-contained notebook-based ML project for pulsar star prediction.

- [README](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/README.md): docs · Project overview, dataset provenance, and workflow context. · `README.md`
- [Prediction Notebook](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/predicting_pulsar_stars.ipynb): jupyter notebook · Interactive analysis, feature exploration, model training, and evaluation workflow. · `predicting_pulsar_stars.ipynb`
- [Pulsar CSV](https://github.com/alexandrehsd/predicting-pulsar-stars/blob/master/pulsar_stars.csv): tabular dataset · HTRU2-derived labeled examples with engineered features and binary class labels. · `pulsar_stars.csv`
- **Engineered Features**: feature space · Eight structured numeric inputs derived from pulse profile and DM-SNR curve summaries.
- **Class Skew**: data characteristic · Negative examples dominate positive pulsar labels, shaping evaluation and model choice.
- **Classifier Training**: ml modeling · Notebook-based fitting of binary classifiers on the structured tabular data.
- **Evaluation Results**: metrics and plots · Notebook outputs such as scores, comparisons, and visualizations.
- **HTRU2 Source**: external data source · Original survey provenance referenced by the repository documentation.

## Connections

- HTRU2 Source → Pulsar CSV: provenance · The CSV is derived from the HTRU2 pulsar-candidate survey.
- README → Prediction Notebook: documents · README explains the notebook-centered workflow.
- README → Pulsar CSV: describes · README introduces the labeled CSV dataset and class imbalance.
- Pulsar CSV → Engineered Features: contains · The CSV stores the engineered feature columns used for modeling.
- Pulsar CSV → Prediction Notebook: loaded by · The notebook reads the tabular data as its main input.
- Engineered Features → Prediction Notebook: analyzed in · Feature exploration and transformation happen inside the notebook.
- Class Skew → Classifier Training: affects · Skewed labels influence classifier selection and evaluation.
- Prediction Notebook → Classifier Training: orchestrates · The notebook coordinates preprocessing and model fitting.
- Classifier Training → Evaluation Results: produces · Trained models generate metrics and plots for comparison.
- Prediction Notebook → Evaluation Results: renders · Results remain in notebook cells and figures rather than external artifacts.
