Stock Indicators for Python

To ensure accuracy and account for the smoothing/convergence required by the ATR calculation, follow these data requirements:

• Minimum requirement: At least N+100 periods of quotes, where N is the lookback_periods.
• Recommended requirement: At least N+250 periods prior to the intended usage date for optimal precision.
• Consistency: quotes must have a consistent frequency (e.g., daily, hourly, or minutely).

Indicators expect inputs as Python datetime.datetime objects wrapped in Quote objects. Do not pass raw strings directly to indicators.

Timezone Behavior

• Tz-aware inputs: Normalized to UTC internally; outputs remain tz-aware in UTC.
• Naive inputs: Treated as unspecified local context and kept as-is (remain naive).
• Mixed series: Supported. Results align 1:1 with input dates and are sorted chronologically.

Construction Examples

When parsing strings to create datetimes, ensure compliance with ISO 8601 (e.g., 2000-03-26T23:00:00+00:00).

# Offset-aware
datetime.fromisoformat('2022-06-02T10:29:00-04:00')

# Zulu/UTC
datetime.fromisoformat('2022-06-02T14:29:00+00:00')

# Naive date-time
datetime.strptime('2022-06-02 14:29:00', '%Y-%m-%d %H:%M:%S')

# Date-only (naive midnight)
datetime.strptime('2022-06-02', '%Y-%m-%d')

Since get_fractal returns a time series of the same length as the input, you can use built-in utilities to clean or search the results:

• .condense(): Simplifies the results.
• .find(lookup_date): Finds the specific indicator result for a given date.
• .remove_warmup_periods(qty): Removes the initial periods where the indicator could not be calculated.

To use the get_doji method, your input quotes must satisfy the following:

• Type: Must be an Iterable[Quote] or a compatible subclass (such as a pandas.DataFrame).
• Quantity: You must have at least one historical quote, though more are typically required to form a meaningful chartable pattern.
• Consistency: The collection should have a consistent frequency (e.g., all daily, all hourly, etc.).

To calculate Stochastic RSI accurately, your quotes collection must meet specific length requirements to account for warmup periods.

Minimum required periods:

• You must have at least N periods, where N is the greater of (rsi_periods + stoch_periods + smooth_periods) and (rsi_periods + 100).

Best practice for precision:

• Because the underlying RSI uses smoothing, it is highly recommended to use at least 10 × rsi_periods of data prior to your intended usage date to avoid convergence-related precision errors.

While each indicator has a specific minimum requirement, it is highly recommended to provide more data than the minimum to ensure precision. Many indicators use smoothing techniques that converge to better accuracy over time.

Rule of thumb: Provide at least 750 points (e.g., 3 years of daily data). For example, to get precise EMA(250) data using daily intervals, you should provide 3 years of data: 1 year for the lookback period and 1 year for convergence, then discard the initial results.

To calculate the Ichimoku Cloud, your quotes collection must contain enough historical data to cover the warmup periods.

Specifically, you need at least the maximum value among tenkan_periods (T), kijun_periods (K), senkou_b_periods (S), and any specified offset periods. Because the indicator uses leading and lagging spans, it is highly recommended to provide significantly more data than this minimum requirement to ensure valid results.

To calculate OBV, your quotes collection must meet these requirements:

• Minimum Data: You must have at least two historical quotes to cover warmup periods. However, because OBV is a trendline indicator, providing more data is highly recommended for accuracy.
• Consistency: The quotes must have a consistent frequency (e.g., daily, hourly, or minute-by-minute).

To calculate VWAP, you must provide an Iterable[Quote] collection of historical price quotes.

Key Requirements:

• Frequency: The quotes should have a consistent frequency (e.g., daily, hourly, or minute-based intraday periods).
• Accumulation: VWAP is an accumulated weighted average. Different start dates will produce different results. The accumulation starts at the first period in the provided quotes unless a specific start parameter is provided.
• Data Volume: While at least one quote is required, more historical data is typically needed for the indicator to be useful, especially when using minute-based intraday data.

The project uses Ruff for linting/formatting, Pyright for type checking, and pytest for testing. Ensure your virtual environment is activated before running these commands.

• Lint and format: Uses ruff to check and format code.
• Type-check: Uses pyright to ensure type safety.
• Standard unit tests: Uses pytest to run the test suite.
• Localization tests: Runs tests specifically marked with the localization marker.
• Performance tests: Runs tests specifically marked with the performance marker.

# lint and format
python -m ruff check .
python -m ruff format --check .

# type-check
python -m pyright

# run standard unit tests
python -m pytest

# Run specific test types
python -m pytest -m "localization"
python -m pytest -m "performance"

Issues are categorized and should be submitted via GitHub:

• Bug Reports: Submit an issue with a detailed description, steps to reproduce, code samples, and reference materials. Use the bug label.
• Feature Requests: Submit an issue for new features using the enhancement label.

Because Ichimoku is a lagging/leading indicator, the first T-1, K-1, and S-1 periods (where T, K, and S are the respective period parameters) will contain None values for the indicator fields.

You can manage these warmup periods using the following utilities available on the IchimokuResults object:

• .remove_warmup_periods(qty): Removes a specified number of warmup periods from the results.
• .condense(): Condenses the results.
• .find(lookup_date): Finds an indicator result by a specific date.