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, distance, magnitudes, etc.
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
# This could contain (ra, dec) coordinates if you want to skip coordinate transformation
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
    'mag_g': rng.uniform(18, 28, 1000),    # g-band magnitude
    'mag_r': rng.uniform(18, 28, 1000),    # r-band magnitude
})

# Apply survey effects: footprint, extinction, photometric errors
observed_data = injector.inject(
    mock_data, 
    seed=42,
    bands = ['r', 'g'] # Choose the bands to use
    mask_type=['footprint', 'ebv'],  # Restrict injection to a mask created from the footprind and low dust area
    verbose=True
)

print(f"Input stars: {len(mock_data)}")
print(f"Detected stars: {len(observed_data[observed_data['flag_observed']==1])}")

What the Injector Does#

The StreamInjector applies several observational effects:

Coordinate conversion: Converts stream coordinates (phi1, phi2) to sky coordinates (RA, Dec)
Extinction: Applies Galactic dust extinction corrections
Photometric errors: Adds realistic magnitude uncertainties
Detection completeness: Applies magnitude-dependent detection probability

The output dataframe includes:

ra, dec: Sky coordinates
mag_g_obs, mag_r_obs: Observed magnitudes with errors
magerr_g, magerr_r: Photometric uncertainties
flag_observed: Detection and clasification flag (1=detected & classified as a star, 0=not detected of 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

Quickstart Guide

Contents