astromol documentation

astromol is a Python package and curated database for astronomical molecule detections. It stores molecule, detection, source, telescope, and reference metadata in version-controlled files, then exposes those records through a small Python API for validation, curation, census views, manuscript tables, figures, and PowerPoint slides.

This documentation describes the active refactor branch. The data model, curation workflow, and output-generation tools are usable, but the public API is still pre-release.

Latest Generated Products

The latest standard figures and PowerPoint slides are generated automatically from the current database and published at:

https://bmcguir2.github.io/astromol/

Use that page for the latest ISM/CSM cumulative detections figure, the ISM/CSM molecule slide, the PPD molecule/isotopologue slide, and the complete generated output bundle. Use the Colab notebooks when you want to customize the view or regenerate selected outputs interactively.

User Guide

• Installation
  • Local Development Checkout
  • Documentation Build
  • Read the Docs
• Quickstart
• FAQ
  • How Do I Get The Latest ISM/CSM Cumulative Detections Figure?
  • How Do I Get The Latest ISM/CSM Detections Slide?
  • How Do I Get The Latest Protoplanetary Disk Detections Slide?
  • How Do I Get Any Of The Other Figures?
• Data Model
  • Stable Identifiers
  • History Metadata
  • Census Views
• Curation Workflow
  • Project-Computed Values
• Calculation Notebooks
• Output Generation
  • Tables And LaTeX
  • Figures
  • Slides
• Census Output Recipes
  • Latest Standard Output Bundle
  • Standard View Options
  • Recreate The Manuscript Tables
  • Recreate The Manuscript Figures
  • Recreate The Slides
  • Custom Database Views
• Example Notebooks And Google Colab
  • Opening A Notebook In Colab
  • Notebook Index
  • Maintenance Notes
• Validation And Tests

Reference

• API Reference
  • Database
  • CensusView
  • FilteredCensusView
  • Ref
  • HistoryEvent
  • RecordHistory
  • Telescope
  • Source
  • RotationalConstants
  • DipoleMoment
  • Molecule
  • Detection
  • ValidationIssue
  • ValidationReport
  • validate_database()
  • format_issue()
  • format_report()
  • TableColumn
  • DetectionRateFit
  • endinput()
  • write_fragments()
  • molecule_link()
  • detection_molecule_link()
  • linked_header()
  • first_detection_sort_keys()
  • molecules_by_first_detection()
  • split_legacy_pair_column()
  • split_balanced_columns()
  • table_rows()
  • table_column_rows()
  • table_column_header()
  • atom_reference_table_header()
  • tabular_spec()
  • species_reference_tabular_spec()
  • single_reference_tabular_spec()
  • latex_table_fragment()
  • molecule_count()
  • element_count()
  • context_molecule_count()
  • ppd_molecule_count()
  • ppd_isotopologue_count()
  • exgal_molecule_count()
  • exgal_percent()
  • exoplanet_molecule_count()
  • ice_molecule_count()
  • molecule_detections_by_label()
  • radio_percent()
  • facility_count()
  • hydrocarbon_molecules()
  • saturated_hydrocarbons()
  • unsaturated_hydrocarbons()
  • saturated_hydrocarbon_count()
  • saturated_hydrocarbon_percent()
  • unsaturated_hydrocarbon_percent()
  • saturated_hydrocarbon_list()
  • molecule_source_types()
  • radical_percent_by_source_type()
  • first_detection_years()
  • detection_rate_since()
  • scalar_fragments()
  • write_scalar_fragments()
  • rate_fit_end_year()
  • category_detection_years()
  • cumulative_counts_by_year()
  • linear_rate_fit()
  • rate_by_atoms_fits()
  • rate_by_atoms_table_fragment()
  • rate_by_atoms_table_fragments()
  • write_rate_by_atoms_table()
  • sorted_count_entries()
  • paired_count_table_rows()
  • paired_count_table_fragment()
  • facility_table_entries()
  • facility_table_fragment()
  • facility_table_fragments()
  • write_facility_table()
  • source_table_entries()
  • source_table_fragment()
  • source_table_fragments()
  • write_source_table()
  • ism_table_molecules()
  • ism_table_detections()
  • ism_table_columns()
  • balanced_ism_table_columns()
  • legacy_ism_table_fragments()
  • balanced_ism_table_fragments()
  • ism_table_fragments()
  • write_ism_tables()
  • first_context_detection_by_molecule()
  • exgal_table_detections()
  • chunked_atom_groups()
  • exgal_table_atom_groups()
  • exgal_table_columns()
  • observation_ref_bibcodes()
  • reference_numbers()
  • detection_reference_table_rows()
  • single_detection_reference_table_rows()
  • numbered_reference_notes()
  • exgal_table_fragment()
  • exgal_table_fragments()
  • write_exgal_table()
  • ppd_table_detections()
  • ppd_table_atom_groups()
  • ppd_table_columns()
  • ppd_table_fragment()
  • ppd_table_fragments()
  • write_ppd_table()
  • parent_first_context_detections()
  • exoplanet_table_detections()
  • exoplanet_table_fragment()
  • exoplanet_table_fragments()
  • write_exoplanet_table()
  • ice_table_detections()
  • ice_table_fragment()
  • ice_table_fragments()
  • write_ice_table()
  • defaultdict
  • dataclass()
  • date
  • Path
  • CensusView
  • Detection
  • DetectionTrend
  • CumulativeDetectionData
  • CumulativeByAtomsSeries
  • CumulativeByAtomsData
  • RollingRateHeatmapData
  • PeriodicHeatmapCell
  • PeriodicHeatmapData
  • DUHistogramData
  • KappaHistogramData
  • MoleculeTypeCategory
  • MoleculeTypeData
  • SourceTypeCategory
  • SourceTypeData
  • IndividualSourceData
  • MoleculeTypesForSource
  • MoleculeTypeBySourceData
  • DUBySourceTypeCategory
  • DUBySourceTypeData
  • RelativeDUBySourceTypeCategory
  • RelativeDUBySourceTypeData
  • MassBySourceTypeCategory
  • MassBySourceTypeData
  • WavelengthBySourceTypeCategory
  • WavelengthBySourceTypeData
  • MassByWavelengthSeries
  • MassByWavelengthData
  • MoleculesByWavelengthAtomsSeries
  • MoleculesByWavelengthAtomsData
  • DetectionRateByAtomsPoint
  • DetectionRateByAtomsData
  • FacilityShare
  • FacilityShareData
  • ScopeDetectionSeries
  • ScopesByYearData
  • first_detections_by_molecule()
  • first_detection_years_by_molecule()
  • cumulative_by_atoms_series_specs()
  • cumulative_by_atoms_data()
  • annual_detection_counts()
  • trailing_rolling_detection_rate()
  • rolling_rate_by_atoms_heatmap_data()
  • periodic_heatmap_data()
  • du_histogram_data()
  • kappa_histogram_data()
  • molecule_type_data()
  • source_type_data()
  • individual_source_data()
  • molecule_type_by_source_type_data()
  • du_by_source_type_data()
  • relative_du_by_source_type_data()
  • mass_by_source_type_data()
  • wavelength_by_source_type_data()
  • mass_by_wavelength_data()
  • molecules_by_wavelength_atoms_data()
  • detection_rate_by_atoms_data()
  • facility_share_data()
  • scopes_by_year_data()
  • cumulative_counts_by_year()
  • linear_cumulative_rate()
  • cumulative_detection_trend_ranges()
  • cumulative_detection_data()
  • plot_cumulative_detections()
  • write_cumulative_detections_plot()
  • plot_cumulative_by_atoms()
  • write_cumulative_by_atoms_plot()
  • plot_stacked_cumulative_by_atoms()
  • write_stacked_cumulative_by_atoms_plot()
  • plot_periodic_heatmap()
  • write_periodic_heatmap()
  • plot_du_histogram()
  • write_du_histogram()
  • plot_kappa_histogram()
  • write_kappa_histogram()
  • plot_du_bar_chart()
  • write_du_bar_chart()
  • plot_type_pie_chart()
  • write_type_pie_chart()
  • plot_source_pie_chart()
  • write_source_pie_chart()
  • plot_individual_source_pie_chart()
  • write_individual_source_pie_chart()
  • plot_molecule_type_by_source_type()
  • write_molecule_type_by_source_type()
  • plot_molecule_type_by_source_enrichment_matrix()
  • write_molecule_type_by_source_enrichment_matrix()
  • plot_du_by_source_type()
  • write_du_by_source_type()
  • plot_relative_du_by_source_type()
  • write_relative_du_by_source_type()
  • plot_mass_by_source_type()
  • write_mass_by_source_type()
  • plot_wavelength_by_source_type()
  • write_wavelength_by_source_type()
  • plot_wavelength_by_source_type_stacked_bar()
  • write_wavelength_by_source_type_stacked_bar()
  • plot_mass_by_wavelength()
  • write_mass_by_wavelength_plot()
  • plot_mass_by_wavelength_boxplot()
  • write_mass_by_wavelength_boxplot()
  • plot_du_by_source_type_boxplot()
  • write_du_by_source_type_boxplot()
  • plot_relative_du_by_source_type_boxplot()
  • write_relative_du_by_source_type_boxplot()
  • plot_mass_by_source_type_boxplot()
  • write_mass_by_source_type_boxplot()
  • plot_molecules_by_wavelength_atoms()
  • write_molecules_by_wavelength_atoms_plot()
  • plot_molecules_by_wavelength_atoms_bubble_heatmap()
  • write_molecules_by_wavelength_atoms_bubble_heatmap()
  • plot_rolling_rate_by_atoms_heatmap()
  • write_rolling_rate_by_atoms_heatmap()
  • plot_detection_rate_by_atoms()
  • write_detection_rate_by_atoms_plot()
  • plot_detection_rate_by_atoms_comparison()
  • write_detection_rate_by_atoms_comparison_plot()
  • plot_facility_shares()
  • write_facility_shares_plot()
  • plot_facility_share_bars()
  • write_facility_share_bars_plot()
  • plot_scopes_by_year()
  • write_scopes_by_year_plot()
  • SlideBox
  • FormulaRun
  • SlideMoleculeEntry
  • SlideGroupSpec
  • SlideColumnPlan
  • SlideGroupPlan
  • MoleculeSlideLayout
  • legacy_molecule_slide_specs()
  • balanced_molecule_slide_specs()
  • compact_molecule_slide_specs()
  • balanced_total_box()
  • compact_total_box()
  • rendered_group_label_box()
  • group_label_alignment()
  • balanced_column_width()
  • balanced_label_width()
  • compact_label_width()
  • selected_molecule_slide_entries()
  • first_detection_sort_keys()
  • build_molecule_slide_layout()
  • estimated_column_capacity()
  • selected_records_last_modified()
  • package_version()
  • repository_git_label()
  • slide_version_label()
  • molecule_slide_report()
  • write_molecule_slide_report()
  • write_molecule_slide()
  • build_ppd_detection_slide_layout()
  • write_ppd_detection_slide()
  • render_molecule_slide()
  • format_slide_date()
  • powerpoint_formula_runs()
  • strip_formula_wrappers()
  • is_atom_count_token()
  • is_terminal_charge()
  • FigureOutputSpec
  • OutputContext
  • SlideOutputSpec
  • TableOutputSpec
  • figure_output_names()
  • slide_output_names()
  • table_output_names()
  • GeneratedProduct
  • FigureProductGroup
  • view_from_choice()
  • generate_standard_outputs()
  • parse_args()
  • main()

Project Records

The repository also contains durable project records that are useful while the refactor is still active:

• SPEC.md: current architecture and schema specification

• GENERATION_MIGRATION.md: table, figure, and slide migration audit trail

• MANUSCRIPT_NOTES_2026.md: writing-time reminders for the 2026 census paper