How elias-wahl/atlas-vis works
1. Overall shape
- atlas-vis is a Python package for atmospheric visualization in local-domain terrain-oriented workflows.
- The architecture is a pipeline: configuration → data discovery/parsing → derived physics/transformations → visualization serving.
2. Entry point
- src/atlas_vis/main.py is the top-level entry module that likely wires the package together.
- It sits above the other subsystems and is the place where runtime startup and orchestration begin.
3. Configuration boundary
- src/atlas_vis/config/default_settings.yaml provides package defaults.
- src/atlas_vis/core/config.py likely loads, merges, and validates runtime settings.
- This is the main control plane for changing behavior without touching the processing or visualization code.
4. Core discovery and error handling
- src/atlas_vis/core/scanner.py suggests filesystem or dataset discovery logic, probably identifying available inputs or variables.
- src/atlas_vis/core/exceptions.py centralizes domain-specific failures so parsing, processing, and visualization can fail cleanly and consistently.
5. Parser subsystem
- The parsers package is responsible for normalizing external data sources into internal structures.
- Separate parser implementations exist for pandas and xarray, which implies support for both tabular and multidimensional scientific data.
- base.py, registry.py, mapper.py, aliases.py, and util.py indicate a pluggable parsing layer with variable-name mapping and alias resolution.
6. Physics / derived-variable subsystem
- The physics package appears to encapsulate atmospheric formulas and computed diagnostics.
- formulas.py contains the actual physical calculations; graph.py suggests dependency tracking between derived quantities.
- registry.py likely registers available physics operations so they can be selected dynamically from configuration or data context.
7. Processing and execution model
- src/atlas_vis/processing/transformer.py likely applies transformations from parsed inputs to visualization-ready outputs.
- src/atlas_vis/processing/dask_manager.py indicates optional or integrated parallel/distributed execution via Dask for heavier computations.
- This layer is the main computation boundary between raw data and interactive presentation.
8. Visualization subsystem
- src/atlas_vis/visualization/engine.py is the presentation orchestrator, likely converting processed data into visual outputs.
- src/atlas_vis/visualization/trame_server.py shows that the UI/runtime is built around Trame, which is commonly used for interactive scientific visualization apps.
- This suggests a server-backed interactive visualization model rather than a static plotting script.
9. Data flow through the system
- Input data is discovered by the scanner, interpreted by the appropriate parser, normalized through mapping/alias logic, then enriched by physics formulas and transformers.
- The processed result is handed to the visualization engine, which serves interactive views through the Trame server.
- The boundaries are cleanly separated: I/O and parsing, domain computation, and presentation.
10. Integration and extensibility
- Registries in both parsers and physics imply a plugin-style architecture where supported data formats and derived quantities can be extended without rewriting the pipeline.
- This makes the system adaptable to different atmospheric datasets and analysis needs while preserving a single orchestration flow.
11. What to show in an architecture diagram
- Draw four main blocks: config/core, parsers, physics + processing, and visualization.
- Show main.py as the entry/orchestration point.
- Represent Dask as an execution accelerator inside processing, and Trame as the interactive serving layer at the output end.
Main entry points: main.py Main · registry.py Parser Registry · transformer.py Transformer · mapper.py Mapper
Components 19
Entry
Package startup and orchestration
- Main · Top-level runtime entry that wires the pipeline together
src/atlas_vis/main.py
Core
Configuration, discovery, and shared errors
- Defaults · Package default configuration values
src/atlas_vis/config/default_settings.yaml - Config · Loads, merges, and validates runtime settings
src/atlas_vis/core/config.py - Scanner · Finds inputs, files, or variables in the local domain
src/atlas_vis/core/scanner.py - Errors · Shared domain-specific failures across the package
src/atlas_vis/core/exceptions.py
Parsers
Input normalization and format adapters
- Parser Base · Common parser interface and shared behavior
src/atlas_vis/parsers/base.py - Parser Registry · Selects parser implementations dynamically
src/atlas_vis/parsers/registry.py - Mapper · Maps dataset names to internal variables
src/atlas_vis/parsers/mapper.py - Aliases · Resolves alternate variable names and synonyms
src/atlas_vis/parsers/aliases.py - Pandas Parser · Parses table-like inputs into internal structures
src/atlas_vis/parsers/pandas.py - Xarray Parser · Parses multidimensional scientific data inputs
src/atlas_vis/parsers/xarray.py - Parser Util · Shared parsing utilities and normalization helpers
src/atlas_vis/parsers/util.py
Physics
Derived-variable formulas and dependency logic
- Physics Registry · Registers available derived-variable computations
src/atlas_vis/physics/registry.py - Formulas · Atmospheric calculations and derived diagnostics
src/atlas_vis/physics/formulas.py - Phys Graph · Tracks dependencies between derived quantities
src/atlas_vis/physics/graph.py
Processing
Transformation and execution management
- Transformer · Applies physics and reshaping to prepare outputs
src/atlas_vis/processing/transformer.py - Dask Manager · Coordinates parallel or distributed computation
src/atlas_vis/processing/dask_manager.py
Visualization
Interactive serving and presentation
- Viz Engine · Builds visualization state from processed data
src/atlas_vis/visualization/engine.py - Trame Server · Serves the interactive visualization runtime
src/atlas_vis/visualization/trame_server.py
Connections 21
- Main → Config: loads · Startup reads and applies runtime configuration
- Main → Scanner: discovers · Entry point begins dataset discovery
- Main → Parser Registry: orchestrates · Chooses parsing strategy for discovered inputs
- Main → Transformer: runs · Coordinates the main processing pipeline
- Main → Viz Engine: starts · Hands processed results to visualization
- Config → Defaults: defaults · Base settings come from packaged defaults
- Config → Errors: raises · Configuration failures use shared errors
- Scanner → Errors: raises · Discovery issues surface through domain exceptions
- Parser Registry → Parser Base: implements · Registry manages parser implementations
- Parser Registry → Pandas Parser: selects · Pandas adapter is one supported implementation
- Parser Registry → Xarray Parser: selects · Xarray adapter is one supported implementation
- Pandas Parser → Mapper: maps · Tabular parsing uses variable mapping
- Xarray Parser → Mapper: maps · Array parsing uses variable mapping
- Mapper → Aliases: resolves · Mappings are normalized through aliases
- Mapper → Parser Util: uses · Shared parsing helpers support normalization
- Transformer → Physics Registry: requests · Transformation layer selects derived computations
- Physics Registry → Formulas: executes · Registered operations resolve to formulas
- Physics Registry → Phys Graph: orders · Dependencies between derived variables are tracked
- Transformer → Dask Manager: accelerates · Heavy work may be dispatched through Dask
- Transformer → Errors: raises · Processing failures share the common error boundary
- Viz Engine → Trame Server: serves · Visualization output is exposed through Trame