Fix P0 control-group bug, stale CS API calls, and SyntheticDiD translation

- Fix always-treated snippet that silently dropped never-treated controls
  by matching actual estimator logic (first_treat > 0 && <= min_period)
- Replace stale results.bootstrap()/aggregate()/att with correct CS API
  (n_bootstrap= at constructor, aggregate= at fit time, overall_att)
- Fix SyntheticDiD R comparison to derive ever-treated indicator and
  post_periods from data instead of passing time-varying treatment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: igerber

docs/python_comparison.rst

@@ -408,7 +408,8 @@ Staggered DiD (Callaway-Sant'Anna)
        unit='unit',
        time='time',
        first_treat='first_treat',
-       covariates=['x1', 'x2']
+       covariates=['x1', 'x2'],
+       aggregate='event_study'
    )
    event_study = results.event_study_effects
 

docs/r_comparison.rst

@@ -114,7 +114,9 @@ staggered DiD. Here's how to translate common operations:
 
 .. code-block:: python
 
-   # Python
+   # Python (unlike R's aggte(), aggregation is requested at fit time)
+   results = cs.fit(data, outcome='Y', time='period', unit='id',
+                    first_treat='G', aggregate='all')
    overall_att = results.overall_att  # Simple aggregation
    event_study = results.event_study_effects  # Dynamic
    by_group = results.group_effects  # By cohort
@@ -191,14 +193,20 @@ The synthdid package implements Arkhangelsky et al. (2021):
    # Python
    from diff_diff import SyntheticDiD
 
+   # SyntheticDiD requires a time-invariant ever-treated indicator
+   data['ever_treated'] = data.groupby('unit')['treatment'].transform('max')
+
+   # Derive post-treatment periods from treatment timing
+   post_periods = sorted(data.loc[data['treatment'] == 1, 'time'].unique())
+
    sdid = SyntheticDiD()
    results = sdid.fit(
        data,
        outcome='Y',
        unit='unit',
        time='time',
-       treatment='treatment',
-       post_periods=[T0, T0+1, T0+2]
+       treatment='ever_treated',
+       post_periods=post_periods
    )
 
 Key Differences

docs/troubleshooting.rst

@@ -205,12 +205,14 @@ Staggered Adoption Issues
    print(data.groupby('first_treat')['unit_id'].nunique())
 
    # Use bootstrap for better inference
-   results = cs.fit(data, ...)
-   bootstrap_results = results.bootstrap(n_bootstrap=999)
+   cs = CallawaySantAnna(n_bootstrap=999)
+   results = cs.fit(data, outcome='y', unit='unit_id',
+                    time='period', first_treat='first_treat',
+                    aggregate='event_study')
 
-   # Aggregate to get more precise estimates
-   event_study = results.aggregate('event_time')
-   overall_att = results.att  # Aggregated ATT
+   # Access aggregated results
+   print(results.overall_att)  # Overall ATT
+   print(results.event_study_effects)  # Event study effects
 
 Visualization Issues
 --------------------
@@ -232,9 +234,11 @@ Visualization Issues
    # Specify reference period explicitly
    plot_event_study(results, reference_period=-1)
 
-   # For CallawaySantAnna, aggregate first
-   event_study = results.aggregate('event_time')
-   plot_event_study(event_study)
+   # For CallawaySantAnna, fit with aggregate='event_study'
+   results = cs.fit(data, outcome='y', unit='unit_id',
+                    time='period', first_treat='first_treat',
+                    aggregate='event_study')
+   plot_event_study(results)
 
 "Plot doesn't show in Jupyter"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -510,15 +514,15 @@ pre-treatment outcomes exist to construct counterfactuals.
 
 .. code-block:: python
 
-   # Identify always-treated units
-   always_treated = data.groupby('unit_id').apply(
-       lambda g: (g['period'] >= g['first_treat']).all()
-   )
-   print(f"Always-treated units: {always_treated.sum()}")
+   # Identify always-treated units (treated at or before first observed period)
+   # Exclude never-treated (first_treat == 0) which are the control group
+   unit_ft = data.groupby('unit_id')['first_treat'].first()
+   min_period = data['period'].min()
+   always_treated = unit_ft[(unit_ft > 0) & (unit_ft <= min_period)]
+   print(f"Always-treated units: {len(always_treated)}")
 
-   # Drop always-treated units
-   keep_units = always_treated[~always_treated].index
-   data = data[data['unit_id'].isin(keep_units)]
+   # Drop always-treated units (keep never-treated controls)
+   data = data[~data['unit_id'].isin(always_treated.index)]
 
 "Horizons not identified without never-treated units"
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~