## download_tidy_finance.download_factor_library_ids()


Download factor library returns for a vector of portfolio IDs.


Usage

``` python
download_tidy_finance.download_factor_library_ids(
    ids, revision="main", grid_revision="main"
)
```


Given a vector of portfolio IDs from the 'tidy-finance/factor-library-grid' Hugging Face dataset, downloads the corresponding return data from the 'tidy-finance/factor-library' dataset on Hugging Face. The returns are stored in files of 1,000 consecutive IDs named after the range they cover (e.g., 'id_0000001-0001000.parquet'), so the function downloads only the files that hold the requested IDs, each once. The grid metadata is joined onto the result.

Use this function when you already know the portfolio IDs you want (for example, from a previous call to 'download_data' with 'dataset' set to 'factor_library'). To resolve IDs from filter criteria (sorting variable, weighting scheme, breakpoints, etc.) and download in a single call, use 'download_data_huggingface' instead.

Raises an error if 'ids' is empty or if none of the requested IDs exist in the grid. IDs whose portfolio sort produced no portfolios have no returns; they are absent from the result, with a warning. Returns are stored in single precision and returned as 64-bit floats, and months without a valid long-short return are stored as 0.

Up to 16 files are downloaded at once and 8 per second on average, also across calls, which keeps the download below the limit of Hugging Face for anonymous users of 3,000 files per five minutes. When Hugging Face still refuses a file, the download waits until the limit resets and tries again, twice at most.


## Parameters


`ids: list of int`  
Portfolio IDs to download. IDs correspond to rows of the 'tidy-finance/factor-library-grid' dataset.

`revision: str = ``"main"`  
Commit hash, branch, or tag of the Hugging Face dataset 'tidy-finance/factor-library', which holds the returns.

`grid_revision: str = ``"main"`  
Commit hash, branch, or tag of the Hugging Face dataset 'tidy-finance/factor-library-grid', which holds the grid.


## Returns


`pl.DataFrame`  
A data frame with the columns 'id', 'date', and 'ret' (the monthly long-short excess return) and the grid metadata columns for the requested IDs.


## Raises


`ValueError`  
If 'ids' is empty, if none of the requested IDs exist in the factor library grid, or if a revision does not exist.

`RuntimeError`  
If the rate limit of Hugging Face refuses a file three times.


## Warns


`UserWarning`  
If some of the requested IDs have no returns in the factor library.


## Examples

``` python
from tidyfinance import download_factor_library_ids
returns = download_factor_library_ids([1, 2, 3])
```
