Quickstart Guide

Quickstart Guide#

This page provides a quick introduction to get you started with StreamObs.

First, make sure you have StreamObs installed (see Installation for details).

Generating Mock Stream Data#

StreamObs can generate parametric stellar stream models using configuration files or directly in Python.

Example 1: Using Command-Line Tools#

The simplest way to generate a stream is using the provided command-line scripts:

# Generate a simple linear stream
./bin/generate_stream.py config/toy1_config.yaml -o toy1_stream.csv --plot

# Generate a sinusoidal stream
./bin/generate_stream.py config/toy2_config.yaml -o toy2_stream.csv --plot

# Generate Pal 5 stream from interpolation
./bin/generate_stream.py config/pal5_config.yaml -o pal5_stream.csv --plot

These commands will:

  • Read the stream parameters from the configuration file

  • Generate mock stellar positions (phi1, phi2) and magnitudes

  • Save the results to a CSV file

  • Create visualization plots (with --plot flag)

Example 2: Generating Streams in Python#

You can also generate streams programmatically:

import numpy as np
import pandas as pd
from streamobs.model import StreamModel
from streamobs.utils import parse_config

# Load configuration
config = parse_config('config/toy1_config.yaml')

# Create stream model and generate stars
stream = StreamModel(config['stream'])
stream_df = stream.sample(config['stream']['nstars'])

# The dataframe contains: phi1, phi2, dist, and the isochrone magnitude
# columns, which are survey-namespaced as <survey>_<band>_true
# (e.g. lsst_g_true, lsst_r_true).
print(stream_df.head())

Converting to Observable Quantities#

Once you have mock stream data (either generated or from simulations), you can convert it to realistic observations using the StreamInjector class.

Example 3: Applying Survey Effects#

import numpy as np
import pandas as pd
from streamobs import surveys, observed

# Load a survey (e.g., LSST Year 1)
lsst_survey = surveys.Survey.load(survey='lsst', release='yr1')

# Create the stream injector
injector = observed.StreamInjector(lsst_survey)

# Create or load your mock stream data.
# Here we create a simple test dataset. Could instead contain (ra, dec) to skip
# the coordinate transformation. True (noiseless) magnitudes are passed in as
# survey-namespaced <namespace>_<band>_true columns, where the namespace is
# "{name}_{release}" — here the survey is lsst/yr1, so "lsst_yr1".
# Alternatively, omit the magnitudes and pass a `stream_config=` so the injector
# samples them from an isochrone.
rng = np.random.default_rng(42)
mock_data = pd.DataFrame({
    'phi1': rng.uniform(-5, 5, 1000),              # Stream longitude
    'phi2': rng.uniform(-1, 1, 1000),              # Stream latitude
    'lsst_yr1_g_true': rng.uniform(18, 28, 1000),  # true g-band apparent magnitude
    'lsst_yr1_r_true': rng.uniform(18, 28, 1000),  # true r-band apparent magnitude
})

# Apply survey effects: footprint, extinction, photometric errors
observed_data = injector.inject(
    mock_data,
    bands=['r', 'g'],                 # bands to inject (single-survey shorthand)
    seed=42,
    mask_type=['footprint', 'ebv'],   # place the stream within the footprint + low-dust area
    verbose=True,
)

print(f"Input stars: {len(mock_data)}")
print(f"Detected stars: {int(observed_data['lsst_yr1_flag_observed'].sum())}")

What the Injector Does#

The StreamInjector applies several observational effects:

  1. Coordinate conversion: Converts stream coordinates (phi1, phi2) to sky coordinates (RA, Dec)

  2. Extinction: Applies Galactic dust extinction corrections

  3. Photometric errors: Adds realistic magnitude uncertainties

  4. Detection completeness: Applies magnitude-dependent detection probability

The output dataframe includes (all magnitude/flag columns are survey-namespaced as <namespace>_..., where the namespace is {name}_{release}; for the LSST/yr1 survey loaded above it is lsst_yr1):

  • ra, dec: Sky coordinates

  • lsst_yr1_g_true, lsst_yr1_r_true: True (noiseless) apparent magnitudes

  • lsst_yr1_g_obs, lsst_yr1_r_obs: Observed (noisy) magnitudes

  • lsst_yr1_g_err, lsst_yr1_r_err: Reported photometric uncertainties

  • lsst_yr1_flag_observed: Detection and classification flag (True=detected & classified as a star, False=not detected or not classified as a star)

Next Steps#

Now that you’ve seen the basics, you can:

  • Learn more about configuration files: See the config/ directory for examples of stream and survey configurations

  • Explore the API: Check the API Reference for detailed documentation of all classes and functions

  • View detailed examples: Visit the notebooks/ directory for Jupyter notebooks with more complex workflows

  • Customize surveys: Learn how to define your own survey parameters in YAML files

  • Try different stream models: Experiment with different parametric stream descriptions

Key Concepts#

  • Mock generation: Create idealized stream data with known properties

  • Survey injection: Apply realistic observational effects to mock data

  • Configuration-driven: Use YAML files to define stream and survey parameters

  • Modular design: Use individual components (generation, photometry, observation) independently

Getting Help#

  • Documentation: Browse the full documentation for detailed information

  • Examples: Check the notebooks/ directory for worked examples

  • Issues: Report bugs or request features on GitHub

Contents