diff --git a/CHANGELOG.md b/CHANGELOG.md index 8beb928..b197282 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,243 +1,243 @@ -# Historia zmian +# Change history -Format oparty na [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/); -wersjonowanie semantyczne. Wersja schematu danych jest odrębna od wersji pakietu -i podawana jako `SCHEMA_VERSION`. +Format based on [Keep a Changelog](https://keepachangelog.com/pl/1.1.0/); +semantic versioning. The version of the data schema is separate from the version of the package +and is reported as `SCHEMA_VERSION`. ## 1.5.2 (2026-10-17) -### Dodane -- **Uruchamianie w przegladarce** (`docs/app/`): strona wczytujaca ten sam pakiet - do interpretera WebAssembly i uruchamiajaca go lokalnie. Dokument nie jest - nigdzie wysylany, bo nie ma serwera, ktory moglby go przyjac. Wynik jest z - konstrukcji identyczny z wynikiem wiersza polecen, bo to ten sam kod i ta sama - wersja. Strona wykrywa publikujacego, wydobywa wiersze schematu, uruchamia osiem - regul jakosci i pozwala pobrac tabele jako CSV oraz raport walidacji jako JSON. - -### Naprawione -- **Regula R3 zwracala -1 zamiast liczby naruszen**, gdy kolumna `publikujacy` - byla obecna, lecz pusta: `groupby` pomija grupe o wartosci pustej, wiec wiersz - bez tej adnotacji nie mial wpisu w slowniku pol ujawnianych i odwolanie po - kluczu rzucalo `KeyError`. Blad byl przechwytywany, regula raportowala -1, - a suma naruszen calego raportu stawala sie ujemna. Defekt niemy, wykryty - uruchomieniem pakietu na ramce zbudowanej recznie przy budowie strony - przegladarkowej. Dodano test regresyjny. - -### Zmienione -- Z prozy repozytorium usunieto pauze i poltpauze. Jedyne pozostale wystapienie - jest w wyrazeniu regularnym adaptera TAURONA i jest noszne: dopasowuje znak - wystepujacy w dokumencie zrodlowym. +### Added +- **Running in the browser** (`docs/app/`): a page that loads this same package + into a WebAssembly interpreter and runs it locally. The document is not + sent anywhere, because there is no server that could receive it. The result is by + construction identical with the result of the command line, because it is the same code and the same + version. The page detects the publisher, extracts the schema rows, runs the eight + quality rules and allows the table to be downloaded as CSV and the validation report as JSON. + +### Fixed +- **Rule R3 returned -1 instead of a count of violations** when the `publikujacy` column + was present but empty: `groupby` omits a group with an empty value, so a row + without that annotation had no entry in the dictionary of disclosed fields and a lookup by + key raised `KeyError`. The error was caught, the rule reported -1, + and the total number of violations in the whole report became negative. A silent defect, detected + by running the package on a frame built by hand while the browser + page was being built. A regression test was added. + +### Changed +- The em dash and en dash were removed from the prose of the repository. The only remaining occurrence + is in the regular expression of the TAURON adapter and is load-bearing: it matches a character + occurring in the source document. ## 1.5.1 (2026-10-08) -### Poprawione -- **Tożsamość arytmetyczna dokumentu hiszpańskiego opisana poprawnie.** Wersja 1.5.0 - podawała, że kolumny „z pozwoleniem" i „w toku" odtwarzają moc zajętą w 395 z 767 - wierszy. Było to **opisem niepełnej tożsamości**: obie grupy są SKŁADNIKAMI, a nie - alternatywnymi rozbiciami. Jedenaście podkolumn, dziewięć pozycji stacji plus te - dwie, sumuje się do mocy zajętej **dokładnie w 1 838 z 1 838 wierszy, w obu - sprawdzonych wydaniach**. Poprzednia liczba była prawdziwa, ale mierzyła wycinek. - -### Dodane -- `suma_skladnikow_mocy_zajetej` oraz pole `tozsamosc_sumy_mocy_zajetej` w raporcie - adaptera hiszpańskiego. Dla tego publikującego **nie ma zbioru odniesienia** odczytanego - niezależnie od parsera, więc dokładności wydobycia nie da się zmierzyć wobec wzorca. - Domknięcie sumy jest świadectwem **spójności odczytu**: aby suma jedenastu komórek - zgadzała się z dwunastą, wszystkie dwanaście musi być odczytane poprawnie. Na dwóch - wydaniach daje to 3 676 niezależnych sprawdzeń, wszystkie domknięte. Jest to - świadectwo słabsze niż wzorzec i tak jest opisane. -- `NODE_KEY_FIELDS`, klucz treściowy dla wierszy encji WĘZEŁ. Domyślny klucz jest - zbudowany dla encji WNIOSEK i na wierszach węzłowych **rozpada się**, bo pola wniosku - są tam puste. Zmierzone na parze wydań hiszpańskich: kluczem domyślnym 916 z 1 838 - wierszy wpada w kolizję i 660 zostaje odrzuconych jako niejednoznaczne; kluczem - węzłowym kolizji jest **zero**, wszystkie 1 838 par dopasowuje się jednoznacznie, - przy precyzji i czułości **1,000**. Wniosek ogólniejszy: klucz treściowy musi być - dobrany do encji tak samo jak rdzeń schematu, a jego niedopasowanie **nie zgłasza - błędu**, po cichu produkuje kolizje wyglądające jak zdarzenia w rejestrze. +### Corrected +- **The arithmetic identity of the Spanish document described correctly.** Version 1.5.0 + stated that the columns "with permission" and "in progress" reconstruct the occupied capacity in 395 of 767 + rows. That was **a description of an incomplete identity**: both groups are COMPONENTS, not + alternative breakdowns. Eleven subcolumns, nine substation items plus those + two, sum to the occupied capacity **in exactly 1 838 of 1 838 rows, in both + editions checked**. The previous figure was true, but it measured a fragment. + +### Added +- `suma_skladnikow_mocy_zajetej` and the field `tozsamosc_sumy_mocy_zajetej` in the report of the + Spanish adapter. For this publisher **there is no reference set** read + independently of the parser, so the extraction accuracy cannot be measured against a reference set. + Arithmetic closure is evidence of **consistency of reading**: for the sum of eleven cells + to agree with the twelfth, all twelve have to be read correctly. Across two + editions that gives 3 676 independent checks, all of them closed. This is + evidence weaker than a reference set and it is described as such. +- `NODE_KEY_FIELDS`, a content key for rows of the WĘZEŁ entity. The default key is + built for the WNIOSEK entity and on node rows it **falls apart**, because the application fields + are empty there. Measured on a pair of Spanish issues: with the default key 916 of 1 838 + rows fall into a collision and 660 are rejected as ambiguous; with the node + key the collisions number **zero**, all 1 838 pairs are linked unambiguously, + at a precision and recall of **1,000**. The more general conclusion: a content key has to be + matched to the entity just as the schema core is, and a mismatch **does not report + an error**, it quietly produces collisions that look like events in the register. ## 1.5.0 (2026-10-08) -### Dodane -- Adapter `es_edistribucion`, **pierwsze zagraniczne źródło wydawane jako dokument - do druku**, co zamyka najmocniejszy brakujący test przenoszalności. Wydanie miesięczne, - 28 stron, 1 838 wierszy encji WĘZEŁ, wszystkie pola zadeklarowane wypełnione - w 100 %, w tym współrzędne geograficzne każdej podstacji. Moce w MW mocy czynnej. -- Adapter `ie_esbnetworks`, najliczniejsze źródło w panelu, 46 527 wierszy, jedyne - schodzące poniżej stacji wysokiego napięcia. Współrzędne w 46 525 wierszach. -- Panel wzorcowy: **68 054 wiersze, dziewięciu publikujących, pięć jurysdykcji** - (PL, GB, PT, ES, IE). Encja WĘZEŁ rośnie z 634 do 48 999 wierszy, a pokrycie pola - współrzędnych z 6,2 % do 72,9 % panelu. - -### Rozstrzygnięte -- **Jednostki, po raz drugi i trzeci.** Źródło irlandzkie miesza w jednym pliku moc - pozorną po stronie odbiorczej z czynną po wytwórczej; pole mocy niesie stronę wytwórczą - przeliczoną z MW, a odbiorcza zostaje w rozszerzeniach z jednostką w nazwie. Źródło - hiszpańskie podaje MW mocy czynnej, więc przelicza się bez założeń. Trzy jurysdykcje - pokazują trzy różne praktyki jednostkowe w jednym polu schematu. -- **Semantyka kolumn hiszpańskich ustalona arytmetyką, nie nagłówkiem.** Nagłówek - z komórkami scalonymi sugerował przypisanie dwóch kolumn do mocy nierozstrzygniętej; - sumy pokazały, że należą do mocy zajętej. Przyjęcie nagłówka na wiarę dałoby ciche - przestawienie dwóch pól mocy. **Uściślone w 1.5.1**, patrz niżej. -- **Pusta komórka ograniczenia w źródle irlandzkim** czytana jest jako brak ograniczenia. - Publikujący tej konwencji nie opisuje, więc jest to interpretacja, nie treść źródła: - surowa fraza zostaje w rozszerzeniu, a decyzja jest przypięta testem. - -### Zmienione -- Test rejestru obejmuje dziewięć adapterów w pięciu jurysdykcjach. -- `reproducibility/manifest.csv` liczy 16 pozycji. +### Added +- The `es_edistribucion` adapter, **the first foreign source issued as a document + meant for printing**, which closes the strongest missing test of transferability. A monthly issue, + 28 pages, 1 838 rows of the WĘZEŁ entity, all declared fields populated + at 100 %, including the geographic coordinates of every substation. Capacities in MW of active power. +- The `ie_esbnetworks` adapter, the largest source in the panel, 46 527 rows, the only one + going below high voltage substations. Coordinates in 46 525 rows. +- Reference panel: **68 054 rows, nine publishers, five jurisdictions** + (PL, GB, PT, ES, IE). The WĘZEŁ entity grows from 634 to 48 999 rows, and the coverage of the + coordinate field from 6,2 % to 72,9 % of the panel. + +### Settled +- **Units, for the second and third time.** The Irish source mixes, in one file, apparent power + on the offtake side with active power on the generating side; the capacity field carries the generating side + converted from MW, and the offtake side stays in the extensions with the unit in the name. The Spanish + source reports MW of active power, so it converts without assumptions. Three jurisdictions + show three different unit practices in one schema field. +- **The semantics of the Spanish columns established by arithmetic, not by the header.** A header + with merged cells suggested that two columns belonged to the unsettled capacity; + the sums showed that they belong to the occupied capacity. Taking the header on trust would have given a silent + transposition of two capacity fields. **Made precise in 1.5.1**, see below. +- **An empty constraint cell in the Irish source** is read as no constraint. + The publisher does not describe this convention, so it is an interpretation, not the content of the source: + the raw phrase stays in an extension, and the decision is pinned by a test. + +### Changed +- The registry test covers nine adapters in five jurisdictions. +- `reproducibility/manifest.csv` counts 16 entries. ## 1.4.0 (2026-10-07) -### Dodane -- Adapter `pt_eredes`, zdolność przyjęcia krajowej sieci dystrybucyjnej Portugalii, - 469 wierszy encji WĘZEŁ, publikacja kwartalna. **Trzecia jurysdykcja w panelu - i trzeci tryb wydania**: nie dokument do druku i nie plik na stronie, lecz zbiór - na portalu otwartych danych z interfejsem REST. -- Pierwsze zagraniczne źródło encji WĘZEŁ. Encja ta rośnie w panelu ze 165 wierszy - do 634, a obie jurysdykcje spełniają jej rdzeń **różnymi członami tej samej - alternatywy**: Polska mocą dostępną (58 % wierszy węzłowych), Portugalia flagą - ograniczenia (100 %). Warunkowy rdzeń wprowadzony w wersji 1.0 dla polskiego - błędu kategorialnego okazał się warunkiem wchłonięcia obcej jurysdykcji. - -### Rozstrzygnięte -- **Jednostki.** Publikujący portugalski podaje moce w MVA, czyli w mocy pozornej, - a jednostką kanoniczną schematu jest kW mocy czynnej. Przeliczenie wymagałoby - nieujawnionego współczynnika mocy, więc `moc_dostepna` pozostaje puste, a wartości - źródłowe trafiają do pól rozszerzenia z jawnie zapisaną jednostką. Jest to ta sama - zasada, którą zastosowano wobec publikującego podającego liczbę wolnych miejsc - przyłączeniowych zamiast mocy. - -### Naprawione -- **Test deklaracji adapterów niósł nieaktualny kontrakt rdzenia.** Wymagał od - każdego adaptera rdzenia encji WNIOSEK, czyli powielał błąd kategorialny naprawiony - w regule R7 w wersji 1.0: publikujący realizujący wyłącznie punkt 2 obowiązku - ujawnia węzły, a nie wnioski, więc nie ma ani identyfikatora wniosku, ani jego mocy. - Defekt ujawnił dopiero adapter portugalski. Test sprawdza teraz rdzeń **właściwej - dla adaptera encji**. - -### Zmienione -- `reproducibility/manifest.csv` obejmuje eksport portugalski z sumą kontrolną. -- Panel wzorcowy liczy 19 689 wierszy od siedmiu publikujących w trzech jurysdykcjach. +### Added +- The `pt_eredes` adapter, the reception capability of the national distribution network of Portugal, + 469 rows of the WĘZEŁ entity, published quarterly. **The third jurisdiction in the panel + and the third mode of issue**: not a document meant for printing and not a file on a page, but a dataset + on an open data portal with a REST interface. +- The first foreign source of the WĘZEŁ entity. That entity grows in the panel from 165 rows + to 634, and both jurisdictions satisfy its core **through different members of the same + alternative**: Poland with available capacity (58 % of the node rows), Portugal with the + constraint flag (100 %). The conditional core introduced in version 1.0 for a Polish + category error turned out to be the condition for absorbing a foreign jurisdiction. + +### Settled +- **Units.** The Portuguese publisher reports capacities in MVA, that is in apparent power, + whereas the canonical unit of the schema is kW of active power. Conversion would require + an undisclosed power factor, so `moc_dostepna` remains empty, and the source + values go into the extension fields with the unit recorded explicitly. This is the same + principle that was applied to the publisher reporting a count of free connection + slots instead of a capacity. + +### Fixed +- **The adapter declaration test carried an out-of-date core contract.** It required + the core of the WNIOSEK entity from every adapter, that is it repeated the category error fixed + in rule R7 in version 1.0: a publisher discharging only point 2 of the duty + discloses nodes rather than applications, so it has neither an application identifier nor an application capacity. + The defect was revealed only by the Portuguese adapter. The test now checks the core **appropriate + to the adapter's entity**. + +### Changed +- `reproducibility/manifest.csv` covers the Portuguese export with a checksum. +- The reference panel counts 19 689 rows from seven publishers in three jurisdictions. ## 1.3.0 (2026-10-07) -### Dodane -- Moduł `analysis` z warstwą badawczą nad schematem: `station_node_map`, +### Added +- The `analysis` module with a research layer above the schema: `station_node_map`, `assign_to_nodes`, `node_loading`, `processing_time`, `kaplan_meier`. - Pozwala policzyć **obciążenie węzła**, stosunek mocy czynnej kolejki do - ujawnionej mocy dostępnej, czyli kryterium, które przeglądy literatury - opisują jako niemierzalne z powodu braku danych. -- `linkage_recall`, **czułość** dopasowania wzdłużnego, obok mierzonej dotąd - precyzji. Na parze edycji operatora przesyłowego czułość klucza wynosi - 0,9652: z 29 pominiętych par 10 rozrywa zapis lokalizacji, 15 zmiana mocy, - 4 zmiana napięcia. -- `surrogate_key(..., zero_jako_brak=True)`, opcja zrównująca zero z brakiem - wartości. Odzyskuje 12 z 51 par traconych przez klucz. **Domyślnie - wyłączona**: zero jest wartością ujawnioną, a brak jej nieujawnieniem, więc - zrównanie ich jest decyzją analityka i ma być widoczne w kodzie. -- `schema_table()` zwraca kolumny `encja` oraz `status_rdzenia`, rdzeń jest - warunkowy per encja, czego dwuwartościowa kolumna `rdzen` nie oddawała. -- `reproducibility/fetch_sources.py`, pobiera dokumenty źródłowe z manifestu - i weryfikuje sumy SHA-256. Obsługuje własny pakiet zaufanych wystawców przez - `GRIDQUEUE_CA_BUNDLE`, bez wyłączania weryfikacji. - -### Naprawione -- **Normalizacja nazw rozcinała wyrazy z literą `ł`.** Rozkład kanoniczny - Unicode nie oddziela od niej znaku diakrytycznego, bo jest to osobna litera, - więc czyszczenie znaków zamieniało ją na spację i „Białogard" stawał się - „bia ogard". Dotyczy też `đ`, `ø`, `ß`, `æ`, `œ`. Jest to drugie wystąpienie - tej samej pułapki w projekcie, pierwsze dotyczyło harmonizacji statusów. -- **Obiekty planowane na linii były arbitralnie przypisywane do węzła.** Wpis - „planowany RS w linii relacji A, B" opisuje obiekt leżący między węzłami; - dopasowanie po nazwie przypisywało mu pełną moc do tego końca, który akurat - występował w wykazie stacji. Takie wnioski mają teraz własny status `LINE` - i nie są przypisywane. Na danych jednego publikującego dotyczy to 63 wniosków. - -### Zmienione -- `reproducibility/manifest.csv` obejmuje edycję lipcową ujawnienia operatora - przesyłowego, używaną w analizie wzdłużnej. -- `DATA_LICENSE.md` wyjaśnia, dlaczego dokumenty nie są redystrybuowane, - i odnotowuje, że odsyłacz jednego z publikujących przestał prowadzić do pliku -, co skrypt pobierający rozpoznaje po sygnaturze pliku i zgłasza osobno. + It makes it possible to compute **node loading**, the ratio of the active capacity of the queue to + the disclosed available capacity, that is the criterion which literature reviews + describe as unmeasurable because of the absence of the data. +- `linkage_recall`, the **recall** of the longitudinal linkage, alongside the precision + measured so far. On a pair of editions of the transmission operator the recall of the key is + 0,9652: of the 29 missed pairs, 10 are broken by the notation of the location, 15 by a change of capacity, + 4 by a change of voltage. +- `surrogate_key(..., zero_jako_brak=True)`, an option equating zero with a missing + value. It recovers 12 of the 51 pairs lost by the key. **Disabled + by default**: zero is a disclosed value and a gap is a non-disclosure of it, so + equating them is a decision of the analyst and is meant to be visible in the code. +- `schema_table()` returns the columns `encja` and `status_rdzenia`; the core is + conditional per entity, which the two-valued `rdzen` column did not convey. +- `reproducibility/fetch_sources.py`, downloads the source documents from the manifest + and verifies the SHA-256 checksums. It supports a custom bundle of trusted issuers through + `GRIDQUEUE_CA_BUNDLE`, without disabling verification. + +### Fixed +- **Name normalization split words containing the letter `ł`.** The canonical Unicode + decomposition does not separate the diacritic from it, because it is a separate letter, + so cleaning the characters turned it into a space and "Białogard" became + "bia ogard". This also concerns `đ`, `ø`, `ß`, `æ`, `œ`. It is the second occurrence + of the same trap in the project; the first concerned the harmonization of statuses. +- **Objects planned on a line were arbitrarily assigned to a node.** The entry + "planowany RS w linii relacji A, B" describes an object lying between nodes; + matching by name assigned its full capacity to whichever end happened + to appear in the list of substations. Such applications now have their own status `LINE` + and are not assigned. On the data of one publisher this concerns 63 applications. + +### Changed +- `reproducibility/manifest.csv` covers the July edition of the disclosure of the transmission + operator, used in the longitudinal analysis. +- `DATA_LICENSE.md` explains why the documents are not redistributed, + and records that the link of one of the publishers stopped leading to the file +, which the download script recognizes by the signature of the file and reports separately. ## 1.2.1 (2026-10-04) -### Dodane -- `notebooks/gridqueue_colab.ipynb`, pełny przebieg badawczy w przeglądarce, bez instalacji: - pobranie dwóch edycji wprost od publikującego, wydobycie, kontrola jakości, przepływy w kolejce - z precyzją dopasowania oraz **asercja zgodności z liczbami opublikowanymi w artykule**. - Dokumentacja: `docs/colab.md`. -- `QualityReport.as_frame()`, metoda **obiecywana przez dokumentację, lecz nieobecna w kodzie**. - Defekt ujawnił się dopiero przy uruchomieniu notatnika, który korzystał z publicznego API - tak, jak opisuje je dokumentacja. -- Dwa zadania ciągłej integracji: przebieg na `pandas>=3.0` oraz kontrola notatnika - (poprawność składniowa komórek i istnienie w API każdej nazwy z niego importowanej). - -### Naprawione -- **Niezgodność z pandas 3.** Klucz wzdłużny budowano przez `.astype(str)`, co w pandas 2 - zamieniało brak na łańcuch `"nan"`, a w pandas 3 zachowuje wartość brakującą, złączenie - składowych rzucało `TypeError` i cała analiza wzdłużna była na tej wersji niewykonalna. - Klucz buduje się teraz jawną konwersją, identycznie w obu wersjach; **wszystkie opublikowane - liczby pozostają bez zmian**, co sprawdzono porównaniem. Ta sama poprawka czyni regułę - „brak jest wartością" własnością kodu, a nie ubocznym skutkiem rzutowania typu. - Analogiczne założenie usunięto z adaptera operatora przesyłowego. - -### Zmienione -- Macierz CI testowała wersje Pythona, lecz nie wersje bibliotek, stąd defekt przeszedł. - Zadanie `pandas3` zamyka tę lukę. +### Added +- `notebooks/gridqueue_colab.ipynb`, a full research run in the browser, with no installation: + downloading two editions directly from the publisher, extraction, quality control, queue flows + with the linkage precision, and **an assertion of agreement with the figures published in the paper**. + Documentation: `docs/colab.md`. +- `QualityReport.as_frame()`, a method **promised by the documentation but absent from the code**. + The defect came to light only when the notebook was run, since it used the public API + the way the documentation describes it. +- Two continuous integration jobs: a run on `pandas>=3.0` and a check of the notebook + (syntactic correctness of the cells and the existence in the API of every name imported from it). + +### Fixed +- **Incompatibility with pandas 3.** The longitudinal key was built using `.astype(str)`, which in pandas 2 + turned a gap into the string `"nan"`, whereas in pandas 3 it preserves the missing value; concatenating + the components raised `TypeError` and the whole longitudinal analysis was impossible on that version. + The key is now built by an explicit conversion, identically in both versions; **all the published + figures remain unchanged**, which was checked by comparison. The same fix makes the rule + "a gap is a value" a property of the code rather than a side effect of a type cast. + An analogous assumption was removed from the adapter of the transmission operator. + +### Changed +- The CI matrix tested Python versions but not library versions, which is how the defect got through. + The `pandas3` job closes that gap. ## 1.2.0 (2026-10-04) -### Dodane -- `linkage_audit`, ocena precyzji dopasowania wzdłużnego na dziewięciu polach - **wyłączonych z klucza** (nazwa podmiotu, nazwa obiektu, data wniosku, sześć pól - rozbicia mocy). Klucz nie wymusza zgodności tych pól, więc ich zgodność jest - niezależnym świadectwem. Na parze edycji PSE precyzja wynosi 98,88-99,63 % - na wszystkich 804 parach. -- `EditionDelta` raportuje teraz kolizje klucza i liczbę wierszy odrzuconych - z dopasowania jako niejednoznaczne. -- `DATA_LICENSE.md`, rozdzielenie licencji kodu od statusu danych wejściowych - i wyjściowych, w tym obowiązków wynikających z ODbL dla gazetera. +### Added +- `linkage_audit`, an assessment of the precision of the longitudinal linkage on nine fields + **excluded from the key** (entity name, object name, application date, six fields of the + capacity breakdown). The key does not enforce the agreement of these fields, so their agreement is + independent evidence. On the pair of PSE editions the precision is 98,88-99,63 % + across all 804 pairs. +- `EditionDelta` now reports key collisions and the number of rows rejected + from the linkage as ambiguous. +- `DATA_LICENSE.md`, separating the licence of the code from the status of the input + and output data, including the duties following from ODbL for the gazetteer. - `CHANGELOG.md`. -- Odznaki stanu w `README.md`. -- `reproducibility/expected/`, oczekiwane wyniki wraz z asercjami w skryptach - odtwarzających; rozbieżność kończy przebieg kodem niezerowym. +- Status badges in `README.md`. +- `reproducibility/expected/`, the expected results together with assertions in the reproducing + scripts; a divergence ends the run with a non-zero code. -### Zmienione -- Dokumentacja analizy wzdłużnej podaje pełną specyfikację algorytmu dopasowania: - zachowanie przy braku wartości, wymóg unikalności, obsługę kolizji, brak tolerancji - na mocach. -- Przykład wzdłużny wypisuje precyzję dopasowania i liczby kolizji. +### Changed +- The documentation of the longitudinal analysis gives the full specification of the linkage algorithm: + behaviour on a missing value, the uniqueness requirement, the handling of collisions, the absence of tolerance + on the capacities. +- The longitudinal example prints the linkage precision and the collision counts. ## 1.1.0 (2026-10-03) -### Dodane -- Moduł `longitudinal`: `compare_editions`, `surrogate_key`, `EditionDelta`. - Rejestr nie publikuje trwałego identyfikatora wniosku, więc dopasowanie między - edycjami idzie po kluczu treściowym. -- `examples/longitudinal_use_case.py` i `docs/wzdluzna.md`. - -### Naprawione -- **Wielokrotne komórki mocy.** Gdy wniosek dotyczy kilku miejsc przyłączenia, - publikujący wpisuje do jednej komórki kilka wartości rozdzielonych złamaniem linii. - Normalizacja białych znaków zamieniała złamanie linii na spację, a konwersja mocy - traktuje spację jako separator tysięczny, więc „129⏎240" (129 MW + 240 MW) stawało się - 129 240 MW. W edycji ze średnikami ta sama komórka nie konwertowała się wcale. - Moc jest teraz rozbijana po złamaniu linii i średniku, i celowo nie po spacji - - składowe sumowane, a podział zachowany w rozszerzeniach. +### Added +- The `longitudinal` module: `compare_editions`, `surrogate_key`, `EditionDelta`. + The register does not publish a persistent application identifier, so linkage between + editions goes by a content key. +- `examples/longitudinal_use_case.py` and `docs/wzdluzna.md`. + +### Fixed +- **Multiple capacity cells.** When an application concerns several connection points, + the publisher enters several values into one cell, separated by a line break. + Whitespace normalization turned the line break into a space, and the capacity conversion + treats a space as a thousands separator, so "129⏎240" (129 MW + 240 MW) became + 129 240 MW. In the edition with semicolons the same cell did not convert at all. + The capacity is now split on the line break and on the semicolon, and deliberately not on the space; + the components are summed and the split is preserved in the extensions. ## 1.0.0 (2026-10-03) -### Zmienione -- **Rdzeń schematu jest warunkowy i osobny dla każdej encji.** Reguła kompletności - rdzenia wymagała bezwarunkowo pola `moc_pobierana` i stosowała wymagania encji - WNIOSEK także do wierszy encji WĘZEŁ. Obie decyzje zamieniały własność schematu - w pozorne naruszenie ujawnienia. Naruszeń reguły R7 jest 771 (4,011 %) zamiast +### Changed +- **The schema core is conditional and separate for each entity.** The core completeness + rule required the `moc_pobierana` field unconditionally and applied the requirements of the + WNIOSEK entity to rows of the WĘZEŁ entity as well. Both decisions turned a property of the schema + into an apparent violation of the disclosure. Violations of rule R7 number 771 (4,011 %) instead of 5 390 (28,044 %). -- Wprowadzono `SCHEMA_VERSION`, wystawiany w raporcie walidacji i w publicznym API. +- `SCHEMA_VERSION` was introduced, exposed in the validation report and in the public API. -### Dodane -- `examples/research_use_case.py`, katalog `reproducibility/`, `CITATION.cff`, - przepływ ciągłej integracji na trzech systemach i czterech wersjach Pythona. +### Added +- `examples/research_use_case.py`, the `reproducibility/` directory, `CITATION.cff`, + a continuous integration workflow on three systems and four Python versions. diff --git a/CITATION.cff b/CITATION.cff index 8ecfcea..6f277ec 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,11 +1,11 @@ cff-version: 1.2.0 -message: "Jeśli używasz tego oprogramowania, zacytuj je według poniższych metadanych." +message: "If you use this software, please cite it using the metadata below." title: "gridqueue" abstract: >- - Harmonizator ustawowych ujawnień przyłączeniowych do sieci elektroenergetycznej. - Przekształca dokumenty publikowane na mocy art. 7 ust. 8l polskiego Prawa energetycznego - oraz odpowiadające im rejestry z innych jurysdykcji w jeden zbiór wierszy w 21-polowym - schemacie wyprowadzonym ze struktury obowiązku prawnego. + Harmonizer of statutory grid-connection disclosures for the electricity network. + Turns the documents published under Article 7(8l) of the Polish Energy Law + and the corresponding registers from other jurisdictions into a single set of rows in a 21-field + schema derived from the structure of the legal obligation. type: software version: "1.2.1" date-released: "2026-10-04" @@ -13,14 +13,14 @@ license: Apache-2.0 repository-code: "https://github.com/s-matysik/gridqueue" url: "https://s-matysik.github.io/gridqueue/" keywords: - - przyłączenie do sieci - - ujawnienia ustawowe - - harmonizacja danych - - wydobycie z dokumentów - - otwarte dane energetyczne + - grid connection + - statutory disclosures + - data harmonization + - document extraction + - open energy data authors: - name: "gridqueue contributors" -# UWAGA DLA ZESPOŁU: powyższy wpis autorski jest zbiorczy i wystarcza, aby plik był poprawny -# według specyfikacji CFF 1.2.0. Przed zgłoszeniem artykułu należy go zastąpić listą autorów -# osobowych (given-names / family-names / orcid / affiliation) zgodną z listą autorów manuskryptu, -# a po zdeponowaniu wydania dopisać pole `doi`. +# NOTE FOR THE TEAM: the author entry above is collective and is enough for the file to be valid +# under the CFF 1.2.0 specification. Before the paper is submitted it has to be replaced with a list +# of individual authors (given-names / family-names / orcid / affiliation) matching the author list +# of the manuscript, and once the release has been deposited, a `doi` field has to be added. diff --git a/CODE_METADATA.md b/CODE_METADATA.md index c151a3d..1667694 100644 --- a/CODE_METADATA.md +++ b/CODE_METADATA.md @@ -1,7 +1,7 @@ # gridqueue, SoftwareX code metadata table Companion to `gridqueue_SoftwareX_manuscript.md`. Fields whose value depends on the packaging -band carry `⟦PAKIET: …⟧`; fields that require a team decision carry `⟦DECYZJA ZESPOŁU⟧` and are +band carry `⟦PACKAGE: …⟧`; fields that require a team decision carry `⟦TEAM DECISION⟧` and are listed again in the final section. ## Required Metadata, Current code version @@ -10,13 +10,13 @@ listed again in the final section. |----|------|-------| | C1 | Current code version | `1.2.1` (declared identically in `pyproject.toml` and in `gridqueue.__version__`; CI asserts the two agree on every push) | | C2 | Permanent link to code / repository used for this code version | https://github.com/s-matysik/gridqueue (tag `v1.2.1`) | -| C3 | Permanent link to Reproducible Capsule | ⟦DECYZJA ZESPOŁU⟧, archive DOI. The repository is ready for a Zenodo deposit of tag `v1.2.1`; enabling the integration requires the team's account | +| C3 | Permanent link to Reproducible Capsule | ⟦TEAM DECISION⟧, archive DOI. The repository is ready for a Zenodo deposit of tag `v1.2.1`; enabling the integration requires the team's account | | C4 | Legal Code License | Apache-2.0, `LICENSE.txt` at the distribution root. Input data licences are fixed and separate: OpenStreetMap gazetteer under ODbL 1.0; operators' statutory publications under the terms each publisher applies to its own site | | C5 | Code versioning system used | git | | C6 | Software code languages, tools and services used | Python, `requires-python >= 3.10`; build backend `setuptools.build_meta` (`setuptools>=68`); test runner `pytest` | | C7 | Compilation requirements, operating environments and dependencies | No compilation (pure Python). Runtime: `pandas>=2.0`, `pdfplumber>=0.11`, `openpyxl>=3.1`, `requests>=2.31`, `pyarrow>=14`. Test extra: `pytest>=8.0`. Build: `setuptools>=68`. The location resolver needs no third-party string-matching library; matching is implemented in `geoloc.py` | | C8 | If available, link to developer documentation / manual | https://s-matysik.github.io/gridqueue/, eight generated pages (schema with legal basis per field, adapters, extraction method, quality rules, measured validation, CLI, limitations). `README.md` at the distribution root duplicates the quick path | -| C9 | Support email for questions | ⟦DECYZJA ZESPOŁU⟧, corresponding author's institutional address | +| C9 | Support email for questions | ⟦TEAM DECISION⟧, corresponding author's institutional address | ## Required Metadata, Software @@ -28,7 +28,7 @@ listed again in the final section. | S4 | Computing platforms / Operating Systems | Linux, macOS, Windows × Python 3.10, 3.11, 3.12, 3.13, a twelve-cell matrix exercised by GitHub Actions (`.github/workflows/ci.yml`) on every push and pull request. The measured figures reported in the paper were produced on macOS/arm64 with Python 3.11.15 | | S5 | Installation requirements & dependencies | As C7. No GPU, no network access required at run time once the source documents and the gazetteer are local | | S6 | If available, link to user manual | `README.md`, plus `examples/research_use_case.py` and `examples/longitudinal_use_case.py`, two runnable research workflows and a Colab notebook that reproduces the longitudinal result in the browser, asserting agreement with the published figures, the longitudinal one additionally reporting linkage precision measured on fields held out of the matching key (administrative processing time by resource class and publisher) that uses the public API only and contains no publisher-specific branch | -| S7 | Support email for questions | ⟦DECYZJA ZESPOŁU⟧, same address as C9 | +| S7 | Support email for questions | ⟦TEAM DECISION⟧, same address as C9 | ## Software characterisation (for the "Software description" section) diff --git a/DATA_LICENSE.md b/DATA_LICENSE.md index e094871..35d212c 100644 --- a/DATA_LICENSE.md +++ b/DATA_LICENSE.md @@ -1,96 +1,96 @@ -# Status prawny kodu i danych - -Plik `LICENSE.txt` obejmuje **wyłącznie kod** tego pakietu. Dane, na których kod pracuje, -i dane, które wytwarza, mają odrębny status i opisujemy go tutaj, bo pomylenie tych warstw -jest realnym ryzykiem przy ponownym wykorzystaniu. - -## 1. Kod pakietu - -Apache-2.0, zgodnie z `LICENSE.txt`. Obejmuje `src/`, `tests/`, `examples/`, -`reproducibility/` i `docs/`. - -## 2. Dokumenty źródłowe publikujących - -Dokumenty wydawane przez operatorów na podstawie art. 7 ust. 8l ustawy Prawo energetyczne -są **publikacjami urzędowymi wykonywanymi pod obowiązkiem ustawowym**. Pakiet ich -**nie redystrybuuje**. `reproducibility/manifest.csv` podaje dla każdego dokumentu adres, -datę pobrania, rozmiar i sumę kontrolną SHA-256, co pozwala **zweryfikować**, że pobrany -plik jest tym samym, na którym liczono wyniki. - -Jest to weryfikacja, nie gwarancja odtworzenia. Obowiązek każe wymieniać publikację co -najmniej raz na kwartał, więc plik pod danym adresem **bywa zastępowany nowszym**. -Dokładne odtworzenie obliczeniowe jest zatem uwarunkowane dalszą dostępnością archiwalnych -plików źródłowych u publikujących albo ich zarchiwizowaniem przez użytkownika. - -## 3. Gazeter geometryczny, OpenStreetMap - -Gazeter wykorzystywany przez rozwiązywacz lokalizacji pochodzi z OpenStreetMap i podlega -**Open Database License 1.0**. Oznacza to dla użytkownika trzy obowiązki, których Apache-2.0 -nie obejmuje: - -- **atrybucja**, wskazanie OpenStreetMap jako źródła przy każdej publikacji wyników - zawierających współrzędne; -- **share-alike**, udostępnienie bazy pochodnej, jeśli jest publicznie dystrybuowana, - na tej samej licencji; -- **brak ograniczeń technicznych**, nie wolno dystrybuować bazy pochodnej w sposób - uniemożliwiający odbiorcy korzystanie z niej na warunkach ODbL. - -Rozróżnienie istotne w praktyce: *produced work*, na przykład mapa albo tabela wyników - -wymaga atrybucji, lecz nie uruchamia share-alike; *derivative database*, na przykład panel -z doklejonymi współrzędnymi, udostępniany dalej, uruchamia share-alike. - -## 4. Panel wynikowy - -Panel wytworzony przez pakiet jest utworem pochodnym od obu powyższych warstw. -W zakresie, w jakim zawiera **wartości wyprowadzone z gazetera** (pole `wspolrzedne` -i kolumny diagnostyczne rozwiązywacza), podlega ODbL. W zakresie, w jakim zawiera -wyłącznie treść przepisaną z dokumentów urzędowych, podlega statusowi tych dokumentów. -Kolumna `_geo_pewnosc` pozwala te dwie warstwy rozdzielić: wiersze bez rozstrzygniętej -lokalizacji nie zawierają żadnej treści pochodzącej z OpenStreetMap. - -## 5. Dane osobowe - -Ujawnienia dotyczą **podmiotów ubiegających się o przyłączenie**, a pole nazwy podmiotu -zawiera w zdecydowanej większości firmy spółek prawa handlowego. Ustawa nie wyłącza -jednak osób fizycznych prowadzących działalność, więc nie twierdzimy, że dane osobowe -w korpusie nie występują. - -Pakiet **nie wykonuje re-identyfikacji** i nie wzbogaca rekordów danymi o osobach -z żadnego innego źródła. Rozwiązywacz lokalizacji działa na nazwie miejscowości i ulicy -podanej w dokumencie, nigdy na nazwie podmiotu. Odpowiedzialność za zgodne z prawem -dalsze wykorzystanie wyjścia, w tym za ewentualną ocenę skutków dla ochrony danych, -spoczywa na użytkowniku. - - -## Dlaczego dokumenty źródłowe nie są dołączone do repozytorium - -Repozytorium zawiera **manifest** dokumentów (adres, data pobrania, rozmiar, -suma SHA-256) oraz skrypt `reproducibility/fetch_sources.py`, który je pobiera -i weryfikuje. Nie zawiera samych dokumentów. Powody są dwa i oba są praktyczne, -a nie ostrożnościowe. - -**Po pierwsze, statusu prawnego redystrybucji nie rozstrzygamy.** Polskie prawo -autorskie wyłącza z ochrony materiały urzędowe, ale ujawnienia, o których mowa, -sporządzają i publikują spółki prowadzące działalność gospodarczą, wykonując -obowiązek ustawowy, a to, czy mieszczą się one w tej kategorii, nie jest -przesądzone. Niezależnie od prawa autorskiego do zbiorów danych może mieć -zastosowanie ochrona *sui generis*. Nie jesteśmy w stanie tego rozstrzygnąć -i nie udajemy, że jesteśmy; zespół zamierzający dołączyć dokumenty do -publikacji powinien uzyskać opinię prawną. - -**Po drugie, dokumenty są wymieniane.** Obowiązek wyznacza co najmniej -kwartalną aktualizację, więc kopia złożona w repozytorium po kilku miesiącach -przedstawiałaby stan, którego już nie ma, i byłaby myląca tym bardziej, im -bardziej wyglądałaby na aktualną. - -Konsekwencję trzeba powiedzieć wprost, bo jest niewygodna: **odtworzenie co do -bajtu przestaje być możliwe, gdy publikujący wymieni albo przeniesie dokument.** -Podczas przygotowania wydania 1.3.0 odsyłacz do ujawnienia jednego z operatorów -przestał prowadzić do pliku i zaczął zwracać stronę serwisu, skrypt pobierający -rozpoznaje ten przypadek i zgłasza go osobno, zamiast zapisać stronę jako -dokument. Dlatego sumy kontrolne są w manifeście: niezgodność jest sygnałem, że -liczby nie będą identyczne z opublikowanymi, a nie usterką do zignorowania. - -Zespołowi przygotowującemu publikację zalecamy **depozyt dokumentów w archiwum -z trwałym identyfikatorem**, o ile opinia prawna na to pozwoli. Jest to jedyny -sposób, by odsyłacz w artykule prowadził do tego, co faktycznie analizowano. +# Legal status of the code and of the data + +The file `LICENSE.txt` covers **the code of this package only**. The data the code works on, +and the data it produces, have a separate status, and we describe it here, because confusing those +layers is a real risk on reuse. + +## 1. The code of the package + +Apache-2.0, in accordance with `LICENSE.txt`. It covers `src/`, `tests/`, `examples/`, +`reproducibility/` and `docs/`. + +## 2. The publishers' source documents + +The documents issued by the operators under Article 7(8l) of the Energy Law +are **official publications made under a statutory duty**. The package +**does not redistribute** them. For each document, `reproducibility/manifest.csv` gives the address, +the date of download, the size and the SHA-256 checksum, which makes it possible to **verify** that +the downloaded file is the same one on which the results were computed. + +This is verification, not a guarantee of reproduction. The duty requires the publication to be +replaced at least once per quarter, so the file at a given address **is sometimes superseded by a +newer one**. Exact computational reproduction is therefore conditional on the continued availability +of archival source files at the publishers, or on their being archived by the user. + +## 3. The geometric gazetteer, OpenStreetMap + +The gazetteer used by the location resolver comes from OpenStreetMap and is subject to the +**Open Database License 1.0**. For the user this means three duties that Apache-2.0 +does not cover: + +- **attribution**, naming OpenStreetMap as the source in every publication of results + containing coordinates; +- **share-alike**, making a derivative database available under the same licence if it is publicly + distributed; +- **no technical restrictions**, a derivative database must not be distributed in a way that + prevents the recipient from using it on ODbL terms. + +A distinction that matters in practice: a *produced work*, for example a map or a table of results, +requires attribution but does not trigger share-alike; a *derivative database*, for example a panel +with coordinates attached, made available onwards, does trigger share-alike. + +## 4. The resulting panel + +The panel produced by the package is a work derived from both of the layers above. +To the extent that it contains **values derived from the gazetteer** (the `wspolrzedne` field +and the resolver's diagnostic columns), it is subject to ODbL. To the extent that it contains +only content transcribed from official documents, it is subject to the status of those documents. +The `_geo_pewnosc` column makes it possible to separate those two layers: rows with no resolved +location contain no content originating from OpenStreetMap. + +## 5. Personal data + +The disclosures concern **entities applying for a connection**, and the entity name field +contains, in the vast majority, the business names of commercial-law companies. The statute does not, +however, exclude natural persons conducting a business activity, so we do not claim that personal data +do not occur in the corpus. + +The package **performs no re-identification** and does not enrich the records with data about persons +from any other source. The location resolver works on the name of the locality and street +given in the document, never on the name of the entity. Responsibility for lawful +further use of the output, including for any data protection impact assessment, +rests with the user. + + +## Why the source documents are not included in the repository + +The repository contains a **manifest** of the documents (address, date of download, size, +SHA-256 checksum) and the script `reproducibility/fetch_sources.py`, which downloads them +and verifies them. It does not contain the documents themselves. There are two reasons and both are +practical rather than precautionary. + +**First, we do not settle the legal status of redistribution.** Polish copyright +law excludes official materials from protection, but the disclosures in question +are compiled and published by companies conducting a business activity, discharging +a statutory duty, and whether they fall within that category is not +settled. Independently of copyright, *sui generis* protection may apply +to databases. We are not in a position to settle this +and we do not pretend to be; a team intending to include the documents in +a publication should obtain a legal opinion. + +**Second, the documents are replaced.** The duty requires an update at least +quarterly, so a copy deposited in the repository would, after a few months, +present a state that no longer exists, and would be the more misleading the +more current it looked. + +The consequence has to be stated openly, because it is inconvenient: **byte-for-byte +reproduction ceases to be possible once a publisher replaces or moves a document.** +While release 1.3.0 was being prepared, the link to the disclosure of one of the operators +stopped leading to the file and began returning a page of the service; the download script +recognizes that case and reports it separately instead of saving the page as +a document. That is why the checksums are in the manifest: a mismatch is a signal that +the figures will not be identical with the published ones, not a fault to be ignored. + +To a team preparing a publication we recommend a **deposit of the documents in an archive +with a permanent identifier**, provided a legal opinion permits it. That is the only +way for the link in the paper to lead to what was actually analysed. diff --git a/README.md b/README.md index c81970b..557e0ce 100644 --- a/README.md +++ b/README.md @@ -1,150 +1,153 @@ # gridqueue -[![testy](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml) +[![tests](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml) [![Python 3.10-3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/s-matysik/gridqueue) -[![licencja Apache-2.0](https://img.shields.io/badge/licencja-Apache--2.0-green)](LICENSE.txt) -[![dokumentacja](https://img.shields.io/badge/dokumentacja-gh--pages-blue)](https://s-matysik.github.io/gridqueue/) -[![wydanie](https://img.shields.io/github/v/release/s-matysik/gridqueue)](https://github.com/s-matysik/gridqueue/releases) -[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) +[![licence Apache-2.0](https://img.shields.io/badge/licencja-Apache--2.0-green)](LICENSE.txt) +[![documentation](https://img.shields.io/badge/dokumentacja-gh--pages-blue)](https://s-matysik.github.io/gridqueue/) +[![release](https://img.shields.io/github/v/release/s-matysik/gridqueue)](https://github.com/s-matysik/gridqueue/releases) +[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) -Harmonizator ustawowych ujawnień przyłączeniowych do sieci elektroenergetycznej. +Harmonizer of statutory grid-connection disclosures for the electricity network. -Operatorzy systemów dystrybucyjnych mają obowiązek publikować, kto ubiega się o przyłączenie, -gdzie, o jaką moc i na jakim etapie stoi postępowanie (art. 7 ust. 8l ustawy z dnia -10 kwietnia 1997 r., Prawo energetyczne). W Polsce obowiązek dotyczy około 180 koncesjonowanych -operatorów i **każdy publikuje we własnym formacie**, najczęściej jako PDF. Informacja jest -jawna, ale nie jest przetwarzalna. +Distribution system operators have a duty to publish who is applying for a connection, +where, for what capacity and at what stage the proceeding stands (Article 7(8l) of the Act of +10 April 1997, the Energy Law). In Poland the duty covers approximately 180 licensed +operators and **each one publishes in its own format**, most often as a PDF. The information is +public, but it is not processable. -`gridqueue` zamienia te publikacje na jeden zbiór wierszy o **zmierzonej dokładności**. +`gridqueue` turns those publications into one set of rows with **measured accuracy**. -Stan wydania 0.3.1: **sześć adapterów, 19 220 wierszy panelu, wszystkie 21 pól schematu -wypełnione**. Publikujący: TAURON Dystrybucja 10 955 wierszy, ENERGA-OPERATOR 5 382, +State of release 0.3.1: **six adapters, 19 220 panel rows, all 21 schema fields +populated**. Publishers: TAURON Dystrybucja 10 955 rows, ENERGA-OPERATOR 5 382, Stoen Operator 1 236, PSE 945, National Grid (GB) 694, Boryszew Green Energy&Gas 8. -Dokumentacja: **https://s-matysik.github.io/gridqueue/** +Documentation: **https://s-matysik.github.io/gridqueue/** -## Czym to nie jest +## What it is not -Nie jest to indeks publikacji operatorów ani mapa przeglądowa. Istnieją narzędzia, które -indeksują i linkują do stron operatorów w skali europejskiej. `gridqueue` robi krok niżej: -**parsuje sam dokument ustawowy na wiersze**. W jurysdykcjach o dobrych danych (Wielka Brytania, -USA) dane są już tabelaryczne i ta warstwa jest zbędna, adapter brytyjski w tym pakiecie -sprowadza się do pobrania CSV. Polska jest przypadkiem, w którym nie jest. +It is not an index of operators' publications and not an overview map. There are tools that +index and link to operators' pages at European scale. `gridqueue` goes one step lower: +**it parses the statutory document itself into rows**. In jurisdictions with good data (Great Britain, +the United States) the data is already tabular and this layer is unnecessary; the British adapter in +this package amounts to downloading a CSV. Poland is the case in which it is not. -## Uruchomienie bez instalacji, Google Colab +## Running without installation, Google Colab -[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) +[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) -Notatnik `notebooks/gridqueue_colab.ipynb` wykonuje **pełny przebieg badawczy w przeglądarce**: -pobiera dwie edycje ujawnienia wprost od publikującego, wydobywa wiersze, ocenia jakość, liczy -przepływy w kolejce wraz z precyzją dopasowania i **porównuje odtworzone liczby z opublikowanymi -w artykule, przerywając wykonanie przy rozjeździe**. Poniżej minuty na darmowej maszynie, bez -akceleratora i bez konfiguracji. +The notebook `notebooks/gridqueue_colab.ipynb` performs **a full research run in the browser**: +it downloads two editions of the disclosure directly from the publisher, extracts the rows, assesses +the quality, computes the queue flows together with the linkage precision and **compares the +reproduced figures with those published in the paper, aborting execution on a divergence**. Under a +minute on a free machine, with no accelerator and no configuration. -Notatnik nie odtwarza dokładności wydobycia wobec zbioru odniesienia, bo ten wymaga odczytu przez -człowieka, ani nie rozstrzyga współrzędnych, bo gazeter jest osobnym pobraniem na licencji ODbL. +The notebook does not reproduce the extraction accuracy against the reference set, because that set +requires a human reading, nor does it resolve coordinates, because the gazetteer is a separate +download under the ODbL licence. -## Instalacja +## Installation -Jedno polecenie, bez kompilacji i bez usług zewnętrznych: +One command, with no compilation and no external services: ```bash pip install git+https://github.com/s-matysik/gridqueue@v1.2.1 ``` -Do pracy nad kodem, z ekstrasem testowym: +For work on the code, with the test extra: ```bash git clone https://github.com/s-matysik/gridqueue && cd gridqueue pip install -e ".[test]" ``` -Zależności: `pandas`, `pdfplumber`, `openpyxl`, `requests`, `pyarrow`. Jednostka kanoniczna mocy -to **kW** bez wyjątku; źródła podające megawaty są przeliczane przy wydobyciu, a jednostka źródłowa -zostaje odnotowana w rozszerzeniu. +Dependencies: `pandas`, `pdfplumber`, `openpyxl`, `requests`, `pyarrow`. The canonical unit of +capacity is **kW** without exception; sources reporting megawatts are converted at extraction, and the +source unit is recorded in an extension. -## Szybki przykład +## A quick example ```python from gridqueue import get_adapter, run_quality, validate_frame, audit_column_shift res = get_adapter("pl_tauron").parse("tauron_informacja.pdf") -df = res.frame # ramka w 21-polowym schemacie +df = res.frame # frame in the 21-field schema print(res.report["n_wierszy"]) # 10955 -print(audit_column_shift(df).udzial) # 0.0, udział wierszy z przesuniętymi kolumnami +print(audit_column_shift(df).udzial) # 0.0, share of rows with shifted columns print(run_quality(df).as_dict()["naruszen_lacznie"]) ``` -Wiersz z rozwiązaną lokalizacją: +A row with a resolved location: ```python from gridqueue import resolver_from_osm_json r = resolver_from_osm_json("ulice_warszawa.json") res = r.resolve("WARSZAWA, WINCENTEGO ŚW.") print(res.matched, res.pewnosc) # Świętego Wincentego REVERSED -print(r.resolve("SKB3").powod) # kod_stacji_bez_slownika, nie zgadujemy +print(r.resolve("SKB3").powod) # kod_stacji_bez_slownika, we do not guess ``` ## CLI ```bash -gridqueue schema # specyfikacja 21 pól -gridqueue adapters # deklaracje publikujących +gridqueue schema # specification of the 21 fields +gridqueue adapters # publisher declarations gridqueue parse tauron.pdf --out tauron.parquet --report tauron.json -gridqueue parse --adapter uk_nationalgrid --out uk.parquet # pobiera z katalogu CKAN +gridqueue parse --adapter uk_nationalgrid --out uk.parquet # downloads from the CKAN catalogue gridqueue validate tauron.parquet --out walidacja.json gridqueue export tauron.parquet stoen.parquet --out panel.parquet --only-schema ``` -## Schemat +## Schema -21 pól w trzech grupach odwzorowujących strukturę obowiązku (TOŻSAMOŚĆ / MOC / PROCES), -rdzeń obowiązkowy 5 pól (`id_wniosku`, `lokalizacja_tekst`, `klasa_zasobu`, `moc_pobierana`, -`status_procesu`), reszta opcjonalna i **deklarowana per publikujący**. Jednostki kanoniczne: -moc w kW, daty ISO 8601, współrzędne WGS84. Pola spoza schematu, których dany operator -dostarcza więcej niż wymaga minimum, trafiają do kolumn z przedrostkiem `_` i są jawnie -deklarowane przez adapter (`adapter.declaration()`). +21 fields in three groups reflecting the structure of the duty (IDENTITY / CAPACITY / PROCESS), +a mandatory core of 5 fields (`id_wniosku`, `lokalizacja_tekst`, `klasa_zasobu`, `moc_pobierana`, +`status_procesu`), the rest optional and **declared per publisher**. Canonical units: +capacity in kW, ISO 8601 dates, WGS84 coordinates. Fields beyond the schema, which a given operator +supplies beyond the required minimum, go into columns with the `_` prefix and are declared explicitly +by the adapter (`adapter.declaration()`). -## Metoda wydobycia +## Extraction method -Zamiast wyrażeń regularnych na spłaszczonym tekście, wydobycie z **położenia słów na stronie**: +Instead of regular expressions over flattened text, extraction from the **position of the words on the +page**: -* `ruled`, granice kolumn brane z pionowych krawędzi wektorowych (TAURON, Stoen); - pusta komórka jest odgrodzona linią, więc nie może zlać się z sąsiednią, -* `banded`, granice z pionowych korytarzy bieli (Boryszew; dokument bez siatki), -* wiersze wielolinijkowe scalane kolumna po kolumnie po numerze porządkowym, -* arkusze (PSE) czytane wprost z komórek, wraz z formatowaniem znaku, bez tego indeksy górne - oznaczające przypisy sklejają się z treścią, a w polach liczbowych niszczą wartość. +* `ruled`, column boundaries taken from the vertical vector edges (TAURON, Stoen); + an empty cell is fenced off by a line, so it cannot merge with the neighbouring one, +* `banded`, boundaries from the vertical corridors of whitespace (Boryszew; a document with no grid), +* multi-line rows merged column by column following the ordinal number, +* spreadsheets (PSE) read directly from the cells, together with character formatting; without that, + the superscripts marking footnotes merge into the content, and in numeric fields they destroy the + value. -Wybrano `pdfplumber`, bo daje bezpośredni dostęp do współrzędnych słów i krawędzi wektorowych -z `pdfminer.six`. `camelot` w trybie lattice odtwarza granice kolumn z rastra i wymaga -Ghostscriptu, `tabula` wymaga JVM, w obu granica kolumny jest wynikiem detekcji na obrazie, -a nie liczbą z pliku. +`pdfplumber` was chosen because it gives direct access to the coordinates of the words and to the +vector edges from `pdfminer.six`. `camelot` in lattice mode reconstructs the column boundaries from a +raster image and requires Ghostscript, `tabula` requires a JVM; in both, the column boundary is the +result of detection on an image rather than a number from the file. -## Przykład badawczy +## A research example -Adaptery są specyficzne dla źródła, ale **analiza badawcza już nie**. `examples/research_use_case.py` -liczy czas od złożenia wniosku do wydania warunków przyłączenia, w podziale na klasę zasobu -i publikującego, bez ani jednej gałęzi zależnej od publikującego, wyłącznie na polach wspólnego -schematu: +Adapters are specific to the source, but **the research analysis is not**. `examples/research_use_case.py` +computes the time from the filing of the application to the issuing of the connection conditions, broken +down by resource class and publisher, without a single publisher-dependent branch, using only the fields +of the common schema: ```bash -gridqueue parse --out panel.parquet +gridqueue parse --out panel.parquet python examples/research_use_case.py panel.parquet ``` -Wynik na panelu sześciu publikujących (mediana, dni): przyłączenia **odbiorcze** 40 u TAURONA -i 57 u ENERGI, **fotowoltaika** 105 i 127, **magazyny energii** 119 i 146, **wiatr** 156 i 158. -Przyłączenia odbiorcze rozpatrywane są dwa do czterech razy szybciej niż wytwórcze, a różnica -między publikującymi utrzymuje się w obrębie klasy. Jest to wynik opisowy: rejestr opisuje -postępowania administracyjne, więc nie wolno z niego wnosić o przyczynach różnic ani o jakości -pracy publikującego, portfel wniosków, struktura sieci i praktyka ujawniania różnią się między -operatorami. +The result on the panel of six publishers (median, days): **consumption** connections 40 at TAURON +and 57 at ENERGA, **photovoltaics** 105 and 127, **energy storage** 119 and 146, **wind** 156 and 158. +Consumption connections are processed two to four times faster than generating ones, and the difference +between publishers persists within a class. This is a descriptive result: the register describes +administrative proceedings, so it must not be used to infer the causes of the differences or the quality +of a publisher's work; the portfolio of applications, the structure of the network and the disclosure +practice differ between operators. -## Analiza wzdłużna +## Longitudinal analysis -Rejestr **nie publikuje trwałego identyfikatora wniosku**, więc śledzenie sprawy między -edycjami wymaga klucza treściowego. `compare_editions` buduje go i zwraca przepływy oraz -macierz przejść statusu: +The register **does not publish a persistent application identifier**, so tracking a case between +editions requires a content key. `compare_editions` builds one and returns the flows together with the +status transition matrix: ```python from gridqueue import compare_editions, linkage_audit, get_adapter @@ -155,95 +158,99 @@ d = compare_editions(a, b, "2026-07-31", "2026-08-31") d.as_dict()["udzial_przejsc_w_przod"] # 0.9828 d.as_dict()["migawka_monotoniczna"] # False -linkage_audit(a, b).as_dict() # precyzja dopasowania: 0.9888-0.9963 +linkage_audit(a, b).as_dict() # linkage precision: 0.9888-0.9963 ``` -Dwa wyniki na parze edycji PSE, lipiec-sierpień 2026. **98,28 % przejść statusu biegnie -zgodnie z porządkiem postępowania**, jest to niezależny test dopasowania klucza, bo klucz -dopasowujący losowo nie wytworzyłby tego porządku. I drugi: **rejestr nie jest monotoniczną -migawką**, 13 wierszy pojawia się już w stanie zamkniętym, a 33 wiersze o statusie czynnym -znikają. Różnicy między edycjami nie wolno więc czytać jako samej zmiany stanu kolejki, -i narzędzie zgłasza to flagą, zamiast pozwolić użytkownikowi tego nie zauważyć. +Two results on the pair of PSE editions, July to August 2026. **98,28 % of the status transitions run +in accordance with the order of the proceeding**, which is an independent test of the key's linkage, +because a key matching at random would not have produced that order. And the second: **the register is +not a monotonic snapshot**, 13 rows appear already in a closed state, and 33 rows with an active status +disappear. The difference between editions must therefore not be read as the change in the state of the +queue alone, and the tool reports this with a flag instead of letting the user fail to notice it. -Ponieważ rejestr nie ma trwałego identyfikatora, samo dopasowanie też wymaga sprawdzenia. -`linkage_audit` porównuje każdą parę na dziewięciu polach **wyłączonych z klucza**, klucz nie -wymusza ich zgodności, więc zgodność jest świadectwem niezależnym. Na wszystkich 804 parach -precyzja wynosi **98,88-99,63 %**: 795 par potwierdzonych, 6 niepewnych, 3 fałszywe. +Since the register has no persistent identifier, the linkage itself also requires checking. +`linkage_audit` compares every pair on nine fields **excluded from the key**; the key does not +enforce their agreement, so the agreement is independent evidence. Across all 804 pairs the +precision is **98,88-99,63 %**: 795 pairs confirmed, 6 uncertain, 3 false. ```bash python examples/longitudinal_use_case.py edycja_A.xlsx edycja_B.xlsx 2026-07-31 2026-08-31 ``` -## Odtwarzalność +## Reproducibility -`reproducibility/` zawiera manifest dokumentów źródłowych (adres, data pobrania, SHA-256), wersje -bibliotek oraz skrypty odtwarzające liczby pochodne i figury. Dokumenty nie są redystrybuowane, -bo są wymieniane co kwartał, manifest pozwala sprawdzić, czy pracujemy na tej samej edycji. +`reproducibility/` contains a manifest of the source documents (address, date of download, SHA-256), +the versions of the libraries and the scripts that reproduce the derived figures and the figures +themselves. The documents are not redistributed, because they are replaced every quarter; the manifest +makes it possible to check whether we are working on the same edition. -## Reguły kontroli jakości +## Quality control rules -Osiem reguł; każda zwraca liczbę naruszeń, nie wyjątek, bo naruszenie jest własnością -ujawnienia, a nie błędem narzędzia: monotoniczność dat postępowania, dwuletnia ważność -warunków przyłączenia (art. 7 ust. 8i), dopuszczalność stanu procesu wobec obecnych dat, -spójność jednostek mocy, zakresy wartości, duplikaty identyfikatorów, kompletność rdzenia, -słownik kontrolowany. +Eight rules; each returns a count of violations, not an exception, because a violation is a property of +the disclosure rather than a fault of the tool: monotonicity of the proceeding dates, the two-year +validity of connection conditions (Article 7(8i)), admissibility of the process state against the dates +present, consistency of the capacity units, value ranges, duplicate identifiers, completeness of the +core, controlled vocabulary. -Od wersji 1.0 reguła kompletności rdzenia ocenia **rdzeń właściwy dla encji wiersza**, a rdzeń -mocy jest **alternatywą**, nie konkretnym polem: wniosek wytwórczy deklaruje moc wprowadzaną, -odbiorczy pobieraną, a pkt 2 obowiązku bywa realizowany mocą dostępną albo liczbą wolnych miejsc -przyłączeniowych. W wersji 0.3.x rdzeń wymagał bezwarunkowo mocy pobieranej i stosował wymagania -encji wniosku także do wierszy węzłowych, co zamieniało własność schematu w pozorne naruszenie -ujawnienia, naruszeń tej reguły było 5 390 (28,044 %) wobec **771 (4,011 %)** teraz. +Since version 1.0 the core completeness rule assesses **the core appropriate to the entity of the row**, +and the capacity core is an **alternative** rather than a specific field: a generating application +declares injected capacity, a consuming one consumed capacity, and point 2 of the duty is sometimes +discharged with available capacity and sometimes with a count of free connection slots. In version 0.3.x +the core unconditionally required consumed capacity and applied the requirements of the application +entity to node rows as well, which turned a property of the schema into an apparent violation of the +disclosure; violations of that rule numbered 5 390 (28,044 %) against **771 (4,011 %)** now. -## Testy +## Tests ```bash -python -m pytest -q # 153 passed, 2 skipped (155 zebranych) +python -m pytest -q # 153 passed, 2 skipped (155 collected) ``` -Dwa pominięcia są warunkowe: to testy integracyjne adapterów PSE i ENERGI, wymagające -dokumentów źródłowych, pomijane gdy dokumentów nie ma w drzewie roboczym. Zestaw działa na -Pythonie 3.10-3.13 pod Linuksem, macOS i Windows, sprawdza to CI przy każdym zgłoszeniu zmiany. - -Pisanie testów i pomiar wzrokowy wychwytują **różne klasy defektów** i oba są w pakiecie obecne. -Pięć defektów odwzorowania przeszło przez cały zestaw testów, bo żaden nie rzucał wyjątku - -w tym jeden zmieniający status umowy na przeciwny w 88 wierszach dwóch publikujących. Wykryło je -porównanie wyjścia z wzorcem odczytanym z dokumentu. - -## Ograniczenia - -* Zbiór odniesienia do pomiaru dokładności jest **częściowo jednoanotatorski**. Zgodność - międzyanotatorską zmierzono na podpróbce 35 wierszy odczytanej niezależnie, w zaślepieniu: - zgodność surowa 0,9725, kappa Cohena 0,9690, zero niezgodności percepcyjnych. Wzorce PSE - i ENERGI pozostają jednoanotatorskie. -* Lokalizacja u TAURONA to wewnętrzny kod stacji; operator nie publikuje słownika kodów, - więc rozwiązywacz zwraca brak z powodem `kod_stacji_bez_slownika`. Nie zgaduje. -* **Żaden z publikujących nie podaje współrzędnych.** Pole `wspolrzedne` jest wypełniane - wyprowadzeniem z nazwy miejsca wobec gazetera z geometrią (13 149 nazw w 25 miejscowościach): - 1 225 z 19 220 wierszy panelu. Wartość dowodowa tego pola jest więc inna niż pól przepisanych - z dokumentu i jest tak opisana w wyniku. -* Nazwa ulicy nie wyznacza punktu: 431 z 6 057 nazw warszawskich (7,12%) ma rozłączne składowe - odległe o ponad 2 km. Rejestr podaje ulicę, lecz nie dzielnicę, więc **tej niejednoznaczności - nie da się usunąć z danych opublikowanych**. Każdy wynik niesie liczbę składowych i ich rozrzut, - żeby odbiorca mógł takie wiersze odfiltrować. -* Portale UK Power Networks i Electricity North West zwracają 403 na poziomie wierszy. - Korzystamy wyłącznie z ich publicznych metadanych i tak to opisujemy. Kontroli dostępu - nie obchodzimy; klient przedstawia się uczciwie w nagłówku `User-Agent`. - -## Cytowanie - -`CITATION.cff` w korzeniu repozytorium. Wpis autorski jest zbiorczy i wymaga uzupełnienia listą -autorów osobowych przed zgłoszeniem artykułu. - -## Licencja - -Apache-2.0 dla **kodu**. Dane wejściowe i wyjściowe mają odrębny status, dokumenty urzędowe nie są redystrybuowane, a gazeter geometryczny podlega ODbL z obowiązkiem atrybucji i share-alike. Szczegóły w [`DATA_LICENSE.md`](DATA_LICENSE.md). - -Historia zmian: [`CHANGELOG.md`](CHANGELOG.md)., patrz `LICENSE.txt`. Jest to wybór **roboczy**, podyktowany tym, że czasopismo -docelowe wymaga pliku licencji w repozytorium, a tekst Apache-2.0 nie wymaga wpisywania danych -właściciela praw w samym pliku. Zmiana na inną licencję z listy dopuszczonych (MIT, BSD, GPL) -jest jednym commitem, dopóki repozytorium nie ma zewnętrznych współautorów. - -Licencje danych wejściowych są osobne i niezmienne: gazeter z OpenStreetMap na licencji ODbL 1.0; -publikacje ustawowe operatorów na ich własnych warunkach korzystania, redystrybuowane wyłącznie -tam, gdzie jest to dozwolone. +The two skips are conditional: they are the integration tests of the PSE and ENERGA adapters, which +require the source documents and are skipped when the documents are absent from the working tree. The +suite runs on Python 3.10-3.13 under Linux, macOS and Windows; CI checks this on every change +submitted. + +Writing tests and visual measurement catch **different classes of defect** and both are present in the +package. Five mapping defects passed through the entire test suite, because none of them raised an +exception, among them one that reversed the agreement status in 88 rows of two publishers. They were +detected by comparing the output with the reference set read from the document. + +## Limitations + +* The reference set used to measure accuracy is **partly single-annotator**. Inter-annotator + agreement was measured on a subsample of 35 rows read independently, blind: + raw agreement 0,9725, Cohen's kappa 0,9690, zero perceptual discrepancies. The PSE + and ENERGA reference sets remain single-annotator. +* The location at TAURON is an internal substation code; the operator does not publish a dictionary of + the codes, so the resolver returns missing with the reason `kod_stacji_bez_slownika`. It does not + guess. +* **None of the publishers reports coordinates.** The `wspolrzedne` field is populated by + derivation from the place name against a gazetteer with geometry (13 149 names in 25 localities): + 1 225 of 19 220 panel rows. The evidential value of this field is therefore different from that of + the fields transcribed from the document, and it is described as such in the result. +* A street name does not determine a point: 431 of 6 057 Warsaw names (7,12%) have disjoint components + more than 2 km apart. The register gives the street but not the district, so **this ambiguity cannot + be removed from the published data**. Every result carries the number of components and their spread, + so that the recipient can filter such rows out. +* The UK Power Networks and Electricity North West portals return 403 at row level. + We use only their public metadata and describe it as such. We do not circumvent access + controls; the client identifies itself honestly in the `User-Agent` header. + +## Citation + +`CITATION.cff` at the root of the repository. The author entry is collective and has to be completed +with a list of individual authors before the paper is submitted. + +## Licence + +Apache-2.0 for **the code**. The input and output data have a separate status; official documents are not redistributed, and the geometric gazetteer is subject to ODbL with attribution and share-alike duties. Details in [`DATA_LICENSE.md`](DATA_LICENSE.md). + +Change history: [`CHANGELOG.md`](CHANGELOG.md)., see `LICENSE.txt`. This is a **working** choice, dictated by the fact that the target journal +requires a licence file in the repository, and the text of Apache-2.0 does not require the rights +holder's details to be entered in the file itself. A change to another licence from the permitted list +(MIT, BSD, GPL) is one commit, as long as the repository has no external co-authors. + +The licences of the input data are separate and fixed: the OpenStreetMap gazetteer under the ODbL 1.0 +licence; the operators' statutory publications under their own terms of use, redistributed only +where that is permitted. diff --git a/build/lib/gridqueue/__init__.py b/build/lib/gridqueue/__init__.py deleted file mode 100644 index e65b49a..0000000 --- a/build/lib/gridqueue/__init__.py +++ /dev/null @@ -1,55 +0,0 @@ -"""gridqueue -- harmonizator ustawowych ujawnień przyłączeniowych do sieci -elektroenergetycznej. - -Narzędzie sprowadza publikacje operatorów systemów dystrybucyjnych, wymagane -art. 7 ust. 8l ustawy -- Prawo energetyczne, do jednego przetwarzalnego schematu. -Wartość narzędzia jest sprawdzalna przez inspekcję: albo dokument staje się -zbiorem wierszy o zmierzonej dokładności, albo nie. -""" - -from .schema import ( # noqa: F401 - SCHEMA, SCHEMA_VERSION, FIELDS, CORE_FIELDS, OPTIONAL_FIELDS, GROUPS, - CORE_ALTERNATIVES, CORE_BY_ENTITY, ENTITY_COLUMN, DEFAULT_ENTITY, - META_COLUMNS, ANNOTATION_PREFIX, core_complete_mask, - canonical_date, canonical_power_kw, validate_instance, validate_frame, - empty_frame, schema_table, -) -from .layout import ( # noqa: F401 - ColumnGeometry, detect_ruled_columns, detect_banded_columns, - extract_ruled_page, assign_words_to_columns, merge_continuation_rows, - audit_column_shift, ShiftAudit, -) -from .geoloc import LocationResolver, Resolution, resolver_from_osm_json # noqa: F401 -from .analysis import ( # noqa: F401 - PRZEDROSTKI_STACJI, KMResult, assign_to_nodes, kaplan_meier, node_loading, - normalizuj_nazwe, processing_time, station_node_map, -) -from .quality import RULES, run_quality, QualityReport # noqa: F401 -from .longitudinal import ( # noqa: F401 - RECALL_FIELDS, NODE_KEY_FIELDS, LinkageRecall, linkage_recall, - DEFAULT_KEY_FIELDS, STATUS_ORDER, TERMINAL_NEGATIVE, - surrogate_key, EditionDelta, compare_editions, - HELD_OUT_FIELDS, LinkageAudit, linkage_audit, -) -from .registry import REGISTRY, get_adapter, detect_publisher, declarations # noqa: F401 - -__version__ = "1.5.2" -__all__ = [ - "NODE_KEY_FIELDS", - "RECALL_FIELDS", "LinkageRecall", "linkage_recall", - "PRZEDROSTKI_STACJI", "KMResult", "assign_to_nodes", "kaplan_meier", - "node_loading", "normalizuj_nazwe", "processing_time", "station_node_map", - "SCHEMA", "SCHEMA_VERSION", "FIELDS", "CORE_FIELDS", "OPTIONAL_FIELDS", "GROUPS", - "CORE_ALTERNATIVES", "CORE_BY_ENTITY", "ENTITY_COLUMN", "DEFAULT_ENTITY", - "META_COLUMNS", "ANNOTATION_PREFIX", "core_complete_mask", - "canonical_date", "canonical_power_kw", "validate_instance", "validate_frame", - "empty_frame", "schema_table", "ColumnGeometry", "detect_ruled_columns", - "detect_banded_columns", "extract_ruled_page", "assign_words_to_columns", - "merge_continuation_rows", "audit_column_shift", "ShiftAudit", - "LocationResolver", "Resolution", "resolver_from_osm_json", - "RULES", "run_quality", "QualityReport", - "DEFAULT_KEY_FIELDS", "STATUS_ORDER", "TERMINAL_NEGATIVE", - "surrogate_key", "EditionDelta", "compare_editions", - "HELD_OUT_FIELDS", "LinkageAudit", "linkage_audit", - "REGISTRY", "get_adapter", "detect_publisher", "declarations", "__version__", -] diff --git a/build/lib/gridqueue/adapters/__init__.py b/build/lib/gridqueue/adapters/__init__.py deleted file mode 100644 index 3a0a71b..0000000 --- a/build/lib/gridqueue/adapters/__init__.py +++ /dev/null @@ -1,5 +0,0 @@ -from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status # noqa: F401 -from .pl_tauron import TauronAdapter # noqa: F401 -from .pl_stoen import StoenAdapter # noqa: F401 -from .pl_boryszew import BoryszewAdapter # noqa: F401 -from .uk_nationalgrid import NationalGridAdapter # noqa: F401 diff --git a/build/lib/gridqueue/adapters/_ptpiree.py b/build/lib/gridqueue/adapters/_ptpiree.py deleted file mode 100644 index bc39486..0000000 --- a/build/lib/gridqueue/adapters/_ptpiree.py +++ /dev/null @@ -1,333 +0,0 @@ -"""Wspólny szablon PTPiREE/PSE dla ujawnień z art. 7 ust. 8l pkt 1), 3) i 4). - -Odkrycie, które to uzasadnia: arkusz PSE ``Informacje_publikowane_zgodnie_z_Art_7_ -ust_8l_ustawy_PE`` ma zakładkę "Listy rozwijane", a w niej listę wartości pola -"OSD/OSP": Energa-Operator S.A., ENEA Operator Sp. z o.o., TAURON Dystrybucja S.A., -PGE Dystrybucja S.A., Stoen Operator Sp. z o.o., PSE S.A. Szablon nie jest więc -formularzem jednego przedsiębiorstwa, tylko UZGODNIONYM WZORCEM BRANŻOWYM dla -sześciu największych operatorów. Publikacja Energa-Operatora (PDF) realizuje ten -sam wzorzec, co arkusz PSE (XLSX) -- różni się nośnikiem i dwiema kolumnami -brzegowymi, nie treścią. - -Kolumny logiczne poniżej są tym wzorcem. Adapter konkretnego publikującego ma -jedno zadanie: powiedzieć, która kolumna FIZYCZNA jego dokumentu odpowiada której -kolumnie logicznej. Odwzorowanie na 21-polowy schemat jest wspólne, więc różnica -między publikującymi zostaje tam, gdzie jest naprawdę -- w układzie dokumentu. - -Zmierzone układy fizyczne (odczytane z nagłówków, nie założone): - - PSE (XLSX, 27 kolumn): id_obiektu, nazwa_obiektu, osd_osp, podmiot, ... - ENERGA (PDF, 28 kolumn): lp, id_obiektu, osd_osp, podmiot, ..., uwagi - -Od kolumny "osd_osp" obie numeracje się pokrywają: PSE ma z przodu dwie kolumny -tożsamości (ID + nazwa obiektu), Energa jedną (ID) poprzedzoną liczbą porządkową, -a na końcu dokłada kolumnę "UWAGI". -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..schema import canonical_date, canonical_power_kw -from .base import harmonize_klasa, harmonize_status - - -#: Rozdzielacze wielu miejsc przyłączenia w jednej komórce mocy. -_ROZDZ_MOC = re.compile(r"[\n\r;]+") - - -def _rozbij_moc(value: Any) -> list[str]: - """Rozbij komórkę mocy na składowe dla wielu miejsc przyłączenia. - - Liczba zwykła zwracana jest jako jedna składowa. Łańcuch rozdzielany jest po - złamaniu linii i średniku, i NIE po spacji, bo spacja jest u publikujących - separatorem tysięcznym. - """ - if value is None: - return [] - if isinstance(value, (int, float)): - return [] if (isinstance(value, float) and value != value) else [str(value)] - czesci = [c.strip() for c in _ROZDZ_MOC.split(str(value))] - return [c for c in czesci if c and c not in {"-", "--", "---"}] - -__all__ = ["LOGICAL", "PSE_XLSX_LAYOUT", "ENERGA_PDF_LAYOUT", "to_schema", "stan_na"] - -#: kolumny logiczne wzorca PTPiREE/PSE -LOGICAL: tuple[str, ...] = ( - "lp", - "id_obiektu", - "nazwa_obiektu", - "osd_osp", - "podmiot", - "lokalizacja", - "poziom_napiecia", - "wiele_miejsc", - "rodzaj", - "moc_wprowadzana", - "moc_pobierana", - "mz_pv", - "mz_fw", - "mz_mee_rozladowania", - "mz_mee_ladowania", - "mz_odb", - "mz_inne", - "status", - "data_zlozenia", - "data_zaliczki", - "data_warunkow", - "data_odmowy", - "uzasadnienie_odmowy", - "data_utraty_waznosci", - "data_umowy", - "data_energizacji", - "data_rozwiazania_umowy", - "data_wygasniecia_umowy", - "uwagi", -) - -#: fizyczny indeks kolumny -> kolumna logiczna. Arkusz PSE, 27 kolumn. -PSE_XLSX_LAYOUT: dict[int, str] = { - 0: "id_obiektu", 1: "nazwa_obiektu", 2: "osd_osp", 3: "podmiot", - 4: "lokalizacja", 5: "poziom_napiecia", 6: "wiele_miejsc", 7: "rodzaj", - 8: "moc_wprowadzana", 9: "moc_pobierana", - 10: "mz_pv", 11: "mz_fw", 12: "mz_mee_rozladowania", 13: "mz_mee_ladowania", - 14: "mz_odb", 15: "mz_inne", - 16: "status", 17: "data_zlozenia", 18: "data_zaliczki", 19: "data_warunkow", - 20: "data_odmowy", 21: "uzasadnienie_odmowy", 22: "data_utraty_waznosci", - 23: "data_umowy", 24: "data_energizacji", 25: "data_rozwiazania_umowy", - 26: "data_wygasniecia_umowy", -} - -#: fizyczny indeks kolumny -> kolumna logiczna. PDF Energa-Operatora, 28 kolumn. -ENERGA_PDF_LAYOUT: dict[int, str] = { - 0: "lp", 1: "id_obiektu", 2: "osd_osp", 3: "podmiot", - 4: "lokalizacja", 5: "poziom_napiecia", 6: "wiele_miejsc", 7: "rodzaj", - 8: "moc_wprowadzana", 9: "moc_pobierana", - 10: "mz_pv", 11: "mz_fw", 12: "mz_mee_rozladowania", 13: "mz_mee_ladowania", - 14: "mz_odb", 15: "mz_inne", - 16: "status", 17: "data_zlozenia", 18: "data_zaliczki", 19: "data_warunkow", - 20: "data_odmowy", 21: "uzasadnienie_odmowy", 22: "data_utraty_waznosci", - 23: "data_umowy", 24: "data_energizacji", 25: "data_rozwiazania_umowy", - 26: "data_wygasniecia_umowy", 27: "uwagi", -} - -#: pola opcjonalne schematu, które wzorzec wypełnia u KAŻDEGO publikującego -DECLARED_FIELDS: tuple[str, ...] = ( - "id_wniosku", "lokalizacja_tekst", "poziom_napiecia", "klasa_zasobu", - "moc_wprowadzana", "moc_pobierana", "status_procesu", "data_wniosku", - "data_warunkow", "data_odmowy", "powod_odmowy", "data_umowy", - "data_energizacji", "data_publikacji", -) - -#: rozszerzenia poza 21-polowym schematem, wspólne dla wzorca -DECLARED_EXTENSIONS: dict[str, str] = { - "_podmiot": "nazwa podmiotu ubiegającego się o przyłączenie", - "_osd_osp": "operator wskazany w dokumencie (pole wzorca)", - "_nazwa_obiektu": "nazwa własna obiektu (tylko PSE)", - "_wiele_miejsc": "czy wniosek dotyczy wielu miejsc przyłączenia / poziomów napięć", - "_rodzaj_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status etapu projektu tak, jak w dokumencie", - "_data_zaliczki": "data wpłaty zaliczki", - "_data_utraty_waznosci": "data utraty ważności / rezygnacji z warunków", - "_data_rozwiazania_umowy": "data rozwiązania/wypowiedzenia/odstąpienia od umowy", - "_data_wygasniecia_umowy": "data wygaśnięcia umowy z mocy prawa", - "_mz_pv": "moc zainstalowana PV [kW]", - "_mz_fw": "moc zainstalowana FW [kW]", - "_mz_mee_rozladowania": "moc zainstalowana magazynu -- rozładowanie [kW]", - "_mz_mee_ladowania": "moc zainstalowana magazynu -- ładowanie [kW]", - "_mz_odb": "moc zainstalowana odbioru [kW]", - "_mz_inne": "moc zainstalowana pozostałych źródeł [kW]", - "_uwagi": "kolumna UWAGI (tylko Energa)", - "_lp_dokumentu": "liczba porządkowa w dokumencie źródłowym", - "_encja": "WNIOSEK albo WEZEL -- którą encję obowiązku realizuje wiersz", -} - -_NULLISH = {"", "-", "--", "---", "nan", "none", "brak", "nie dotyczy", "n/d"} - - -def _blank(v: Any) -> bool: - """Czy wartość jest pusta. ``nan`` jest prawdziwe, więc ``if v`` nie wystarcza.""" - if v is None: - return True - if isinstance(v, float) and v != v: - return True - return isinstance(v, str) and not v.strip() - - -def _clean(v: Any) -> Optional[str]: - if v is None: - return None - if isinstance(v, float) and v != v: - return None - s = re.sub(r"\s+", " ", str(v)).strip() - return None if s.lower() in _NULLISH else s - - -def _volt(v: Any) -> Optional[str]: - """Poziom napięcia w postaci kanonicznej " kV". - - Wzorzec dopuszcza WIELOKROTNOŚĆ ("110; 220; 400") -- tak stanowi lista - rozwijana arkusza PSE. Zapisujemy pełną treść, bo wybranie jednej wartości - byłoby utratą danej; konsekwencją jest to, że detektor sprzeczności typu - (``looks_like_voltage``) oznacza takie wiersze -- i tak ma być, bo miara - ma pozostać PORÓWNYWALNA z wcześniejszymi pomiarami, a nie wygodna. - - Wartości KLASOWE ("SN", "nn", "WN") nie są liczbami kilowoltów i nie wolno - dopisywać im jednostki: "SN kV" nie znaczy nic. Panel czterech dotychczasowych - publikujących zapisuje je jako samo "SN", więc trzymamy tę samą konwencję -- - inaczej ten sam poziom napięcia miałby dwie różne postaci w jednym panelu - i pole przestałoby być porównywalne między publikującymi. - """ - s = _clean(v) - if s is None: - return None - if re.fullmatch(r"(?:nn|sn|wn|nN|SN|WN)", s.strip(), re.IGNORECASE): - return s.strip().upper() if s.strip().lower() != "nn" else "nn" - s = s.replace("\n", " ") - s = re.sub(r"\s*kV\s*", "", s, flags=re.IGNORECASE).strip() - s = re.sub(r"\s*;\s*", "; ", s) - s = re.sub(r"\s+", " ", s).strip(" ;") - if not s: - return None - # liczby całkowite bez ".0" po przejściu przez pandas/openpyxl - s = re.sub(r"\b(\d+)\.0\b", r"\1", s) - return f"{s} kV" - - -def stan_na(text: str) -> Optional[str]: - """Data, na którą publikujący sporządził ujawnienie. - - Postać bywa różna nawet u jednego publikującego: "Stan na 30.06.2026 r." - w zestawieniu wniosków i "(STAN NA DZIEŃ 31.08.2026 ROKU)" wersalikami na - stronie tytułowej ujawnienia węzłowego -- stąd dopasowanie bez rozróżniania - wielkości liter. - """ - m = re.search(r"stan\s+na\s+(?:dzie[nń]\s+)?(\d{1,2}\.\d{1,2}\.\d{4})", - text or "", re.IGNORECASE) - return canonical_date(m.group(1)) if m else None - - -def to_schema(raw, *, publisher_key: str, data_publikacji: Optional[str]): - """Odwzoruj ramkę w kolumnach logicznych wzorca na 21-polowy schemat. - - ``raw`` ma kolumny z ``LOGICAL`` (brakujące mogą nie występować). Jednostka - mocy we wzorcu to MW -- sprowadzamy do kanonicznych kW. - """ - import pandas as pd - - def col(name: str): - if name in raw.columns: - return raw[name].map(_clean) - return pd.Series([None] * len(raw), index=raw.index, dtype="object") - - def mw(name: str): - """Moc z kolumny SUROWEJ, z obsługą wielu miejsc przyłączenia. - - Pułapka, która zawyżyła jeden wiersz o trzy rzędy wielkości: gdy wniosek - dotyczy kilku miejsc przyłączenia (kolumna "Wiele miejsc przyłączenia" - = TAK), publikujący wpisuje do jednej komórki kilka wartości rozdzielonych - ZŁAMANIEM LINII, czasem dodatkowo średnikiem. ``_clean`` zamieniał złamanie - linii na spację, a ``canonical_power_kw`` traktuje spację jako separator - tysięczny, więc "129⏎240" (129 MW + 240 MW) stawało się 129 240 MW. - W edycji, w której publikujący dopisał średniki, ta sama komórka nie - konwertowała się wcale i pole zostawało puste, czyli ten sam defekt - dawał raz absurd, raz milczący brak. - - Zwracamy SUMĘ składowych, bo pole schematu opisuje moc wniosku, a wniosek - jest jeden. Składowe zachowujemy w rozszerzeniu, żeby nie zgubić podziału - na miejsca przyłączenia. - """ - if name not in raw.columns: - return (pd.Series([None] * len(raw), index=raw.index, dtype="object"), - pd.Series([None] * len(raw), index=raw.index, dtype="object")) - sumy, skladowe = [], [] - for v in raw[name]: - czesci = _rozbij_moc(v) - vals = [canonical_power_kw(c, "MW") for c in czesci] - vals = [x for x in vals if x is not None] - if not vals: - sumy.append(None) - skladowe.append(None) - elif len(vals) == 1: - sumy.append(vals[0]) - skladowe.append(None) - else: - sumy.append(float(sum(vals))) - skladowe.append("; ".join(f"{x / 1000.0:g}" for x in vals)) - return (pd.Series(sumy, index=raw.index, dtype="object"), - pd.Series(skladowe, index=raw.index, dtype="object")) - - def dcol(name: str): - """Data z kolumny SUROWEJ, bez przejścia przez ``_clean``. - - Pułapka, która kosztowała wszystkie daty PSE: nośnikiem PSE jest XLSX, - a openpyxl zwraca komórki daty jako ``Timestamp``. ``_clean`` robi na - wartości ``str()``, więc Timestamp zamieniał się w "2023-08-07 00:00:00", - a ``canonical_date`` ma wzorce ZAKOTWICZONE i takiego łańcucha nie - dopasowuje -- zwracał None. Efekt: pola ``data_*`` pustoszały dla całego - publikującego, a reguły jakości R1 i R2 (monotoniczność dat, dwuletnia - ważność warunków) nie miały na czym pracować i pokazywały zero naruszeń. - ``canonical_date`` sam obsługuje ``datetime``/``date``, więc wystarczy - podać mu wartość nietkniętą. - """ - if name not in raw.columns: - return pd.Series([None] * len(raw), index=raw.index, dtype="object") - return raw[name].map(lambda v: None if _blank(v) else canonical_date(v)) - - out = pd.DataFrame(index=raw.index) - ident = col("id_obiektu") - lp = col("lp") - # Uwaga na pułapkę: ``Series.map`` zamienia zwrócone ``None`` na ``nan``, - # a ``nan`` jest w Pythonie PRAWDZIWE. Test pustości musi być jawny, inaczej - # zastępnik identyfikatora nigdy się nie uruchomi, a 866 z 876 wierszy PSE - # (te z "-" w polu ID Obiektu) zostaje bez identyfikatora. - out["id_wniosku"] = [ - i if not _blank(i) - else f"{publisher_key}:poz:{(str(l).rstrip('.') if not _blank(l) else str(k + 1))}" - for k, (i, l) in enumerate(zip(ident, lp)) - ] - out["lokalizacja_tekst"] = col("lokalizacja") - out["poziom_napiecia"] = col("poziom_napiecia").map(_volt) - out["klasa_zasobu"] = col("rodzaj").map(harmonize_klasa) - out["moc_wprowadzana"], _skl_wpr = mw("moc_wprowadzana") - out["moc_pobierana"], _skl_pob = mw("moc_pobierana") - out["status_procesu"] = col("status").map(harmonize_status) - out["data_wniosku"] = dcol("data_zlozenia") - out["data_warunkow"] = dcol("data_warunkow") - out["data_odmowy"] = dcol("data_odmowy") - out["powod_odmowy"] = col("uzasadnienie_odmowy") - out["data_umowy"] = dcol("data_umowy") - # Energa zapisuje planowaną energizację NIERÓWNOŚCIĄ ("po 30.06.2026"), a nie - # datą. ``canonical_date`` jest zakotwiczony na początku łańcucha, więc słusznie - # zwraca None -- zapisanie 2026-06-30 gubiłoby słowo "po" i zamieniało termin - # dolny na termin dokładny. Żeby jednak nie utracić danej, surowy tekst idzie - # do rozszerzenia, a pole schematu zostaje puste. - _energ = col("data_energizacji") - out["data_energizacji"] = dcol("data_energizacji") - out["_energizacja_tekst"] = [ - t if (not _blank(t) and canonical_date(t) is None) else None for t in _energ - ] - out["data_publikacji"] = data_publikacji - - out["_encja"] = "WNIOSEK" - out["_podmiot"] = col("podmiot") - out["_osd_osp"] = col("osd_osp") - out["_nazwa_obiektu"] = col("nazwa_obiektu") - out["_wiele_miejsc"] = col("wiele_miejsc") - out["_rodzaj_raw"] = col("rodzaj") - out["_status_raw"] = col("status") - out["_data_zaliczki"] = dcol("data_zaliczki") - out["_data_utraty_waznosci"] = dcol("data_utraty_waznosci") - out["_data_rozwiazania_umowy"] = dcol("data_rozwiazania_umowy") - out["_data_wygasniecia_umowy"] = dcol("data_wygasniecia_umowy") - for src, dst in (("mz_pv", "_mz_pv"), ("mz_fw", "_mz_fw"), - ("mz_mee_rozladowania", "_mz_mee_rozladowania"), - ("mz_mee_ladowania", "_mz_mee_ladowania"), - ("mz_odb", "_mz_odb"), ("mz_inne", "_mz_inne")): - out[dst], _ = mw(src) - out["_uwagi"] = col("uwagi") - out["_moc_wprowadzana_skladowe_mw"] = _skl_wpr - out["_moc_pobierana_skladowe_mw"] = _skl_pob - out["_lp_dokumentu"] = lp - return out diff --git a/build/lib/gridqueue/adapters/base.py b/build/lib/gridqueue/adapters/base.py deleted file mode 100644 index 3ee65ec..0000000 --- a/build/lib/gridqueue/adapters/base.py +++ /dev/null @@ -1,156 +0,0 @@ -"""Wspólny interfejs adapterów publikujących. - -Adapter jest jedynym miejscem, w którym wolno wiedzieć cokolwiek o układzie -konkretnego dokumentu. Na zewnątrz każdy adapter wygląda tak samo: - - adapter.parse(source) -> ParseResult(frame, report) - -``frame`` jest w schemacie (moduł ``schema``), ``report`` jest raportem jakości -wydobycia -- liczbami, nie wyjątkami. Adapter DEKLARUJE, które pola opcjonalne -wypełnia i jakie rozszerzenia poza 21-polowym schematem wnosi; deklaracja jest -częścią kontraktu, bo pokrycie pól jest tu wynikiem pomiaru, a nie założeniem. -""" - -from __future__ import annotations - -import re -import unicodedata -from dataclasses import dataclass, field -from typing import Any, Optional - -from ..schema import FIELDS, META_COLUMNS, canonical_date, canonical_power_kw - -__all__ = ["Adapter", "ParseResult", "harmonize_klasa", "harmonize_status", "norm_text"] - - -@dataclass -class ParseResult: - frame: Any # pandas.DataFrame w schemacie - report: dict[str, Any] = field(default_factory=dict) - - -class Adapter: - """Klasa bazowa adaptera.""" - - #: identyfikator publikującego - publisher: str = "" - #: jurysdykcja (kod kraju) - jurisdiction: str = "" - #: pola schematu, które ten publikujący ujawnia (deklaracja, weryfikowana pomiarem) - declared_fields: tuple[str, ...] = () - #: rozszerzenia poza 21-polowym schematem -> opis; w ramce z przedrostkiem "_" - declared_extensions: dict[str, str] = {} - #: wzorce nazw plików / treści, po których wykrywamy publikującego - detect_patterns: tuple[str, ...] = () - - def parse(self, source) -> ParseResult: # pragma: no cover - interfejs - raise NotImplementedError - - # -- pomoc wspólna ----------------------------------------------------- - - def blank_frame(self, n: int): - import pandas as pd - - return pd.DataFrame( - {c: pd.Series([None] * n, dtype="object") for c in FIELDS + META_COLUMNS} - ) - - def finalize(self, df, *, document: str = ""): - """Domknij ramkę: kolejność kolumn, metadane, typy kanoniczne.""" - import pandas as pd - - for c in FIELDS + META_COLUMNS: - if c not in df.columns: - df[c] = None - df["publikujacy"] = self.publisher - df["jurysdykcja"] = self.jurisdiction - if document: - df["dokument_zrodlowy"] = document - extra = [c for c in df.columns if c not in FIELDS + META_COLUMNS] - df = df[list(FIELDS) + list(META_COLUMNS) + sorted(extra)] - return df.reset_index(drop=True) - - def declaration(self) -> dict[str, Any]: - return { - "publikujacy": self.publisher, - "jurysdykcja": self.jurisdiction, - "pola_deklarowane": list(self.declared_fields), - "rozszerzenia": dict(self.declared_extensions), - } - - -# -------------------------------------------------------------------------- -# harmonizacja słowników kontrolowanych -# -------------------------------------------------------------------------- - - -_STROKE = str.maketrans({"ł": "l", "Ł": "L", "đ": "d", "Đ": "D", "ø": "o", "Ø": "O"}) - - -def norm_text(s: Any) -> str: - if s is None: - return "" - s = str(s).replace("\n", " ") - # znaki z kreska nie rozkladaja sie przez NFKD (l/L, d/D, o/O) -- mapujemy wprost - s = s.translate(_STROKE) - s = unicodedata.normalize("NFKD", s) - s = "".join(ch for ch in s if not unicodedata.combining(ch)) - return re.sub(r"\s+", " ", s).strip().lower() - - -#: mapowanie oznaczeń rodzaju instalacji na słownik kontrolowany. -#: Skróty TAURONA pochodzą z legendy na ostatniej stronie jego dokumentu. -_KLASA_MAP: tuple[tuple[str, str], ...] = ( - (r"^pv$|fotowolta|^solar$", "PV"), - (r"^fw$|^mfw$|farma wiatrow|^wind$", "FW"), - (r"^ew$|elektrownia wodn|^hydro$", "EW"), - (r"biogaz|biomas|^jbm$", "BIOGAZ"), - # legenda TAURONA (ostatnia strona dokumentu): BG blok gazowy, BGP blok - # gazowo-parowy, SG silnik gazowy -- to sa jednostki GAZOWE, nie biogazowe - (r"^bg$|^bgp$|^sg$|blok gazow|silnik gazow", "GAZ"), - (r"^jw$|jednostka weglow", "WEGIEL"), - (r"^mee|magazyn energii|^bess$|^battery", "BESS"), - (r"^odb$|instalacja odbiorcz|^demand$|odbiorc", "ODB"), - (r"^mix$", "MIX"), - (r"^osd|^siec$|^network$|stacja transformator|siec dystrybucyjn|^sieci$", "SIEC"), - (r"^inne zrodla$|^inne$|^other$|^ej$|^esp$|^ogw$|^js$|^mfw$", "INNE"), - (r"wytworcz", "INNE"), -) - -_STATUS_MAP: tuple[tuple[str, str], ...] = ( - (r"wniosek niekompletny|uzupelnien", "WNIOSEK_NIEKOMPLETNY"), - (r"w trakcie analiz|w trakcie rozpatr|wniosek kompletny", "W_TRAKCIE_ANALIZY"), - (r"wniosek wycofan|wycofan", "WNIOSEK_WYCOFANY"), - (r"utracil\w* waznosc|utrata waznosci|wygasl", "WARUNKI_WYGASLE"), - (r"odmow|refus", "ODMOWA"), - # "rozwiazan" bez dookreslenia: lista rozwijana wspolnego szablonu PTPiREE/PSE - # deklaruje status "UMOWA O PRZYŁĄCZENIE rozwiązana", ktorego nie lapaly ani - # "umowa rozwiazan" (brak przyleglosci), ani "rozwiazanie umowy". Bez tej - # poprawki rozwiazana umowa spadala na regule "umowa o przylaczenie" i byla - # raportowana jako UMOWA_OBOWIAZUJACA -- czyli status odwrotny do prawdziwego. - (r"rozwiazan", "UMOWA_ROZWIAZANA"), - (r"obiekt przylaczony|recently connected|^connected$|przylaczon", "PRZYLACZONY"), - (r"umowa o przylaczenie|umowa obowiazuj|accepted not yet connected|^accepted", "UMOWA_OBOWIAZUJACA"), - (r"warunki przylaczenia|warunki wydane|warunki okreslone", "WARUNKI_WYDANE"), - (r"wniosek", "WNIOSEK_ZLOZONY"), -) - - -def harmonize_klasa(raw: Any) -> str: - t = norm_text(raw) - if not t: - return "NIEOKRESLONA" - for rx, out in _KLASA_MAP: - if re.search(rx, t): - return out - return "INNE" - - -def harmonize_status(raw: Any) -> str: - t = norm_text(raw) - if not t: - return "NIEOKRESLONY" - for rx, out in _STATUS_MAP: - if re.search(rx, t): - return out - return "NIEOKRESLONY" diff --git a/build/lib/gridqueue/adapters/es_edistribucion.py b/build/lib/gridqueue/adapters/es_edistribucion.py deleted file mode 100644 index fe59935..0000000 --- a/build/lib/gridqueue/adapters/es_edistribucion.py +++ /dev/null @@ -1,239 +0,0 @@ -"""Adapter: e-Distribución Redes Digitales (ES), zdolność przyłączeniowa węzłów. - -Dlaczego to źródło jest dla pakietu ważniejsze niż kolejny plik tabelaryczny --------------------------------------------------------------------------- -Manuskrypt wskazywał jako najmocniejszy brakujący test **drugą jurysdykcję -publikującą dokumenty przeznaczone do druku**: dotąd oba źródła zagraniczne -wydawały dane już tabelaryczne, więc przenoszalność wykazano na przypadku -łatwiejszym niż polski. To źródło ten brak zamyka. Publikujący wydaje **PDF -miesięczny**, w serii obejmującej lata 2023-2025, na podstawie art. 33 ust. 9 -ustawy 24/2013, art. 5 ust. 4 dekretu 1183/2020 oraz art. 12 okólnika 1/2021 -regulatora CNMC, konstrukcja prawna jest więc taka sama jak polska: obowiązek -ustawowy, stała częstość, format pozostawiony publikującemu. - -Układ strony niesie linie wektorowe tabeli, więc wydobycie opiera się na nich, -a nie na odstępach między słowami. - -Semantyka kolumn ustalona arytmetyką, nie nagłówkiem ----------------------------------------------------- -Nagłówek ma komórki scalone w dwóch poziomach i sugeruje, że kolumny „Con -permiso de AyC" oraz „En trámite con capacidad" należą do grupy mocy przyjętej -i nierozstrzygniętej. **Jest to mylące.** Rozstrzyga arytmetyka dokumentu: - -* jedenaście podkolumn, dziewięć pozycji stacji oraz te dwie, **sumuje się do - mocy ZAJĘTEJ**, dokładnie, w 1838 z 1838 wierszy, w obu sprawdzonych wydaniach; -* rozbicie technologiczne sumuje się do mocy **przyjętej i nierozstrzygniętej** - we wszystkich wierszach o niezerowej wartości. - -Obie grupy są więc SKŁADNIKAMI mocy zajętej, a nie jej alternatywnymi -rozbiciami: część węzłów ma wypełnione tylko pozycje, część tylko dwie -pozostałe, a część obie, i dopiero suma wszystkich jedenastu zamyka się do -wartości łącznej. - -Ma to wartość wykraczającą poza odwzorowanie pól. Dla tego publikującego **nie -istnieje zbiór odniesienia odczytany niezależnie od parsera**, więc dokładności -wydobycia nie da się zmierzyć w sposób, w jaki zmierzono ją dla publikujących -polskich. Domknięcie sumy jest tu zastępczym, słabszym, ale sprawdzalnym -świadectwem: aby suma jedenastu komórek zgadzała się z dwunastą, wszystkie -dwanaście musi być odczytane poprawnie. Na dwóch wydaniach daje to 3676 -niezależnych sprawdzeń, wszystkie domknięte. Jest to świadectwo spójności -odczytu, NIE pomiar dokładności wobec wzorca, i tak należy je czytać. - -Jednostki ---------- -Publikujący podaje moce w **MW mocy czynnej**, więc przeliczenie na kanoniczne -kW jest zwykłą zmianą rzędu wielkości, bez założeń. Różni to to źródło od -portugalskiego, które podaje moc pozorną w MVA i dlatego pola mocy nie wypełnia. - -Źródło podaje też **współrzędne geograficzne każdej podstacji**, czego nie robi -żaden publikujący polski. -""" - -from __future__ import annotations - -import re -from pathlib import Path - -from .base import Adapter, ParseResult - -PUBLISHER = "e-Distribución Redes Digitales S.L.U." -JURISDICTION = "ES" - -#: Indeksy kolumn w wydobytej tabeli. Ustalone na wydaniu z sierpnia 2025 -#: i zweryfikowane sumami; patrz nagłówek modułu. -K_WSPOLNOTA, K_PROWINCJA, K_GMINA, K_PODSTACJA = 0, 1, 2, 3 -K_SZEROKOSC, K_DLUGOSC, K_NAPIECIE = 4, 5, 6 -K_DOSTEPNA, K_ZAJETA_TOTAL = 7, 8 -K_POZYCJE = tuple(range(9, 18)) # rozbicie mocy zajętej po pozycjach stacji -K_ZAJETA_Z_POZWOLENIEM, K_ZAJETA_W_TOKU = 18, 19 -K_PRZYJETA_TOTAL = 20 # przyjęta i nierozstrzygnięta -K_TECHNOLOGIE = (21, 22, 23, 24, 25) -K_SCC, K_WEZEL_PRZESYLOWY, K_KOMENTARZ = 26, 27, 28 -SZEROKOSC_WIERSZA = 29 - -_WSPOLNOTA = re.compile(r"^\d{2}\s*-\s*") - - -def _liczba(v) -> float | None: - """Liczba w zapisie hiszpańskim: przecinek dziesiętny, kropka tysięcy.""" - if v is None: - return None - s = str(v).strip().replace("\xa0", "").replace(" ", "") - if s in {"", "-", "--"}: - return None - s = s.replace(".", "").replace(",", ".") - try: - return float(s) - except ValueError: - return None - - -def _mw_na_kw(v) -> float | None: - """MW mocy czynnej -> kW mocy czynnej. Zmiana rzędu, nie wielkości fizycznej.""" - x = _liczba(v) - return None if x is None else x * 1000.0 - - -def _data_z_nazwy(nazwa: str) -> str | None: - """'EDRD_Capacidad_de_Acceso_2025_08_01.pdf' -> '2025-08-01'. - - Data brana jest z nazwy pliku, a nie ze strony tytułowej, bo nazwa jest - maszynowa i rozstrzygalna, a strona tytułowa podaje ją słownie po hiszpańsku. - """ - m = re.search(r"(\d{4})[_-](\d{2})[_-](\d{2})", nazwa) - return f"{m.group(1)}-{m.group(2)}-{m.group(3)}" if m else None - - -def suma_skladnikow_mocy_zajetej(wiersze) -> "tuple[int, int]": - """Ile wierszy domyka tożsamość arytmetyczną dokumentu. - - Jedenaście podkolumn mocy zajętej (dziewięć pozycji stacji plus „z - pozwoleniem" i „w toku") sumuje się do wartości łącznej. Funkcja zwraca - parę (domkniętych, wszystkich). - - Po co to jest: dla tego publikującego nie ma zbioru odniesienia odczytanego - niezależnie od parsera, więc dokładności wydobycia nie da się zmierzyć wobec - wzorca. Domknięcie sumy jest zastępczym świadectwem spójności odczytu - - słabszym niż wzorzec, ale sprawdzalnym na każdym wydaniu, bo wymaga - poprawnego odczytania wszystkich dwunastu komórek bloku. - """ - domkniete = 0 - for w in wiersze: - if not w or len(w) != SZEROKOSC_WIERSZA: - continue - laczna = _liczba(w[K_ZAJETA_TOTAL]) - if laczna is None: - continue - skladniki = [_liczba(w[i]) or 0.0 - for i in (*K_POZYCJE, K_ZAJETA_Z_POZWOLENIEM, K_ZAJETA_W_TOKU)] - if round(sum(skladniki), 2) == round(laczna, 2): - domkniete += 1 - return domkniete, sum(1 for w in wiersze - if w and len(w) == SZEROKOSC_WIERSZA - and _liczba(w[K_ZAJETA_TOTAL]) is not None) - - -class EDistribucionAdapter(Adapter): - publisher = PUBLISHER - jurisdiction = JURISDICTION - declared_fields = ( - "id_wezla", "nazwa_wezla", "lokalizacja_tekst", "wspolrzedne", "poziom_napiecia", - "moc_dostepna", "moc_zarezerwowana", "ograniczenie_flaga", "data_publikacji", - ) - declared_extensions = { - "_wspolnota_autonomiczna": "wspólnota autonomiczna", - "_prowincja": "prowincja", - "_moc_przyjeta_nierozstrzygnieta_kw": "moc wniosków przyjętych i nierozstrzygniętych", - "_moc_zajeta_z_pozwoleniem_kw": "część mocy zajętej objęta pozwoleniem na przyłączenie", - "_moc_zajeta_w_toku_kw": "część mocy zajętej w toku postępowania", - "_rozbicie_technologiczne_kw": "moc nierozstrzygnięta w podziale na technologie", - "_rozbicie_pozycyjne_kw": "moc zajęta w podziale na pozycje stacji", - "_wezel_przesylowy": "węzeł sieci przesyłowej o największym oddziaływaniu", - "_komentarz": "komentarz publikującego", - } - detect_patterns = (r"edrd[_ ]?capacidad", r"capacidad[_ ]de[_ ]acceso", r"e-?distribuci") - - def parse(self, source) -> ParseResult: - import pandas as pd - import pdfplumber - - path = Path(str(source)) - data_pub = _data_z_nazwy(path.name) - - surowe, stron = [], 0 - with pdfplumber.open(path) as pdf: - stron = len(pdf.pages) - for strona in pdf.pages: - for tabela in strona.extract_tables(): - for wiersz in tabela: - if (wiersz and len(wiersz) == SZEROKOSC_WIERSZA - and _WSPOLNOTA.match(str(wiersz[K_WSPOLNOTA] or ""))): - surowe.append(wiersz) - - domkniete, sprawdzonych = suma_skladnikow_mocy_zajetej(surowe) - rekordy, ograniczonych, bez_wspolrzednych = [], 0, 0 - for w in surowe: - def kom(i): - v = w[i] - return None if v is None or str(v).strip() == "" else str(v).strip() - - lat, lon = _liczba(w[K_SZEROKOSC]), _liczba(w[K_DLUGOSC]) - if lat is None or lon is None: - bez_wspolrzednych += 1 - scc = (kom(K_SCC) or "").upper() - ogr = {"SI": True, "SÍ": True, "NO": False}.get(scc) - if ogr: - ograniczonych += 1 - napiecie = kom(K_NAPIECIE) - podstacja = kom(K_PODSTACJA) - - tech = {i: _mw_na_kw(w[i]) for i in K_TECHNOLOGIE} - poz = {i: _mw_na_kw(w[i]) for i in K_POZYCJE} - - rekordy.append({ - # Identyfikator musi rozróżniać poziomy napięcia tej samej podstacji: - # publikujący wydaje osobny wiersz dla każdego poziomu. - "id_wezla": f"{podstacja}|{napiecie}" if podstacja and napiecie else podstacja, - "nazwa_wezla": podstacja, - "lokalizacja_tekst": ", ".join(x for x in (kom(K_GMINA), kom(K_PROWINCJA)) if x) or None, - "wspolrzedne": f"{lat},{lon}" if lat is not None and lon is not None else None, - "poziom_napiecia": f"{napiecie} kV" if napiecie else None, - "moc_dostepna": _mw_na_kw(w[K_DOSTEPNA]), - "moc_zarezerwowana": _mw_na_kw(w[K_ZAJETA_TOTAL]), - "ograniczenie_flaga": ogr, - "data_publikacji": data_pub, - "_encja": "WEZEL", - "_wspolnota_autonomiczna": kom(K_WSPOLNOTA), - "_prowincja": kom(K_PROWINCJA), - "_moc_przyjeta_nierozstrzygnieta_kw": _mw_na_kw(w[K_PRZYJETA_TOTAL]), - "_moc_zajeta_z_pozwoleniem_kw": _mw_na_kw(w[K_ZAJETA_Z_POZWOLENIEM]), - "_moc_zajeta_w_toku_kw": _mw_na_kw(w[K_ZAJETA_W_TOKU]), - "_rozbicie_technologiczne_kw": ";".join( - f"{i}={v:.1f}" for i, v in tech.items() if v) or None, - "_rozbicie_pozycyjne_kw": ";".join( - f"{i}={v:.1f}" for i, v in poz.items() if v) or None, - "_wezel_przesylowy": kom(K_WEZEL_PRZESYLOWY), - "_komentarz": kom(K_KOMENTARZ), - }) - - df = self.finalize(pd.DataFrame(rekordy), document=path.name) - notes = { - "publikujacy": PUBLISHER, - "jurysdykcja": JURISDICTION, - "tryb_wydania": "dokument przeznaczony do druku, wydanie miesięczne", - "stron": stron, - "wierszy": int(len(df)), - "wezlow_ograniczonych_przez_Scc": ograniczonych, - "wierszy_bez_wspolrzednych": bez_wspolrzednych, - "jednostka_mocy_zrodlowa": "MW", - "przeliczenie": "MW -> kW, obie wielkości to moc czynna", - "data_publikacji": data_pub, - "tozsamosc_sumy_mocy_zajetej": f"{domkniete}/{sprawdzonych}", - "uwaga_tozsamosc": ( - "Jedenaście podkolumn mocy zajętej sumuje się do wartości łącznej. " - "Jest to świadectwo SPÓJNOŚCI odczytu, nie pomiar dokładności wobec " - "wzorca odczytanego niezależnie od parsera, takiego wzorca dla tego " - "publikującego nie ma." - ), - } - return ParseResult(frame=df, report=notes) diff --git a/build/lib/gridqueue/adapters/ie_esbnetworks.py b/build/lib/gridqueue/adapters/ie_esbnetworks.py deleted file mode 100644 index 7f254df..0000000 --- a/build/lib/gridqueue/adapters/ie_esbnetworks.py +++ /dev/null @@ -1,254 +0,0 @@ -"""Adapter: ESB Networks (IE), mapa zdolności przyłączeniowej sieci. - -Publikujący wydaje jeden arkusz obejmujący **całą sieć aż do poziomu stacji -SN/nn**, więc jest to najliczniejsze źródło w panelu i zarazem jedyne, które -schodzi poniżej poziomu stacji wysokiego napięcia. Jednostką wiersza jest grupa -transformatorów w stacji. - -Dwie jednostki w jednym źródle ------------------------------- -Publikujący podaje stronę **odbiorczą w MVA** (moc pozorna), a stronę -**wytwórczą w MW** (moc czynna). Jednostką kanoniczną schematu jest kW mocy -czynnej, więc: - -* wartości wytwórcze są przeliczane (MW -> kW, ta sama wielkość fizyczna), -* wartości odbiorcze **nie są przeliczane** i trafiają do pól rozszerzenia - z jawnie zapisaną jednostką. - -Pole `moc_dostepna` niesie zatem dostępną moc **wytwórczą trwałą**, a nie sumę -obu stron. Zsumowanie MW z MVA dałoby liczbę bez sensu fizycznego, a wybór -jednej strony bez powiedzenia tego wprost byłby ukryciem decyzji. - -Źródło podaje współrzędne oraz dwie osobne flagi ograniczenia, dla strony -odbiorczej i wytwórczej. Do pola `ograniczenie_flaga` wchodzi **alternatywa -obu**, bo pole schematu jest jedno; obie wartości źródłowe pozostają -w rozszerzeniach. -""" - -from __future__ import annotations - -import re -from pathlib import Path - -from .base import Adapter, ParseResult - -PUBLISHER = "ESB Networks DAC" -JURISDICTION = "IE" -ARKUSZ = "Heatmap data" - -#: Nagłówek zajmuje dwa wiersze; nazwy właściwe są w drugim. -WIERSZ_NAGLOWKA = 2 - -KOL = { - "stacja": "Station Name", - "grupa": "Transformer GroupID", - "napiecie_pierwotne": "Primary kV", - "napiecie_wtorne": "Secondary voltage(s)", - "klasa_napiecia": "Voltage Class", - "konfiguracja": "Transformer Configuration", - "moc_zainstalowana_mva": "Installed Capacity MVA", - "odbior_trwala_mva": "Demand FirmCapacity MVA", - "odbior_dostepna_mva": "Demand Available MVA", - "odbior_nadrzedna_mva": "Parent Available MVA", - "odbior_ograniczenie": "Demand Parent Constraint", - "wytw_trwala_mw": "Generation Firm Capacity MW", - "wytw_nietrwala_mw": "Generation NonFirm Capacity MW", - "wytw_zakontraktowana_mw": "Generation Total Committed MW", - "wytw_dostepna_trwala_mw": "Gen Available Firm MW", - "wytw_dostepna_nietrwala_mw": "Gen Available NonFirm MW", - "wytw_ograniczenie": "Generation Parent Constraint", - "zasilanie": "Parent Feeder", - "stacja_nadrzedna": "Parent Station", - "styk_przesylowy": "TSO Interface Station", - "komentarz": "Comment", - "szerokosc": "Latitude", - "dlugosc": "Longitude", -} - -_TAK = {"yes", "y", "true", "constrained", "1"} -_NIE = {"no", "n", "false", "unconstrained", "0"} - -#: Kolumny ograniczenia niosą frazę "Constrained, otherwise capacity available = X kVA" -#: albo są puste. Przyjmujemy, że pusta komórka oznacza BRAK ograniczenia, a nie brak -#: deklaracji: kolumna jest wskaźnikiem binarnym, w którym wartość dodatnia niesie -#: objaśnienie, a ujemna jest wyrażona pustką. Jest to INTERPRETACJA, nie treść źródła -#: -- publikujący nigdzie tej konwencji nie opisuje -- więc surowa fraza zostaje -#: w rozszerzeniu, a decyzja jest odnotowana w raporcie adaptera. -_FRAZA_OGRANICZENIA = re.compile(r"constrained", re.IGNORECASE) -_POJEMNOSC_W_FRAZIE = re.compile(r"=\s*([\d.,]+)\s*kVA", re.IGNORECASE) - - -def _liczba(v) -> float | None: - if v is None: - return None - s = str(v).strip().replace(",", "") - if s in {"", "-", "_", "n/a", "N/A", "None", "nan"}: - return None - try: - return float(s) - except ValueError: - return None - - -def _mw_na_kw(v) -> float | None: - x = _liczba(v) - return None if x is None else x * 1000.0 - - -def _flaga(v) -> bool | None: - """Wskaźnik ograniczenia; pusta komórka to brak ograniczenia (patrz wyżej).""" - if v is None or str(v).strip() == "": - return False - s = str(v).strip().lower() - if s in _TAK: - return True - if s in _NIE: - return False - return True if _FRAZA_OGRANICZENIA.search(s) else None - - -def _pojemnosc_bez_ograniczenia(v) -> float | None: - """Z frazy 'Constrained, otherwise capacity available = X kVA' wyjmij X. - - Wartość jest w kVA, czyli w mocy pozornej, więc NIE jest przeliczana na kW - i zostaje w rozszerzeniu z jednostką w nazwie pola. - """ - if v is None: - return None - m = _POJEMNOSC_W_FRAZIE.search(str(v)) - return _liczba(m.group(1)) if m else None - - -def _alternatywa(a: bool | None, b: bool | None) -> bool | None: - """Alternatywa zachowująca nieokreśloność: None or False -> None, nie False.""" - if a is True or b is True: - return True - if a is False and b is False: - return False - return None - - -class ESBNetworksAdapter(Adapter): - publisher = PUBLISHER - jurisdiction = JURISDICTION - declared_fields = ( - "id_wezla", "nazwa_wezla", "wspolrzedne", "poziom_napiecia", - "moc_dostepna", "moc_zarezerwowana", "ograniczenie_flaga", - ) - declared_extensions = { - "_jednostka_mocy_odbiorczej": "jednostka strony odbiorczej u publikującego (MVA)", - "_klasa_napiecia": "klasa napięcia wg publikującego", - "_konfiguracja_transformatorow": "konfiguracja grupy transformatorów", - "_moc_zainstalowana_mva": "moc zainstalowana transformatorów", - "_odbior_dostepna_mva": "dostępna moc odbiorcza", - "_odbior_trwala_mva": "trwała moc odbiorcza", - "_odbior_nadrzedna_mva": "dostępna moc odbiorcza stacji nadrzędnej", - "_odbior_ograniczenie": "ograniczenie po stronie odbiorczej", - "_wytw_ograniczenie": "ograniczenie po stronie wytwórczej", - "_odbior_ograniczenie_opis": "surowa fraza ograniczenia po stronie odbiorczej", - "_wytw_ograniczenie_opis": "surowa fraza ograniczenia po stronie wytwórczej", - "_odbior_bez_ograniczenia_kva": "moc odbiorcza dostępna, gdyby nie ograniczenie", - "_wytw_bez_ograniczenia_kva": "moc wytwórcza dostępna, gdyby nie ograniczenie", - "_wytw_dostepna_nietrwala_kw": "dostępna moc wytwórcza nietrwała", - "_wytw_zakontraktowana_kw": "moc wytwórcza zakontraktowana łącznie", - "_wytw_trwala_kw": "trwała moc wytwórcza", - "_zasilanie": "linia zasilająca", - "_stacja_nadrzedna": "stacja nadrzędna", - "_styk_przesylowy": "stacja styku z siecią przesyłową", - "_komentarz": "komentarz publikującego", - } - detect_patterns = (r"customer.?heatmap", r"esb.?networks", r"heatmap.?data") - - def parse(self, source) -> ParseResult: - import openpyxl - import pandas as pd - - path = Path(str(source)) - wb = openpyxl.load_workbook(path, read_only=True, data_only=True) - ws = wb[ARKUSZ] if ARKUSZ in wb.sheetnames else wb[wb.sheetnames[0]] - it = ws.iter_rows(values_only=True) - for _ in range(WIERSZ_NAGLOWKA - 1): - next(it) - naglowek = [str(c).strip() if c is not None else "" for c in next(it)] - pozycja = {nazwa: naglowek.index(etykieta) - for nazwa, etykieta in KOL.items() if etykieta in naglowek} - brakujace = sorted(set(KOL) - set(pozycja)) - - rekordy, bez_wspolrzednych, ograniczonych = [], 0, 0 - for w in it: - def g(nazwa): - i = pozycja.get(nazwa) - if i is None or i >= len(w): - return None - v = w[i] - return None if v is None or str(v).strip() in {"", "_", "-"} else v - - stacja = g("stacja") - if stacja is None: - continue - grupa = g("grupa") - lat, lon = _liczba(g("szerokosc")), _liczba(g("dlugosc")) - if lat is None or lon is None: - bez_wspolrzednych += 1 - s_odb, s_wyt = g("odbior_ograniczenie"), g("wytw_ograniczenie") - f_odb, f_wyt = _flaga(s_odb), _flaga(s_wyt) - ogr = _alternatywa(f_odb, f_wyt) - if ogr: - ograniczonych += 1 - nap = g("napiecie_pierwotne") - - rekordy.append({ - "id_wezla": f"{stacja}|{grupa}" if grupa else str(stacja), - "nazwa_wezla": str(stacja).strip(), - "wspolrzedne": f"{lat},{lon}" if lat is not None and lon is not None else None, - "poziom_napiecia": str(nap).strip() if nap else None, - # Strona wytwórcza jest w MW mocy czynnej -- jedyna przeliczalna. - "moc_dostepna": _mw_na_kw(g("wytw_dostepna_trwala_mw")), - "moc_zarezerwowana": _mw_na_kw(g("wytw_zakontraktowana_mw")), - "ograniczenie_flaga": ogr, - "_encja": "WEZEL", - "_jednostka_mocy_odbiorczej": "MVA", - "_klasa_napiecia": g("klasa_napiecia"), - "_konfiguracja_transformatorow": g("konfiguracja"), - "_moc_zainstalowana_mva": _liczba(g("moc_zainstalowana_mva")), - "_odbior_dostepna_mva": _liczba(g("odbior_dostepna_mva")), - "_odbior_trwala_mva": _liczba(g("odbior_trwala_mva")), - "_odbior_nadrzedna_mva": _liczba(g("odbior_nadrzedna_mva")), - "_odbior_ograniczenie": f_odb, - "_wytw_ograniczenie": f_wyt, - "_odbior_ograniczenie_opis": str(s_odb) if s_odb is not None else None, - "_wytw_ograniczenie_opis": str(s_wyt) if s_wyt is not None else None, - "_odbior_bez_ograniczenia_kva": _pojemnosc_bez_ograniczenia(s_odb), - "_wytw_bez_ograniczenia_kva": _pojemnosc_bez_ograniczenia(s_wyt), - "_wytw_dostepna_nietrwala_kw": _mw_na_kw(g("wytw_dostepna_nietrwala_mw")), - "_wytw_zakontraktowana_kw": _mw_na_kw(g("wytw_zakontraktowana_mw")), - "_wytw_trwala_kw": _mw_na_kw(g("wytw_trwala_mw")), - "_zasilanie": g("zasilanie"), - "_stacja_nadrzedna": g("stacja_nadrzedna"), - "_styk_przesylowy": g("styk_przesylowy"), - "_komentarz": g("komentarz"), - }) - wb.close() - - df = self.finalize(pd.DataFrame(rekordy), document=path.name) - notes = { - "publikujacy": PUBLISHER, - "jurysdykcja": JURISDICTION, - "tryb_wydania": "arkusz kalkulacyjny na stronie publikującego", - "wierszy": int(len(df)), - "wierszy_bez_wspolrzednych": bez_wspolrzednych, - "wezlow_ograniczonych": ograniczonych, - "interpretacja_pustej_flagi": ( - "pusta komórka kolumny ograniczenia czytana jako BRAK ograniczenia; " - "publikujący tej konwencji nie opisuje, surowa fraza w rozszerzeniu" - ), - "kolumny_nieznalezione": brakujace, - "jednostka_strony_wytworczej": "MW", - "jednostka_strony_odbiorczej": "MVA", - "uwaga_jednostki": ( - "Pole moc_dostepna niesie dostępną moc WYTWÓRCZĄ trwałą, przeliczoną z MW " - "na kW. Strona odbiorcza jest podana w MVA (moc pozorna) i nie jest " - "przeliczana ani sumowana ze stroną wytwórczą; pozostaje w rozszerzeniach." - ), - } - return ParseResult(frame=df, report=notes) diff --git a/build/lib/gridqueue/adapters/pl_boryszew.py b/build/lib/gridqueue/adapters/pl_boryszew.py deleted file mode 100644 index 0e1da35..0000000 --- a/build/lib/gridqueue/adapters/pl_boryszew.py +++ /dev/null @@ -1,232 +0,0 @@ -"""Adapter: Boryszew Green Energy&Gas Sp. z o.o. (Elana, Toruń) -- mały OSD przemysłowy. - -Publikacja jest 4-stronicowym dokumentem prozą z tabelami BEZ SIATKI LINIOWEJ. -Nie ma tu żadnej struktury do odzyskania z linii -- granice kolumn istnieją tylko -jako pionowe korytarze bieli. Dlatego ten adapter używa strategii BANDED: -wykrywa korytarze w rozkładzie pokrycia osi x, a wiersze wielolinijkowe scala po -numerze porządkowym w pierwszej kolumnie. - -Dokument realizuje wszystkie cztery punkty art. 7 ust. 8l w osobnych sekcjach -numerowanych w tekście. Sekcje 1, 3 i 4 to encja WNIOSEK i trafiają do panelu. -Sekcja 2 to encja WĘZEŁ (dostępna moc przyłączeniowa per stacja na 6 lat) -- -zwracamy ją osobno w raporcie, bo nie ma rdzenia wnioskowego i nie wolno jej -mieszać z wierszami wnioskowymi bez łamania walidacji schematu. - -Przypadek ten jest w korpusie istotny jako dolny kraniec jakości ujawnień: -ten sam obowiązek ustawowy, publikacja bez żadnej struktury maszynowej. -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..layout import detect_banded_columns, assign_words_to_columns, merge_continuation_rows -from ..schema import canonical_date, canonical_power_kw -from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status, norm_text - -_RE_LP = re.compile(r"^\d+\.$") -_SECTIONS = ( - (1, re.compile(r"^1\.\s*Podmioty ubiegaj", re.I)), - (2, re.compile(r"^2\.\s*Warto", re.I)), - (3, re.compile(r"^3\.\s*Z(ł|l)o(ż|z)one wnioski", re.I)), - (4, re.compile(r"^4\.\s*Wydane odmowy", re.I)), - (5, re.compile(r"^5\.\s*Spos(ó|o)b", re.I)), -) - -LAYOUTS = { - 1: ("lp", "rodzaj_podmiotu", "lokalizacja", "moc_mw", "rodzaj_instalacji", - "data_warunkow", "data_umowy", "data_energizacji"), - 3: ("lp", "rodzaj_podmiotu", "lokalizacja", "moc_mw", "rodzaj_instalacji", - "data_zlozenia", "data_zaliczki", "status_wniosku"), - 4: ("lp", "lokalizacja", "moc_mw", "rodzaj_instalacji", "data_zlozenia", - "data_zaliczki", "powod_odmowy"), -} - - -class BoryszewAdapter(Adapter): - publisher = "Boryszew Green Energy&Gas Sp. z o.o." - jurisdiction = "PL" - declared_fields = ( - "id_wniosku", "lokalizacja_tekst", "klasa_zasobu", "moc_pobierana", - "status_procesu", "data_wniosku", "data_warunkow", "data_umowy", - "data_energizacji", "data_publikacji", - ) - declared_extensions = { - "_rodzaj_podmiotu": "określenie przyłączanego obiektu (osoba prawna/fizyczna)", - "_data_zaliczki": "data wpłaty zaliczki", - "_sekcja": "punkt art. 7 ust. 8l, z którego pochodzi wiersz", - "_rodzaj_instalacji_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status rozpatrywania tak, jak w dokumencie", - "_uwaga_zrodlowa": "adnotacja publikującego (np. 'Nie dotyczy / istniejące przyłącze')", - } - detect_patterns = (r"boryszew", r"elana") - - def __init__(self, data_publikacji: Optional[str] = None): - self.data_publikacji = data_publikacji - - # ------------------------------------------------------------------ - def parse(self, source) -> ParseResult: - import pandas as pd - import pdfplumber - - sec_lines: dict[int, list[list[dict]]] = {k: [] for k, _ in _SECTIONS} - wezly_lines: list[list[dict]] = [] - full_text_parts: list[str] = [] - current = 0 - n_pages = 0 - with pdfplumber.open(source) as pdf: - for page in pdf.pages: - n_pages += 1 - full_text_parts.append(page.extract_text() or "") - lines = _group_lines(page.extract_words()) - for ln in lines: - txt = " ".join(w["text"] for w in ln).strip() - for num, rx in _SECTIONS: - if rx.match(txt): - current = num - break - else: - if current in sec_lines: - sec_lines[current].append(ln) - continue - full_text = "\n".join(full_text_parts) - if self.data_publikacji is None: - self.data_publikacji = _data_aktualizacji(full_text) - - frames = [] - per_section = {} - for sec in (1, 3, 4): - f, n_raw = self._section_frame(sec, sec_lines[sec]) - per_section[sec] = {"wierszy_surowych": n_raw, "wierszy_wynikowych": int(len(f))} - if len(f): - frames.append(f) - df = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame() - - wezly = _parse_wezly(sec_lines[2]) - - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "banded (korytarze bieli; brak siatki liniowej)", - "strony": n_pages, - "sekcje": per_section, - "n_wierszy": int(len(df)), - "wezly_pkt2": wezly, - "data_publikacji": self.data_publikacji, - } - return ParseResult(self.finalize(df, document=str(source)), report) - - # ------------------------------------------------------------------ - def _section_frame(self, sec: int, lines: list[list[dict]]): - import pandas as pd - - cols = LAYOUTS[sec] - # linie danych: od pierwszej zaczynającej się numerem porządkowym - start = next((i for i, ln in enumerate(lines) - if ln and _RE_LP.match(ln[0]["text"])), None) - if start is None: - return pd.DataFrame(), 0 - data_lines = lines[start:] - words = [w for ln in data_lines for w in ln] - geom = detect_banded_columns(words, min_gap=6.0) - cells = assign_words_to_columns(words, geom) - rows = merge_continuation_rows(cells, lambda r: bool(r) and bool(_RE_LP.match(r[0]))) - n_raw = len(rows) - width = max((len(r) for r in rows), default=0) - if width != len(cols): - # dopasuj do deklarowanego układu: nadmiarowe kolumny doklej do ostatniej - rows = [_fit(r, len(cols)) for r in rows] - raw = pd.DataFrame([(r + [""] * len(cols))[: len(cols)] for r in rows], columns=cols) - raw = raw.map(lambda v: re.sub(r"\s+", " ", str(v)).strip()) - # odrzuć wiersze-zaślepki ("brak" we wszystkich polach poza Lp.) - body = raw.drop(columns=["lp"]) - keep = ~body.map(lambda v: norm_text(v) in {"", "brak", "-"}).all(axis=1) - raw = raw[keep].reset_index(drop=True) - if raw.empty: - return pd.DataFrame(), n_raw - - out = pd.DataFrame(index=raw.index) - out["id_wniosku"] = [f"boryszew:pkt{sec}:{i + 1}" for i in range(len(raw))] - out["lokalizacja_tekst"] = raw["lokalizacja"].replace("", None) - out["klasa_zasobu"] = raw["rodzaj_instalacji"].map(harmonize_klasa) - out["moc_pobierana"] = raw["moc_mw"].map(lambda v: canonical_power_kw(v, "MW")) - out["data_publikacji"] = self.data_publikacji - out["_sekcja"] = f"art. 7 ust. 8l pkt {sec}" - out["_rodzaj_instalacji_raw"] = raw["rodzaj_instalacji"].replace("", None) - if "rodzaj_podmiotu" in raw: - out["_rodzaj_podmiotu"] = raw["rodzaj_podmiotu"].replace("", None) - if sec == 1: - out["data_warunkow"] = raw["data_warunkow"].map(canonical_date) - out["data_umowy"] = raw["data_umowy"].map(canonical_date) - out["data_energizacji"] = raw["data_energizacji"].map(canonical_date) - out["_uwaga_zrodlowa"] = raw["data_umowy"].replace("", None) - _ok = lambda v: v is not None and not (isinstance(v, float) and v != v) - out["status_procesu"] = [ - "PRZYLACZONY" if _ok(e) else ("UMOWA_OBOWIAZUJACA" if _ok(u) else - ("WARUNKI_WYDANE" if _ok(w) else "NIEOKRESLONY")) - for e, u, w in zip(out["data_energizacji"], out["data_umowy"], - out["data_warunkow"]) - ] - elif sec == 3: - out["data_wniosku"] = raw["data_zlozenia"].map(canonical_date) - out["_data_zaliczki"] = raw["data_zaliczki"].map(canonical_date) - out["status_procesu"] = raw["status_wniosku"].map(harmonize_status) - out["_status_raw"] = raw["status_wniosku"].replace("", None) - else: - out["data_wniosku"] = raw["data_zlozenia"].map(canonical_date) - out["powod_odmowy"] = raw["powod_odmowy"].replace("", None) - out["status_procesu"] = "ODMOWA" - out["_lp_dokumentu"] = raw["lp"] - return out, n_raw - - -def _fit(row: list[str], n: int) -> list[str]: - if len(row) <= n: - return row + [""] * (n - len(row)) - return row[: n - 1] + [" ".join(x for x in row[n - 1:] if x)] - - -def _group_lines(words, tol: float = 2.5) -> list[list[dict]]: - ws = sorted(words, key=lambda w: (round(w["top"], 1), w["x0"])) - out: list[list[dict]] = [] - for w in ws: - if out and abs(w["top"] - out[-1][0]["top"]) <= tol: - out[-1].append(w) - else: - out.append([w]) - return [sorted(ln, key=lambda w: w["x0"]) for ln in out] - - -def _data_aktualizacji(text: str) -> Optional[str]: - m = re.search(r"Data aktualizacji publikacji:\s*(\d{1,2})\s+(\w+)\s+(\d{4})", text) - months = {"stycznia": 1, "lutego": 2, "marca": 3, "kwietnia": 4, "maja": 5, - "czerwca": 6, "lipca": 7, "sierpnia": 8, "września": 9, "wrzesnia": 9, - "października": 10, "pazdziernika": 10, "listopada": 11, "grudnia": 12} - if m and m.group(2).lower() in months: - return f"{m.group(3)}-{months[m.group(2).lower()]:02d}-{int(m.group(1)):02d}" - return None - - -def _parse_wezly(lines: list[list[dict]]) -> list[dict]: - """Sekcja 2 (pkt 2): dostępna moc przyłączeniowa per stacja na 6 lat.""" - out: list[dict] = [] - years: list[str] = [] - for ln in lines: - toks = [w["text"] for w in ln] - if len(toks) >= 4 and all(re.fullmatch(r"20\d{2}", t) for t in toks): - years = toks - continue - if toks and toks[0].upper().startswith("STACJA"): - name_toks, vals = [], [] - for w in ln: - if re.fullmatch(r"-?\d+(?:[.,]\d+)?", w["text"]) and w["x0"] > 260: - vals.append(w["text"]) - else: - name_toks.append(w["text"]) - rec = {"nazwa_wezla": " ".join(name_toks), - "moc_dostepna_kw": {}} - for i, v in enumerate(vals): - y = years[i] if i < len(years) else f"kol{i}" - rec["moc_dostepna_kw"][y] = canonical_power_kw(v, "MW") - out.append(rec) - return out diff --git a/build/lib/gridqueue/adapters/pl_energa.py b/build/lib/gridqueue/adapters/pl_energa.py deleted file mode 100644 index 09f4ffe..0000000 --- a/build/lib/gridqueue/adapters/pl_energa.py +++ /dev/null @@ -1,282 +0,0 @@ -"""Adapter: ENERGA-OPERATOR S.A. (PL, OSD, sześć oddziałów, obszar północny). - -Energa jest jedynym z dotychczas zmierzonych publikujących, który realizuje OBA -punkty obowiązku w rozłącznych dokumentach i w obu podaje dane w postaci tabelarycznej: - - pkt 1), 3), 4) -- "Informacje publikowane zgodnie z Art. 7 ust. 8l pkt 1), 3) - i 4) ustawy Prawo energetyczne", PDF, 37 stron, 28 kolumn. - To jest ten sam wzorzec PTPiREE/PSE co arkusz PSE (moduł - ``_ptpiree``), przeniesiony do PDF-a. Encja WNIOSEK. - pkt 2) -- dwa dokumenty "Informacja o wartości łącznej dostępnej - {odbiorczej|wytwórczej} mocy przyłączeniowej [MW]". Encja WĘZEŁ. - TO JEST PIERWSZE ŹRÓDŁO W PANELU, KTÓRE WYPEŁNIA ``moc_dostepna``. - -Geometria pkt 1/3/4: dokument nie ma obiektów ``line``, ma natomiast 176 cienkich -prostokątów pełniących rolę linii siatki; pdfplumber wystawia je jako krawędzie, więc -strategia ``ruled`` działa bez zmian. Nagłówek szczegółowy jest złożony z bardzo -wąskich kolumn ze zawijanym tekstem -- płaski ``extract_text`` przeplata go między -kolumnami i jest bezużyteczny, dlatego układ odczytujemy przez przypisanie słów -nagłówka do kolumn geometrią, a nie z tekstu strony. - -Geometria pkt 2: tabele 2.1 (skład grup węzłów koherentnych), 2.2 (słownik skrótów -stacji) i 2.3/2.4 (wartości mocy) też mają siatkę wektorową. - -Rozstrzygnięcie merytoryczne przy dokumencie wytwórczym: są w nim DWIE tabele -wartości. Tabela 2.3 jest ujawnieniem ustawowym; tabela 2.4 jest -- słowami samego -dokumentu -- podana "dodatkowo", dla podejścia analitycznego jak w ekspertyzach wg -ustawy o morskich farmach wiatrowych. Do ``moc_dostepna`` bierzemy 2.3; 2.4 trafia -do rozszerzenia. Odwrotny wybór zawyżałby ujawnioną moc bez podstawy w dokumencie. - -Rozbieżność dat, którą trzeba zgłosić, a nie wygładzić: plik pkt 1/3/4 nazywa się -``2026_08_31_pusop_wnioski_i_odmowy_eop.pdf`` i wisi w cyklu sierpniowym, ale jego -własny nagłówek deklaruje "Stan na 30.06.2026 r.". ``data_publikacji`` bierzemy -z DOKUMENTU (30.06.2026), bo to on jest ujawnieniem, a nie nazwa pliku. -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..layout import detect_ruled_columns, extract_ruled_page -from ..schema import canonical_power_kw -from . import _ptpiree as T -from .base import Adapter, ParseResult, norm_text - -__all__ = ["EnergaAdapter"] - -_RE_LP = re.compile(r"^\d+\.?$") -_RE_YEAR = re.compile(r"^(19|20)\d{2}$") - - -class EnergaAdapter(Adapter): - publisher = "ENERGA-OPERATOR S.A." - jurisdiction = "PL" - declared_fields = T.DECLARED_FIELDS + ("id_wezla", "nazwa_wezla", "moc_dostepna") - declared_extensions = dict( - T.DECLARED_EXTENSIONS, - _kierunek="kierunek mocy dostępnej: odbiorcza albo wytwórcza", - _nr_grupy="numer grupy węzłów koherentnych w dokumencie", - _stacje_grupy="stacje wchodzące w skład grupy (model sieci na rok bazowy)", - _zmiany_w_latach="zmiany składu grupy w kolejnych latach (kolumna uwag)", - _oddzial="oddział ENERGA-OPERATOR, w którego obszarze leży grupa", - _moc_dostepna_analityczna="wartość z tabeli 2.4 (podejście analityczne), rok bazowy [kW]", - ) - detect_patterns = (r"energa", r"eop") - - #: lata horyzontu ujawnienia pkt 2 - HORYZONT = ("2026", "2027", "2028", "2029", "2030", "2031", "2035") - - def __init__(self, data_publikacji: Optional[str] = None, rok_bazowy: str = "2026"): - self.data_publikacji = data_publikacji - self.rok_bazowy = rok_bazowy - - # ------------------------------------------------------------------ - def parse(self, source) -> ParseResult: - import pandas as pd - - sources = [source] if isinstance(source, (str, bytes)) else list(source) - frames, reports = [], [] - for src in sources: - rola = self._detect_role(src) - if rola == "wnioski": - f, r = self._parse_wnioski(src) - else: - f, r = self._parse_wezly(src, kierunek=rola) - frames.append(f) - reports.append(r) - df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka z cienkich prostokątów), nagłówek odczytany geometrią", - "wzorzec": "PTPiREE/PSE dla pkt 1/3/4; autorski układ IEn dla pkt 2", - "dokumenty": reports, - "n_wierszy": int(len(df)), - "data_publikacji": self.data_publikacji, - } - return ParseResult(self.finalize(df, document="; ".join(map(str, sources))), report) - - # ------------------------------------------------------------------ - @staticmethod - def _detect_role(src) -> str: - import pdfplumber - - with pdfplumber.open(src) as pdf: - t = norm_text(pdf.pages[0].extract_text() or "") - if "dostepnej odbiorczej mocy" in t: - return "odbiorcza" - if "dostepnej wytworczej mocy" in t: - return "wytworcza" - return "wnioski" - - # ------------------------------------------------------------------ - def _parse_wnioski(self, src): - """pkt 1/3/4 -- wzorzec PTPiREE w PDF-ie z siatką wektorową.""" - import pandas as pd - import pdfplumber - - rows: list[list[Optional[str]]] = [] - n_pages = 0 - n_cols_seen: set[int] = set() - stan = None - with pdfplumber.open(src) as pdf: - for page in pdf.pages: - n_pages += 1 - if stan is None: - stan = T.stan_na(page.extract_text() or "") - geom = detect_ruled_columns(page) - if geom.n_cols < 10: - continue - n_cols_seen.add(geom.n_cols) - tbl = extract_ruled_page(page, geom) - for row in tbl or []: - if row and _RE_LP.match((row[0] or "").strip()): - rows.append(row) - if stan and self.data_publikacji is None: - self.data_publikacji = stan - - width = max(T.ENERGA_PDF_LAYOUT) + 1 - raw = pd.DataFrame(index=range(len(rows))) - padded = [(list(r) + [None] * width)[:width] for r in rows] - for phys, logical in T.ENERGA_PDF_LAYOUT.items(): - raw[logical] = [p[phys] for p in padded] - out = T.to_schema(raw, publisher_key="energa", data_publikacji=self.data_publikacji) - return out, { - "plik": str(src), - "encja": "WNIOSEK", - "strony": n_pages, - "n_kolumn_zrodlowych": sorted(n_cols_seen), - "n_wierszy": int(len(out)), - "stan_na": stan, - "uwaga_data": "nazwa pliku wskazuje cykl 31.08.2026, dokument deklaruje " - f"stan na {stan}; przyjęto deklarację dokumentu", - } - - # ------------------------------------------------------------------ - def _parse_wezly(self, src, *, kierunek: str): - """pkt 2 -- wartości łącznej dostępnej mocy przyłączeniowej per grupa węzłów.""" - import pandas as pd - import pdfplumber - - grupy: dict[str, dict] = {} # nr grupy -> skład - wartosci: dict[str, dict] = {} # nr grupy -> {rok: MW} z tabeli 2.3 - analit: dict[str, dict] = {} # nr grupy -> {rok: MW} z tabeli 2.4 - oddzial_biezacy = None - stan = None - n_pages = 0 - - with pdfplumber.open(src) as pdf: - for page in pdf.pages: - n_pages += 1 - txt = page.extract_text() or "" - if stan is None: - stan = T.stan_na(txt) - if len(page.rects) < 50: - continue - geom = detect_ruled_columns(page) - if geom.n_cols < 2: - continue - tbl = extract_ruled_page(page, geom) or [] - caption = norm_text(" ".join(l for l in txt.split("\n")[:6] - if l.strip().startswith("Tabela"))) - if caption.startswith("tabela 2.1"): - oddzial_biezacy = self._collect_grupy(tbl, grupy, oddzial_biezacy) - elif caption.startswith("tabela 2.3"): - self._collect_wartosci(tbl, wartosci) - elif caption.startswith("tabela 2.4"): - self._collect_wartosci(tbl, analit) - - if kierunek == "odbiorcza" and stan and self.data_publikacji is None: - self.data_publikacji = stan - - nry = sorted(wartosci, key=lambda s: int(s)) - out = pd.DataFrame(index=range(len(nry))) - g = [grupy.get(n, {}) for n in nry] - out["id_wniosku"] = None - out["id_wezla"] = [f"energa:grupa110:{n}:{kierunek}" for n in nry] - out["nazwa_wezla"] = [wartosci[n].get("_nazwa") for n in nry] - out["lokalizacja_tekst"] = [ - gi.get("stacje") or wartosci[n].get("_nazwa") for n, gi in zip(nry, g) - ] - out["poziom_napiecia"] = "110 kV" - # Kierunek mocy nie jest rodzajem instalacji: ujawnienie pkt 2 dotyczy - # WĘZŁA, nie zasobu. Dla mocy odbiorczej klasa jest jednoznaczna (ODB), - # dla wytwórczej dokument nie wskazuje technologii -- i tak zostaje. - out["klasa_zasobu"] = "ODB" if kierunek == "odbiorcza" else "NIEOKRESLONA" - out["status_procesu"] = "NIEOKRESLONY" - out["moc_dostepna"] = [ - canonical_power_kw(wartosci[n].get(self.rok_bazowy), "MW") for n in nry - ] - out["data_publikacji"] = stan - out["_encja"] = "WEZEL" - out["_kierunek"] = kierunek - out["_nr_grupy"] = nry - out["_stacje_grupy"] = [gi.get("stacje") for gi in g] - out["_zmiany_w_latach"] = [gi.get("zmiany") for gi in g] - out["_oddzial"] = [gi.get("oddzial") for gi in g] - for rok in self.HORYZONT: - out[f"_moc_dostepna_{rok}"] = [ - canonical_power_kw(wartosci[n].get(rok), "MW") for n in nry - ] - out["_moc_dostepna_analityczna"] = [ - canonical_power_kw(analit.get(n, {}).get(self.rok_bazowy), "MW") for n in nry - ] - for rok in self.HORYZONT: - self.declared_extensions[f"_moc_dostepna_{rok}"] = ( - f"dostępna moc przyłączeniowa w horyzoncie {rok} [kW]" - ) - return out, { - "plik": str(src), - "encja": "WEZEL", - "kierunek": kierunek, - "strony": n_pages, - "n_grup_z_wartosciami": len(nry), - "n_grup_ze_skladem": len(grupy), - "n_grup_analitycznych": len(analit), - "horyzont": list(self.HORYZONT), - "rok_bazowy": self.rok_bazowy, - "n_wierszy": int(len(out)), - "stan_na": stan, - } - - # ------------------------------------------------------------------ - @staticmethod - def _collect_grupy(tbl, grupy: dict, oddzial: Optional[str]) -> Optional[str]: - for row in tbl: - cells = [(c or "").replace("\n", " ").strip() for c in row] - if len(cells) < 3: - continue - joined = " ".join(cells).strip() - if "Oddział" in joined and not re.match(r"^\d+$", cells[0]): - m = re.search(r"Oddział\s+([\w\śółęąźżćń-]+)", joined) - if m: - oddzial = m.group(1).strip() - continue - if not re.match(r"^\d+$", cells[0]): - continue - grupy[cells[0]] = { - "nazwa": cells[1] or None, - "stacje": re.sub(r"\s+", " ", cells[2]) or None, - "zmiany": (re.sub(r"\s+", " ", cells[3]) or None) if len(cells) > 3 else None, - "oddzial": oddzial, - } - return oddzial - - @staticmethod - def _collect_wartosci(tbl, store: dict) -> None: - lata: list[str] = [] - for row in tbl: - cells = [(c or "").replace("\n", " ").strip() for c in row] - if not cells: - continue - kandydaci = [c for c in cells[2:] if _RE_YEAR.match(c)] - if len(kandydaci) >= 3: - lata = [c if _RE_YEAR.match(c) else "" for c in cells[2:]] - continue - if not lata or not re.match(r"^\d+$", cells[0]): - continue - rec = {"_nazwa": cells[1] or None} - for rok, val in zip(lata, cells[2:]): - if rok and val not in {"", "-"}: - rec[rok] = val - store[cells[0]] = rec diff --git a/build/lib/gridqueue/adapters/pl_pse.py b/build/lib/gridqueue/adapters/pl_pse.py deleted file mode 100644 index 4b6bdaa..0000000 --- a/build/lib/gridqueue/adapters/pl_pse.py +++ /dev/null @@ -1,304 +0,0 @@ -"""Adapter: Polskie Sieci Elektroenergetyczne S.A. (PL, operator PRZESYŁOWY). - -Uwaga ustrojowa, którą trzeba zapisać w manuskrypcie, bo zmienia zakres wniosku: -PSE jest operatorem systemu PRZESYŁOWEGO, nie dystrybucyjnego. Nie naciągamy tu -niczego -- dokument sam deklaruje podstawę: plik nazywa się "Informacje -publikowane zgodnie z Art. 7 ust. 8l ustawy PE", a komórka A1 arkusza powtarza tę -deklarację. Art. 7 ust. 8l adresuje "przedsiębiorstwo energetyczne zajmujące się -przesyłaniem LUB dystrybucją", więc obowiązek obejmuje OSP tak samo jak OSD. - -Co z tego naprawdę wynika dla porównywalności: - * zakres napięć jest inny -- 110/220/400 kV zamiast SN/110 kV. To nie jest - niezgodność ze schematem (obowiązek dotyczy sieci powyżej 1 kV), tylko - zmierzona różnica w polu ``poziom_napiecia``; - * PSE realizuje pkt 1), 3) i 4) w jednym zestawieniu (encja WNIOSEK); - * pkt 2) (dostępna moc w stacjach) PSE ujawnia INACZEJ: nie jako moc w MW, lecz - jako "Listę rozdzielni, dla których brak jest dostępnych miejsc przyłączenia" - z LICZBĄ dostępnych miejsc. To jest informacja o węźle i o ograniczeniu, ale - NIE jest wartością mocy -- mapujemy ją na ``ograniczenie_flaga`` i rozszerzenie - ``_liczba_dostepnych_miejsc``, a pole ``moc_dostepna`` zostawiamy puste. - Wpisanie tam zera albo liczby miejsc byłoby fabrykacją jednostki. - -Nośnikiem jest XLSX, a nie PDF, więc geometria kolumn nie jest tu w ogóle problemem: -komórka arkusza ma tożsamość z definicji. Zachowujemy jednak ten sam audyt -sprzeczności typu, żeby liczba dla PSE była porównywalna z liczbami dla publikujących -PDF-owych -- i żeby było widać, ile z niej pochodzi z układu, a ile z samego źródła. -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..schema import canonical_date -from . import _ptpiree as T -from .base import Adapter, ParseResult - -__all__ = ["PSEAdapter"] - -_SHEET_MAIN = "Wykaz wspólny" -_SHEET_VOCAB = "Listy rozwijane" - - -class PSEAdapter(Adapter): - publisher = "PSE S.A." - jurisdiction = "PL" - declared_fields = T.DECLARED_FIELDS + ("id_wezla", "nazwa_wezla", "ograniczenie_flaga") - declared_extensions = dict( - T.DECLARED_EXTENSIONS, - _liczba_dostepnych_miejsc="liczba wolnych miejsc przyłączenia w rozdzielni", - _symbol_stacji="symbol stacji w nomenklaturze PSE", - _zko_pse="Zakład Koordynacyjny Ośrodka PSE", - _rozdzielnia="oznaczenie rozdzielni w stacji", - _przypisy="odnośniki przypisów odcięte od treści komórek (pole=znacznik)", - ) - detect_patterns = (r"pse", r"art_7_ust_8l", r"polskie sieci elektroenergetyczne") - - def __init__(self, data_publikacji: Optional[str] = None): - self.data_publikacji = data_publikacji - - # ------------------------------------------------------------------ - def parse(self, source) -> ParseResult: - """``source``: ścieżka do arkusza pkt 1/3/4 albo lista ścieżek. - - Rozpoznanie roli pliku po zawartości, nie po nazwie: arkusz o nazwie - "Wykaz wspólny" to zestawienie wniosków, arkusz "Lista zajętych rozdzielni" - to ujawnienie węzłowe. - """ - import pandas as pd - - sources = [source] if isinstance(source, (str, bytes)) else list(source) - frames, reports = [], [] - for src in sources: - xl = pd.ExcelFile(src) - if _SHEET_MAIN in xl.sheet_names: - f, r = self._parse_wnioski(xl, src) - elif any("rozdzielni" in s.lower() for s in xl.sheet_names): - f, r = self._parse_wezly(xl, src) - else: - raise ValueError(f"nierozpoznany arkusz PSE w {src!r}: {xl.sheet_names}") - frames.append(f) - reports.append(r) - df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "arkusz kalkulacyjny (tożsamość komórki z definicji)", - "wzorzec": "PTPiREE/PSE, art. 7 ust. 8l pkt 1), 3), 4)", - "dokumenty": reports, - "n_wierszy": int(len(df)), - "data_publikacji": self.data_publikacji, - } - return ParseResult(self.finalize(df, document="; ".join(map(str, sources))), report) - - # ------------------------------------------------------------------ - def _parse_wnioski(self, xl, src): - import pandas as pd - - d, przypisy = _read_sheet_bez_przypisow(src, _SHEET_MAIN) - tytul = " ".join(str(v) for v in d.iloc[0].tolist() if isinstance(v, str)) - stan = T.stan_na(tytul) - if stan and self.data_publikacji is None: - self.data_publikacji = stan - - hdr_row = self._find_header_row(d) - body = d.iloc[hdr_row + 1:].reset_index(drop=True) - body.columns = range(body.shape[1]) - - # Ostatnie wiersze arkusza to LEGENDA przedrostków identyfikatora - # ("E- Wnioskodawca wystąpił z wnioskiem..."). Wiersz danych ma wypełnione - # pole wzorca "Nazwa OSD/OSP"; legenda go nie ma. Kryterium jest więc - # własnością wzorca, a nie zgadywaniem po pozycji. - osd_col = 2 - keep = body[osd_col].notna() & body[osd_col].map( - lambda v: bool(str(v).strip()) if v is not None else False) - legenda = int((~keep).sum()) - body = body[keep].reset_index(drop=True) - - raw = pd.DataFrame(index=body.index) - for phys, logical in T.PSE_XLSX_LAYOUT.items(): - if phys < body.shape[1]: - raw[logical] = body[phys] - out = T.to_schema(raw, publisher_key="pse", data_publikacji=self.data_publikacji) - - # Odnośniki przypisów wracają jako rozszerzenie, żeby odcięcie ich od - # treści nie było utratą danej. Klucz ``marks`` to (wiersz arkusza, - # kolumna arkusza), a ``keep`` mówi, które wiersze arkusza zostały. - wiersze_arkusza = [i for i, k in enumerate(keep.tolist(), start=hdr_row + 1) if k] - znaczniki = [] - for ri in wiersze_arkusza: - m = {T.PSE_XLSX_LAYOUT.get(ci, f"kol{ci}"): txt - for (rr, ci), txt in przypisy.items() if rr == ri} - znaczniki.append("; ".join(f"{k}={v}" for k, v in sorted(m.items())) or None) - out["_przypisy"] = znaczniki - n_przypisow = sum(1 for z in znaczniki if z) - - vocab = self._read_vocab(xl) - return out, { - "plik": str(src), - "arkusz": _SHEET_MAIN, - "encja": "WNIOSEK", - "n_kolumn_zrodlowych": int(body.shape[1]), - "wiersz_naglowka": hdr_row, - "wierszy_legendy_odrzuconych": legenda, - "n_wierszy": int(len(out)), - "stan_na": stan, - "wierszy_z_przypisem": n_przypisow, - "slownik_zrodlowy": vocab, - } - - # ------------------------------------------------------------------ - def _parse_wezly(self, xl, src): - """Lista rozdzielni bez wolnych miejsc przyłączenia (ujawnienie węzłowe).""" - import pandas as pd - - sheet = next(s for s in xl.sheet_names if "rozdzielni" in s.lower()) - d = xl.parse(sheet, header=None) - stan = T.stan_na(" ".join(str(v) for v in d.values.ravel() if isinstance(v, str))) - - hdr = None - for i in range(min(12, len(d))): - vals = [str(v).strip().lower() for v in d.iloc[i].tolist() if isinstance(v, str)] - if any("symbol stacji" in v for v in vals): - hdr = i - break - if hdr is None: - raise ValueError(f"nie znaleziono nagłówka listy rozdzielni w {src!r}") - cols = [str(v).strip() if isinstance(v, str) else "" for v in d.iloc[hdr].tolist()] - body = d.iloc[hdr + 1:].reset_index(drop=True) - body.columns = cols - - def c(frag): - for name in body.columns: - if frag in name.lower(): - return body[name] - return pd.Series([None] * len(body)) - - symbol = c("symbol stacji").map(lambda v: None if v is None or (isinstance(v, float) and v != v) else str(v).strip()) - nazwa = c("nazwa stacji").map(lambda v: None if v is None or (isinstance(v, float) and v != v) else str(v).strip()) - rozdz = c("rozdzielnia").map(lambda v: None if v is None or (isinstance(v, float) and v != v) else str(v).strip()) - miejsc = c("liczba dostępnych") - zko = c("zko") - - keep = symbol.notna() & nazwa.notna() - idx = [i for i in range(len(body)) if keep.iloc[i]] - - out = pd.DataFrame(index=range(len(idx))) - out["id_wniosku"] = None - out["id_wezla"] = [f"pse:{symbol.iloc[i]}:{_volt_tag(rozdz.iloc[i])}" for i in idx] - out["nazwa_wezla"] = [nazwa.iloc[i] for i in idx] - out["lokalizacja_tekst"] = [nazwa.iloc[i] for i in idx] - out["poziom_napiecia"] = [_volt_of(rozdz.iloc[i]) for i in idx] - out["klasa_zasobu"] = "NIEOKRESLONA" - out["status_procesu"] = "NIEOKRESLONY" - # moc_dostepna NIE jest wypełniana: źródło podaje LICZBĘ MIEJSC, nie moc. - out["moc_dostepna"] = None - out["ograniczenie_flaga"] = [ - (float(miejsc.iloc[i]) == 0.0) if _num(miejsc.iloc[i]) is not None else None - for i in idx - ] - out["data_publikacji"] = stan - out["_encja"] = "WEZEL" - out["_liczba_dostepnych_miejsc"] = [_num(miejsc.iloc[i]) for i in idx] - out["_symbol_stacji"] = [symbol.iloc[i] for i in idx] - out["_rozdzielnia"] = [rozdz.iloc[i] for i in idx] - out["_zko_pse"] = [zko.iloc[i] for i in idx] - return out, { - "plik": str(src), - "arkusz": sheet, - "encja": "WEZEL", - "n_wierszy": int(len(out)), - "stan_na": stan, - "uwaga": "źródło podaje liczbę wolnych miejsc przyłączenia, nie moc w MW; " - "moc_dostepna pozostaje pusta", - } - - # ------------------------------------------------------------------ - @staticmethod - def _find_header_row(d) -> int: - for i in range(min(12, len(d))): - vals = [str(v).strip().lower() for v in d.iloc[i].tolist() if isinstance(v, str)] - if any(v.startswith("id obiektu") for v in vals): - return i - raise ValueError("nie znaleziono wiersza nagłówka arkusza PSE") - - @staticmethod - def _read_vocab(xl) -> dict[str, list[str]]: - """Słowniki kontrolowane zadeklarowane przez sam dokument.""" - if _SHEET_VOCAB not in xl.sheet_names: - return {} - lr = xl.parse(_SHEET_VOCAB, header=None) - out: dict[str, list[str]] = {} - for j in range(lr.shape[1]): - vals = [re.sub(r"\s+", " ", str(v)).strip() - for v in lr[j].tolist() if isinstance(v, str) and str(v).strip()] - if len(vals) >= 2: - out[vals[0]] = vals[1:] - return out - - -def _read_sheet_bez_przypisow(src, sheet: str): - """Wczytaj arkusz, odłączając ODNOŚNIKI PRZYPISÓW od treści komórek. - - Dlaczego to nie jest kosmetyka. Pomiar dokładności na wzorcu odczytanym - wzrokowo pokazał siedem niezgodności u PSE i wszystkie miały jedną przyczynę: - PSE oznacza część wartości odnośnikiem przypisu zapisanym jako INDEKS GÓRNY - wewnątrz komórki -- lokalizacja "WYP" z przypisem M, "CPK" z przypisem K, - "SE EJ" z F, "Norki" z Y, oraz moce "300,1", "50,1" i "300" z przypisem E. - Płaski odczyt sklejał je w "WYPM", "CPKK", "300,1E" -- w polu tekstowym - powstawał zanieczyszczony ciąg, a w polu liczbowym wartość PRZEPADAŁA, bo - "300,1E" nie jest liczbą. - - Rozstrzygające jest to, że odnośnik daje się rozpoznać STRUKTURALNIE: - openpyxl wystawia komórkę jako ``CellRichText``, a fragment przypisu ma - ``font.vertAlign == "superscript"``. Odcinamy więc po FORMATOWANIU, a nie - przez zgadywanie, że końcowa wielka litera "pewnie jest przypisem" -- takie - zgadywanie okaleczyłoby prawdziwe nazwy stacji kończące się literą. - Sam odnośnik nie jest wyrzucany: wraca w rozszerzeniu ``_przypisy``. - """ - import pandas as pd - from openpyxl import load_workbook - from openpyxl.cell.rich_text import CellRichText, TextBlock - - wb = load_workbook(src, rich_text=True, data_only=True) - ws = wb[sheet] - rows, marks = [], {} - for ri, row in enumerate(ws.iter_rows(values_only=False)): - out = [] - for ci, cell in enumerate(row): - v = cell.value - if isinstance(v, CellRichText): - keep, sup = [], [] - for part in v: - if isinstance(part, TextBlock): - if getattr(part.font, "vertAlign", None) == "superscript": - sup.append(str(part.text)) - continue - keep.append(str(part.text)) - else: - keep.append(str(part)) - if sup: - marks[(ri, ci)] = "".join(sup) - v = "".join(keep) - out.append(v) - rows.append(out) - wb.close() - return pd.DataFrame(rows), marks - - -def _num(v) -> Optional[float]: - if v is None or (isinstance(v, float) and v != v): - return None - try: - return float(str(v).strip().replace(",", ".")) - except ValueError: - return None - - -def _volt_of(rozdzielnia: Any) -> Optional[str]: - m = re.search(r"(\d+)\s*kV", str(rozdzielnia or ""), re.IGNORECASE) - return f"{m.group(1)} kV" if m else None - - -def _volt_tag(rozdzielnia: Any) -> str: - m = re.search(r"(\d+)", str(rozdzielnia or "")) - return m.group(1) if m else "nn" diff --git a/build/lib/gridqueue/adapters/pl_stoen.py b/build/lib/gridqueue/adapters/pl_stoen.py deleted file mode 100644 index 53ca65d..0000000 --- a/build/lib/gridqueue/adapters/pl_stoen.py +++ /dev/null @@ -1,194 +0,0 @@ -"""Adapter: Stoen Operator Sp. z o.o. (PL, obszar Warszawy). - -Trzy rozłączne zestawienia, po jednym na punkt obowiązku: - * pkt 1 -- podmioty ubiegające się o przyłączenie (10 kolumn, ~29 stron) - * pkt 3 -- złożone wnioski o określenie warunków (10 kolumn) - * pkt 4 -- wydane odmowy określenia warunków (11 kolumn) - -Wszystkie trzy mają pełną siatkę liniową i DWUPOZIOMOWY nagłówek powtarzany na -każdej stronie (drugi poziom rozbija "Lokalizacja" na miejscowość/adres oraz -"Moc przyłączeniowa [kW]" na Podstawa/Rezerwa). Typ zestawienia rozpoznajemy po -treści nagłówka, nie po nazwie pliku. - -Uwaga merytoryczna do zapisania w manuskrypcie: Stoen NIE rozróżnia kierunku mocy. -Kolumna "Podstawa" jest mocą przyłączeniową niezależnie od tego, czy instalacja -jest odbiorcza czy wytwórcza. Mapujemy ją na ``moc_pobierana`` (zgodnie ze -zmierzoną macierzą pokrycia) i deklarujemy brak rozróżnienia jako cechę źródła, -a nie jako lukę parsera. -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..layout import detect_ruled_columns, extract_ruled_page -from ..schema import canonical_date, canonical_power_kw -from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status, norm_text - -_RE_LP = re.compile(r"^\d+\.?$") - -LAYOUTS: dict[str, tuple[str, ...]] = { - "podmioty": ( - "lp", "rodzaj_klienta", "miejscowosc", "adres", "moc_podstawa", "moc_rezerwa", - "rodzaj_instalacji", "data_warunkow", "data_umowy", "data_energizacji", - ), - "wnioski": ( - "lp", "rodzaj_klienta", "miejscowosc", "adres", "moc_podstawa", "moc_rezerwa", - "rodzaj_instalacji", "data_zlozenia", "data_zaliczki", "status_wniosku", - ), - "odmowy": ( - "lp", "rodzaj_klienta", "miejscowosc", "adres", "moc_podstawa", "moc_rezerwa", - "rodzaj_instalacji", "data_zlozenia", "data_zaliczki", "powod_odmowy", - "data_odmowy", - ), -} - - -def detect_layout(header_text: str) -> Optional[str]: - t = norm_text(header_text) - if "odmowa przylaczenia" in t or "data odmowy" in t: - return "odmowy" - if "status rozpatrywania" in t: - return "wnioski" - if "data rozpoczecia" in t and "data zawarcia" in t: - return "podmioty" - return None - - -class StoenAdapter(Adapter): - publisher = "Stoen Operator Sp. z o.o." - jurisdiction = "PL" - declared_fields = ( - "id_wniosku", "lokalizacja_tekst", "klasa_zasobu", "moc_pobierana", - "moc_zarezerwowana", "status_procesu", "data_wniosku", "data_warunkow", - "data_odmowy", "powod_odmowy", "data_umowy", "data_energizacji", - "data_publikacji", - ) - declared_extensions = { - "_data_zaliczki": "data wpłaty zaliczki", - "_rodzaj_podmiotu": "rodzaj klienta (osoba prawna / fizyczna)", - "_miejscowosc": "miejscowość wydzielona z lokalizacji", - "_adres": "adres wydzielony z lokalizacji", - "_zestawienie": "który punkt art. 7 ust. 8l realizuje dany wiersz", - "_rodzaj_instalacji_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status rozpatrywania wniosku tak, jak w dokumencie", - } - detect_patterns = (r"stoen",) - - def __init__(self, data_publikacji: Optional[str] = None): - self.data_publikacji = data_publikacji - - # ------------------------------------------------------------------ - def parse(self, source) -> ParseResult: - """``source``: ścieżka do jednego PDF albo lista ścieżek.""" - import pandas as pd - - sources = [source] if isinstance(source, (str, bytes)) or hasattr(source, "read") \ - else list(source) - frames, reports = [], [] - for src in sources: - f, r = self._parse_one(src) - frames.append(f) - reports.append(r) - df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka wektorowa), nagłówek dwupoziomowy", - "dokumenty": reports, - "n_wierszy": int(len(df)), - "data_publikacji": self.data_publikacji, - } - return ParseResult(self.finalize(df, document="; ".join(map(str, sources))), report) - - # ------------------------------------------------------------------ - def _parse_one(self, src): - import pandas as pd - import pdfplumber - - rows: list[list[Optional[str]]] = [] - layout = None - n_pages = 0 - with pdfplumber.open(src) as pdf: - for page in pdf.pages: - n_pages += 1 - geom = detect_ruled_columns(page) - if geom.n_cols < 2: - continue - tbl = extract_ruled_page(page, geom) - if not tbl: - continue - if layout is None: - layout = detect_layout(" ".join( - (c or "") for r in tbl[:2] for c in r)) - for row in tbl: - if row and _RE_LP.match((row[0] or "").strip()): - rows.append(row) - if self.data_publikacji is None: - self.data_publikacji = _stan_na(page.extract_text() or "") - if layout is None: - raise ValueError(f"nie rozpoznano układu zestawienia Stoen w {src!r}") - - cols = LAYOUTS[layout] - raw = pd.DataFrame( - [(r + [None] * len(cols))[: len(cols)] for r in rows], columns=cols - ).map(lambda v: re.sub(r"\s+", " ", v).strip() if isinstance(v, str) else v) - - out = pd.DataFrame(index=raw.index) - out["id_wniosku"] = [f"stoen:{layout}:{i + 1}" for i in range(len(raw))] - miejsc = raw["miejscowosc"].fillna("") - adres = raw["adres"].fillna("") - out["lokalizacja_tekst"] = [ - ", ".join(x for x in (m.strip(), a.strip()) if x) or None - for m, a in zip(miejsc, adres) - ] - out["klasa_zasobu"] = raw["rodzaj_instalacji"].map(harmonize_klasa) - out["moc_pobierana"] = raw["moc_podstawa"].map(lambda v: canonical_power_kw(v, "kW")) - out["moc_zarezerwowana"] = raw["moc_rezerwa"].map(lambda v: canonical_power_kw(v, "kW")) - for c in ("data_wniosku", "data_warunkow", "data_odmowy", "data_umowy", - "data_energizacji"): - out[c] = None - if layout == "podmioty": - out["data_warunkow"] = raw["data_warunkow"].map(canonical_date) - out["data_umowy"] = raw["data_umowy"].map(canonical_date) - out["data_energizacji"] = raw["data_energizacji"].map(canonical_date) - _ok = lambda v: v is not None and not (isinstance(v, float) and v != v) - out["status_procesu"] = [ - "PRZYLACZONY" if _ok(e) else ("UMOWA_OBOWIAZUJACA" if _ok(u) else - ("WARUNKI_WYDANE" if _ok(w) else "NIEOKRESLONY")) - for e, u, w in zip(out["data_energizacji"], out["data_umowy"], - out["data_warunkow"]) - ] - out["_status_raw"] = None - elif layout == "wnioski": - out["data_wniosku"] = raw["data_zlozenia"].map(canonical_date) - out["_data_zaliczki"] = raw["data_zaliczki"].map(canonical_date) - out["status_procesu"] = raw["status_wniosku"].map(harmonize_status) - out["_status_raw"] = raw["status_wniosku"].replace("", None) - else: # odmowy - out["data_wniosku"] = raw["data_zlozenia"].map(canonical_date) - out["data_odmowy"] = raw["data_odmowy"].map(canonical_date) - out["_data_zaliczki"] = raw["data_zaliczki"].map(canonical_date) - out["powod_odmowy"] = raw["powod_odmowy"].replace("", None) - out["status_procesu"] = "ODMOWA" - out["_status_raw"] = raw["powod_odmowy"].replace("", None) - out["data_publikacji"] = self.data_publikacji - out["_rodzaj_podmiotu"] = raw["rodzaj_klienta"].replace("", None) - out["_miejscowosc"] = miejsc.replace("", None) - out["_adres"] = adres.replace("", None) - out["_zestawienie"] = layout - out["_rodzaj_instalacji_raw"] = raw["rodzaj_instalacji"].replace("", None) - out["_lp_dokumentu"] = raw["lp"] - - return out, { - "plik": str(src), - "uklad": layout, - "strony": n_pages, - "n_kolumn_zrodlowych": len(cols), - "n_wierszy": int(len(out)), - } - - -def _stan_na(text: str) -> Optional[str]: - m = re.search(r"[Ss]tan\s+na\s+(?:dzień\s+)?(\d{2}\.\d{2}\.\d{4})", text) - return canonical_date(m.group(1)) if m else None diff --git a/build/lib/gridqueue/adapters/pl_tauron.py b/build/lib/gridqueue/adapters/pl_tauron.py deleted file mode 100644 index c0a1aca..0000000 --- a/build/lib/gridqueue/adapters/pl_tauron.py +++ /dev/null @@ -1,161 +0,0 @@ -"""Adapter: TAURON Dystrybucja S.A. (PL). - -Dokument: "Informacja o przyłączanych obiektach i wydanych odmowach", PDF ~99 stron, -tabela z pełną siatką liniową, 27 kolumn, nagłówek tylko na pierwszej stronie, -legenda rodzajów instalacji na stronie ostatniej. - -Kluczowa własność: daty SĄ w dokumencie rozdzielone na osobne kolumny (złożenie, -zaliczka, warunki, odmowa, utrata ważności, umowa, energizacja, rozwiązanie, -wygaśnięcie). Poprzedni parser regexowy zlewał je w jedno pole zbiorcze -- nie -dlatego, że dokument ich nie rozdziela, tylko dlatego, że spłaszczony tekst gubi -granice pustych komórek. Wydobycie po siatce odzyskuje je wprost. - -Lokalizacja jest podawana jako WEWNĘTRZNY KOD STACJI (np. "SKB3", "RCB4"). -Słownika kodów TAURON nie publikuje, więc rozwiązywacz lokalizacji zwraca dla -tego publikującego brak z jawnym powodem -- nie zgadujemy. -""" - -from __future__ import annotations - -import re -from typing import Any, Optional - -from ..layout import ColumnGeometry, detect_ruled_columns, extract_ruled_page -from ..schema import canonical_date, canonical_power_kw -from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status, norm_text - -#: kolejność kolumn w dokumencie TAURONA (indeks -> znaczenie źródłowe) -COLUMNS = ( - "lp", "id_obiektu", "nazwa_osd", "rodzaj_podmiotu", "lokalizacja_stacja", - "poziom_napiecia", "wiele_miejsc", "rodzaj_instalacji", - "moc_wprowadzana_mw", "moc_pobierana_mw", - "mz_pv_mw", "mz_fw_mw", "mz_mee_rozl_mw", "mz_mee_lad_mw", "mz_odb_mw", "mz_inne_mw", - "status_etapu", "data_zlozenia", "data_zaliczki", "data_warunkow", - "data_odmowy", "uzasadnienie_odmowy", "data_utraty_waznosci", - "data_umowy", "data_energizacji", "data_rozwiazania", "data_wygasniecia", -) - -_RE_LP = re.compile(r"^\d+$") -_RE_LEGEND = re.compile(r"^([A-ZĘÓŁŚŻŹĆŃ]{2,4})\s*[-–]\s*(.+)$") - - -class TauronAdapter(Adapter): - publisher = "TAURON Dystrybucja S.A." - jurisdiction = "PL" - declared_fields = ( - "id_wniosku", "id_wezla", "lokalizacja_tekst", "poziom_napiecia", - "klasa_zasobu", "moc_wprowadzana", "moc_pobierana", "status_procesu", - "data_wniosku", "data_warunkow", "data_odmowy", "powod_odmowy", - "data_umowy", "data_energizacji", "data_publikacji", - ) - declared_extensions = { - "_data_zaliczki": "data wpłaty zaliczki na poczet opłaty za przyłączenie", - "_data_utraty_waznosci": "data utraty ważności lub rezygnacji z warunków", - "_data_rozwiazania": "data rozwiązania/wypowiedzenia/odstąpienia od umowy", - "_data_wygasniecia": "data wygaśnięcia umowy z mocy prawa", - "_wiele_miejsc": "wniosek obejmuje wiele miejsc przyłączenia lub poziomów napięcia", - "_rodzaj_podmiotu": "osoba prawna / osoba fizyczna", - "_moc_zainstalowana_kw": "moc zainstalowana w rozbiciu na technologie (suma)", - "_rodzaj_instalacji_raw": "oznaczenie rodzaju instalacji tak, jak w dokumencie", - "_status_raw": "status etapu projektu tak, jak w dokumencie", - } - detect_patterns = (r"tauron", r"TAURON Dystrybucja") - - def __init__(self, data_publikacji: Optional[str] = None): - self.data_publikacji = data_publikacji - - # ------------------------------------------------------------------ - def parse(self, source) -> ParseResult: - import pandas as pd - import pdfplumber - - raw_rows: list[list[Optional[str]]] = [] - legend: dict[str, str] = {} - stats = {"strony": 0, "strony_bez_siatki": [], "geometrie": set()} - with pdfplumber.open(source) as pdf: - if self.data_publikacji is None: - self.data_publikacji = _cover_date(pdf.pages[0].extract_text() or "") - modal_geom: Optional[ColumnGeometry] = None - for page in pdf.pages: - stats["strony"] += 1 - geom = detect_ruled_columns(page) - if geom.n_cols < 2: - stats["strony_bez_siatki"].append(page.page_number) - legend.update(_parse_legend(page.extract_text() or "")) - continue - if modal_geom is None: - modal_geom = geom - stats["geometrie"].add(tuple(round(x, 0) for x in geom.bounds)) - for row in extract_ruled_page(page, geom): - if row and _RE_LP.match((row[0] or "").strip()): - raw_rows.append(row) - - n_expected = len(COLUMNS) - raw = pd.DataFrame( - [(r + [None] * n_expected)[:n_expected] for r in raw_rows], columns=COLUMNS - ) - raw = raw.map(lambda v: re.sub(r"\s+", " ", v).strip() if isinstance(v, str) else v) - - out = pd.DataFrame(index=raw.index) - out["id_wniosku"] = raw["id_obiektu"].replace("", None) - out["id_wezla"] = raw["lokalizacja_stacja"].replace("", None) - out["lokalizacja_tekst"] = raw["lokalizacja_stacja"].replace("", None) - out["poziom_napiecia"] = raw["poziom_napiecia"].replace("", None) - out["klasa_zasobu"] = raw["rodzaj_instalacji"].map(harmonize_klasa) - out["moc_wprowadzana"] = raw["moc_wprowadzana_mw"].map( - lambda v: canonical_power_kw(v, "MW")) - out["moc_pobierana"] = raw["moc_pobierana_mw"].map( - lambda v: canonical_power_kw(v, "MW")) - out["status_procesu"] = raw["status_etapu"].map(harmonize_status) - for dst, src in ( - ("data_wniosku", "data_zlozenia"), - ("data_warunkow", "data_warunkow"), - ("data_odmowy", "data_odmowy"), - ("data_umowy", "data_umowy"), - ("data_energizacji", "data_energizacji"), - ): - out[dst] = raw[src].map(canonical_date) - out["powod_odmowy"] = raw["uzasadnienie_odmowy"].replace("", None) - out["data_publikacji"] = self.data_publikacji - - # rozszerzenia deklarowane - out["_data_zaliczki"] = raw["data_zaliczki"].map(canonical_date) - out["_data_utraty_waznosci"] = raw["data_utraty_waznosci"].map(canonical_date) - out["_data_rozwiazania"] = raw["data_rozwiazania"].map(canonical_date) - out["_data_wygasniecia"] = raw["data_wygasniecia"].map(canonical_date) - out["_wiele_miejsc"] = raw["wiele_miejsc"].replace("", None) - out["_rodzaj_podmiotu"] = raw["rodzaj_podmiotu"].replace("", None) - mz_cols = ["mz_pv_mw", "mz_fw_mw", "mz_mee_rozl_mw", "mz_mee_lad_mw", - "mz_odb_mw", "mz_inne_mw"] - mz = raw[mz_cols].map(lambda v: canonical_power_kw(v, "MW")) - out["_moc_zainstalowana_kw"] = mz.sum(axis=1, min_count=1) - out["_rodzaj_instalacji_raw"] = raw["rodzaj_instalacji"].replace("", None) - out["_status_raw"] = raw["status_etapu"].replace("", None) - out["_lp_dokumentu"] = raw["lp"] - - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka wektorowa)", - "strony": stats["strony"], - "strony_bez_siatki": stats["strony_bez_siatki"], - "n_geometrii_kolumn": len(stats["geometrie"]), - "n_kolumn_zrodlowych": n_expected, - "n_wierszy": int(len(out)), - "legenda_rodzajow": legend, - "data_publikacji": self.data_publikacji, - } - return ParseResult(self.finalize(out, document=str(source)), report) - - -def _cover_date(text: str) -> Optional[str]: - m = re.search(r"Stan\s+na\s+(\d{2}\.\d{2}\.\d{4})", text) - return canonical_date(m.group(1)) if m else None - - -def _parse_legend(text: str) -> dict[str, str]: - out: dict[str, str] = {} - for line in text.splitlines(): - m = _RE_LEGEND.match(line.strip()) - if m: - out[m.group(1)] = m.group(2).strip() - return out diff --git a/build/lib/gridqueue/adapters/pt_eredes.py b/build/lib/gridqueue/adapters/pt_eredes.py deleted file mode 100644 index 981d4db..0000000 --- a/build/lib/gridqueue/adapters/pt_eredes.py +++ /dev/null @@ -1,181 +0,0 @@ -"""Adapter: E-REDES (PT), zdolność przyjęcia krajowej sieci dystrybucyjnej. - -Źródło jest trzecim trybem wydania w panelu: nie dokument do druku i nie plik -na stronie, lecz **zbiór na portalu otwartych danych z interfejsem REST**. -Publikacja jest kwartalna, tak jak polski obowiązek, a jednostką wiersza jest -podstacja albo punkt cięcia sieci wysokiego napięcia. - -Co ten adapter wnosi do panelu ------------------------------- -Pierwsze zagraniczne źródło wypełniające encję **WĘZEŁ**. Dotąd moc dostępną -w węźle ujawniał wyłącznie jeden publikujący polski, więc kryterium „dostępna -moc przyłączeniowa" dało się policzyć w jednej jurysdykcji. Źródło portugalskie -podaje ponadto **skład grupy podstacji**, czyli dokładnie tę informację, która -w panelu polskim umożliwia przypisanie wniosków do węzła. - -Rozstrzygnięcie jednostek, przeczytaj, zanim zaczniesz porównywać ------------------------------------------------------------------- -Publikujący podaje zdolność przyjęcia i moce przyłączone w **MVA**, czyli -w mocy pozornej. Jednostką kanoniczną schematu jest **kW mocy czynnej**. Są to -różne wielkości fizyczne i przeliczenie jednej na drugą wymaga założenia -o współczynniku mocy, którego publikujący nie podaje. - -Dlatego pole `moc_dostepna` pozostaje **puste**, a wartości w MVA trafiają do -pól rozszerzenia wraz z jawnie zapisaną jednostką źródłową. Jest to ta sama -zasada, którą zastosowano wobec publikującego podającego liczbę wolnych miejsc -przyłączeniowych zamiast mocy: wpisanie liczby w pole o innej jednostce byłoby -fabrykacją, a nie harmonizacją. - -Rdzeń encji WĘZEŁ jest mimo to spełniony, bo realizuje go drugi człon -alternatywy, `ograniczenie_flaga`, ustawiana na podstawie zerowej zdolności -przyjęcia. Zero zdolności przyjęcia jest wartością ujawnioną i oznacza -ograniczenie, a nie brak danych. - -Format wejścia --------------- -Eksport CSV z portalu (separator średnik, nagłówki techniczne, nie etykiety). -Adapter celowo czyta PLIK, a nie odpytuje interfejsu przy parsowaniu: dzięki -temu wynik jest odtwarzalny z manifestu z sumą kontrolną, tak jak u pozostałych -publikujących. -""" - -from __future__ import annotations - -import csv -from pathlib import Path - -from .base import Adapter, ParseResult - -PUBLISHER = "E-REDES S.A." -JURISDICTION = "PT" -#: Jednostka, w której publikujący podaje moce. NIE jest to jednostka kanoniczna -#: schematu (kW mocy czynnej) i nie jest na nią przeliczana. -SOURCE_POWER_UNIT = "MVA" - -#: Kolumny zdolności przyjęcia w podziale na poziomy napięcia, od najwyższego. -#: Służą wyłącznie do ustalenia poziomu napięcia, na którym zdolność występuje; -#: ich wartości nie wchodzą do pola mocy z powodu różnicy jednostek. -_KOLUMNY_NAPIEC = [ - ("capacidade_de_recepcao_at_mva_ultimo_trimestre", "AT"), - ("capacidade_de_recepcao_mt_30kv_mva_ultimo_trimestre", "30 kV"), - ("capacidade_de_recepcao_mt_15kv_mva_ultimo_trimestre", "15 kV"), - ("capacidade_de_recepcao_mt_10kv_mva_ultimo_trimestre", "10 kV"), -] - -_TYP_INSTALACJI = { - "SE AT": "substation_HV", - "PC AT": "cutting_point_HV", -} - - -def _liczba(v) -> float | None: - """Liczba z zapisu portalowego; przecinek dziesiętny dopuszczony.""" - if v is None: - return None - s = str(v).strip().replace("\xa0", "").replace(" ", "") - if s == "" or s.lower() in {"none", "nan"}: - return None - s = s.replace(",", ".") - try: - return float(s) - except ValueError: - return None - - -def _kwartal_na_date(v) -> str | None: - """'2T2026' -> '2026-06-30'. Publikacja kwartalna, dzień ostatni kwartału.""" - s = str(v or "").strip().upper() - if len(s) == 6 and s[1] == "T" and s[0].isdigit() and s[2:].isdigit(): - kw, rok = int(s[0]), int(s[2:]) - koniec = {1: "03-31", 2: "06-30", 3: "09-30", 4: "12-31"}.get(kw) - if koniec: - return f"{rok}-{koniec}" - return None - - -class EredesAdapter(Adapter): - publisher = PUBLISHER - jurisdiction = JURISDICTION - declared_fields = ( - "id_wezla", "nazwa_wezla", "lokalizacja_tekst", "poziom_napiecia", - "ograniczenie_flaga", "data_publikacji", - ) - declared_extensions = { - "_jednostka_mocy_zrodlowa": "jednostka, w której publikujący podaje moce (MVA)", - "_moc_dostepna_mva": "zdolność przyjęcia SN+WN w MVA, tak jak w źródle", - "_moc_przylaczona_mva": "moc przyłączona w MVA", - "_moc_zakontraktowana_mva": "moc zakontraktowana w MVA", - "_moc_w_potwierdzaniu_mva": "moc w trakcie potwierdzania w MVA", - "_typ_instalacji": "podstacja albo punkt cięcia sieci wysokiego napięcia", - "_dystrykt": "dystrykt administracyjny", - "_gmina": "gmina", - "_nuts3": "jednostka statystyczna NUTS 3", - "_wezel_rnt": "węzeł sieci przesyłowej, z którym połączona jest podstacja", - } - detect_patterns = (r"capacidade.?rececao", r"e.?redes", r"\brnd\b") - - def parse(self, source) -> ParseResult: - path = Path(str(source)) - with path.open(encoding="utf-8-sig", newline="") as f: - wiersze = list(csv.DictReader(f, delimiter=";")) - - rekordy, bez_kodu, zerowa = [], 0, 0 - for w in wiersze: - kod = (w.get("codigo") or "").strip() - if not kod: - bez_kodu += 1 - zdolnosc = _liczba(w.get("capacidade_de_recepcao_mt_at_mva_ultimo_trimestre")) - ograniczenie = None - if zdolnosc is not None: - ograniczenie = zdolnosc == 0.0 - zerowa += int(ograniczenie) - - napiecia = [etykieta for kol, etykieta in _KOLUMNY_NAPIEC - if (_liczba(w.get(kol)) or 0.0) > 0.0] - - rekordy.append({ - "id_wezla": kod or None, - "nazwa_wezla": (w.get("instalacao") or "").strip() or None, - # Skład grupy podstacji, odpowiednik listy stacji w wierszu - # węzłowym publikującego polskiego, więc trafia w to samo pole. - "lokalizacja_tekst": (w.get("grupo_de_subestacoes_rari") or "").strip() or None, - "poziom_napiecia": ", ".join(napiecia) or None, - "moc_dostepna": None, # jednostka źródłowa to MVA, patrz nagłówek modułu - "moc_zarezerwowana": None, # jw. - "ograniczenie_flaga": ograniczenie, - "data_publikacji": _kwartal_na_date(w.get("data_ultimo_trimestre")), - "_encja": "WEZEL", - "_jednostka_mocy_zrodlowa": SOURCE_POWER_UNIT, - "_moc_dostepna_mva": zdolnosc, - "_moc_przylaczona_mva": _liczba(w.get("potencia_de_ligacao_ligado_mva_ultimo_trimestre")), - "_moc_zakontraktowana_mva": _liczba(w.get("potencia_de_ligacao_comprometido_mva_ultimo_trimestre")), - "_moc_w_potwierdzaniu_mva": _liczba(w.get("potencia_de_ligacao_em_confirmacao_mva_ultimo_trimestre")), - "_typ_instalacji": _TYP_INSTALACJI.get( - (w.get("tipo_de_instalacao") or "").strip(), - (w.get("tipo_de_instalacao") or "").strip() or None), - "_dystrykt": (w.get("distrito") or "").strip() or None, - "_gmina": (w.get("concelho") or "").strip() or None, - "_nuts3": (w.get("nut3") or "").strip() or None, - "_wezel_rnt": (w.get("ligacao_rnt_barramento_60kv_ultimo_trimestre") or "").strip() or None, - }) - - import pandas as pd - - df = self.finalize(pd.DataFrame(rekordy), document=path.name) - notes = { - "publikujacy": PUBLISHER, - "jurysdykcja": JURISDICTION, - "tryb_wydania": "portal otwartych danych, eksport CSV z interfejsu REST", - "wierszy": int(len(df)), - "wierszy_bez_kodu_instalacji": bez_kodu, - "wezlow_o_zerowej_zdolnosci_przyjecia": zerowa, - "jednostka_mocy_zrodlowa": SOURCE_POWER_UNIT, - "moc_dostepna_pusta_z_powodu_jednostki": True, - "uwaga_jednostki": ( - "Publikujący podaje moce w MVA (moc pozorna); jednostką kanoniczną schematu " - "jest kW mocy czynnej. Przeliczenie wymagałoby nieujawnionego współczynnika " - "mocy, więc pole moc_dostepna pozostaje puste, a wartości źródłowe są " - "w polach rozszerzenia z jawną jednostką." - ), - } - return ParseResult(frame=df, report=notes) diff --git a/build/lib/gridqueue/adapters/uk_nationalgrid.py b/build/lib/gridqueue/adapters/uk_nationalgrid.py deleted file mode 100644 index 707615f..0000000 --- a/build/lib/gridqueue/adapters/uk_nationalgrid.py +++ /dev/null @@ -1,166 +0,0 @@ -"""Adapter: National Grid Electricity Distribution (UK) -- zbiór "Connection Queue". - -Ten adapter istnieje po to, żeby udowodnić przenoszalność schematu, a nie żeby -sparsować kolejny PDF. Brytyjski publikujący wystawia te same informacje jako -45 osobnych plików CSV w katalogu CKAN -- dane są już tabelaryczne, więc CAŁA -warstwa wydobycia po układzie strony jest tu zbędna. To jest dokładnie ta -asymetria, którą narzędzie ma pokazać: w jurysdykcji o dobrych danych parser -jest niepotrzebny, w Polsce jest warunkiem dostępu do treści obowiązku. - -Dostęp: publiczny endpoint ``package_search`` CKAN, bez klucza. Klient -przedstawia się uczciwie w nagłówku User-Agent; nie podszywamy się pod przeglądarkę. -""" - -from __future__ import annotations - -import io -import re -from typing import Any, Optional - -from ..schema import canonical_date, canonical_power_kw -from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status - -CKAN_BASE = "https://connecteddata.nationalgrid.co.uk/api/3/action" -USER_AGENT = ( - "gridqueue/0.1 (research prototype; harmonisation of statutory " - "grid-connection disclosures; contact via repository)" -) - - -class NationalGridAdapter(Adapter): - publisher = "National Grid Electricity Distribution" - jurisdiction = "UK" - declared_fields = ( - "id_wniosku", "id_wezla", "nazwa_wezla", "lokalizacja_tekst", "klasa_zasobu", - "moc_wprowadzana", "moc_pobierana", "ograniczenie_flaga", "pozycja_w_kolejce", - "status_procesu", - ) - declared_extensions = { - "_licence_area": "obszar licencyjny operatora", - "_gsp": "Grid Supply Point", - "_machine_id": "identyfikator jednostki w ramach lokalizacji", - "_machine_export_kw": "moc eksportowa pojedynczej jednostki", - "_machine_import_kw": "moc importowa pojedynczej jednostki", - "_tanm": "Transmission Area Network Management (flaga ograniczenia)", - "_danm": "Distribution Area Network Management (flaga ograniczenia)", - "_plik_zrodlowy": "nazwa zasobu CSV w katalogu CKAN", - "_status_raw": "status tak, jak w źródle", - } - detect_patterns = (r"connection.?queue", r"national.?grid") - - def __init__(self, dataset: str = "connection-queue", timeout: int = 90): - self.dataset = dataset - self.timeout = timeout - - # ------------------------------------------------------------------ - def fetch(self) -> tuple["Any", dict]: - """Pobierz wszystkie zasoby CSV zbioru z katalogu CKAN.""" - import pandas as pd - import requests - - s = requests.Session() - s.headers.update({"User-Agent": USER_AGENT}) - r = s.get(f"{CKAN_BASE}/package_search", - params={"q": self.dataset, "rows": 50}, timeout=self.timeout) - r.raise_for_status() - pkgs = [p for p in r.json()["result"]["results"] if p["name"] == self.dataset] - if not pkgs: - raise LookupError(f"nie znaleziono zbioru {self.dataset!r} w katalogu CKAN") - pkg = pkgs[0] - resources = [res for res in pkg["resources"] - if (res.get("format") or "").upper() == "CSV"] - frames, ok, failed = [], [], [] - for res in resources: - try: - rr = s.get(res["url"], timeout=self.timeout) - rr.raise_for_status() - d = pd.read_csv(io.BytesIO(rr.content)) - d["_plik_zrodlowy"] = res.get("name") or res["url"].rsplit("/", 1)[-1] - frames.append(d) - ok.append(res.get("name")) - except Exception as exc: # zapisujemy, nie ukrywamy - failed.append({"zasob": res.get("name"), "blad": f"{type(exc).__name__}: {exc}"}) - raw = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame() - meta = { - "zbior": pkg["name"], - "tytul": pkg.get("title"), - "n_zasobow_csv": len(resources), - "pobrane": len(ok), - "nieudane": failed, - "ostatnia_modyfikacja": pkg.get("metadata_modified"), - } - return raw, meta - - # ------------------------------------------------------------------ - def parse(self, source=None) -> ParseResult: - """``source``: None -> pobierz z CKAN; ścieżka/DataFrame -> użyj lokalnie.""" - import pandas as pd - - if source is None: - raw, meta = self.fetch() - elif isinstance(raw_src := source, pd.DataFrame): - raw, meta = raw_src.copy(), {"zrodlo": "DataFrame"} - else: - raw, meta = pd.read_csv(raw_src), {"zrodlo": str(raw_src)} - - def col(*names): - for n in names: - if n in raw.columns: - return raw[n] - return pd.Series([None] * len(raw), index=raw.index) - - out = pd.DataFrame(index=raw.index) - site = col("Site ID").astype("object") - app = col("Application ID").astype("object") - mach = col("Machine ID").astype("object") - out["id_wniosku"] = [ - "nged:" + ":".join(str(x) for x in t if x is not None and str(x) != "nan") - for t in zip(site, app, mach) - ] - out["id_wezla"] = col("Bus Number").map( - lambda v: None if pd.isna(v) else str(int(v)) if float(v).is_integer() else str(v)) - out["nazwa_wezla"] = col("Bus Name") - out["lokalizacja_tekst"] = col("GSP") - out["klasa_zasobu"] = col("Fuel type").map(harmonize_klasa) - out["moc_wprowadzana"] = col("Site Export Capacity (MW)").map( - lambda v: canonical_power_kw(v, "MW")) - out["moc_pobierana"] = col("Site Import Capacity (MW)").map( - lambda v: canonical_power_kw(v, "MW")) - tanm = col("TANM").map(_as_bool) - danm = col("DANM").map(_as_bool) - out["ograniczenie_flaga"] = [bool(a) or bool(b) for a, b in zip(tanm, danm)] - out["pozycja_w_kolejce"] = col("Position").map( - lambda v: None if pd.isna(v) else float(v)) - out["status_procesu"] = col("Status").map(harmonize_status) - out["_status_raw"] = col("Status") - out["_licence_area"] = col("Licence Area") - out["_gsp"] = col("GSP") - out["_machine_id"] = mach - out["_machine_export_kw"] = col("Machine Export Capacity (MW)").map( - lambda v: canonical_power_kw(v, "MW")) - out["_machine_import_kw"] = col("Machine Import Capacity (MW)").map( - lambda v: canonical_power_kw(v, "MW")) - out["_tanm"] = tanm - out["_danm"] = danm - out["_plik_zrodlowy"] = col("_plik_zrodlowy", "_plik") - - report = { - "publikujacy": self.publisher, - "strategia_wydobycia": "CSV z katalogu CKAN (dane już tabelaryczne)", - "n_wierszy": int(len(out)), - "katalog": meta, - } - return ParseResult(self.finalize(out, document=str(meta.get("zbior", source))), report) - - -def _as_bool(v) -> Optional[bool]: - import pandas as pd - - if v is None or (isinstance(v, float) and pd.isna(v)): - return None - s = str(v).strip().lower() - if s in {"true", "1", "yes", "y", "tak"}: - return True - if s in {"false", "0", "no", "n", "nie"}: - return False - return None diff --git a/build/lib/gridqueue/analysis.py b/build/lib/gridqueue/analysis.py deleted file mode 100644 index 5ae8150..0000000 --- a/build/lib/gridqueue/analysis.py +++ /dev/null @@ -1,374 +0,0 @@ -"""Analizy badawcze na zharmonizowanym panelu. - -Dwie rodziny funkcji, obie wyprowadzone z pytań, które rejestr pozwala zadać -dopiero po harmonizacji: - -* **obciążenie węzła**, zestawienie mocy objętej wnioskami z ujawnioną mocą - dostępną w węźle. Jest to policzalna wersja kryterium „dostępna moc - przyłączeniowa", które przeglądy literatury opisują jako niemierzalne - z powodu braku danych. Wymaga publikującego, który ujawnia JEDNOCZEŚNIE moc - dostępną w węźle i skład stacji wchodzących do węzła; -* **czas rozpatrywania z cenzurowaniem**, wnioski bez daty rozstrzygnięcia nie - są brakiem danych, tylko obserwacjami uciętymi na dacie publikacji. Liczenie - mediany wyłącznie na przypadkach kompletnych ZANIŻA ją, i to tym silniej, im - dłuższy jest rzeczywisty czas rozpatrywania. - -Żadna z tych funkcji nie jest specyficzna dla publikującego: specyficzne są -adaptery, a to jest warstwa nad schematem. -""" - -from __future__ import annotations - -import math -import re -import unicodedata -from dataclasses import dataclass, field -from typing import Iterable, Sequence - -import pandas as pd - -__all__ = [ - "PRZEDROSTKI_STACJI", - "normalizuj_nazwe", - "station_node_map", - "assign_to_nodes", - "node_loading", - "processing_time", - "kaplan_meier", - "KMResult", -] - -#: Przedrostki oznaczeń stacji, usuwane przed porównaniem nazw. Nie niosą -#: tożsamości obiektu, a występują niekonsekwentnie po obu stronach złączenia. -PRZEDROSTKI_STACJI: tuple[str, ...] = ("GPZ", "SE", "RS", "RPZ", "STACJA") - -_NIEALFANUM = re.compile(r"[^a-z0-9 ]+") - -#: Wpisy opisujące obiekt PLANOWANY NA LINII między stacjami, a nie obiekt -#: w węźle. Przypisanie ich do węzła byłoby arbitralne: linia łączy dwa węzły, -#: a dopasowanie po nazwie wybrałoby ten koniec, który akurat występuje -#: w wykazie stacji. Pełna moc takiego wniosku nie obciąża żadnego z nich -#: w całości, więc wpis zostaje nieprzypisany i jawnie oznaczony. -_RELACJA_LINII = re.compile( - r"\b(w\s+lini(?:i|ach)|relacj(?:i|a)|odczep\s+z\s+lini)", re.IGNORECASE) - -#: Litery, których rozkład kanoniczny NIE oddziela znaku diakrytycznego: Unicode -#: traktuje je jako osobne litery, więc NFKD ich nie rozkłada i naiwne czyszczenie -#: zamienia je na spację, rozcinając wyraz ("Białogard" -> "bia ogard"). -_NIEROZKLADALNE = {"ł": "l", "Ł": "L", "đ": "d", "Đ": "D", "ø": "o", "Ø": "O", - "ß": "ss", "æ": "ae", "Æ": "AE", "œ": "oe", "Œ": "OE"} - - -def normalizuj_nazwe(v) -> str: - """Nazwa stacji sprowadzona do postaci porównywalnej. - - Usuwa znaki diakrytyczne, sprowadza do małych liter, odrzuca przedrostki - oznaczeń i zbędne znaki. Porównanie odbywa się na TOKENACH, nie na znakach, - żeby „Kutno" nie pasowało do „Kutnowska". - """ - if v is None or (isinstance(v, float) and v != v): - return "" - s = str(v) - for znak, zamiennik in _NIEROZKLADALNE.items(): - s = s.replace(znak, zamiennik) - s = unicodedata.normalize("NFKD", s) - s = "".join(c for c in s if not unicodedata.combining(c)).lower() - s = _NIEALFANUM.sub(" ", s) - tokeny = [t for t in s.split() if t and t.upper() not in PRZEDROSTKI_STACJI] - return " ".join(tokeny) - - -def _tokeny(s: str) -> tuple[str, ...]: - return tuple(s.split()) - - -def _podciag(igla: Sequence[str], stog: Sequence[str]) -> bool: - """Czy `igla` jest ciągłym podciągiem tokenów `stog`.""" - n, m = len(igla), len(stog) - if n == 0 or n > m: - return False - return any(tuple(stog[i : i + n]) == tuple(igla) for i in range(m - n + 1)) - - -def station_node_map( - df: pd.DataFrame, - kolumna_encji: str = "_encja", - kolumna_grupy: str = "_nr_grupy", - separator: str = ",", -) -> pd.DataFrame: - """Odwzorowanie stacja → grupa stacji, odczytane z wierszy encji WEZEL. - - Publikujący, który realizuje punkt 2 obowiązku w podziale na GRUPY stacji, - wymienia skład grupy w polu lokalizacji. To jedyne miejsce, w którym - przynależność stacji do węzła jest w ogóle ujawniona, stąd ta funkcja. - - Kluczem jest GRUPA, nie identyfikator wiersza węzłowego. Publikujący - wystawia tę samą grupę osobno dla kierunku wytwórczego i odbiorczego, więc - odwzorowanie po identyfikatorze wiersza czyniłoby każdą stację - dwuznaczną, co byłoby artefaktem układu dokumentu, nie własnością sieci. - Gdy kolumna grupy nie występuje, kluczem staje się identyfikator węzła. - - Zwraca ramkę: publikujacy, grupa, nazwa_wezla, stacja, stacja_norm. - """ - if kolumna_encji in df.columns: - wez = df[df[kolumna_encji] == "WEZEL"] - else: # bez anotacji encji rozpoznajemy węzeł po obecności mocy dostępnej - wez = df[df["moc_dostepna"].notna()] if "moc_dostepna" in df else df.iloc[0:0] - klucz = kolumna_grupy if kolumna_grupy in df.columns else "id_wezla" - wiersze = [] - for _, r in wez.iterrows(): - lista = r.get("lokalizacja_tekst") - if lista is None or (isinstance(lista, float) and lista != lista): - continue - for czesc in str(lista).split(separator): - nazwa = czesc.strip() - if not nazwa: - continue - wiersze.append( - { - "publikujacy": r.get("publikujacy"), - "grupa": r.get(klucz), - "nazwa_wezla": r.get("nazwa_wezla"), - "stacja": nazwa, - "stacja_norm": normalizuj_nazwe(nazwa), - } - ) - out = pd.DataFrame(wiersze) - if not len(out): - return out - out = out[out["stacja_norm"] != ""] - return out.drop_duplicates(["grupa", "stacja_norm"]).reset_index(drop=True) - - -def assign_to_nodes( - df: pd.DataFrame, - mapa: pd.DataFrame, - kolumna_encji: str = "_encja", -) -> pd.DataFrame: - """Przypisuje wiersze wnioskowe do grup stacji przez nazwę stacji. - - Przypisanie jest NAZWOWE, nie topologiczne: opiera się na zgodności nazw - ujawnionych przez publikującego, a nie na modelu sieci. Jego trafność nie - jest tu walidowana wobec zewnętrznego wzorca, bo taki nie istnieje. - - Zwracany status rozróżnia cztery przypadki, bo brak przypisania - i przypisanie niepewne to nie to samo: - - ``EXACT`` nazwa stacji równa lokalizacji wniosku po normalizacji - ``EXTENDED`` lokalizacja zawiera nazwę stacji jako ciągły podciąg tokenów - ``LINE`` obiekt planowany na linii między stacjami, nie w węźle - ``AMBIGUOUS`` pasuje więcej niż jedna grupa, przypisania nie dokonujemy - ``NONE`` brak trafienia albo brak lokalizacji - - Dodaje kolumny `_grupa`, `_grupa_nazwa`, `_grupa_dopasowanie`. - """ - if not len(mapa): - out = df.copy() - out["_grupa"] = None - out["_grupa_nazwa"] = None - out["_grupa_dopasowanie"] = "NONE" - return out - maska = df[kolumna_encji] != "WEZEL" if kolumna_encji in df.columns \ - else pd.Series(True, index=df.index) - wykaz = ( - mapa.groupby("stacja_norm") - .agg(grupa=("grupa", lambda s: tuple(dict.fromkeys(s))), - nazwa=("nazwa_wezla", lambda s: tuple(dict.fromkeys(s)))) - .reset_index() - ) - pary = [(s, _tokeny(s), g, n) for s, g, n in - zip(wykaz["stacja_norm"], wykaz["grupa"], wykaz["nazwa"])] - kol = {"_grupa": [], "_grupa_nazwa": [], "_grupa_dopasowanie": []} - for idx, loc in df["lokalizacja_tekst"].items(): - if not maska.loc[idx]: - kol["_grupa"].append(None); kol["_grupa_nazwa"].append(None) - kol["_grupa_dopasowanie"].append(None); continue - norm = normalizuj_nazwe(loc) - if not norm: - kol["_grupa"].append(None); kol["_grupa_nazwa"].append(None) - kol["_grupa_dopasowanie"].append("NONE"); continue - if _RELACJA_LINII.search(str(loc)): - kol["_grupa"].append(None); kol["_grupa_nazwa"].append(None) - kol["_grupa_dopasowanie"].append("LINE"); continue - tok = _tokeny(norm) - dokladne = [(g, n) for s, st, g, n in pary if s == norm] - kandydaci = dokladne or [(g, n) for s, st, g, n in pary if _podciag(st, tok)] - plaskie = list(dict.fromkeys( - (g, n) for grupy, nazwy in kandydaci for g, n in zip(grupy, nazwy))) - if not plaskie: - kol["_grupa"].append(None); kol["_grupa_nazwa"].append(None) - kol["_grupa_dopasowanie"].append("NONE") - elif len({g for g, _ in plaskie}) > 1: - kol["_grupa"].append(None); kol["_grupa_nazwa"].append(None) - kol["_grupa_dopasowanie"].append("AMBIGUOUS") - else: - kol["_grupa"].append(plaskie[0][0]); kol["_grupa_nazwa"].append(plaskie[0][1]) - kol["_grupa_dopasowanie"].append("EXACT" if dokladne else "EXTENDED") - out = df.copy() - for k, v in kol.items(): - out[k] = v - return out - - -def node_loading( - df: pd.DataFrame, - pole_mocy: str = "moc_wprowadzana", - kierunek: str | None = None, - kolumna_kierunku: str = "_kierunek", - kolumna_grupy: str = "_nr_grupy", - statusy_czynne: Iterable[str] | None = None, - kolumna_encji: str = "_encja", -) -> pd.DataFrame: - """Obciążenie węzła: moc czynnej kolejki wobec ujawnionej mocy dostępnej. - - Iloraz większy od jedności oznacza, że sama kolejka przekracza moc, którą - publikujący deklaruje jako dostępną. Jest to policzalna postać kryterium - „dostępna moc przyłączeniowa". - - Wymaga ramki po `assign_to_nodes`. Gdy publikujący podaje moc dostępną - osobno dla kierunku wytwórczego i odbiorczego, `kierunek` wybiera właściwe - wiersze węzłowe; domyślnie wyprowadzany jest z `pole_mocy`. - - Węzły o zerowej mocy dostępnej zwracane są z ilorazem ``NaN`` i flagą - `moc_dostepna_zero`: iloraz jest tam NIEOKREŚLONY, a nie nieskończony, - i uśrednianie go byłoby błędem. Wiersz zachowuje jednak moc wnioskowaną, - bo kolejka do węzła bez wolnej mocy jest informacją, nie brakiem danych. - """ - if statusy_czynne is None: - statusy_czynne = ("WNIOSEK_ZLOZONY", "WNIOSEK_NIEKOMPLETNY", - "W_TRAKCIE_ANALIZY", "WARUNKI_WYDANE", "UMOWA_OBOWIAZUJACA") - if kierunek is None and kolumna_kierunku in df.columns: - dostepne = set(df[kolumna_kierunku].dropna().unique()) - domysl = "wytworcza" if "wprowadzana" in pole_mocy else "odbiorcza" - kierunek = domysl if domysl in dostepne else None - jest_wezel = df[kolumna_encji] == "WEZEL" if kolumna_encji in df.columns \ - else df["moc_dostepna"].notna() - wnioski = df[~jest_wezel] - wnioski = wnioski[wnioski["status_procesu"].isin(set(statusy_czynne))] - wnioski = wnioski[wnioski["_grupa"].notna()] - suma = wnioski.groupby("_grupa")[pole_mocy].sum(min_count=1).rename("moc_wnioskowana") - liczba = wnioski.groupby("_grupa").size().rename("wnioskow") - wez = df[jest_wezel] - wez = wez[wez["moc_dostepna"].notna()] - if kierunek is not None and kolumna_kierunku in wez.columns: - wez = wez[wez[kolumna_kierunku] == kierunek] - klucz = kolumna_grupy if kolumna_grupy in wez.columns else "id_wezla" - kolumny = [c for c in ("id_wezla", "nazwa_wezla", "moc_dostepna", "poziom_napiecia") - if c in wez.columns] - baza = wez.set_index(wez[klucz])[kolumny].join(suma).join(liczba) - baza.index.name = "grupa" - baza["moc_wnioskowana"] = baza["moc_wnioskowana"].fillna(0.0) - baza["wnioskow"] = baza["wnioskow"].fillna(0).astype(int) - baza["moc_dostepna_zero"] = baza["moc_dostepna"] == 0 - wolna = baza["moc_dostepna"].where(~baza["moc_dostepna_zero"]) - baza["obciazenie"] = baza["moc_wnioskowana"] / wolna - baza["kierunek"] = kierunek - return baza.reset_index() - - -def processing_time( - df: pd.DataFrame, - od: str = "data_wniosku", - do: str = "data_warunkow", - na_dzien=None, -) -> pd.DataFrame: - """Czas rozpatrywania wraz z klasyfikacją cenzurowania. - - Wniosek bez daty rozstrzygnięcia NIE jest brakiem danych: jest obserwacją - uciętą na dacie publikacji edycji. Funkcja zwraca kolumnę `czas_dni` dla - obu rodzajów obserwacji oraz `zdarzenie` równe 1 dla rozstrzygniętych i 0 - dla uciętych, w postaci, której oczekuje estymator przeżycia. - - `na_dzien` domyślnie bierze maksimum z pola daty publikacji, a gdy go brak - - maksimum z dat rozstrzygnięć. - """ - d = df.copy() - for c in (od, do): - d[c] = pd.to_datetime(d[c], errors="coerce") - if na_dzien is None: - if "data_publikacji" in d: - na_dzien = pd.to_datetime(d["data_publikacji"], errors="coerce").max() - if na_dzien is None or pd.isna(na_dzien): - na_dzien = d[do].max() - na_dzien = pd.to_datetime(na_dzien) - ma_start = d[od].notna() - zdarzenie = ma_start & d[do].notna() - czas = pd.Series(pd.NA, index=d.index, dtype="Float64") - czas[zdarzenie] = (d.loc[zdarzenie, do] - d.loc[zdarzenie, od]).dt.days - uciete = ma_start & ~zdarzenie - czas[uciete] = (na_dzien - d.loc[uciete, od]).dt.days - d["czas_dni"] = czas - d["zdarzenie"] = zdarzenie.astype(int).where(ma_start) - d["na_dzien"] = na_dzien - ujemne = d["czas_dni"] < 0 - d.loc[ujemne, ["czas_dni", "zdarzenie"]] = pd.NA - return d - - -@dataclass -class KMResult: - """Krzywa przeżycia Kaplana-Meiera z przedziałem Greenwooda.""" - - tabela: pd.DataFrame = field(repr=False) - mediana: float - mediana_dolna: float - mediana_gorna: float - n: int - zdarzen: int - cenzurowanych: int - - def as_dict(self) -> dict: - return {"n": self.n, "zdarzen": self.zdarzen, "cenzurowanych": self.cenzurowanych, - "udzial_cenzurowanych": self.cenzurowanych / self.n if self.n else float("nan"), - "mediana": self.mediana, "mediana_dolna": self.mediana_dolna, - "mediana_gorna": self.mediana_gorna} - - -def kaplan_meier(czas, zdarzenie, alpha: float = 0.05) -> KMResult: - """Estymator Kaplana-Meiera z wariancją Greenwooda. - - Zaimplementowany wprost, żeby nie wprowadzać zależności od biblioteki - analizy przeżycia dla jednego estymatora. Przedział dla mediany wyznaczany - jest metodą odwrócenia przedziału krzywej: granicami są skrajne czasy, dla - których pas ufności krzywej obejmuje poziom 0,5. - """ - d = pd.DataFrame({"t": pd.to_numeric(pd.Series(czas), errors="coerce"), - "e": pd.to_numeric(pd.Series(zdarzenie), errors="coerce")}).dropna() - d = d[d["t"] >= 0] - n0 = len(d) - if n0 == 0: - pusta = pd.DataFrame(columns=["t", "n_ryzyka", "zdarzen", "S", "S_dolne", "S_gorne"]) - return KMResult(pusta, float("nan"), float("nan"), float("nan"), 0, 0, 0) - try: - from scipy.stats import norm - z = float(norm.ppf(1 - alpha / 2)) - except Exception: - z = 1.959963984540054 - czasy = sorted(d.loc[d["e"] == 1, "t"].unique()) - S, kum_war, wiersze = 1.0, 0.0, [] - for t in czasy: - n_ryz = int((d["t"] >= t).sum()) - zd = int(((d["t"] == t) & (d["e"] == 1)).sum()) - if n_ryz == 0: - continue - S *= 1 - zd / n_ryz - if n_ryz > zd: - kum_war += zd / (n_ryz * (n_ryz - zd)) - se = S * math.sqrt(kum_war) if S > 0 else 0.0 - wiersze.append({"t": float(t), "n_ryzyka": n_ryz, "zdarzen": zd, "S": S, - "S_dolne": max(0.0, S - z * se), "S_gorne": min(1.0, S + z * se)}) - tab = pd.DataFrame(wiersze) - - def pierwszy_ponizej(kol): - pod = tab[tab[kol] <= 0.5] - return float(pod["t"].iloc[0]) if len(pod) else float("nan") - - return KMResult( - tabela=tab, - mediana=pierwszy_ponizej("S"), - mediana_dolna=pierwszy_ponizej("S_gorne"), - mediana_gorna=pierwszy_ponizej("S_dolne"), - n=n0, - zdarzen=int((d["e"] == 1).sum()), - cenzurowanych=int((d["e"] == 0).sum()), - ) diff --git a/build/lib/gridqueue/cli.py b/build/lib/gridqueue/cli.py deleted file mode 100644 index 702d501..0000000 --- a/build/lib/gridqueue/cli.py +++ /dev/null @@ -1,148 +0,0 @@ -"""Interfejs wiersza poleceń: ``gridqueue parse | validate | export``.""" - -from __future__ import annotations - -import argparse -import json -import sys -from pathlib import Path -from typing import Optional - -from . import __version__ -from .layout import audit_column_shift -from .quality import run_quality -from .registry import REGISTRY, declarations, detect_publisher, get_adapter -from .schema import FIELDS, schema_table, validate_frame - - -def _read_table(path: str): - import pandas as pd - - p = Path(path) - if p.suffix.lower() in {".parquet", ".pq"}: - return pd.read_parquet(p) - return pd.read_csv(p) - - -def _write_table(df, path: str) -> None: - p = Path(path) - p.parent.mkdir(parents=True, exist_ok=True) - if p.suffix.lower() in {".parquet", ".pq"}: - df.to_parquet(p, index=False) - elif p.suffix.lower() in {".json", ".jsonl"}: - df.to_json(p, orient="records", force_ascii=False, indent=2) - else: - df.to_csv(p, index=False) - - -def cmd_parse(args) -> int: - import pandas as pd - - key = args.adapter or (detect_publisher(args.source[0]) if args.source else None) - if key is None: - print("nie rozpoznano publikującego; podaj --adapter", file=sys.stderr) - return 2 - adapter = get_adapter(key) - source = args.source if len(args.source) > 1 else (args.source[0] if args.source else None) - res = adapter.parse(source) - _write_table(res.frame, args.out) - audit = audit_column_shift(res.frame) - report = { - "adapter": key, - "deklaracja": adapter.declaration(), - "raport_wydobycia": res.report, - "audyt_przesuniecia_kolumn": audit.as_dict(), - "wyjscie": args.out, - "n_wierszy": int(len(res.frame)), - } - if args.report: - Path(args.report).write_text( - json.dumps(report, ensure_ascii=False, indent=2, default=str), encoding="utf-8") - print(json.dumps({k: v for k, v in report.items() if k != "raport_wydobycia"}, - ensure_ascii=False, indent=2, default=str)) - return 0 - - -def cmd_validate(args) -> int: - df = _read_table(args.input) - schema_rep = validate_frame(df) - qual = run_quality(df).as_dict() - audit = audit_column_shift(df).as_dict() - out = {"schemat": schema_rep, "jakosc": qual, "przesuniecie_kolumn": audit} - text = json.dumps(out, ensure_ascii=False, indent=2, default=str) - if args.out: - Path(args.out).write_text(text, encoding="utf-8") - print(text) - return 0 - - -def cmd_export(args) -> int: - import pandas as pd - - frames = [_read_table(p) for p in args.input] - df = pd.concat(frames, ignore_index=True) - if args.only_schema: - keep = [c for c in FIELDS if c in df.columns] + \ - [c for c in ("publikujacy", "jurysdykcja", "dokument_zrodlowy") if c in df.columns] - df = df[keep] - _write_table(df, args.out) - print(json.dumps({"wierszy": int(len(df)), "kolumn": int(df.shape[1]), - "wyjscie": args.out}, ensure_ascii=False, indent=2)) - return 0 - - -def cmd_schema(args) -> int: - t = schema_table() - if args.out: - _write_table(t, args.out) - print(t.to_string(index=False, max_colwidth=60)) - return 0 - - -def cmd_adapters(args) -> int: - print(json.dumps(declarations(), ensure_ascii=False, indent=2)) - return 0 - - -def build_parser() -> argparse.ArgumentParser: - ap = argparse.ArgumentParser( - prog="gridqueue", - description="Harmonizator ustawowych ujawnień przyłączeniowych (art. 7 ust. 8l PE)") - ap.add_argument("--version", action="version", version=f"gridqueue {__version__}") - sub = ap.add_subparsers(dest="cmd", required=True) - - p = sub.add_parser("parse", help="sparsuj dokument publikującego do schematu") - p.add_argument("source", nargs="*", help="ścieżka(-i) do dokumentu; brak = pobierz z sieci") - p.add_argument("--adapter", choices=sorted(REGISTRY), help="wymuś adapter") - p.add_argument("--out", required=True, help="plik wyjściowy (.csv/.parquet/.json)") - p.add_argument("--report", help="plik raportu JSON") - p.set_defaults(func=cmd_parse) - - p = sub.add_parser("validate", help="waliduj zbiór wobec schematu i reguł jakości") - p.add_argument("input") - p.add_argument("--out", help="plik raportu JSON") - p.set_defaults(func=cmd_validate) - - p = sub.add_parser("export", help="złóż panel z wielu zbiorów") - p.add_argument("input", nargs="+") - p.add_argument("--out", required=True) - p.add_argument("--only-schema", action="store_true", - help="pomiń rozszerzenia (kolumny z przedrostkiem _)") - p.set_defaults(func=cmd_export) - - p = sub.add_parser("schema", help="wypisz specyfikację schematu") - p.add_argument("--out") - p.set_defaults(func=cmd_schema) - - p = sub.add_parser("adapters", help="wypisz deklaracje adapterów") - p.set_defaults(func=cmd_adapters) - return ap - - -def main(argv: Optional[list[str]] = None) -> int: - args = build_parser().parse_args(argv) - return args.func(args) - - -if __name__ == "__main__": # pragma: no cover - raise SystemExit(main()) diff --git a/build/lib/gridqueue/geoloc.py b/build/lib/gridqueue/geoloc.py deleted file mode 100644 index f3cfc69..0000000 --- a/build/lib/gridqueue/geoloc.py +++ /dev/null @@ -1,672 +0,0 @@ -"""Rozwiązywacz lokalizacji z JAWNYM poziomem pewności. - -Reguła nadrzędna: rozwiązywacz nigdy nie zgaduje po cichu. Każdy wynik niesie -poziom pewności, a odsetek rozwiązanych jest raportowaną metryką, nie założeniem. - -Poziomy pewności (malejąco): - EXACT -- znormalizowany opis jest identyczny z nazwą w gazeterze - UNIQUE_TOKEN -- dokładnie jedna nazwa w gazeterze zawiera rozpoznawalny token - wyróżniający z opisu - TOKEN_SUBSET -- zbiór tokenów opisu zawiera się w tokenach dokładnie jednej nazwy - REVERSED -- dopasowanie po odwróceniu kolejności członów nazwy - ("WINCENTEGO ŚW." -> "Świętego Wincentego", "BEMA J." -> "Józefa Bema") - SKRZYZOWANIE -- opis wskazuje skrzyżowanie dwóch ulic ("WALICÓW / GRZYBOWSKA"); - rozwiązane, gdy co najmniej dwa człony trafiają w gazeter - NONE -- brak dopasowania; pole ``powod`` mówi dlaczego - -Dla publikujących, którzy podają lokalizację jako WEWNĘTRZNY KOD STACJI -(TAURON: "SKB3", "RCB4"), rozwiązywacz zwraca NONE z powodem -``kod_stacji_bez_slownika`` -- nie próbuje zgadywać, bo operator nie publikuje -słownika kodów i każde dopasowanie byłoby konfabulacją. - -Rozszerzenie o współrzędne (wersja 0.2) ---------------------------------------- -Wynik niesie teraz punkt oraz DRUGI, niezależny poziom -- ``dokladnosc`` -(patrz :data:`DOKLADNOSC`). Dwa poziomy odpowiadają na dwa różne pytania: - - ``pewnosc`` -- jak pewna jest IDENTYFIKACJA nazwy miejsca, - ``dokladnosc`` -- jak precyzyjnie zwrócony punkt reprezentuje to miejsce. - -Są rozłączne z założenia: dopasowanie EXACT do ulicy o długości 6 km daje punkt -o dokładności ``PUNKT_NA_OSI_ULICY`` z rozmyciem rzędu kilometra, a dopasowanie -UNIQUE_TOKEN do krótkiej ulicy -- punkt lepszy. Długość osi dopasowanej ulicy -jest zwracana w ``dlugosc_ulicy_m`` właśnie po to, by rozmycie dało się -policzyć, a nie tylko zadeklarować. - -Zachowane jest rozróżnienie między **nierozwiązaniem nazwy** -(``pewnosc == "NONE"``) a **rozwiązaniem nazwy bez dostępnej geometrii** -(``pewnosc != "NONE"``, ``dokladnosc == "BRAK_GEOMETRII"``, -``powod == "nazwa_rozwiazana_bez_geometrii"``) -- to dwa różne stany wiedzy -i mieszanie ich zawyżałoby albo zaniżałoby pokrycie. Predykaty: -``Resolution.rozwiazane`` (nazwa) i ``Resolution.ma_wspolrzedne`` (punkt). - -Numer domu nie jest interpolowany wzdłuż osi ulicy bez znanego zakresu -numeracji -- byłoby to zgadywanie. ``punkt_dla_numeru`` zwraca punkt wyłącznie -z indeksu punktów adresowych, jeśli taki jest wczytany. -""" - -from __future__ import annotations - -import re -import unicodedata -from collections import defaultdict -from dataclasses import dataclass -from typing import Iterable, Optional - -__all__ = [ - "Resolution", "LocationResolver", "MultiLocalityResolver", - "PEWNOSC", "DOKLADNOSC", "normalize", "tokens", - "resolver_from_osm_json", "resolver_from_gazeter_json", -] - -PEWNOSC = ("EXACT", "UNIQUE_TOKEN", "TOKEN_SUBSET", "REVERSED", "SKRZYZOWANIE", "NONE") - -#: Poziom DOKLADNOSCI UMIEJSCOWIENIA -- odpowiada na inne pytanie niz ``pewnosc``. -#: ``pewnosc`` mowi, jak pewna jest IDENTYFIKACJA nazwy; ``dokladnosc`` mowi, -#: jak precyzyjnie zwrocony punkt reprezentuje wskazane miejsce. Rozdzielenie -#: jest konieczne, bo nazwa moze byc zidentyfikowana bezblednie (EXACT), a punkt -#: i tak byc tylko srodkiem kilkukilometrowej ulicy. -#: -#: PUNKT_ADRESOWY -- znany punkt adresowy (ulica + numer domu) -#: PUNKT_SKRZYZOWANIA -- przeciecie osi dwoch wskazanych ulic -#: PUNKT_NA_OSI_ULICY -- punkt w 50% dlugosci osi ulicy (niepewnosc ~ dlugosc/4) -#: CENTROID_MIEJSCOWOSCI -- rozwiazano tylko miejscowosc, nie ulice -#: BRAK_GEOMETRII -- nazwa ROZWIAZANA, ale gazeter nie ma dla niej wspolrzednych -#: BRAK -- nazwa nierozwiazana, wiec nie ma czego umiejscawiac -DOKLADNOSC = ( - "PUNKT_ADRESOWY", "PUNKT_SKRZYZOWANIA", "PUNKT_NA_OSI_ULICY", - "CENTROID_MIEJSCOWOSCI", "BRAK_GEOMETRII", "BRAK", -) - -#: przedrostki i człony, które nie wyróżniają ulicy -_STOP = { - "ul", "ulica", "al", "aleja", "aleje", "pl", "plac", "os", "osiedle", "rondo", - "sw", "swietego", "swietej", "im", "imienia", "gen", "generala", "gen.", - "ks", "ksiedza", "dr", "prof", "mjr", "plk", "kpt", "por", "mjra", "marsz", - "marszalka", "bp", "biskupa", "kard", "kardynala", "droga", "trakt", "skwer", - "bulwar", "park", "most", "wybrzeze", "brak", "dzialka", "nr", "dz", "obreb", -} - -#: kod stacji: 2-6 znaków wielkich liter/cyfr bez spacji, albo opis projektowanej stacji -_RE_STATION_CODE = re.compile(r"^[A-ZĄĆĘŁŃÓŚŻŹ]{2,5}\d{0,2}$") - - -_STROKE = str.maketrans({"ł": "l", "Ł": "L", "đ": "d", "Đ": "D", "ø": "o", "Ø": "O"}) - - -def strip_diacritics(s: str) -> str: - s = str(s).translate(_STROKE) - s = unicodedata.normalize("NFKD", s) - return "".join(ch for ch in s if not unicodedata.combining(ch)) - - -def normalize(s: Optional[str]) -> str: - if not s: - return "" - s = strip_diacritics(str(s)).lower() - s = re.sub(r"[^\w\s]", " ", s) - return re.sub(r"\s+", " ", s).strip() - - -def tokens(s: Optional[str], *, drop_stop: bool = True) -> list[str]: - t = [w for w in normalize(s).split() if w] - if drop_stop: - t = [w for w in t if w not in _STOP and not w.isdigit()] - return t - - -@dataclass -class Resolution: - query: str - matched: Optional[str] - lat: Optional[float] - lon: Optional[float] - pewnosc: str - powod: str = "" - #: poziom dokladnosci umiejscowienia -- patrz DOKLADNOSC - dokladnosc: str = "BRAK" - #: miejscowosc, w ktorej gazeterze szukano (None dla gazetera jednoobszarowego) - miejscowosc: Optional[str] = None - #: dlugosc osi dopasowanej ulicy w metrach, jesli gazeter ja niesie; - #: jest to jawna miara rozmycia punktu PUNKT_NA_OSI_ULICY - dlugosc_ulicy_m: Optional[float] = None - #: liczba ROZLACZNYCH skladowych geometrii o tej nazwie w tej miejscowosci - n_skladowych: Optional[int] = None - #: najwieksza odleglosc miedzy centroidami tych skladowych [m]. Duza - #: wartosc oznacza, ze nazwa ulicy NIE wyznacza jednego miejsca: w jednym - #: miescie istnieje kilka odleglych ulic o tej samej nazwie, a punkt lezy - #: na najdluzszej skladowej. Rejestry ustawowe nie podaja dzielnicy, wiec - #: tej niejednoznacznosci nie da sie usunac z danych opublikowanych -- - #: dlatego jest RAPORTOWANA, nie ukrywana. - rozrzut_skladowych_m: Optional[float] = None - - @property - def rozwiazane(self) -> bool: - """Czy NAZWA zostala zidentyfikowana (niezaleznie od dostepnosci geometrii).""" - return self.pewnosc != "NONE" - - @property - def ma_wspolrzedne(self) -> bool: - """Czy wynik niesie punkt. Rozlaczne z ``rozwiazane``: nazwa moze byc - rozwiazana, a geometrii moze nie byc (``dokladnosc == BRAK_GEOMETRII``).""" - return self.lat is not None and self.lon is not None - - -class LocationResolver: - """Dopasowanie opisu miejsca do gazetera nazw ulic/miejsc. - - ``gazetteer``: mapa nazwa -> (lat, lon) albo nazwa -> None (gdy współrzędnych - nie ma, a interesuje nas samo rozstrzygnięcie identyfikacji). - """ - - def __init__(self, gazetteer: dict[str, Optional[tuple[float, float]]]): - self.gazetteer = dict(gazetteer) - self._by_norm: dict[str, list[str]] = defaultdict(list) - self._by_tokenset: dict[frozenset, list[str]] = defaultdict(list) - self._by_token: dict[str, list[str]] = defaultdict(list) - for name in self.gazetteer: - n = normalize(name) - self._by_norm[n].append(name) - ts = frozenset(tokens(name)) - if ts: - self._by_tokenset[ts].append(name) - for t in ts: - self._by_token[t].append(name) - - # ------------------------------------------------------------------ - def _coords(self, name: str) -> tuple[Optional[float], Optional[float]]: - """Wspolrzedne wpisu gazetera. - - Obslugiwane postacie wpisu (zgodnosc wstecz zachowana): - ``None`` -- brak geometrii - ``(lat, lon)`` -- goly punkt - ``{"lat":..,"lon":..}`` -- wpis rozszerzony, moze dodatkowo niesc - ``os`` (lista [lat, lon]) i ``dlugosc_m`` - """ - c = self.gazetteer.get(name) - if isinstance(c, dict): - lat, lon = c.get("lat"), c.get("lon") - if lat is not None and lon is not None: - return float(lat), float(lon) - return None, None - if isinstance(c, (tuple, list)) and len(c) == 2: - return float(c[0]), float(c[1]) - return None, None - - def _meta(self, name: str) -> dict: - c = self.gazetteer.get(name) - return c if isinstance(c, dict) else {} - - def axis(self, name: str) -> Optional[list[tuple[float, float]]]: - """Os ulicy jako lista (lat, lon), jesli gazeter ja niesie.""" - os_ = self._meta(name).get("os") - if not os_ or len(os_) < 2: - return None - return [(float(p[0]), float(p[1])) for p in os_] - - #: prog udzialu wyjasnionych tokenow opisu; ponizej progu dopasowanie - #: nie-EXACT jest odrzucane jako opis slowny, nie nazwa ulicy - PROG_POKRYCIA_TOKENOW = 0.5 - #: od tylu tokenow opisu prog jest stosowany (krotkie opisy sa nazwami ulic) - MIN_TOKENOW_DLA_PROGU = 4 - - def _udzial_wyjasnionych(self, ts: list[str], name: str) -> float: - """Jaka czesc tokenow opisu wyjasnia dopasowana nazwa. - - Token uchodzi za wyjasniony, gdy jest rowny tokenowi nazwy albo jest - jego przedrostkiem (obsluga inicjalow: "a." -> "augusta"). - """ - if not ts: - return 0.0 - nt = tokens(name) - ile = sum(1 for t in ts if any(t == x or x.startswith(t) for x in nt)) - return ile / len(ts) - - def _opis_slowny(self, ts: list[str], name: str) -> bool: - """Czy dopasowanie opiera sie na jednym tokenie dlugiego opisu slownego. - - Zmierzone na panelu: opis "Bezposrednie sasiedztwo Lotniska Chopina w - Warszawie" trafial w ulice "Fryderyka Chopina" przez sam token - "chopina", dajac punkt w srodmiesciu zamiast przy lotnisku. Dopasowanie - wyjasniajace mniej niz polowe tokenow dlugiego opisu nie jest - identyfikacja ulicy i jest odrzucane z jawnym powodem. - """ - if len(ts) < self.MIN_TOKENOW_DLA_PROGU: - return False - return self._udzial_wyjasnionych(ts, name) < self.PROG_POKRYCIA_TOKENOW - - def _hit(self, query: str, name: str, level: str, - miejscowosc: Optional[str] = None) -> Resolution: - lat, lon = self._coords(name) - meta = self._meta(name) - dokl = "PUNKT_NA_OSI_ULICY" if lat is not None else "BRAK_GEOMETRII" - powod = "" if lat is not None else "nazwa_rozwiazana_bez_geometrii" - return Resolution(query, name, lat, lon, level, powod, - dokladnosc=dokl, miejscowosc=miejscowosc, - dlugosc_ulicy_m=meta.get("dlugosc_m"), - n_skladowych=meta.get("n_skladowych"), - rozrzut_skladowych_m=meta.get("rozrzut_skladowych_m")) - - # ------------------------------------------------------------------ - def punkt_dla_numeru(self, name: str, numer: Optional[str]) -> Optional[tuple[float, float]]: - """Umiejscowienie numeru domu. - - Jesli gazeter niesie punkt adresowy dla pary (ulica, numer) -- zwraca go. - W przeciwnym razie zwraca ``None``: interpolacja numeru wzdluz osi bez - znanego zakresu numeracji bylaby zgadywaniem, a rozwiazywacz nie zgaduje. - Os ulicy jest zachowana w gazeterze wlasnie po to, by punkt adresowy dal - sie do niej odniesc, gdy zbior punktow adresowych bedzie dostepny. - """ - if not numer: - return None - idx = getattr(self, "punkty_adresowe", None) - if not idx: - return None - key = (normalize(name), normalize(str(numer))) - p = idx.get(key) - return (float(p[0]), float(p[1])) if p else None - - @staticmethod - def _przeciecie(a: list[tuple[float, float]], - b: list[tuple[float, float]]) -> Optional[tuple[float, float]]: - """Punkt przeciecia (albo najmniejszego zblizenia) dwoch osi ulic. - - Liczone na osiach z gazetera, w przyblizeniu rownopolowym wokol - szerokosci srodkowej -- na skali miasta blad tej aproksymacji jest - rzedu metrow i nie ma znaczenia wobec rozmycia samego wejscia. - """ - import math - - lat0 = math.radians(sum(p[0] for p in a + b) / len(a + b)) - kx = 111320.0 * math.cos(lat0) - ky = 110540.0 - - def xy(p): - return (p[1] * kx, p[0] * ky) - - best = None - for i in range(len(a) - 1): - p1, p2 = xy(a[i]), xy(a[i + 1]) - for j in range(len(b) - 1): - p3, p4 = xy(b[j]), xy(b[j + 1]) - d1 = (p2[0] - p1[0], p2[1] - p1[1]) - d2 = (p4[0] - p3[0], p4[1] - p3[1]) - den = d1[0] * d2[1] - d1[1] * d2[0] - if abs(den) < 1e-9: - continue - t = ((p3[0] - p1[0]) * d2[1] - (p3[1] - p1[1]) * d2[0]) / den - u = ((p3[0] - p1[0]) * d1[1] - (p3[1] - p1[1]) * d1[0]) / den - if 0.0 <= t <= 1.0 and 0.0 <= u <= 1.0: - x, y = p1[0] + t * d1[0], p1[1] + t * d1[1] - cand = (y / ky, x / kx) - if best is None: - best = cand - return cand - return best - - # ------------------------------------------------------------------ - def resolve(self, query: Optional[str], *, is_station_code: bool = False, - sprawdzaj_kod_stacji: bool = True) -> Resolution: - """Rozwiąż opis miejsca. - - ``sprawdzaj_kod_stacji=False`` wyłącza heurystykę kodu stacji. Jest to - potrzebne, gdy wywołujący już rozstrzygnął, że opis NIE jest kodem - stacji -- na przykład :class:`MultiLocalityResolver` sprawdza kod na - pełnym opisie, a potem przekazuje tu sam człon ulicy. Bez tego - przełącznika krótkie nazwy ulic zapisane wersalikami ("MARSA", "TAMKA", - "DŁUGA") wpadały w wzorzec kodu stacji: zmierzone 25 fałszywych braków - na 1 236 wierszach rejestru Stoen Operator. - """ - q = (query or "").strip() - if not q: - return Resolution(q, None, None, None, "NONE", "pusty_opis") - if is_station_code or (sprawdzaj_kod_stacji and _RE_STATION_CODE.match(q)): - return Resolution(q, None, None, None, "NONE", "kod_stacji_bez_slownika") - - # odetnij człon miejscowości, jeśli podany jako "MIASTO, adres" - street = q.split(",", 1)[1] if "," in q else q - nq = normalize(street) - - # 1) dokładne - if nq in self._by_norm: - return self._hit(q, self._by_norm[nq][0], "EXACT") - nq_full = normalize(street.split(" nr ")[0]) - if nq_full in self._by_norm: - return self._hit(q, self._by_norm[nq_full][0], "EXACT") - - ts = tokens(street) - if not ts: - return Resolution(q, None, None, None, "NONE", "brak_tokenow_wyrozniajacych") - - # 2) unikalny token - cands = {t: self._by_token.get(t, []) for t in ts} - # Odrzucenie przez prog pokrycia tokenow NIE konczy rozwiazywania: - # dalsze strategie (odwrocenie czlonow, skrzyzowanie) moga opis wyjasnic - # w calosci. Flaga sluzy tylko do nadania powodu, gdy nic nie zadziala. - odrzucono_opis = False - - unique = [names[0] for t, names in cands.items() if len(names) == 1] - if len(set(unique)) == 1: - if self._opis_slowny(ts, unique[0]): - odrzucono_opis = True - else: - return self._hit(q, unique[0], "UNIQUE_TOKEN") - - # 3) podzbiór tokenów - fs = frozenset(ts) - subset_hits = [n for tsx, names in self._by_tokenset.items() - if fs and fs <= tsx for n in names] - if len(set(subset_hits)) == 1: - if self._opis_slowny(ts, subset_hits[0]): - odrzucono_opis = True - else: - return self._hit(q, subset_hits[0], "TOKEN_SUBSET") - - # 4) odwrócona kolejność członów - rev = self._resolve_reversed(street, ts) - if rev is not None: - if self._opis_slowny(ts, rev): - odrzucono_opis = True - else: - return self._hit(q, rev, "REVERSED") - - # 5) skrzyżowanie: publikujący podaje dwie ulice ("WALICÓW / GRZYBOWSKA"). - # Miejsce jest określone -- to węzeł sieci ulic, nie jedna ulica. - parts = [p for p in re.split(r"[/\\]", street) if p.strip()] - if len(parts) > 1: - hits = [] - for p in parts: - sub = self.resolve(p, sprawdzaj_kod_stacji=sprawdzaj_kod_stacji) - if sub.rozwiazane: - hits.append(sub) - if len(hits) >= 2: - lat, lon = hits[0].lat, hits[0].lon - dokl = "PUNKT_NA_OSI_ULICY" if lat is not None else "BRAK_GEOMETRII" - powod = f"dopasowano {len(hits)} z {len(parts)} członów" - # jesli gazeter niesie osie obu ulic, punktem jest ich przeciecie - ax = [self.axis(h.matched) for h in hits[:2]] - if all(ax): - xp = self._przeciecie(ax[0], ax[1]) - if xp is not None: - lat, lon = round(xp[0], 6), round(xp[1], 6) - dokl = "PUNKT_SKRZYZOWANIA" - else: - powod += "; osie się nie przecinają, punkt z pierwszego członu" - return Resolution(q, " / ".join(h.matched for h in hits), - lat, lon, "SKRZYZOWANIE", powod, - dokladnosc=dokl) - - if odrzucono_opis: - return Resolution(q, None, None, None, "NONE", - "opis_slowny_nie_nazwa_ulicy") - if not any(cands.values()): - return Resolution(q, None, None, None, "NONE", "brak_kandydatow") - return Resolution(q, None, None, None, "NONE", "wiele_kandydatow") - - # ------------------------------------------------------------------ - def _resolve_reversed(self, street: str, ts: list[str]) -> Optional[str]: - """Domyka przypadki typu "WINCENTEGO ŚW." / "BEMA J.". - - Publikujący zapisują nazwisko na początku i skracają imię lub tytuł do - inicjału. Szukamy nazw gazetera, których zbiór tokenów zawiera WSZYSTKIE - pełne tokeny opisu (niezależnie od kolejności), a pozostałe tokeny opisu - są przedrostkami tokenów kandydata (obsługa inicjałów "J." -> "jozefa"). - """ - full = [t for t in ts if len(t) > 2] - inits = [t for t in ts if len(t) <= 2] - if not full: - return None - pool: Optional[set[str]] = None - for t in full: - names = set(self._by_token.get(t, [])) - pool = names if pool is None else (pool & names) - if not pool: - return None - if inits: - pool = { - n for n in pool - if all(any(tok.startswith(i) for tok in tokens(n)) for i in inits) - } - # dopuść też nieskrócone odwrócenie: dokładnie ten sam multizbiór tokenów - exact_rev = {n for n in pool if frozenset(tokens(n)) == frozenset(ts)} - if len(exact_rev) == 1: - return next(iter(exact_rev)) - if len(pool) == 1: - return next(iter(pool)) - return None - - # ------------------------------------------------------------------ - def resolve_series(self, values: Iterable[Optional[str]], *, - is_station_code: bool = False) -> list[Resolution]: - return [self.resolve(v, is_station_code=is_station_code) for v in values] - - @staticmethod - def summarize(resolutions: list[Resolution]) -> dict: - n = len(resolutions) - per = {lvl: sum(1 for r in resolutions if r.pewnosc == lvl) for lvl in PEWNOSC} - powody: dict[str, int] = {} - for r in resolutions: - if r.pewnosc == "NONE" and r.powod: - powody[r.powod] = powody.get(r.powod, 0) + 1 - solved = n - per["NONE"] - return { - "n": n, - "rozwiazane": solved, - "odsetek_rozwiazanych": round(solved / n, 6) if n else 0.0, - "per_pewnosc": per, - "powody_braku": dict(sorted(powody.items(), key=lambda kv: -kv[1])), - } - - -class MultiLocalityResolver: - """Rozwiązywacz dla gazetera z podziałem na miejscowości. - - Rejestry przyłączeniowe podają lokalizację jako ``MIEJSCOWOŚĆ, ulica``. - Jedna płaska przestrzeń nazw ulic byłaby tu błędem: ta sama nazwa ulicy - występuje w kilkunastu miejscowościach aglomeracji i płaski gazeter musiałby - albo zgadywać, albo zwracać ``wiele_kandydatow``. Ta klasa trzyma osobny - :class:`LocationResolver` na miejscowość i kieruje zapytanie do właściwego. - - Zachowana jest nadrzędna zasada pakietu: **brak z przyczyną zamiast - zgadywania**. Dochodzą dwa nowe, jawne powody braku: - - ``miejscowosc_poza_gazeterem`` -- podanej miejscowości nie ma w gazeterze; - to ograniczenie ZASIĘGU, nie porażka - dopasowania, i jest raportowane osobno - ``nazwa_rozwiazana_bez_geometrii`` -- nazwa dopasowana, ale wpis gazetera - nie ma współrzędnych - - Gdy ulicy nie udało się rozwiązać, a miejscowość owszem, zwracany jest - **brak** (``pewnosc == "NONE"``) -- centroid miejscowości NIE jest - podstawiany w pole ``wspolrzedne``, bo byłby punktem o innym znaczeniu niż - reszta kolumny. Centroid jest natomiast udostępniony w polu - ``lat``/``lon`` z ``dokladnosc == "CENTROID_MIEJSCOWOSCI"`` tylko wtedy, gdy - wywołujący jawnie poprosi (``dopusc_centroid=True``), i wtedy rozpoznaje go - po polu ``dokladnosc``. - """ - - def __init__(self, miejscowosci: dict[str, dict], - *, domyslna: Optional[str] = None): - self.centroidy: dict[str, tuple[float, float]] = {} - self.resolvery: dict[str, LocationResolver] = {} - self._alias: dict[str, str] = {} - for key, m in miejscowosci.items(): - k = normalize(key) - self.resolvery[k] = LocationResolver(m.get("ulice", {})) - # opcjonalny indeks punktow adresowych: "|" -> [lat, lon] - pa = m.get("punkty_adresowe") or {} - if pa: - idx = {} - for kk, vv in pa.items(): - st, _, nr = str(kk).partition("|") - idx[(normalize(st), normalize(nr))] = (float(vv[0]), float(vv[1])) - self.resolvery[k].punkty_adresowe = idx - if m.get("lat") is not None and m.get("lon") is not None: - self.centroidy[k] = (float(m["lat"]), float(m["lon"])) - self._alias[k] = k - self._alias.setdefault(normalize(m.get("nazwa") or key), k) - # alias czlonu glownego: "SEKOCIN NOWY"/"SEKOCIN STARY" -> pierwszy czlon, - # gdy jest jednoznaczny; gdy nie jest, alias nie powstaje i zapytanie - # o "SEKOCIN" konczy sie jawnym brakiem zamiast wyborem na chybil trafil - heads: dict[str, list[str]] = defaultdict(list) - for k in list(self.resolvery): - parts = k.split() - if len(parts) > 1: - heads[parts[0]].append(k) - for h, ks in heads.items(): - if h not in self._alias and len(ks) == 1: - self._alias[h] = ks[0] - elif h not in self._alias: - self._alias[h] = "\x00AMBIG\x00" + "|".join(sorted(ks)) - self.domyslna = normalize(domyslna) if domyslna else None - - # ------------------------------------------------------------------ - def rozdziel(self, tekst: Optional[str]) -> tuple[Optional[str], str]: - """Rozdziel ``"MIEJSCOWOŚĆ, ulica"`` na (miejscowość, ulica).""" - t = (tekst or "").strip() - if "," in t: - a, b = t.split(",", 1) - return a.strip(), b.strip() - return None, t - - #: numer domu na koncu opisu: "25", "85A", "12/14", "3 bis" - _RE_NUMER = re.compile(r"\s+(\d+\s*[a-zA-Z]?(?:\s*/\s*\d+\s*[a-zA-Z]?)?)\s*$") - - @classmethod - def rozdziel_numer(cls, street: str) -> tuple[str, Optional[str]]: - """Odetnij numer domu z końca opisu ulicy. - - Zwraca ``(ulica, numer)`` albo ``(ulica, None)``. Sama obecność liczby - na końcu nie dowodzi, że to numer domu -- w nazwach ulic liczby są - częste ("Aleja 4 Czerwca 1989", "11 Listopada"). Dlatego wynik tego - cięcia jest w :meth:`resolve` przyjmowany tylko wtedy, gdy reszta opisu - dopasowuje się do TEJ SAMEJ nazwy ulicy, a numer trafia w indeks - punktów adresowych. Inaczej opis pozostaje nietknięty. - """ - m = cls._RE_NUMER.search(street or "") - if not m: - return street, None - return street[: m.start()].strip(), re.sub(r"\s+", "", m.group(1)) - - def resolve(self, query: Optional[str], *, - miejscowosc: Optional[str] = None, - numer: Optional[str] = None, - is_station_code: bool = False, - dopusc_centroid: bool = False) -> Resolution: - q = (query or "").strip() - if not q: - return Resolution(q, None, None, None, "NONE", "pusty_opis") - if is_station_code or _RE_STATION_CODE.match(q): - return Resolution(q, None, None, None, "NONE", "kod_stacji_bez_slownika") - - m_txt, street = self.rozdziel(q) - if miejscowosc: - m_txt = miejscowosc - if not m_txt: - # Bez ZADEKLAROWANEJ miejscowosci dopasowanie nazwy ulicy do gazetera - # konkretnego miasta jest zgadywaniem, nie rozwiazaniem. Zmierzone: - # przy podstawianiu domyslnej miejscowosci opisy TAURONA typu - # "Stacja projektowana" trafialy w warszawska "ul. Projektowana", - # a "Wrzoski (planowany)" w drogowe "planowany lacznik". Dlatego - # domyslna miejscowosc jest opcjonalna i domyslnie WYLACZONA. - if not self.domyslna: - return Resolution(q, None, None, None, "NONE", - "brak_deklaracji_miejscowosci") - key = self.domyslna - else: - key = self._alias.get(normalize(m_txt)) - if key is None: - return Resolution(q, None, None, None, "NONE", - "miejscowosc_poza_gazeterem", miejscowosc=m_txt) - if key.startswith("\x00AMBIG\x00"): - warianty = key[len("\x00AMBIG\x00"):] - return Resolution(q, None, None, None, "NONE", - f"miejscowosc_niejednoznaczna:{warianty}", - miejscowosc=m_txt) - - sub = self.resolvery[key] - r = sub.resolve(street, sprawdzaj_kod_stacji=False) - - # numer domu: jesli nie podano wprost, spróbuj odciąć z końca opisu. - # Cięcie jest przyjmowane tylko wtedy, gdy reszta wskazuje TĘ SAMĄ ulicę - # (albo gdy pełny opis w ogóle się nie dopasował) -- inaczej liczba jest - # częścią nazwy ulicy, nie numerem domu. - num = numer - if num is None: - rest, kand = self.rozdziel_numer(street) - if kand: - r_rest = sub.resolve(rest, sprawdzaj_kod_stacji=False) - if r_rest.rozwiazane and (not r.rozwiazane or r_rest.matched == r.matched): - num = kand - if not r.rozwiazane: - r = r_rest - - r.query = q - r.miejscowosc = m_txt - - if r.rozwiazane and r.matched and num: - pt = sub.punkt_dla_numeru(r.matched, num) - if pt is not None: - r.lat, r.lon = pt - r.dokladnosc = "PUNKT_ADRESOWY" - r.powod = f"numer_domu={num}" - - if not r.rozwiazane and dopusc_centroid and key in self.centroidy: - lat, lon = self.centroidy[key] - return Resolution(q, None, lat, lon, "NONE", r.powod, - dokladnosc="CENTROID_MIEJSCOWOSCI", miejscowosc=m_txt) - return r - - def resolve_series(self, values: Iterable[Optional[str]], **kw) -> list[Resolution]: - return [self.resolve(v, **kw) for v in values] - - @staticmethod - def summarize(resolutions: list[Resolution]) -> dict: - s = LocationResolver.summarize(resolutions) - s["per_dokladnosc"] = {d: sum(1 for r in resolutions if r.dokladnosc == d) - for d in DOKLADNOSC} - z = sum(1 for r in resolutions if r.ma_wspolrzedne) - s["ze_wspolrzednymi"] = z - s["odsetek_ze_wspolrzednymi"] = round(z / len(resolutions), 6) if resolutions else 0.0 - return s - - -def resolver_from_gazeter_json(path, *, domyslna: Optional[str] = None) -> MultiLocalityResolver: - """Zbuduj :class:`MultiLocalityResolver` z gazetera ze współrzędnymi. - - Oczekiwany układ pliku: ``{"miejscowosci": {KLUCZ: {"nazwa","lat","lon", - "ulice": {nazwa: {"lat","lon","dlugosc_m","os"}}}}}``. - """ - import json - - with open(path, encoding="utf-8") as fh: - data = json.load(fh) - miejsc = data["miejscowosci"] if "miejscowosci" in data else data - return MultiLocalityResolver(miejsc, domyslna=domyslna) - - -def resolver_from_osm_json(path) -> LocationResolver: - """Zbuduj rozwiązywacz z pliku JSON z nazwami ulic (lista nazw albo mapa).""" - import json - - with open(path, encoding="utf-8") as fh: - data = json.load(fh) - if isinstance(data, dict): - if "streets" in data: - data = data["streets"] - elif "ulice" in data: - data = data["ulice"] - if isinstance(data, dict): - gaz = {k: (tuple(v) if isinstance(v, (list, tuple)) and len(v) == 2 else None) - for k, v in data.items()} - else: - gaz = {} - for item in data: - if isinstance(item, str): - gaz[item] = None - elif isinstance(item, dict): - nm = item.get("name") or item.get("nazwa") - if nm: - lat, lon = item.get("lat"), item.get("lon") - gaz[nm] = (float(lat), float(lon)) if lat is not None and lon is not None else None - return LocationResolver(gaz) diff --git a/build/lib/gridqueue/layout.py b/build/lib/gridqueue/layout.py deleted file mode 100644 index 061511f..0000000 --- a/build/lib/gridqueue/layout.py +++ /dev/null @@ -1,353 +0,0 @@ -"""Wydobycie oparte na UKŁADZIE STRONY, nie na wyrażeniach regularnych. - -Wyrażenie regularne działa na tekście spłaszczonym przez ekstraktor PDF: kolejność -słów jest kolejnością rysowania, a granice kolumn są odtwarzane ze spacji. Gdy -komórka jest pusta albo zawiera spację, sąsiednie pola się zlewają i wartość wsiąka -do złego pola. W poprzedniej wersji parsera TAURONA dotyczyło to 767 z 10 559 -wierszy (7,3%). - -Tu robimy odwrotnie: czytamy POŁOŻENIE każdego słowa (x0, x1, top, bottom) i -najpierw ustalamy geometrię tabeli, a dopiero potem przypisujemy słowa do komórek. -Dwie strategie, wybierane po tym, co dokument faktycznie zawiera: - - RULED -- dokument ma linie siatki (pionowe krawędzie prostokątów). Granice - kolumn są WPROST narysowane przez wytwórcę dokumentu; pusta komórka - nie może zlać się z sąsiednią, bo jest odgrodzona linią. - BANDED -- dokument nie ma linii. Granice wyprowadzamy z rozkładu pokrycia osi x - przez słowa: kolumna to spójny przedział pokryty słowami, granica to - pionowy korytarz bieli obecny na całej wysokości bloku tabeli. - -Wybór pdfplumber zamiast camelot/tabula: camelot w trybie lattice wymaga Ghostscriptu -i konwersji do rastra (granice kolumn odtwarzane z obrazu, nie z wektorów), tabula -wymaga JVM. pdfplumber daje bezpośredni dostęp do współrzędnych słów i krawędzi -wektorowych z pdfminer.six, więc granica kolumny jest liczbą z pliku, a nie wynikiem -detekcji krawędzi na bitmapie -- co jest dokładnie tą własnością, od której zależy -teza tego narzędzia. -""" - -from __future__ import annotations - -import re -import statistics -from dataclasses import dataclass, field -from typing import Any, Callable, Iterable, Optional, Sequence - -__all__ = [ - "ColumnGeometry", - "detect_ruled_columns", - "detect_banded_columns", - "extract_ruled_page", - "assign_words_to_columns", - "merge_continuation_rows", - "ShiftAudit", - "audit_column_shift", -] - - -# -------------------------------------------------------------------------- -# geometria kolumn -# -------------------------------------------------------------------------- - - -@dataclass -class ColumnGeometry: - """Granice kolumn na stronie: n+1 współrzędnych x dla n kolumn.""" - - bounds: list[float] - strategy: str # "ruled" | "banded" - page_number: int = -1 - - @property - def n_cols(self) -> int: - return max(0, len(self.bounds) - 1) - - def column_of(self, x0: float, x1: float) -> Optional[int]: - """Kolumna, do której należy słowo o rozpiętości [x0, x1]. - - Decyduje ŚRODEK słowa, nie jego lewa krawędź: słowo przycięte przez linię - siatki (co zdarza się przy wąskich kolumnach) trafia tam, gdzie leży jego - większa część. - """ - mid = 0.5 * (x0 + x1) - for i in range(self.n_cols): - if self.bounds[i] <= mid < self.bounds[i + 1]: - return i - if mid >= self.bounds[-1]: - return self.n_cols - 1 if self.n_cols else None - if mid < self.bounds[0]: - return 0 if self.n_cols else None - return None - - -def detect_ruled_columns(page, *, min_len: float = 5.0, tol: float = 1.5) -> ColumnGeometry: - """Granice kolumn z pionowych krawędzi wektorowych strony. - - Krawędzie krótsze niż ``min_len`` to zwykle ozdobniki / ramki nagłówka, nie - linie siatki. Krawędzie odległe o mniej niż ``tol`` to dwie strony tej samej - grubej linii -- scalane do średniej. - """ - xs = sorted( - e["x0"] for e in page.edges - if e.get("orientation") == "v" and (e["bottom"] - e["top"]) > min_len - ) - merged: list[list[float]] = [] - for x in xs: - if merged and x - merged[-1][-1] <= tol: - merged[-1].append(x) - else: - merged.append([x]) - bounds = [float(statistics.fmean(g)) for g in merged] - return ColumnGeometry(bounds, "ruled", getattr(page, "page_number", -1)) - - -def detect_banded_columns( - words: Sequence[dict], - *, - min_gap: float = 4.0, - resolution: float = 0.5, -) -> ColumnGeometry: - """Granice kolumn z pionowych korytarzy bieli w bloku słów. - - Buduje wektor pokrycia osi x (czy jakiekolwiek słowo zajmuje daną pozycję), - znajduje przerwy dłuższe niż ``min_gap`` i stawia granicę w ich środku. - Używane, gdy dokument nie ma linii siatki. - """ - if not words: - return ColumnGeometry([], "banded") - x_min = min(w["x0"] for w in words) - x_max = max(w["x1"] for w in words) - n = max(1, int((x_max - x_min) / resolution) + 1) - cover = bytearray(n) - for w in words: - a = int((w["x0"] - x_min) / resolution) - b = min(n, int((w["x1"] - x_min) / resolution) + 1) - for i in range(max(0, a), b): - cover[i] = 1 - bounds = [x_min - 1.0] - i = 0 - while i < n: - if cover[i] == 0: - j = i - while j < n and cover[j] == 0: - j += 1 - if (j - i) * resolution >= min_gap and i > 0 and j < n: - bounds.append(x_min + (i + j) / 2.0 * resolution) - i = j - else: - i += 1 - bounds.append(x_max + 1.0) - return ColumnGeometry(bounds, "banded") - - -# -------------------------------------------------------------------------- -# przypisanie słów do komórek -# -------------------------------------------------------------------------- - - -def assign_words_to_columns( - words: Iterable[dict], - geom: ColumnGeometry, - *, - line_tol: float = 2.0, -) -> list[list[str]]: - """Ułóż słowa w wiersze wizualne, a w wierszu -- w komórki wg geometrii kolumn.""" - ws = sorted(words, key=lambda w: (round(w["top"], 1), w["x0"])) - lines: list[list[dict]] = [] - for w in ws: - if lines and abs(w["top"] - lines[-1][0]["top"]) <= line_tol: - lines[-1].append(w) - else: - lines.append([w]) - out: list[list[str]] = [] - for ln in lines: - cells: list[list[str]] = [[] for _ in range(geom.n_cols)] - for w in sorted(ln, key=lambda w: w["x0"]): - ci = geom.column_of(w["x0"], w["x1"]) - if ci is not None: - cells[ci].append(w["text"]) - out.append([" ".join(c).strip() for c in cells]) - return out - - -def merge_continuation_rows( - lines: Sequence[Sequence[str]], - is_row_start: Callable[[Sequence[str]], bool], - *, - joiner: str = " ", -) -> list[list[str]]: - """Scal wiersze wielolinijkowe. - - ``is_row_start`` rozstrzyga, czy linia rozpoczyna nowy rekord (u polskich - publikujących: pierwsza komórka to numer porządkowy). Linie pomiędzy są - dopisywane do ostatniego rekordu, kolumna po kolumnie -- dzięki temu zawinięty - adres nie przenosi się do sąsiedniego pola. - """ - rows: list[list[str]] = [] - for ln in lines: - if is_row_start(ln) or not rows: - rows.append(list(ln)) - else: - for i, v in enumerate(ln): - if i >= len(rows[-1]): - rows[-1].append(v) - elif v: - rows[-1][i] = (rows[-1][i] + joiner + v).strip() if rows[-1][i] else v - return rows - - -def extract_ruled_page(page, geom: Optional[ColumnGeometry] = None, *, - intersection_tolerance: float = 5.0) -> list[list[Optional[str]]]: - """Wiersze strony z tabeli o narysowanej siatce. - - Granice pionowe podajemy jawnie (z ``detect_ruled_columns``), poziome zostawiamy - detekcji linii -- dzięki temu komórka wielolinijkowa jest scalana przez samą - siatkę, bez heurystyki ciągłości. - """ - if geom is None: - geom = detect_ruled_columns(page) - if geom.n_cols < 2: - return [] - settings = { - "vertical_strategy": "explicit", - "explicit_vertical_lines": geom.bounds, - "horizontal_strategy": "lines", - "intersection_tolerance": intersection_tolerance, - } - tbl = page.extract_table(settings) - return tbl or [] - - -# -------------------------------------------------------------------------- -# audyt przesunięcia kolumn -# -------------------------------------------------------------------------- - -_RE_DATE = re.compile(r"^\s*\d{2}[./-]\d{2}[./-]\d{4}\s*$|^\s*\d{4}-\d{2}-\d{2}\s*$") -_RE_NUM = re.compile(r"^\s*-?[\d \u00a0\u202f]*\d(?:[.,]\d+)?\s*$") -_RE_INT = re.compile(r"^\s*\d+\s*$") - - -def looks_like_date(v: Any) -> bool: - return bool(_RE_DATE.match(str(v))) if v is not None else False - - -def looks_like_number(v: Any) -> bool: - if v is None: - return False - if isinstance(v, (int, float)) and not isinstance(v, bool): - return True - return bool(_RE_NUM.match(str(v))) - - -#: liczba doklejona na początku pola tekstowego -- ślad wsiąknięcia sąsiedniej -#: kolumny liczbowej w pole opisowe (najczęstsza postać przesunięcia kolumn) -_RE_LEADING_NUM = re.compile(r"^\s*-?\d+(?:[.,]\d+)?(?:\s+-?\d+(?:[.,]\d+)?)*\s+\S") - - -def looks_like_text(v: Any) -> bool: - """Czy wartość może stać w polu opisowym. - - Odrzuca nie tylko czyste liczby i daty, ale też ciągi rozpoczynające się od - tokenu liczbowego przed tekstem ("0,1 0,1 WARUNKI PRZYŁĄCZENIA ..."). Ta - postać jest podpisem przesunięcia kolumn w wydobyciu regexowym: pusta komórka - mocy znika ze spłaszczonego tekstu i wartość mocy dokleja się do statusu. - """ - s = str(v).strip() - if not s or looks_like_number(s) or looks_like_date(s): - return False - return not bool(_RE_LEADING_NUM.match(s)) - - -#: poziom napięcia jest polem o wąskiej, znanej dziedzinie: skrót klasy (nn/SN/WN/NN) -#: albo wartość z jednostką ("110 kV", "15 kV"). Liczba bez jednostki albo zdanie -#: oznaczają, że do pola wsiąkła treść sąsiedniej kolumny. -_RE_VOLT = re.compile( - r"^\s*(?:nn|sn|wn|nn/sn|sn/nn|nN)\s*$" - r"|^\s*\d+(?:[.,]\d+)?\s*[kKmM]?[vV]\s*$" - r"|^\s*\d+(?:[.,]\d+)?\s*[kKmM][vV]\s*/\s*\d+(?:[.,]\d+)?\s*[kKmM][vV]\s*$", - re.IGNORECASE, -) - - -def looks_like_voltage(v: Any) -> bool: - return bool(_RE_VOLT.match(str(v))) if v is not None else False - - -#: predykaty dziedziny dla kolumn schematu -- "czy ta wartość MOŻE stać w tym polu" -DOMAIN_PREDICATES: dict[str, Callable[[Any], bool]] = { - "moc_wprowadzana": looks_like_number, - "moc_pobierana": looks_like_number, - "moc_dostepna": looks_like_number, - "moc_zarezerwowana": looks_like_number, - "data_wniosku": looks_like_date, - "data_warunkow": looks_like_date, - "data_odmowy": looks_like_date, - "data_umowy": looks_like_date, - "data_energizacji": looks_like_date, - "data_publikacji": looks_like_date, - "status_procesu": looks_like_text, - "klasa_zasobu": looks_like_text, - "poziom_napiecia": lambda v: looks_like_voltage(v), - "lokalizacja_tekst": lambda v: bool(str(v).strip()), -} - - -@dataclass -class ShiftAudit: - """Wynik audytu przesunięcia kolumn.""" - - n_wierszy: int - n_przesunietych: int - per_pole: dict[str, int] = field(default_factory=dict) - przyklady: list[dict] = field(default_factory=list) - - @property - def udzial(self) -> float: - return self.n_przesunietych / self.n_wierszy if self.n_wierszy else 0.0 - - def as_dict(self) -> dict: - return { - "n_wierszy": self.n_wierszy, - "n_przesunietych": self.n_przesunietych, - "udzial": round(self.udzial, 6), - "per_pole": dict(sorted(self.per_pole.items(), key=lambda kv: -kv[1])), - } - - -def audit_column_shift( - df, - predicates: Optional[dict[str, Callable[[Any], bool]]] = None, - *, - nullish: Optional[set[str]] = None, - n_examples: int = 5, -) -> ShiftAudit: - """Policz wiersze, w których jakaś niepusta wartość stoi w polu, do którego - nie może należeć (liczba w polu daty, tekst statusu w polu mocy itd.). - - To jest operacyjna definicja "przesuniętej kolumny": nie porównujemy z wzorcem, - tylko sprawdzamy WEWNĘTRZNĄ sprzeczność typu. Ta sama miara jest liczona dla - starego i nowego wydobycia, więc porównanie jest uczciwe. - """ - preds = predicates if predicates is not None else DOMAIN_PREDICATES - nl = nullish or {"", "-", "--", "---", "nan", "none", "brak", "nie dotyczy"} - cols = [c for c in preds if c in df.columns] - bad_rows = 0 - per_pole: dict[str, int] = {} - examples: list[dict] = [] - for idx, row in df.iterrows(): - offenders = [] - for c in cols: - v = row[c] - if v is None or (isinstance(v, float) and v != v): - continue - s = str(v).strip() - if s.lower() in nl: - continue - if not preds[c](v): - offenders.append((c, s)) - if offenders: - bad_rows += 1 - for c, _ in offenders: - per_pole[c] = per_pole.get(c, 0) + 1 - if len(examples) < n_examples: - examples.append({"index": idx, "naruszenia": offenders}) - return ShiftAudit(len(df), bad_rows, per_pole, examples) diff --git a/build/lib/gridqueue/longitudinal.py b/build/lib/gridqueue/longitudinal.py deleted file mode 100644 index 59f711b..0000000 --- a/build/lib/gridqueue/longitudinal.py +++ /dev/null @@ -1,496 +0,0 @@ -"""Porównanie dwóch edycji tego samego rejestru. - -Dlaczego to nie jest zwykłe złączenie po identyfikatorze --------------------------------------------------------- -Rejestry ustawowe **nie publikują trwałego identyfikatora wniosku**. U części -publikujących pole identyfikatora jest puste w niemal każdym wierszu, a pakiet -wstawia wtedy zastępnik oparty na liczbie porządkowej w dokumencie. Taki -zastępnik jest stabilny w obrębie jednej edycji i **bezwartościowy między -edycjami**: wiersz numer 869 w jednej edycji nie jest tym samym wnioskiem co -wiersz 869 w następnej, bo pozycje się przesuwają. - -Śledzenie wniosku w czasie wymaga więc klucza zastępczego zbudowanego z treści. -Nie jest to obejście, lecz właściwość ujawnienia, którą trzeba zadeklarować: -klucz treściowy rozjeżdża się, gdy publikujący skoryguje którekolwiek z pól -wchodzących w jego skład, i wtedy ten sam wniosek wygląda jak zniknięcie -w parze z pojawieniem. - -Walidacja dopasowania ---------------------- -Macierz przejść statusu daje na to niezależny test. Jeśli klucz dopasowuje -właściwe wiersze, przejścia powinny biec **zgodnie z kierunkiem postępowania -administracyjnego** (złożony → w analizie → warunki wydane → umowa). Jeśli -dopasowuje losowo, przejścia będą rozłożone bez tego porządku. Własność -``udzial_przejsc_w_przod`` zwraca tę miarę, żeby nie trzeba jej było liczyć -ręcznie. -""" - -from __future__ import annotations - -import re -from functools import reduce - -from dataclasses import dataclass, field -from typing import Optional, Sequence - -import pandas as pd - -__all__ = [ - "DEFAULT_KEY_FIELDS", - "NODE_KEY_FIELDS", - - "STATUS_ORDER", - "TERMINAL_NEGATIVE", - "surrogate_key", - "EditionDelta", - "compare_editions", - "HELD_OUT_FIELDS", - "LinkageAudit", - "linkage_audit", - "RECALL_FIELDS", - "LinkageRecall", - "linkage_recall", -] - -#: Pola domyślnego klucza treściowego. Celowo BEZ dat i bez statusu: daty bywają -#: uzupełniane między edycjami, a status jest właśnie tym, czego zmianę mierzymy. -DEFAULT_KEY_FIELDS: tuple[str, ...] = ( - "publikujacy", - "lokalizacja_tekst", - "poziom_napiecia", - "klasa_zasobu", - "moc_wprowadzana", - "moc_pobierana", -) - - -#: Klucz dla wierszy encji WEZEL. Domyślny `DEFAULT_KEY_FIELDS` jest zbudowany -#: dla encji WNIOSEK i na wierszach węzłowych ROZPADA SIĘ: pola `klasa_zasobu`, -#: `moc_wprowadzana` i `moc_pobierana` są tam puste, więc klucz traci -#: rozróżnialność. Zmierzone na parze wydań publikującego hiszpańskiego: -#: kluczem domyślnym 916 z 1838 wierszy wpada w kolizję i 660 zostaje -#: odrzuconych jako niejednoznaczne, a kluczem poniżej kolizji jest ZERO, -#: wszystkie 1838 par dopasowuje się jednoznacznie, przy precyzji i czułości -#: równych 1,000. -#: -#: Wniosek ogólniejszy: klucz treściowy musi być dobrany do ENCJI, tak samo jak -#: rdzeń schematu. Użycie klucza wnioskowego do wierszy węzłowych nie zgłasza -#: błędu, po cichu produkuje kolizje, które w dalszej analizie wyglądają jak -#: zdarzenia w rejestrze. -NODE_KEY_FIELDS: tuple = ("publikujacy", "id_wezla") - -#: Porządek etapów postępowania. Służy wyłącznie do oceny, czy przejścia biegną -#: w przód, nie jest słownikiem kontrolowanym schematu. -STATUS_ORDER: dict[str, int] = { - "WNIOSEK_ZLOZONY": 0, - "WNIOSEK_NIEKOMPLETNY": 1, - "W_TRAKCIE_ANALIZY": 2, - "WARUNKI_WYDANE": 3, - "UMOWA_OBOWIAZUJACA": 4, - "PRZYLACZONY": 5, -} - -#: Stany kończące postępowanie bez przyłączenia. -TERMINAL_NEGATIVE: frozenset = frozenset( - {"ODMOWA", "WNIOSEK_WYCOFANY", "WARUNKI_WYGASLE"} -) - - -def _jako_tekst(v) -> str: - """Wartosc jako lancuch; brak jako lancuch pusty, niezaleznie od wersji pandas.""" - if v is None: - return "" - if isinstance(v, float) and v != v: - return "" - return str(v) - - -def _jako_tekst_zero_jak_brak(v) -> str: - """Jak `_jako_tekst`, ale wartość liczbowa równa zeru daje łańcuch pusty.""" - s = _jako_tekst(v) - if s == "": - return "" - try: - return "" if float(s) == 0.0 else s - except (TypeError, ValueError): - return s - - -def surrogate_key( - df: pd.DataFrame, - fields: Sequence[str] = DEFAULT_KEY_FIELDS, - zero_jako_brak: bool = False, -) -> pd.Series: - """Klucz treściowy wiersza, do dopasowania między edycjami. - - `zero_jako_brak` zrównuje wartość 0 z brakiem wartości. Publikujący bywa - niekonsekwentny: tę samą nieujawnioną moc zapisuje raz jako pustą komórkę, - raz jako zero, i wtedy klucz rozpada parę, która dotyczy jednego wniosku. - Na parze edycji operatora przesyłowego włączenie tej opcji odzyskuje - 12 z 51 par traconych przez klucz. Domyślnie WYŁĄCZONE, bo zero jest - wartością ujawnioną, a brak jej nieujawnieniem, zrównanie ich jest - decyzją analityka, nie własnością danych, i musi być widoczne w kodzie. - """ - uzyte = [f for f in fields if f in df.columns] - if not uzyte: - raise ValueError(f"żadne z pól klucza nie występuje w ramce: {list(fields)}") - # Konwersja wprost, zamiast .astype(str): w pandas 2 brak stawal sie lancuchem - # "nan", a w pandas 3 pozostaje wartoscia brakujaca i zlaczenie rzuca TypeError. - # Jawna konwersja daje ten sam klucz w obu wersjach i czyni regule "brak jest - # wartoscia" wlasnoscia kodu, a nie ubocznym skutkiem rzutowania typu. - konw = _jako_tekst_zero_jak_brak if zero_jako_brak else _jako_tekst - kolumny = [df[c].map(konw) for c in uzyte] - return reduce(lambda a, b: a + "|" + b, kolumny) - - -@dataclass -class EditionDelta: - """Wynik porównania dwóch edycji.""" - - edycja_a: str - edycja_b: str - wierszy_a: int - wierszy_b: int - kluczy_unikalnych_a: int - kluczy_unikalnych_b: int - wspolnych: int - nowych: int - ubylych: int - zmian_statusu: int - przejscia: pd.DataFrame = field(repr=False) - nowe_zamkniete: int = 0 - ubyle_czynne: int = 0 - przejscia_wstecz: int = 0 - wierszy_w_kolizji_a: int = 0 - wierszy_w_kolizji_b: int = 0 - - @property - def udzial_przejsc_w_przod(self) -> Optional[float]: - """Udział przejść biegnących zgodnie z porządkiem postępowania. - - Wysoka wartość jest dowodem, że klucz treściowy dopasowuje właściwe - wiersze; niska oznacza dopasowanie losowe i unieważnia porównanie. - Zwraca ``None``, gdy nie ma ani jednego uporządkowanego przejścia. - """ - w_przod = uporzadkowanych = 0 - for a in self.przejscia.index: - for b in self.przejscia.columns: - n = int(self.przejscia.loc[a, b]) - if a == b or not n: - continue - if a in STATUS_ORDER and b in STATUS_ORDER: - uporzadkowanych += n - w_przod += n if STATUS_ORDER[b] > STATUS_ORDER[a] else 0 - elif a in STATUS_ORDER and b in TERMINAL_NEGATIVE: - uporzadkowanych += n - w_przod += n - return (w_przod / uporzadkowanych) if uporzadkowanych else None - - def as_dict(self) -> dict: - return { - "edycja_a": self.edycja_a, - "edycja_b": self.edycja_b, - "wierszy_a": self.wierszy_a, - "wierszy_b": self.wierszy_b, - "wierszy_netto": self.wierszy_b - self.wierszy_a, - "kluczy_unikalnych_a": self.kluczy_unikalnych_a, - "kluczy_unikalnych_b": self.kluczy_unikalnych_b, - "wspolnych": self.wspolnych, - "nowych": self.nowych, - "ubylych": self.ubylych, - "zmian_statusu": self.zmian_statusu, - "udzial_przejsc_w_przod": self.udzial_przejsc_w_przod, - "nowe_zamkniete": self.nowe_zamkniete, - "ubyle_czynne": self.ubyle_czynne, - "przejscia_wstecz": self.przejscia_wstecz, - "wierszy_w_kolizji_a": self.wierszy_w_kolizji_a, - "wierszy_w_kolizji_b": self.wierszy_w_kolizji_b, - "odrzuconych_jako_niejednoznaczne_a": self.wierszy_a - self.kluczy_unikalnych_a, - "odrzuconych_jako_niejednoznaczne_b": self.wierszy_b - self.kluczy_unikalnych_b, - "migawka_monotoniczna": self.nowe_zamkniete == 0 and self.ubyle_czynne == 0, - } - - -def compare_editions( - a: pd.DataFrame, - b: pd.DataFrame, - edycja_a: str = "A", - edycja_b: str = "B", - fields: Sequence[str] = DEFAULT_KEY_FIELDS, -) -> EditionDelta: - """Porównaj dwie edycje rejestru i zwróć przepływy oraz przejścia statusu. - - Wiersze o powtarzającym się kluczu są odrzucane przed dopasowaniem (pierwszy - zachowany), bo dla nich przypisanie jest niejednoznaczne; liczba kluczy - unikalnych wobec liczby wierszy pokazuje, ile wiersze na tym tracą. - """ - a = a.copy() - b = b.copy() - a["_klucz"] = surrogate_key(a, fields) - b["_klucz"] = surrogate_key(b, fields) - au = a.drop_duplicates("_klucz").set_index("_klucz") - bu = b.drop_duplicates("_klucz").set_index("_klucz") - - wsp = au.index.intersection(bu.index) - nowe = bu.index.difference(au.index) - ubyle = au.index.difference(bu.index) - - kol_a = int(a["_klucz"].duplicated(keep=False).sum()) - kol_b = int(b["_klucz"].duplicated(keep=False).sum()) - - tr = pd.crosstab(au.loc[wsp, "status_procesu"], bu.loc[wsp, "status_procesu"]) - zmian = int(sum(int(tr.loc[i, j]) for i in tr.index for j in tr.columns if i != j)) - wstecz = int(sum( - int(tr.loc[i, j]) - for i in tr.index for j in tr.columns - if i != j and i in STATUS_ORDER and j in STATUS_ORDER - and STATUS_ORDER[j] < STATUS_ORDER[i] - )) - czynne = set(STATUS_ORDER) - {"PRZYLACZONY"} - return EditionDelta( - edycja_a=edycja_a, - edycja_b=edycja_b, - wierszy_a=len(a), - wierszy_b=len(b), - kluczy_unikalnych_a=len(au), - kluczy_unikalnych_b=len(bu), - wspolnych=len(wsp), - nowych=len(nowe), - ubylych=len(ubyle), - zmian_statusu=zmian, - przejscia=tr, - nowe_zamkniete=int(bu.loc[nowe, "status_procesu"].isin(TERMINAL_NEGATIVE).sum()), - ubyle_czynne=int(au.loc[ubyle, "status_procesu"].isin(czynne).sum()), - przejscia_wstecz=wstecz, - wierszy_w_kolizji_a=kol_a, - wierszy_w_kolizji_b=kol_b, - ) - - -#: Pola, których NIE ma w kluczu i które służą do niezależnej oceny dopasowania. -#: Jeśli para jest fałszywa, te pola się rozjadą, klucz ich nie wymusza. -HELD_OUT_FIELDS: tuple = ( - "_podmiot", - "_nazwa_obiektu", - "data_wniosku", - "_mz_pv", - "_mz_fw", - "_mz_mee_rozladowania", - "_mz_mee_ladowania", - "_mz_odb", - "_mz_inne", -) - -_FORMA_PRAWNA = re.compile( - r"\b(SP\.?\s*Z\s*O\.?\s*O\.?|S\.?A\.?|SPÓŁKA|AKCYJNA" - r"|Z\s*OGRANICZONĄ|ODPOWIEDZIALNOŚCIĄ)\b" -) -_NIEALFANUM = re.compile(r"[^A-ZĄĆĘŁŃÓŚŹŻ0-9]+") - - -def _norm_txt(v) -> str: - if v is None or (isinstance(v, float) and v != v): - return "" - return re.sub(r"\s+", " ", str(v)).strip().upper() - - -def _rdzen_nazwy(v) -> str: - """Nazwa sprowadzona do rdzenia: bez formy prawnej, interpunkcji i spacji. - - Bez tego „Stigma sp.z o.o." i „Stigma Sp. z o.o." byłyby różnymi podmiotami, - a publikujący zmienia zapis formy prawnej między edycjami. - """ - return _NIEALFANUM.sub("", _FORMA_PRAWNA.sub("", _norm_txt(v))) - - -@dataclass -class LinkageAudit: - """Ocena dopasowania par na polach WYŁĄCZONYCH z klucza. - - Nie jest to walidacja wobec prawdy zewnętrznej, bo takiej dla tego rejestru - nie ma, jest to test wewnętrznej spójności: klucz nie wymusza zgodności - tych pól, więc ich zgodność jest niezależnym świadectwem, że para dotyczy - tego samego wniosku. Zgłaszamy obie granice, bo przypadki niepewne nie - rozstrzygają się same. - """ - - par: int - potwierdzonych: int - niepewnych: int - falszywych: int - rozbieznosci: pd.DataFrame = field(repr=False) - - @property - def precyzja_dolna(self) -> float: - """Niepewne liczone jako błędne.""" - return self.potwierdzonych / self.par if self.par else float("nan") - - @property - def precyzja_gorna(self) -> float: - """Niepewne liczone jako trafne.""" - return (self.par - self.falszywych) / self.par if self.par else float("nan") - - def as_dict(self) -> dict: - return { - "par": self.par, - "potwierdzonych": self.potwierdzonych, - "niepewnych": self.niepewnych, - "falszywych": self.falszywych, - "precyzja_dolna": self.precyzja_dolna, - "precyzja_gorna": self.precyzja_gorna, - } - - -def linkage_audit( - a: pd.DataFrame, - b: pd.DataFrame, - fields: Sequence[str] = DEFAULT_KEY_FIELDS, - held_out: Sequence[str] = HELD_OUT_FIELDS, -) -> LinkageAudit: - """Oceń dopasowanie kluczem treściowym na polach z klucza wyłączonych. - - Para jest klasyfikowana jako: - - * **fałszywa**, rdzeń nazwy podmiotu ORAZ rdzeń nazwy obiektu są rozbieżne - i żaden nie zawiera się w drugim; to dwa różne wnioski, które przypadkiem - dzielą lokalizację, napięcie, klasę i obie moce; - * **niepewna**, rozbieżny jest dokładnie jeden z tych dwóch; - * **potwierdzona**, oba zgodne albo nieobecne. - - Pola uzupełnione jednostronnie (puste w jednej edycji, wypełnione w drugiej) - nie są liczone jako rozbieżność, bo publikujący uzupełnia rekordy między - edycjami i jest to zmiana TEGO SAMEGO wniosku, nie świadectwo innego. - """ - a = a.copy() - b = b.copy() - a["_klucz"] = surrogate_key(a, fields) - b["_klucz"] = surrogate_key(b, fields) - au = a.drop_duplicates("_klucz").set_index("_klucz") - bu = b.drop_duplicates("_klucz").set_index("_klucz") - wsp = au.index.intersection(bu.index) - - wiersze = [] - potw = niep = falsz = 0 - for k in wsp: - ra, rb = au.loc[k], bu.loc[k] - for p in held_out: - if p not in au.columns or p not in bu.columns: - continue - va, vb = _norm_txt(ra.get(p)), _norm_txt(rb.get(p)) - if va == vb: - continue - if va == "" or vb == "": - kat = "uzupelnienie_jednostronne" - elif _rdzen_nazwy(va) == _rdzen_nazwy(vb): - kat = "inny_zapis_tej_samej_nazwy" - elif _rdzen_nazwy(va) in _rdzen_nazwy(vb) or _rdzen_nazwy(vb) in _rdzen_nazwy(va): - kat = "nazwa_rozszerzona_lub_skrocona" - else: - kat = "konflikt_tresci" - wiersze.append({"klucz": k, "pole": p, "kategoria": kat, "a": va, "b": vb}) - - pa, pb = _rdzen_nazwy(ra.get("_podmiot")), _rdzen_nazwy(rb.get("_podmiot")) - oa, ob = _rdzen_nazwy(ra.get("_nazwa_obiektu")), _rdzen_nazwy(rb.get("_nazwa_obiektu")) - - def _rozne(x: str, y: str) -> bool: - return bool(x) and bool(y) and x not in y and y not in x - - rp, ro = _rozne(pa, pb), _rozne(oa, ob) - if rp and ro: - falsz += 1 - elif rp or ro: - niep += 1 - else: - potw += 1 - - return LinkageAudit( - par=len(wsp), - potwierdzonych=potw, - niepewnych=niep, - falszywych=falsz, - rozbieznosci=pd.DataFrame(wiersze), - ) - - -#: Pola tożsamości używane do odzyskania par, których klucz treściowy nie połączył. -#: Muszą być ROZŁĄCZNE z polami klucza. Pole wspólne z kluczem nie wykryje pary -#: rozerwanej zmianą właśnie tego pola, bo sama tożsamość też się wtedy rozjedzie: -#: dołożenie lokalizacji do tego zestawu obniża zmierzoną czułość z 0,9652 do -#: 0,9757, co wygląda na poprawę, a jest przeoczeniem dziesięciu par. -RECALL_FIELDS: tuple = ("_podmiot", "_nazwa_obiektu") - - -@dataclass -class LinkageRecall: - """Czułość dopasowania: ile par klucz treściowy POMINĄŁ. - - `linkage_audit` mierzy precyzję, czy połączone pary są tą samą sprawą. - Nie mówi nic o parach, których klucz nie połączył, a te są groźniejsze: - rozerwana para pojawia się jako jeden wiersz „ubyły" i jeden „nowy", - więc wygląda jak zdarzenie w rejestrze, a jest artefaktem dopasowania. - """ - - kluczy_a: int - kluczy_b: int - dopasowanych: int - odzyskanych: int - odzyskane: pd.DataFrame = field(repr=False) - - @property - def czulosc_klucza(self) -> float: - """Udział par faktycznie połączonych wśród par możliwych do połączenia.""" - mozliwe = self.dopasowanych + self.odzyskanych - return self.dopasowanych / mozliwe if mozliwe else float("nan") - - def as_dict(self) -> dict: - return {"kluczy_a": self.kluczy_a, "kluczy_b": self.kluczy_b, - "dopasowanych": self.dopasowanych, "odzyskanych": self.odzyskanych, - "czulosc_klucza": self.czulosc_klucza} - - -def linkage_recall( - a: pd.DataFrame, - b: pd.DataFrame, - fields: Sequence[str] = DEFAULT_KEY_FIELDS, - pola_tozsamosci: Sequence[str] = RECALL_FIELDS, -) -> LinkageRecall: - """Szuka par pominiętych przez klucz treściowy, po polach tożsamości. - - Bierze wiersze NIEDOPASOWANE kluczem i próbuje je połączyć po polach, które - do klucza nie wchodzą, nazwie podmiotu, nazwie obiektu i lokalizacji. - Para odzyskana tą drogą dotyczy tego samego wniosku, któremu zmieniono - którąś z wartości wchodzących do klucza; zwracana ramka podaje, które - pole klucza się różni, więc wynik jest sprawdzalny, a nie deklarowany. - - Odzyskiwane są wyłącznie dopasowania JEDNOZNACZNE: jeśli ta sama tożsamość - występuje po którejkolwiek stronie więcej niż raz, para nie jest liczona. - """ - aa, bb = a.copy(), b.copy() - aa["_klucz"] = surrogate_key(aa, fields) - bb["_klucz"] = surrogate_key(bb, fields) - wspolne = set(aa["_klucz"]) & set(bb["_klucz"]) - reszta_a = aa[~aa["_klucz"].isin(wspolne)] - reszta_b = bb[~bb["_klucz"].isin(wspolne)] - uzyte = [p for p in pola_tozsamosci if p in aa.columns and p in bb.columns] - if not uzyte or not len(reszta_a) or not len(reszta_b): - return LinkageRecall(aa["_klucz"].nunique(), bb["_klucz"].nunique(), - len(wspolne), 0, pd.DataFrame()) - def tozsamosc(df): - return reduce(lambda x, y: x + "|" + y, - [df[c].map(_jako_tekst).str.strip().str.upper() for c in uzyte]) - reszta_a = reszta_a.assign(_toz=tozsamosc(reszta_a)) - reszta_b = reszta_b.assign(_toz=tozsamosc(reszta_b)) - jedno_a = reszta_a[~reszta_a["_toz"].duplicated(keep=False) & (reszta_a["_toz"] != "||")] - jedno_b = reszta_b[~reszta_b["_toz"].duplicated(keep=False) & (reszta_b["_toz"] != "||")] - wsp = set(jedno_a["_toz"]) & set(jedno_b["_toz"]) - ia = jedno_a[jedno_a["_toz"].isin(wsp)].set_index("_toz") - ib = jedno_b[jedno_b["_toz"].isin(wsp)].set_index("_toz") - wiersze = [] - for t in sorted(wsp): - ra, rb = ia.loc[t], ib.loc[t] - rozne = [f for f in fields - if f in aa.columns and _jako_tekst(ra.get(f)) != _jako_tekst(rb.get(f))] - wiersze.append({"tozsamosc": t, "pola_klucza_rozne": ";".join(rozne), - "status_a": ra.get("status_procesu"), "status_b": rb.get("status_procesu")}) - return LinkageRecall(aa["_klucz"].nunique(), bb["_klucz"].nunique(), - len(wspolne), len(wsp), pd.DataFrame(wiersze)) diff --git a/build/lib/gridqueue/quality.py b/build/lib/gridqueue/quality.py deleted file mode 100644 index bbe0f80..0000000 --- a/build/lib/gridqueue/quality.py +++ /dev/null @@ -1,389 +0,0 @@ -"""Kontrola jakości zbioru: reguły z przepisu i z semantyki postępowania. - -Każda reguła zwraca LICZBĘ NARUSZEŃ, nie wyjątek. Naruszenie nie jest błędem -narzędzia -- jest własnością ujawnienia i właśnie po to ten moduł istnieje. -Raport jakości jest wynikiem naukowym: mówi, na ile publikacja ustawowa jest -wewnętrznie spójna. - -Reguły: - R1 monotonicznosc_dat -- wniosek <= warunki <= umowa <= energizacja - R2 waznosc_warunkow_2lata -- warunki przyłączenia są ważne 2 lata - (art. 7 ust. 8i); data utraty ważności nie może - wypaść później niż 2 lata po ich określeniu - R3 dopuszczalnosc_przejsc -- status musi być zgodny z zestawem obecnych dat - R4 spojnosc_jednostek_mocy -- wartości mocy w kW muszą mieścić się w zakresie - fizycznym przyłączeń >1 kV (wykrywa pomyłkę MW/kW) - R5 zakresy_wartosci -- moce nieujemne, daty w oknie 1990-2100 - R6 duplikaty_identyfikatorow -- ten sam id_wniosku w wielu wierszach - R7 kompletnosc_rdzenia -- rdzeń WŁAŚCIWEJ DLA WIERSZA ENCJI: dla WNIOSKU - 4 pola niepuste oraz co najmniej jedno z pary - (moc_pobierana, moc_wprowadzana); dla WEZLA - id_wezla oraz co najmniej jedno z pary - (moc_dostepna, ograniczenie_flaga) - R8 slownik_kontrolowany -- klasa_zasobu i status_procesu ze słownika -""" - -from __future__ import annotations - -import datetime as _dt -from dataclasses import dataclass, field - -import pandas as pd -from typing import Any, Callable, Optional - -from .schema import (CORE_ALTERNATIVES, CORE_BY_ENTITY, CORE_FIELDS, DEFAULT_ENTITY, - ENTITY_COLUMN, KLASY_ZASOBU, STATUSY, core_complete_mask, _is_null) - -__all__ = ["Rule", "RULES", "run_quality", "QualityReport"] - - -@dataclass -class Rule: - kod: str - nazwa: str - podstawa: str - fn: Callable[[Any], tuple[int, dict]] = field(repr=False) - - -@dataclass -class QualityReport: - n_wierszy: int - reguly: list[dict] - - def as_dict(self) -> dict: - return {"n_wierszy": self.n_wierszy, - "n_regul": len(self.reguly), - "reguly": self.reguly, - "naruszen_lacznie": sum(r["naruszenia"] for r in self.reguly)} - - def as_frame(self): - """Jeden wiersz na regule: kod, nazwa, naruszenia, udzial. - - Kolumna `szczegoly` jest celowo pominieta, jej zawartosc rozni sie - strukturalnie miedzy regulami, wiec w ramce bylaby kolumna obiektow. - Pelne szczegoly zwraca `as_dict()`. - """ - import pandas as pd - - return pd.DataFrame( - [{"kod": r["kod"], "nazwa": r["nazwa"], - "naruszenia": r["naruszenia"], "udzial": r["udzial"]} - for r in self.reguly] - ) - - -def _plus_years(d: _dt.date, n: int) -> _dt.date: - """Data przesunieta o n lat; 29 lutego w roku nieprzestepnym -> 28 lutego.""" - try: - return d.replace(year=d.year + n) - except ValueError: - return d.replace(year=d.year + n, day=28) - - -def _d(v) -> Optional[_dt.date]: - if _is_null(v): - return None - try: - return _dt.date.fromisoformat(str(v)[:10]) - except ValueError: - return None - - -# -------------------------------------------------------------------------- - - -def r1_monotonicznosc_dat(df) -> tuple[int, dict]: - order = ["data_wniosku", "data_warunkow", "data_umowy", "data_energizacji"] - have = [c for c in order if c in df.columns] - n_bad, pary = 0, {} - for i in range(len(have) - 1): - a, b = have[i], have[i + 1] - cnt = 0 - for va, vb in zip(df[a], df[b]): - da, db = _d(va), _d(vb) - if da and db and da > db: - cnt += 1 - if cnt: - pary[f"{a}>{b}"] = cnt - # wiersz liczony raz - mask = [False] * len(df) - for i in range(len(have) - 1): - a, b = have[i], have[i + 1] - for j, (va, vb) in enumerate(zip(df[a], df[b])): - da, db = _d(va), _d(vb) - if da and db and da > db: - mask[j] = True - n_bad = sum(mask) - return n_bad, {"pary": pary, "porownywane_pola": have} - - -def r2_waznosc_warunkow(df) -> tuple[int, dict]: - """Warunki przyłączenia są ważne dwa lata (art. 7 ust. 8i). - - Jeśli publikujący podaje datę utraty ważności, musi ona wypadać nie później - niż dwa lata po dacie określenia warunków. Sprawdzamy też umowy zawarte po - upływie dwóch lat od warunków, które ich nie utraciły. - """ - if "data_warunkow" not in df.columns: - return 0, {"uwaga": "brak pola data_warunkow"} - col_utr = "_data_utraty_waznosci" if "_data_utraty_waznosci" in df.columns else None - n_utr_bad = n_umowa_bad = 0 - n_sprawdzonych_utr = 0 - nadwyzki: list[int] = [] - for i in range(len(df)): - dw = _d(df["data_warunkow"].iloc[i]) - if not dw: - continue - limit = _plus_years(dw, 2) - if col_utr: - du = _d(df[col_utr].iloc[i]) - if du: - n_sprawdzonych_utr += 1 - if du > limit: - n_utr_bad += 1 - nadwyzki.append((du - limit).days) - if "data_umowy" in df.columns: - dm = _d(df["data_umowy"].iloc[i]) - if dm and dm > limit: - n_umowa_bad += 1 - det = { - "utrata_waznosci_pozniej_niz_2_lata": n_utr_bad, - "sprawdzonych_dat_utraty": n_sprawdzonych_utr, - "umowa_po_uplywie_2_lat_od_warunkow": n_umowa_bad, - } - if nadwyzki: - nadwyzki.sort() - det["nadwyzka_dni_mediana"] = nadwyzki[len(nadwyzki) // 2] - det["nadwyzka_dni_min"] = nadwyzki[0] - det["nadwyzka_dni_max"] = nadwyzki[-1] - det["poza_tolerancja_30_dni"] = sum(1 for x in nadwyzki if x > 30) - # Liczba MUSI byc policzona, nie wpisana. Wczesniej stala tu literalna - # "334" -- akurat tyle wypadalo na panelu czterech publikujacych, ale - # ten sam string wracal przy KAZDYM wywolaniu, takze per publikujacy - # i na panelu szesciu, gdzie n_utr_bad ma inna wartosc. Diagnostyka - # podawala wtedy liczbe niezgodna z wlasnym wynikiem reguly. - det["interpretacja"] = ( - "systematyczne przesuniecie o stala liczbe dni wskazuje na regule " - f"administracyjna publikujacego, a nie na {n_utr_bad} niezaleznych " - "naruszen terminu" - ) - return n_utr_bad + n_umowa_bad, det - - -#: jakie daty MUSZĄ / NIE MOGĄ istnieć przy danym statusie -_STATUS_WYMAGA: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = { - # status: (pola wymagane, pola zakazane) - "WARUNKI_WYDANE": (("data_warunkow",), ("data_odmowy",)), - "ODMOWA": (("data_odmowy",), ("data_umowy", "data_energizacji")), - "UMOWA_OBOWIAZUJACA": (("data_umowy",), ("data_odmowy",)), - "PRZYLACZONY": (("data_energizacji",), ("data_odmowy",)), - "WNIOSEK_ZLOZONY": ((), ("data_umowy", "data_energizacji")), - "W_TRAKCIE_ANALIZY": ((), ("data_umowy", "data_energizacji")), - "WNIOSEK_NIEKOMPLETNY": ((), ("data_umowy", "data_energizacji")), -} - - -def r3_dopuszczalnosc_przejsc(df) -> tuple[int, dict]: - """Status musi byc zgodny z zestawem obecnych dat. - - Wymog obecnosci daty stosujemy TYLKO do pol, ktore dany publikujacy w ogole - ujawnia. Brytyjski rejestr nie publikuje zadnych dat postepowania -- zadanie - od niego "daty umowy" nie jest kontrola spojnosci, tylko bledem kategorii. - Pola ujawniane wyznaczamy empirycznie: kolumna z co najmniej jedna wartoscia - niepusta w obrebie publikujacego. - """ - if "status_procesu" not in df.columns: - return 0, {} - date_cols = [c for c in ("data_wniosku", "data_warunkow", "data_odmowy", - "data_umowy", "data_energizacji") if c in df.columns] - globalne = {c for c in date_cols if df[c].map(lambda v: not _is_null(v)).any()} - if "publikujacy" in df.columns: - ujawniane = {} - for pub, g in df.groupby("publikujacy"): - ujawniane[pub] = {c for c in date_cols if g[c].map(lambda v: not _is_null(v)).any()} - else: - ujawniane = None - szczegoly: dict[str, int] = {} - n_bad = 0 - for i in range(len(df)): - st = df["status_procesu"].iloc[i] - spec = _STATUS_WYMAGA.get(st) - if not spec: - continue - # Klucz moze nie istniec: groupby pomija grupe o pustej nazwie publikujacego, - # wiec wiersz bez tej adnotacji nie ma wlasnego wpisu. Wtedy stosujemy zbior - # globalny zamiast rzucac KeyError i tracic cala regule. - dost = (ujawniane.get(df["publikujacy"].iloc[i], globalne) - if ujawniane is not None else globalne) - wymagane = tuple(c for c in spec[0] if c in dost) - zakazane = spec[1] - bad = False - for c in wymagane: - if c in df.columns and _is_null(df[c].iloc[i]): - szczegoly[f"{st}: brak {c}"] = szczegoly.get(f"{st}: brak {c}", 0) + 1 - bad = True - for c in zakazane: - if c in df.columns and not _is_null(df[c].iloc[i]): - szczegoly[f"{st}: nieoczekiwane {c}"] = szczegoly.get(f"{st}: nieoczekiwane {c}", 0) + 1 - bad = True - n_bad += bad - return n_bad, {"szczegoly": dict(sorted(szczegoly.items(), key=lambda kv: -kv[1])[:20])} - - -#: zakres fizyczny przyłączeń >1 kV w kW. Dolny próg 1 kW odrzuca wartości, -#: które najpewniej podano w MW zamiast kW; górny 5 GW -- powyżej największej -#: pojedynczej jednostki wytwórczej w KSE. -_MOC_MIN_KW, _MOC_MAX_KW = 1.0, 5_000_000.0 - - -def r4_spojnosc_jednostek(df) -> tuple[int, dict]: - cols = [c for c in ("moc_wprowadzana", "moc_pobierana", "moc_dostepna", - "moc_zarezerwowana") if c in df.columns] - per: dict[str, int] = {} - mask = [False] * len(df) - for c in cols: - cnt = 0 - for j, v in enumerate(df[c]): - if _is_null(v) or not isinstance(v, (int, float)): - continue - if v == 0: - continue - if v < _MOC_MIN_KW or v > _MOC_MAX_KW: - cnt += 1 - mask[j] = True - if cnt: - per[c] = cnt - return sum(mask), {"per_pole": per, "zakres_kw": [_MOC_MIN_KW, _MOC_MAX_KW]} - - -def r5_zakresy_wartosci(df) -> tuple[int, dict]: - lo, hi = _dt.date(1990, 1, 1), _dt.date(2100, 1, 1) - per: dict[str, int] = {} - mask = [False] * len(df) - for c in df.columns: - if c.startswith("data_") or c.startswith("_data_"): - cnt = 0 - for j, v in enumerate(df[c]): - d = _d(v) - if d and not (lo <= d <= hi): - cnt += 1 - mask[j] = True - if cnt: - per[c] = cnt - if c.startswith("moc_"): - cnt = 0 - for j, v in enumerate(df[c]): - if isinstance(v, (int, float)) and not _is_null(v) and v < 0: - cnt += 1 - mask[j] = True - if cnt: - per[c + " (ujemna)"] = cnt - return sum(mask), {"per_pole": per} - - -def r6_duplikaty_identyfikatorow(df) -> tuple[int, dict]: - if "id_wniosku" not in df.columns: - return 0, {} - s = df["id_wniosku"].dropna() - vc = s.value_counts() - dup = vc[vc > 1] - return int(dup.sum() - len(dup)), { - "n_unikalnych": int(s.nunique()), - "n_identyfikatorow_powtorzonych": int(len(dup)), - "max_krotnosc": int(dup.max()) if len(dup) else 0, - } - - -def r7_kompletnosc_rdzenia(df) -> tuple[int, dict]: - """Rdzeń schematu: wszystkie CORE_FIELDS niepuste oraz z każdej grupy - CORE_ALTERNATIVES co najmniej jedno pole niepuste. - - Grupa alternatywna istnieje, bo wniosek przyłączeniowy zawsze deklaruje moc, - lecz nie zawsze tę samą: wytwórczy wprowadzaną, odbiorczy pobieraną, - dwukierunkowy obie. Wymaganie jednej konkretnej zamieniałoby własność - schematu w pozorne naruszenie ujawnienia. - """ - if ENTITY_COLUMN in df.columns: - enc = df[ENTITY_COLUMN].map( - lambda v: DEFAULT_ENTITY if _is_null(v) else str(v).upper()) - else: - enc = pd.Series(DEFAULT_ENTITY, index=df.index) - - per: dict[str, int] = {} - n_enc: dict[str, int] = {} - for nazwa, spec in CORE_BY_ENTITY.items(): - sub = df.loc[enc == nazwa] - if not len(sub): - continue - n_enc[nazwa] = int(len(sub)) - for c in spec["wymagane"]: - if c not in sub.columns: - per[f"{nazwa}/{c}"] = int(len(sub)) - continue - cnt = int(sum(1 for v in sub[c] if _is_null(v))) - if cnt: - per[f"{nazwa}/{c}"] = cnt - for grupa in spec["alternatywy"]: - obecne = [c for c in grupa if c in sub.columns] - etykieta = f"{nazwa}/co najmniej jedno z: " + ", ".join(grupa) - if not obecne: - per[etykieta] = int(len(sub)) - continue - cnt = int(sum(1 for _, row in sub[obecne].iterrows() - if all(_is_null(row[c]) for c in obecne))) - if cnt: - per[etykieta] = cnt - return int((~core_complete_mask(df)).sum()), {"per_pole": per, "wierszy_encji": n_enc} - - -def r8_slownik_kontrolowany(df) -> tuple[int, dict]: - per = {} - mask = [False] * len(df) - for c, vocab in (("klasa_zasobu", KLASY_ZASOBU), ("status_procesu", STATUSY)): - if c not in df.columns: - continue - cnt = 0 - for j, v in enumerate(df[c]): - if not _is_null(v) and v not in vocab: - cnt += 1 - mask[j] = True - if cnt: - per[c] = cnt - return sum(mask), {"per_pole": per} - - -RULES: tuple[Rule, ...] = ( - Rule("R1", "monotoniczność dat postępowania", "semantyka procesu (art. 7 ust. 8l pkt 1)", - r1_monotonicznosc_dat), - Rule("R2", "dwuletnia ważność warunków przyłączenia", "art. 7 ust. 8i", - r2_waznosc_warunkow), - Rule("R3", "dopuszczalność stanu procesu wobec dat", "semantyka procesu", - r3_dopuszczalnosc_przejsc), - Rule("R4", "spójność jednostek mocy", "art. 7 ust. 8l (sieć >1 kV)", - r4_spojnosc_jednostek), - Rule("R5", "zakresy wartości", "kontrola techniczna", r5_zakresy_wartosci), - Rule("R6", "duplikaty identyfikatorów", "wymóg identyfikowalności pozycji", - r6_duplikaty_identyfikatorow), - Rule("R7", "kompletność rdzenia schematu", "art. 7 ust. 8l pkt 1/3/4", - r7_kompletnosc_rdzenia), - Rule("R8", "słownik kontrolowany", "harmonizacja międzyoperatorska", - r8_slownik_kontrolowany), -) - - -def run_quality(df, rules: Optional[tuple[Rule, ...]] = None) -> QualityReport: - out = [] - for rule in (rules or RULES): - try: - n, det = rule.fn(df) - except Exception as exc: # reguła nie może wywrócić raportu - n, det = -1, {"blad": f"{type(exc).__name__}: {exc}"} - out.append({ - "kod": rule.kod, - "nazwa": rule.nazwa, - "podstawa": rule.podstawa, - "naruszenia": int(n), - "udzial": round(n / len(df), 6) if len(df) and n >= 0 else None, - "szczegoly": det, - }) - return QualityReport(int(len(df)), out) diff --git a/build/lib/gridqueue/registry.py b/build/lib/gridqueue/registry.py deleted file mode 100644 index 41c0980..0000000 --- a/build/lib/gridqueue/registry.py +++ /dev/null @@ -1,70 +0,0 @@ -"""Rejestr adapterów i wykrywanie publikującego.""" - -from __future__ import annotations - -import re -from pathlib import Path -from typing import Optional, Type - -from .adapters.base import Adapter -from .adapters.pl_boryszew import BoryszewAdapter -from .adapters.pl_energa import EnergaAdapter -from .adapters.pl_pse import PSEAdapter -from .adapters.pl_stoen import StoenAdapter -from .adapters.pl_tauron import TauronAdapter -from .adapters.es_edistribucion import EDistribucionAdapter -from .adapters.ie_esbnetworks import ESBNetworksAdapter -from .adapters.pt_eredes import EredesAdapter -from .adapters.uk_nationalgrid import NationalGridAdapter - -__all__ = ["REGISTRY", "get_adapter", "detect_publisher", "declarations"] - -REGISTRY: dict[str, Type[Adapter]] = { - "pl_tauron": TauronAdapter, - "pl_energa": EnergaAdapter, - "pl_pse": PSEAdapter, - "pl_stoen": StoenAdapter, - "pl_boryszew": BoryszewAdapter, - "es_edistribucion": EDistribucionAdapter, - "ie_esbnetworks": ESBNetworksAdapter, - "pt_eredes": EredesAdapter, - "uk_nationalgrid": NationalGridAdapter, -} - - -def get_adapter(key: str, **kwargs) -> Adapter: - if key not in REGISTRY: - raise KeyError(f"nieznany adapter {key!r}; dostępne: {sorted(REGISTRY)}") - return REGISTRY[key](**kwargs) - - -def detect_publisher(source, *, sniff_bytes: int = 4000) -> Optional[str]: - """Rozpoznaj publikującego po nazwie pliku, a jeśli trzeba -- po treści. - - Kolejność jest celowa: nazwa pliku jest tania i zwykle wystarcza, treść - pierwszej strony rozstrzyga resztę. Zwraca klucz rejestru albo None. - """ - name = str(source).lower() - for key, cls in REGISTRY.items(): - for pat in cls.detect_patterns: - if re.search(pat, name): - return key - p = Path(str(source)) - if p.suffix.lower() == ".pdf" and p.exists(): - try: - import pdfplumber - - with pdfplumber.open(p) as pdf: - text = (pdf.pages[0].extract_text() or "")[:sniff_bytes].lower() - except Exception: - return None - for key, cls in REGISTRY.items(): - for pat in cls.detect_patterns: - if re.search(pat, text): - return key - return None - - -def declarations() -> list[dict]: - """Deklaracje pól opcjonalnych wszystkich zarejestrowanych publikujących.""" - return [cls().declaration() for cls in REGISTRY.values()] diff --git a/build/lib/gridqueue/schema.py b/build/lib/gridqueue/schema.py deleted file mode 100644 index 4b6ea42..0000000 --- a/build/lib/gridqueue/schema.py +++ /dev/null @@ -1,514 +0,0 @@ -"""Wspólny schemat ujawnień przyłączeniowych (statutory connection-queue disclosure). - -Schemat jest wyprowadzony ze STRUKTURY OBOWIĄZKU PRAWNEGO, nie z układu konkretnego -dokumentu. Art. 7 ust. 8l ustawy z dnia 10 kwietnia 1997 r. -- Prawo energetyczne -nakłada na operatora systemu dystrybucyjnego cztery rozłączne obowiązki ujawnieniowe: - - pkt 1 -- podmioty ubiegające się o przyłączenie źródeł (kto, gdzie, jaka moc, - jaki zasób, na jakim etapie) -> encja WNIOSEK - pkt 2 -- łączna dostępna moc przyłączeniowa i jej planowane zmiany w okresie - kolejnych 5 lat, w podziale na stacje lub ich grupy - -> encja WĘZEŁ - pkt 3 -- złożone wnioski o określenie warunków przyłączenia -> encja WNIOSEK - pkt 4 -- wydane odmowy określenia warunków przyłączenia -> encja WNIOSEK - -Z tego wynikają trzy osie, które schemat odwzorowuje jako grupy pól: - - TOŻSAMOŚĆ -- co jest przyłączane i gdzie (id_wniosku, id_wezla, nazwa_wezla, - lokalizacja_tekst, wspolrzedne, poziom_napiecia, klasa_zasobu) - MOC -- ile mocy w którą stronę i ile jej jeszcze jest - (moc_wprowadzana, moc_pobierana, moc_dostepna, moc_zarezerwowana, - ograniczenie_flaga, pozycja_w_kolejce) - PROCES -- gdzie w postępowaniu administracyjnym stoi sprawa - (status_procesu, data_wniosku, data_warunkow, data_odmowy, - powod_odmowy, data_umowy, data_energizacji, data_publikacji) - -Oś PROCES jest bezpośrednim odwzorowaniem ścieżki proceduralnej ustawy: wniosek -> -(zaliczka) -> warunki przyłączenia albo odmowa -> umowa o przyłączenie -> -rozpoczęcie dostarczania energii. Warunki przyłączenia są ważne dwa lata -(art. 7 ust. 8i), co czyni parę (data_warunkow, data_umowy) sprawdzalną regułą, -a nie tylko dwiema kolumnami. - -RDZEŃ OBOWIĄZKOWY (5 pól) to minimum, bez którego ujawnienie nie realizuje -żadnego z pkt 1/3/4: nie da się powiedzieć, czyj to wniosek, gdzie, na co, -o jaką moc i na jakim etapie. - -Jednostki kanoniczne: moc w kW (nie MW -- publikujący używają obu), daty w ISO -8601 (YYYY-MM-DD), współrzędne w WGS84 jako (lat, lon). -""" - -from __future__ import annotations - -import datetime as _dt -import math -import re -from dataclasses import dataclass, field -from typing import Any, Callable, Optional - -__all__ = [ - "Field", - "SCHEMA", - "FIELDS", - "CORE_FIELDS", - "OPTIONAL_FIELDS", - "GROUPS", - "canonical_power_kw", - "canonical_date", - "validate_instance", - "validate_frame", - "empty_frame", -] - -# -------------------------------------------------------------------------- -# normalizacja jednostek kanonicznych -# -------------------------------------------------------------------------- - -_NUM_RE = re.compile(r"^-?\d+(?:[.,]\d+)?$") - - -def canonical_power_kw(value: Any, unit: str = "kW") -> Optional[float]: - """Sprowadź moc do kW. Zwraca None dla pustych/nieparsowalnych wartości. - - Akceptuje polski separator dziesiętny (przecinek) i spacje tysięczne - (także NBSP i wąską spację, których używają generatory PDF). - """ - if value is None: - return None - if isinstance(value, (int, float)): - if isinstance(value, float) and math.isnan(value): - return None - num = float(value) - else: - s = str(value).strip() - s = s.replace("\u00a0", "").replace("\u202f", "").replace(" ", "") - if s in {"", "-", "--", "---", "brak", "nie dotyczy", "n/d", "N/D"}: - return None - s = s.replace(",", ".") - # dopuść wielokrotne kropki tysięczne typu 1.234.5 -> odrzuć - if not _NUM_RE.match(s.replace(".", "", max(0, s.count(".") - 1))): - try: - num = float(s) - except ValueError: - return None - else: - try: - num = float(s) - except ValueError: - return None - u = unit.strip().lower() - if u in {"kw", "kilowat", "kilowatt"}: - return num - if u in {"mw", "megawat", "megawatt"}: - return num * 1000.0 - if u in {"w", "wat", "watt"}: - return num / 1000.0 - raise ValueError(f"nieznana jednostka mocy: {unit!r}") - - -# Publikujacy nie trzymaja sie wlasnego wzorca [dd.mm.rrrr]: w zestawieniu wnioskow -# Stoena wystepuja daty z jednocyfrowym dniem ("2.04.2026"), wiec wzorzec musi je -# przyjmowac -- inaczej poprawnie wydobyta data przepada na normalizacji. -_DATE_PATTERNS = ( - ("%d.%m.%Y", re.compile(r"^\d{1,2}\.\d{1,2}\.\d{4}$")), - ("%Y-%m-%d", re.compile(r"^\d{4}-\d{1,2}-\d{1,2}$")), - ("%d/%m/%Y", re.compile(r"^\d{1,2}/\d{1,2}/\d{4}$")), - ("%d-%m-%Y", re.compile(r"^\d{1,2}-\d{1,2}-\d{4}$")), -) - -_NULLISH = { - "", "-", "--", "---", "----", "-----", "brak", "nie dotyczy", "nie wymagano", - "n/d", "none", "nan", "--------", "---------", "----------", - "-----------", "------------", "-------------", "--------------", - "---------------", -} - - -def canonical_date(value: Any) -> Optional[str]: - """Sprowadź datę do ISO 8601 (YYYY-MM-DD). None dla pustych/nieparsowalnych.""" - if value is None: - return None - if isinstance(value, _dt.datetime): - return value.date().isoformat() - if isinstance(value, _dt.date): - return value.isoformat() - s = str(value).strip() - if s.lower() in _NULLISH or set(s) == {"-"}: - return None - s = s.replace("r.", "").strip() - for fmt, rx in _DATE_PATTERNS: - if rx.match(s): - try: - return _dt.datetime.strptime(s, fmt).date().isoformat() - except ValueError: - return None - return None - - -def _is_null(v: Any) -> bool: - if v is None: - return True - if isinstance(v, float) and math.isnan(v): - return True - if isinstance(v, str) and v.strip().lower() in _NULLISH: - return True - return False - - -# -------------------------------------------------------------------------- -# specyfikacja pól -# -------------------------------------------------------------------------- - - -@dataclass(frozen=True) -class Field: - name: str - dtype: str # "string" | "number" | "date" | "boolean" | "geopoint" - group: str # "tozsamosc" | "moc" | "proces" - core: bool - unit: Optional[str] - podstawa: str # który punkt art. 7 ust. 8l uzasadnia pole - opis: str - check: Optional[Callable[[Any], bool]] = field(default=None, repr=False) - - -def _num_nonneg(v: Any) -> bool: - try: - return float(v) >= 0.0 - except (TypeError, ValueError): - return False - - -def _is_iso_date(v: Any) -> bool: - return bool(re.match(r"^\d{4}-\d{2}-\d{2}$", str(v))) and canonical_date(v) is not None - - -def _is_geopoint(v: Any) -> bool: - if isinstance(v, (tuple, list)) and len(v) == 2: - lat, lon = v - elif isinstance(v, str) and "," in v: - try: - lat, lon = (float(x) for x in v.split(",", 1)) - except ValueError: - return False - else: - return False - try: - return -90.0 <= float(lat) <= 90.0 and -180.0 <= float(lon) <= 180.0 - except (TypeError, ValueError): - return False - - -def _is_bool(v: Any) -> bool: - return isinstance(v, bool) or str(v).strip().lower() in { - "true", "false", "tak", "nie", "0", "1" - } - - -SCHEMA: tuple[Field, ...] = ( - # ---------------- TOŻSAMOŚĆ ---------------- - Field("id_wniosku", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Identyfikator pozycji w rejestrze publikującego; unikalny w obrębie " - "publikacji, nie globalnie."), - Field("id_wezla", "string", "tozsamosc", False, None, "pkt 2", - "Identyfikator stacji elektroenergetycznej lub jej grupy, w podziale na " - "które ustawa każe podawać dostępną moc."), - Field("nazwa_wezla", "string", "tozsamosc", False, None, "pkt 2", - "Nazwa własna stacji/punktu zasilania, jeśli publikujący ją ujawnia."), - Field("lokalizacja_tekst", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Lokalizacja miejsca przyłączenia tak, jak ją podał publikujący " - "(adres, miejscowość, kod stacji) -- bez interpretacji."), - Field("wspolrzedne", "geopoint", "tozsamosc", False, "WGS84", "pkt 1/2", - "Współrzędne geograficzne (lat, lon); wynik rozwiązania lokalizacji albo " - "dana źródłowa.", _is_geopoint), - Field("poziom_napiecia", "string", "tozsamosc", False, None, "pkt 1 (>1 kV)", - "Poziom napięcia przyłączenia; obowiązek dotyczy sieci powyżej 1 kV, więc " - "pole rozstrzyga o zakresie ujawnienia."), - Field("klasa_zasobu", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Rodzaj instalacji, urządzeń lub sieci, zharmonizowany do słownika " - "kontrolowanego (PV, FW, BESS, ODB, ...)."), - # ---------------- MOC ---------------- - Field("moc_wprowadzana", "number", "moc", False, "kW", "pkt 1/3", - "Moc przyłączeniowa wprowadzana do sieci (generacja/eksport).", _num_nonneg), - Field("moc_pobierana", "number", "moc", False, "kW", "pkt 1/3/4", - "Moc przyłączeniowa pobierana z sieci (odbiór/import); dla wniosków " - "odbiorczych jest to główna wielkość wniosku. Nie jest polem rdzenia " - "bezwarunkowo: rdzeń wymaga CO NAJMNIEJ JEDNEGO z pary " - "(moc_pobierana, moc_wprowadzana) -- patrz CORE_ALTERNATIVES.", _num_nonneg), - Field("moc_dostepna", "number", "moc", False, "kW", "pkt 2", - "Łączna dostępna moc przyłączeniowa w węźle.", _num_nonneg), - Field("moc_zarezerwowana", "number", "moc", False, "kW", "pkt 2", - "Moc zajęta wydanymi i ważnymi warunkami / rezerwą.", _num_nonneg), - Field("ograniczenie_flaga", "boolean", "moc", False, None, "pkt 2", - "Czy w węźle występuje czynnik ograniczający przyłączenie.", _is_bool), - Field("pozycja_w_kolejce", "number", "moc", False, None, "pkt 1", - "Pozycja wniosku w kolejce przyłączeniowej, jeśli publikujący ją prowadzi."), - # ---------------- PROCES ---------------- - Field("status_procesu", "string", "proces", True, None, "pkt 1/3/4", - "Etap postępowania, zharmonizowany do słownika kontrolowanego."), - Field("data_wniosku", "date", "proces", False, "ISO-8601", "pkt 3", - "Data złożenia wniosku o określenie warunków przyłączenia.", _is_iso_date), - Field("data_warunkow", "date", "proces", False, "ISO-8601", "pkt 1/3", - "Data określenia warunków przyłączenia; początek dwuletniego terminu " - "ważności (art. 7 ust. 8i).", _is_iso_date), - Field("data_odmowy", "date", "proces", False, "ISO-8601", "pkt 4", - "Data wydania odmowy określenia warunków przyłączenia.", _is_iso_date), - Field("powod_odmowy", "string", "proces", False, None, "pkt 4", - "Uzasadnienie odmowy (przyczyny techniczne / ekonomiczne / inne)."), - Field("data_umowy", "date", "proces", False, "ISO-8601", "pkt 1", - "Data zawarcia umowy o przyłączenie.", _is_iso_date), - Field("data_energizacji", "date", "proces", False, "ISO-8601", "pkt 1", - "Data rozpoczęcia dostarczania energii elektrycznej.", _is_iso_date), - Field("data_publikacji", "date", "proces", False, "ISO-8601", "art. 7 ust. 8m", - "Stan na dzień, dla którego publikujący sporządził ujawnienie; " - "ustawa wymaga aktualizacji co najmniej raz na kwartał.", _is_iso_date), -) - -SCHEMA_VERSION: str = "1.0" - -FIELDS: tuple[str, ...] = tuple(f.name for f in SCHEMA) -CORE_FIELDS: tuple[str, ...] = tuple(f.name for f in SCHEMA if f.core) -OPTIONAL_FIELDS: tuple[str, ...] = tuple(f.name for f in SCHEMA if not f.core) - -# Rdzeń warunkowy, osobny dla każdej encji obowiązku. -# -# Schemat ma dwie encje, bo przepis ma dwa punkty o różnym przedmiocie, i rdzeń -# jednej z nich nie jest wymaganiem wobec drugiej. Ocenianie wiersza encji -# WEZEL wymaganiami encji WNIOSEK mierzyłoby niezgodność encji, nie braki -# ujawnienia. -# -# W obu encjach część wymagań jest ALTERNATYWĄ, nie konkretnym polem. Wniosek -# przyłączeniowy zawsze deklaruje moc, lecz nie zawsze tę samą: wytwórczy -# wprowadzaną, odbiorczy pobieraną, dwukierunkowy (np. magazyn) obie. Analogicznie -# pkt 2 bywa realizowany mocą dostępną albo liczbą wolnych miejsc przyłączeniowych -# (wtedy flagą ograniczenia) -- obie postaci spotkaliśmy u różnych publikujących. -ENTITY_COLUMN: str = "_encja" -DEFAULT_ENTITY: str = "WNIOSEK" - -CORE_BY_ENTITY: dict[str, dict[str, tuple]] = { - "WNIOSEK": { - "wymagane": CORE_FIELDS, - "alternatywy": (("moc_pobierana", "moc_wprowadzana"),), - }, - "WEZEL": { - "wymagane": ("id_wezla",), - "alternatywy": (("moc_dostepna", "ograniczenie_flaga"),), - }, -} - -# zachowane dla zgodności wstecznej z 0.3.x; odnosi się do encji WNIOSEK -CORE_ALTERNATIVES: tuple[tuple[str, ...], ...] = tuple( - CORE_BY_ENTITY["WNIOSEK"]["alternatywy"]) - - -def _mask_dla_encji(df, sub_idx, spec): - import pandas as _pd - - m = _pd.Series(True, index=sub_idx) - for c in spec["wymagane"]: - if c not in df.columns: - return _pd.Series(False, index=sub_idx) - m &= df.loc[sub_idx, c].map(lambda v: not _is_null(v)) - for grupa in spec["alternatywy"]: - obecne = [c for c in grupa if c in df.columns] - if not obecne: - return _pd.Series(False, index=sub_idx) - alt = _pd.Series(False, index=sub_idx) - for c in obecne: - alt |= df.loc[sub_idx, c].map(lambda v: not _is_null(v)) - m &= alt - return m - - -def core_complete_mask(df): - """Maska wierszy z kompletnym rdzeniem WŁAŚCIWEJ DLA SIEBIE ENCJI. - - Encja czytana jest z kolumny anotacyjnej ``_encja``; wiersze bez tej anotacji - traktowane są jako ``WNIOSEK`` (tak wiersze emitują adaptery, które encji nie - rozróżniają, bo ich publikujący realizuje wyłącznie pkt 1/3/4). Brak kolumny - wymaganej traktowany jest jak kolumna pusta -- rdzeń jest wymaganiem wobec - WIERSZA, nie wobec kształtu ramki. - """ - import pandas as _pd - - if ENTITY_COLUMN in df.columns: - enc = df[ENTITY_COLUMN].map( - lambda v: DEFAULT_ENTITY if _is_null(v) else str(v).upper()) - else: - enc = _pd.Series(DEFAULT_ENTITY, index=df.index) - - mask = _pd.Series(False, index=df.index) - for nazwa, spec in CORE_BY_ENTITY.items(): - sub = enc.index[enc == nazwa] - if len(sub): - mask.loc[sub] = _mask_dla_encji(df, sub, spec).values - return mask -BY_NAME: dict[str, Field] = {f.name: f for f in SCHEMA} -GROUPS: dict[str, tuple[str, ...]] = { - g: tuple(f.name for f in SCHEMA if f.group == g) - for g in ("tozsamosc", "moc", "proces") -} - -# kolumny towarzyszące, nie należące do schematu (metadane panelu / anotacje) -META_COLUMNS: tuple[str, ...] = ("publikujacy", "jurysdykcja", "dokument_zrodlowy") -ANNOTATION_PREFIX = "_" - -# słowniki kontrolowane -KLASY_ZASOBU = ( - "PV", "FW", "EW", "BIOGAZ", "GAZ", "WEGIEL", "BESS", "ODB", "MIX", "SIEC", - "INNE", "NIEOKRESLONA", -) -STATUSY = ( - "WNIOSEK_ZLOZONY", "WNIOSEK_NIEKOMPLETNY", "W_TRAKCIE_ANALIZY", - "WARUNKI_WYDANE", "WARUNKI_WYGASLE", "ODMOWA", "UMOWA_OBOWIAZUJACA", - "UMOWA_ROZWIAZANA", "PRZYLACZONY", "WNIOSEK_WYCOFANY", "NIEOKRESLONY", -) - - -# -------------------------------------------------------------------------- -# walidator instancji -# -------------------------------------------------------------------------- - - -def validate_instance(row: dict[str, Any], *, strict_vocab: bool = False) -> list[str]: - """Zwróć listę komunikatów o naruszeniach dla pojedynczego wiersza. - - Pusta lista = wiersz zgodny ze schematem. Walidator NIE rzuca wyjątku -- - ujawnienia bywają niekompletne z winy publikującego i to jest wynik pomiaru, - a nie błąd wykonania. - """ - problems: list[str] = [] - unknown = set(row) - set(FIELDS) - set(META_COLUMNS) - unknown = {k for k in unknown if not k.startswith(ANNOTATION_PREFIX)} - if unknown: - problems.append(f"pola spoza schematu: {sorted(unknown)}") - for name in CORE_FIELDS: - if name not in row or _is_null(row.get(name)): - problems.append(f"brak pola rdzenia: {name}") - for name, value in row.items(): - f = BY_NAME.get(name) - if f is None or _is_null(value): - continue - if f.dtype == "number": - if not isinstance(value, (int, float)) or isinstance(value, bool): - problems.append(f"{name}: oczekiwano liczby, jest {type(value).__name__}") - continue - if f.check is not None and not f.check(value): - problems.append(f"{name}: wartość nie przechodzi kontroli typu ({value!r})") - if strict_vocab: - kz = row.get("klasa_zasobu") - if not _is_null(kz) and kz not in KLASY_ZASOBU: - problems.append(f"klasa_zasobu spoza słownika: {kz!r}") - st = row.get("status_procesu") - if not _is_null(st) and st not in STATUSY: - problems.append(f"status_procesu spoza słownika: {st!r}") - return problems - - -def validate_frame(df, *, strict_vocab: bool = True) -> dict[str, Any]: - """Walidacja całej ramki. Zwraca raport (liczby), nie wyjątek.""" - import pandas as pd # lokalny import: schema.py ma być użyteczny bez pandas - - report: dict[str, Any] = { - "n_wierszy": int(len(df)), - "kolumny_spoza_schematu": sorted( - set(df.columns) - set(FIELDS) - set(META_COLUMNS) - - {c for c in df.columns if c.startswith(ANNOTATION_PREFIX)} - ), - "brakujace_kolumny_rdzenia": [c for c in CORE_FIELDS if c not in df.columns], - "wypelnienie": {}, - "naruszenia_typu": {}, - "wiersze_z_kompletnym_rdzeniem": 0, - "slownik": {}, - } - for c in FIELDS: - if c in df.columns: - s = df[c] - nn = int(s.notna().sum() - sum( - 1 for v in s.dropna() if isinstance(v, str) and v.strip().lower() in _NULLISH - )) - report["wypelnienie"][c] = round(nn / len(df), 6) if len(df) else 0.0 - else: - report["wypelnienie"][c] = 0.0 - for c in FIELDS: - if c not in df.columns: - continue - f = BY_NAME[c] - bad = 0 - for v in df[c]: - if _is_null(v): - continue - if f.dtype == "number" and (not isinstance(v, (int, float)) or isinstance(v, bool)): - bad += 1 - elif f.check is not None and not f.check(v): - bad += 1 - if bad: - report["naruszenia_typu"][c] = bad - report["wiersze_z_kompletnym_rdzeniem"] = int(core_complete_mask(df).sum()) - report["schema_version"] = SCHEMA_VERSION - if strict_vocab: - for c, vocab in (("klasa_zasobu", KLASY_ZASOBU), ("status_procesu", STATUSY)): - if c in df.columns: - bad = sorted({v for v in df[c].dropna().unique() if v not in vocab and not _is_null(v)}) - report["slownik"][c] = bad - return report - - -def empty_frame(): - """Pusta ramka w schemacie (wszystkie 21 pól + kolumny metadanych).""" - import pandas as pd - - return pd.DataFrame({c: pd.Series(dtype="object") for c in FIELDS + META_COLUMNS}) - - -def _encja_pola(nazwa: str) -> str: - """Encja, w której pole występuje: WNIOSEK, WEZEL albo obie. - - Wyprowadzone z CORE_BY_ENTITY oraz z przynależności pola do punktu obowiązku: - punkt 2 opisuje węzeł, punkty 1, 3 i 4 opisują wniosek. - """ - wezlowe = {"id_wezla", "nazwa_wezla", "moc_dostepna", "moc_zarezerwowana", - "ograniczenie_flaga"} - obie = {"wspolrzedne", "data_publikacji"} - if nazwa in obie: - return "obie" - return "WEZEL" if nazwa in wezlowe else "WNIOSEK" - - -def _status_rdzenia(nazwa: str) -> str: - """Trójwartościowy status: rdzeń bezwarunkowy, alternatywa rdzenia, rozszerzenie. - - Rdzeń jest WARUNKOWY: pole bezwarunkowe dla jednej encji nie musi być - wymagane dla drugiej, a pary alternatyw wymagają wypełnienia co najmniej - jednego członu. Dwuwartościowa kolumna `rdzen` tego nie oddaje i dlatego - istnieje ta druga. - """ - for encja, spec in CORE_BY_ENTITY.items(): - if nazwa in spec["wymagane"]: - return f"rdzeń bezwarunkowy ({encja})" - for encja, spec in CORE_BY_ENTITY.items(): - for para in spec["alternatywy"]: - if nazwa in para: - return f"alternatywa rdzenia ({encja}: {' albo '.join(para)})" - return "rozszerzenie" - - -def schema_table(): - """Specyfikacja jako ramka -- artefakt do manuskryptu.""" - import pandas as pd - - return pd.DataFrame( - [ - { - "pole": f.name, - "typ": f.dtype, - "grupa": f.group, - "encja": _encja_pola(f.name), - "rdzen": f.core, - "status_rdzenia": _status_rdzenia(f.name), - "jednostka_kanoniczna": f.unit or "", - "podstawa_prawna": f.podstawa, - "opis": f.opis, - } - for f in SCHEMA - ] - ) diff --git a/docs/_config.yml b/docs/_config.yml index 23bf6c5..07935ef 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,5 +1,5 @@ title: gridqueue -description: Harmonizator ustawowych ujawnień przyłączeniowych do sieci elektroenergetycznej +description: Harmonizer of statutory grid-connection disclosures for the electricity network theme: jekyll-theme-primer -lang: pl +lang: en exclude: [Gemfile, Gemfile.lock] diff --git a/docs/adaptery.md b/docs/adaptery.md index 3007e6e..2ae6eb7 100644 --- a/docs/adaptery.md +++ b/docs/adaptery.md @@ -1,14 +1,14 @@ --- -title: Adaptery +title: Adapters --- -# Adaptery +# Adapters -Każdy adapter realizuje ten sam interfejs i **deklaruje**, które pola schematu wypełnia oraz jakie -rozszerzenia wnosi. Deklaracja jest częścią wyniku, nie dokumentacji, dzięki temu pokrycie pól -nie jest twierdzeniem, a wartością odczytywalną z kodu. +Every adapter implements the same interface and **declares** which schema fields it populates and +which extensions it contributes. The declaration is part of the result rather than of the +documentation; thanks to that, field coverage is not an assertion but a value readable from the code. -| klucz | publikujący | jurysdykcja | pól schematu | rozszerzeń | +| key | publisher | jurisdiction | schema fields | extensions | |---|---|---|---:|---:| | `pl_tauron` | TAURON Dystrybucja S.A. | PL | 15 | 9 | | `pl_energa` | ENERGA-OPERATOR S.A. | PL | 17 | 25 | @@ -17,11 +17,12 @@ nie jest twierdzeniem, a wartością odczytywalną z kodu. | `pl_boryszew` | Boryszew Green Energy&Gas Sp. z o.o. | PL | 10 | 6 | | `uk_nationalgrid` | National Grid Electricity Distribution | UK | 10 | 9 | -Adaptery `pl_pse` i `pl_energa` dzielą moduł `adapters/_ptpiree.py`, bo oba publikujące wypełniają -ten sam uzgodniony wzorzec sprawozdawczy, jeden wydaje go jako arkusz, drugi jako dokument do -druku. To nie jest zbieg okoliczności implementacyjny, lecz odwzorowanie praktyki sektora. +The `pl_pse` and `pl_energa` adapters share the module `adapters/_ptpiree.py`, because both +publishers fill in the same agreed reporting template, one issuing it as a spreadsheet, the other as a +document meant for printing. This is not an implementation coincidence but a reflection of sector +practice. -## Dodanie publikującego +## Adding a publisher ```python from gridqueue.adapters.base import Adapter, ParseResult @@ -30,72 +31,72 @@ class MojAdapter(Adapter): klucz = "pl_moj_operator" publikujacy = "Nazwa Operatora S.A." jurysdykcja = "PL" - detekcja = [r"moj_operator", r"nazwa_operatora"] # wzorce nazwy pliku + detekcja = [r"moj_operator", r"nazwa_operatora"] # file name patterns def parse(self, source) -> ParseResult: - ... # zwróć ramkę w schemacie + raport + ... # return a frame in the schema + a report ``` -Rejestracja: dopisanie klasy do `REGISTRY` w `gridqueue/registry.py`. Rdzeń pozostaje nietknięty. +Registration: adding the class to `REGISTRY` in `gridqueue/registry.py`. The core stays untouched. ```bash -gridqueue adapters # deklaracje wszystkich publikujących +gridqueue adapters # declarations of all publishers ``` -## Wykrywanie publikującego +## Detecting the publisher ```python from gridqueue import detect_publisher detect_publisher("tauron_informacja_2026_06_30.pdf") # 'pl_tauron' ``` -Kolejność jest celowa: nazwa pliku jest tania i zwykle wystarcza, treść pierwszej strony -rozstrzyga resztę. Gdy nie rozstrzyga żadna z nich, zwracane jest `None`, bez zgadywania. +The order is deliberate: the file name is cheap and usually sufficient, the content of the first page +settles the rest. When neither settles it, `None` is returned, with no guessing. -## E-REDES (Portugalia), `pt_eredes` +## E-REDES (Portugal), `pt_eredes` -Trzecia jurysdykcja w panelu i trzeci tryb wydania: **zbiór na portalu otwartych -danych z interfejsem REST**, publikowany kwartalnie. Jednostką wiersza jest -podstacja albo punkt cięcia sieci wysokiego napięcia; wierszy jest 469 i wszystkie -należą do encji WĘZEŁ. +The third jurisdiction in the panel and the third mode of issue: **a dataset on an open +data portal with a REST interface**, published quarterly. The unit of a row is a +substation or a cut point of the high voltage network; there are 469 rows and all of them +belong to the WĘZEŁ entity. -Co ten adapter wnosi, czego nie było: **pierwsze zagraniczne źródło encji WĘZEŁ**. -Dotąd wiersze węzłowe pochodziły wyłącznie od dwóch publikujących polskich, więc -kryterium „dostępna moc przyłączeniowa" dawało się policzyć w jednej jurysdykcji. -Źródło portugalskie podaje ponadto **skład grupy podstacji**, dokładnie tę -informację, która w panelu polskim umożliwia przypisanie wniosków do węzła. +What this adapter contributes that was not there before: **the first foreign source of the WĘZEŁ +entity**. Until now the node rows came only from two Polish publishers, so the +criterion "available connection capacity" could be computed in one jurisdiction. +The Portuguese source additionally reports the **composition of the substation group**, exactly the +information which, in the Polish panel, makes it possible to assign applications to a node. -### Rozstrzygnięcie o jednostkach +### The settlement on units -Publikujący podaje zdolność przyjęcia i moce przyłączone w **MVA**, czyli w mocy -pozornej. Jednostką kanoniczną schematu jest **kW mocy czynnej**. Są to różne -wielkości fizyczne, a przeliczenie jednej na drugą wymaga współczynnika mocy, -którego publikujący nie podaje. +The publisher reports the reception capability and the connected capacities in **MVA**, that is in +apparent power. The canonical unit of the schema is **kW of active power**. These are different +physical quantities, and converting one into the other requires a power factor, +which the publisher does not report. -Dlatego `moc_dostepna` pozostaje **puste**, a wartości w MVA trafiają do pól -rozszerzenia wraz z jawnie zapisaną jednostką źródłową: +That is why `moc_dostepna` remains **empty**, and the values in MVA go into the +extension fields together with the source unit recorded explicitly: -| pole rozszerzenia | znaczenie | +| extension field | meaning | |---|---| | `_jednostka_mocy_zrodlowa` | `MVA` | -| `_moc_dostepna_mva` | zdolność przyjęcia SN+WN | -| `_moc_przylaczona_mva` | moc już przyłączona | -| `_moc_zakontraktowana_mva` | moc zakontraktowana | -| `_moc_w_potwierdzaniu_mva` | moc w trakcie potwierdzania | +| `_moc_dostepna_mva` | MV+HV reception capability | +| `_moc_przylaczona_mva` | capacity already connected | +| `_moc_zakontraktowana_mva` | contracted capacity | +| `_moc_w_potwierdzaniu_mva` | capacity under confirmation | -Jest to ta sama zasada, którą zastosowano wobec publikującego podającego liczbę -wolnych miejsc przyłączeniowych zamiast mocy: wpisanie liczby w pole o innej -jednostce byłoby fabrykacją, nie harmonizacją. +This is the same principle that was applied to the publisher reporting a count of +free connection slots instead of a capacity: entering a count of slots into a field with a different +unit would be fabrication, not harmonization. -Rdzeń encji WĘZEŁ jest mimo to spełniony, bo realizuje go drugi człon alternatywy - -`ograniczenie_flaga`, ustawiana na podstawie zerowej zdolności przyjęcia. Zero jest -wartością **ujawnioną** i oznacza ograniczenie; pusta komórka oznacza nieujawnienie -i flagi nie ustawia. Dotyczy to 222 z 469 węzłów. +The core of the WĘZEŁ entity is nevertheless satisfied, because it is discharged by the second member of +the alternative, `ograniczenie_flaga`, set on the basis of a zero reception capability. Zero is +a **disclosed** value and means a constraint; an empty cell means non-disclosure +and does not set the flag. This concerns 222 of 469 nodes. -To rozstrzygnięcie jest zarazem wynikiem obserwacyjnym: **obie jurysdykcje spełniają -rdzeń encji WĘZEŁ różnymi członami tej samej alternatywy**, Polska mocą dostępną, -Portugalia flagą ograniczenia. Warunkowy rdzeń, wprowadzony w wersji 1.0 dla -polskiego błędu kategorialnego, okazał się warunkiem wchłonięcia obcej jurysdykcji. +That settlement is at the same time an observational finding: **both jurisdictions satisfy +the core of the WĘZEŁ entity through different members of the same alternative**, Poland with available +capacity, Portugal with the constraint flag. The conditional core, introduced in version 1.0 for +a Polish category error, turned out to be the condition for absorbing a foreign jurisdiction. ```python from gridqueue import get_adapter @@ -104,65 +105,66 @@ r.frame[["id_wezla", "nazwa_wezla", "lokalizacja_tekst", "ograniczenie_flaga"]] r.report["uwaga_jednostki"] ``` -## e-Distribución (Hiszpania), `es_edistribucion` - -**Pierwsze zagraniczne źródło wydawane jako dokument do druku.** Dotąd oba adaptery -zagraniczne czytały dane już tabelaryczne, więc przenoszalność była wykazana na przypadku -łatwiejszym niż polski; to źródło ten brak zamyka. Publikujący wydaje **PDF miesięczny** -w serii obejmującej lata 2023-2025, na podstawie art. 33 ust. 9 ustawy 24/2013, -art. 5 ust. 4 dekretu 1183/2020 i art. 12 okólnika 1/2021 regulatora CNMC, czyli -w konstrukcji prawnej takiej samej jak polska: obowiązek ustawowy, stała częstość, format -pozostawiony publikującemu. - -Wydanie z 1 sierpnia 2025: 28 stron, **1 838 wierszy encji WĘZEŁ**, wszystkie pola -zadeklarowane wypełnione w 100 %, w tym **współrzędne geograficzne każdej podstacji** - -czego nie robi żaden publikujący polski. Moce są w **MW mocy czynnej**, więc przeliczenie -na kanoniczne kW jest zwykłą zmianą rzędu wielkości. - -### Semantyka kolumn ustalona arytmetyką, nie nagłówkiem - -Nagłówek ma komórki scalone w dwóch poziomach i sugeruje, że kolumny „Con permiso de AyC" -oraz „En trámite con capacidad" należą do grupy mocy **przyjętej i nierozstrzygniętej**. -Rozstrzyga arytmetyka dokumentu. Jedenaście podkolumn, dziewięć pozycji stacji plus te dwie - -sumuje się do mocy **zajętej**, dokładnie w **1 838 z 1 838 wierszy, w obu sprawdzonych -wydaniach**; rozbicie technologiczne sumuje się do mocy przyjętej i nierozstrzygniętej we -wszystkich wierszach o niezerowej wartości. Obie grupy są więc **składnikami**, a nie -alternatywnymi rozbiciami. Przyjęcie nagłówka na wiarę dałoby ciche przestawienie dwóch pól mocy. - -### Domknięcie sumy zamiast zbioru odniesienia - -Dla tego publikującego **nie ma wzorca odczytanego niezależnie od parsera**, więc dokładności -wydobycia nie da się zmierzyć tak, jak zmierzono ją dla publikujących polskich. Domknięcie sumy -jest zastępczym świadectwem: aby suma jedenastu komórek zgadzała się z dwunastą, wszystkie -dwanaście musi być odczytane poprawnie. Na dwóch wydaniach daje to **3 676 niezależnych -sprawdzeń, wszystkie domknięte**. Jest to świadectwo **spójności odczytu, nie pomiar dokładności** -- słabsze niż wzorzec, ale sprawdzalne na każdym nowym wydaniu, bez pracy anotatora. -Raport adaptera podaje je w polu `tozsamosc_sumy_mocy_zajetej`. - -## ESB Networks (Irlandia), `ie_esbnetworks` - -Najliczniejsze źródło w panelu: **46 527 wierszy**, jedyne schodzące poniżej poziomu stacji -wysokiego napięcia aż do stacji SN/nn. Jednostką wiersza jest grupa transformatorów w stacji. -Współrzędne są w 46 525 wierszach. - -### Dwie jednostki w jednym pliku - -Publikujący podaje stronę **odbiorczą w MVA** (moc pozorna), a **wytwórczą w MW** (moc czynna). -Pole `moc_dostepna` niesie zatem dostępną moc **wytwórczą trwałą**, przeliczoną z MW na kW, -a strona odbiorcza zostaje w rozszerzeniach z jednostką w nazwie pola. Zsumowanie MW z MVA -dałoby liczbę bez sensu fizycznego, a wybór jednej strony bez powiedzenia tego wprost byłby -ukryciem decyzji. - -### Jedna interpretacja, zapisana jawnie - -Kolumny ograniczenia niosą frazę `Constrained, otherwise capacity available = X kVA` albo są -puste. Przyjmujemy, że **pusta komórka oznacza brak ograniczenia**, a nie brak deklaracji: -kolumna jest wskaźnikiem binarnym, w którym wartość dodatnia niesie objaśnienie, a ujemna jest -wyrażona pustką. Publikujący tej konwencji nigdzie nie opisuje, więc jest to **interpretacja, -nie treść źródła**, surowa fraza zostaje w rozszerzeniu, liczba z niej jest wydobywana -osobno i **nie jest przeliczana**, bo jest w kVA. Decyzja jest odnotowana w raporcie adaptera -i przypięta testem, żeby jej zmiana była widoczna. - -Dwie flagi źródłowe (odbiorcza i wytwórcza) wchodzą do jednego pola schematu jako -**alternatywa zachowująca nieokreśloność**: `None` w połączeniu z `False` daje `None`, -a nie `False`. +## e-Distribución (Spain), `es_edistribucion` + +**The first foreign source issued as a document meant for printing.** Until now both foreign +adapters read data that was already tabular, so transferability had been shown on a case +easier than the Polish one; this source closes that gap. The publisher issues a **monthly PDF** +in a series covering the years 2023-2025, under Article 33(9) of Law 24/2013, +Article 5(4) of Decree 1183/2020 and Article 12 of Circular 1/2021 of the regulator CNMC, that is +in a legal construction identical to the Polish one: a statutory duty, a fixed frequency, the format +left to the publisher. + +The issue of 1 August 2025: 28 pages, **1 838 rows of the WĘZEŁ entity**, all declared fields +populated at 100 %, including **the geographic coordinates of every substation**, +which no Polish publisher does. The capacities are in **MW of active power**, so conversion +to the canonical kW is an ordinary change of order of magnitude. + +### Column semantics established by arithmetic, not by the header + +The header has cells merged at two levels and suggests that the columns "Con permiso de AyC" +and "En trámite con capacidad" belong to the group of **accepted and unsettled** capacity. +The arithmetic of the document settles it. Eleven subcolumns, nine substation items plus those two, +sum to the **occupied** capacity, in exactly **1 838 of 1 838 rows, in both editions +checked**; the technology breakdown sums to the accepted and unsettled capacity in +all rows with a non-zero value. Both groups are therefore **components** rather than +alternative breakdowns. Taking the header on trust would have given a silent transposition of two +capacity fields. + +### Arithmetic closure instead of a reference set + +For this publisher there is **no reference set read independently of the parser**, so the extraction +accuracy cannot be measured the way it was measured for the Polish publishers. Arithmetic closure +is a substitute piece of evidence: for the sum of eleven cells to agree with the twelfth, all +twelve have to be read correctly. Across two editions that gives **3 676 independent +checks, all of them closed**. This is evidence of **consistency of reading, not a measurement of +accuracy**, weaker than a reference set, but checkable on every new edition, without an annotator's +work. The adapter report gives it in the field `tozsamosc_sumy_mocy_zajetej`. + +## ESB Networks (Ireland), `ie_esbnetworks` + +The largest source in the panel: **46 527 rows**, the only one going below the level of high +voltage substations all the way down to MV/LV substations. The unit of a row is a group of +transformers at a substation. Coordinates are present in 46 525 rows. + +### Two units in one file + +The publisher reports the **offtake side in MVA** (apparent power) and the **generating side in MW** +(active power). The `moc_dostepna` field therefore carries the available **firm generating** +capacity, converted from MW to kW, while the offtake side stays in the extensions with the unit in the +field name. Summing MW with MVA would give a figure with no physical sense, and choosing one side +without saying so openly would be hiding a decision. + +### One interpretation, recorded explicitly + +The constraint columns carry the phrase `Constrained, otherwise capacity available = X kVA` or are +empty. We assume that **an empty cell means no constraint** rather than no declaration: +the column is a binary indicator in which the positive value carries an explanation and the negative +one is expressed by emptiness. The publisher nowhere describes this convention, so it is **an +interpretation, not the content of the source**; the raw phrase stays in an extension, the figure in +it is extracted separately and **is not converted**, because it is in kVA. The decision is recorded in +the adapter report and pinned by a test, so that a change to it would be visible. + +The two source flags (offtake and generating) enter one schema field as an +**alternative that preserves indeterminacy**: `None` combined with `False` gives `None`, +not `False`. diff --git a/docs/analiza.md b/docs/analiza.md index e75d936..db3e5c8 100644 --- a/docs/analiza.md +++ b/docs/analiza.md @@ -1,65 +1,65 @@ --- -title: Warstwa analityczna +title: Analytical layer --- -# Warstwa analityczna +# Analytical layer -Adaptery są specyficzne dla publikującego. Wszystko powyżej schematu już nie - -i o to w całym pakiecie chodzi. Ta strona opisuje dwie analizy, które stają się -możliwe dopiero po harmonizacji. +Adapters are specific to the publisher. Everything above the schema is not, +and that is the whole point of the package. This page describes two analyses that +become possible only after harmonization. -## Obciążenie węzła, czyli kryterium „dostępna moc przyłączeniowa" +## Node loading, that is the criterion "available connection capacity" -Przeglądy literatury o lokalizowaniu infrastruktury sieciowej wymieniają -dostępną moc przyłączeniową jako kryterium częste i zarazem niemierzalne - -z powodu braku danych w źródłach otwartych. Jest mierzalne, o ile publikujący -ujawnia jednocześnie moc dostępną w węźle **i** skład stacji wchodzących do -węzła. W panelu robi to jeden publikujący. +Literature reviews on siting network infrastructure list available connection +capacity as a criterion that is frequent and at the same time unmeasurable, +because of the absence of the data in open sources. It is measurable, provided the +publisher discloses both the available capacity at the node **and** the composition +of the substations belonging to the node. In the panel, one publisher does so. ```python from gridqueue import station_node_map, assign_to_nodes, node_loading -mapa = station_node_map(panel) # stacja -> grupa stacji -panel = assign_to_nodes(panel, mapa) # przypisanie wniosków do grup +mapa = station_node_map(panel) # station -> group of stations +panel = assign_to_nodes(panel, mapa) # assignment of applications to groups L = node_loading(panel, pole_mocy="moc_wprowadzana") L[["nazwa_wezla", "wnioskow", "moc_wnioskowana", "moc_dostepna", "obciazenie"]] ``` -**Kluczem jest grupa stacji, nie wiersz węzłowy.** Publikujący wystawia tę samą -grupę dwa razy, osobno dla kierunku wytwórczego i odbiorczego, więc -odwzorowanie po identyfikatorze wiersza czyniłoby każdą stację dwuznaczną. -Byłby to artefakt układu dokumentu, a nie własność sieci. +**The key is the group of stations, not the node row.** The publisher lists the same +group twice, separately for the generating and the consuming direction, so a mapping +based on the row identifier would make every substation ambiguous. +That would be an artefact of the document layout, not a property of the network. -**Przypisanie jest nazwowe, nie topologiczne.** Opiera się na zgodności nazw -ujawnionych przez publikującego, nie na modelu sieci, a jego trafności nie -walidowano wobec wzorca zewnętrznego, bo taki nie istnieje. Status dopasowania -jest zwracany jawnie i rozróżnia pięć przypadków: +**The assignment is by name, not topological.** It rests on the agreement of the names +disclosed by the publisher, not on a model of the network, and its correctness was not +validated against an external reference set, because none exists. The matching status +is returned explicitly and distinguishes five cases: -| status | znaczenie | +| status | meaning | |---|---| -| `EXACT` | nazwa stacji równa lokalizacji po normalizacji | -| `EXTENDED` | lokalizacja zawiera nazwę stacji jako ciągły podciąg tokenów | -| `LINE` | obiekt planowany **na linii** między stacjami, nie w węźle | -| `AMBIGUOUS` | pasuje więcej niż jedna grupa | -| `NONE` | brak trafienia albo brak lokalizacji | - -Kategoria `LINE` istnieje, bo wpisy w rodzaju „planowany RS w linii 110 kV -relacji A, B" opisują obiekt leżący **między** węzłami. Dopasowanie po nazwie -przypisałoby im pełną moc do tego końca linii, który akurat występuje w wykazie -stacji, co jest arbitralne. Takie wnioski zostają nieprzypisane i policzone -osobno. - -Węzeł o zerowej ujawnionej mocy dostępnej dostaje iloraz `NaN`, nie -nieskończoność: iloraz jest tam **nieokreślony**, a uśrednianie go byłoby -błędem. Moc wnioskowana jest przy nim mimo to zachowana, bo kolejka do węzła -bez wolnej mocy jest informacją, nie brakiem danych. - -## Czas rozpatrywania z cenzurowaniem - -Wniosek bez daty rozstrzygnięcia **nie jest brakiem danych**: jest obserwacją -uciętą na dacie publikacji edycji. Liczenie mediany wyłącznie na przypadkach -kompletnych zaniża ją, i to tym silniej, im dłuższy jest rzeczywisty czas -rozpatrywania, czyli najmocniej tam, gdzie zależy nam na wyniku. +| `EXACT` | substation name equal to the location after normalization | +| `EXTENDED` | the location contains the substation name as a contiguous subsequence of tokens | +| `LINE` | an object planned **on a line** between substations, not at a node | +| `AMBIGUOUS` | more than one group matches | +| `NONE` | no hit or no location | + +The `LINE` category exists because entries of the kind "planowany RS w linii 110 kV +relacji A, B" describe an object lying **between** nodes. Matching by name +would assign their full capacity to whichever end of the line happens to appear in the +list of substations, which is arbitrary. Such applications are left unassigned and +counted separately. + +A node with zero disclosed available capacity gets a quotient of `NaN`, not +infinity: the quotient there is **undefined**, and averaging it would be an +error. The applied capacity is nevertheless retained for it, because a queue to a node +with no free capacity is information, not missing data. + +## Processing time with censoring + +An application with no settlement date **is not missing data**: it is an observation +truncated at the publication date of the edition. Computing the median only on complete +cases understates it, and the more strongly the longer the real processing +time is, that is most strongly exactly where the result matters to us. ```python from gridqueue import processing_time, kaplan_meier @@ -69,17 +69,18 @@ km = kaplan_meier(d["czas_dni"], d["zdarzenie"]) km.as_dict()["mediana"], km.as_dict()["udzial_cenzurowanych"] ``` -Estymator Kaplana-Meiera zaimplementowano wprost, z wariancją Greenwooda, żeby -nie wprowadzać zależności od biblioteki analizy przeżycia dla jednego -estymatora. Przedział dla mediany wyznaczany jest przez odwrócenie pasa ufności -krzywej. +The Kaplan-Meier estimator was implemented directly, with Greenwood variance, so as +not to introduce a dependency on a survival analysis library for the sake of one +estimator. The interval for the median is determined by inverting the confidence band +of the curve. -## Czułość dopasowania wzdłużnego +## Recall of the longitudinal linkage -`linkage_audit` mierzy **precyzję**: czy połączone pary dotyczą tej samej -sprawy. `linkage_recall` mierzy **czułość**: ile par klucz pominął. Te drugie -są groźniejsze, bo rozerwana para pojawia się jako jeden wiersz „ubyły" i jeden -„nowy", więc wygląda jak zdarzenie w rejestrze, a jest artefaktem dopasowania. +`linkage_audit` measures **precision**: whether the linked pairs concern the same +case. `linkage_recall` measures **recall**: how many pairs the key missed. The latter +are the more dangerous, because a broken pair appears as one "departed" row and one +"new" one, so it looks like an event in the register when it is an artefact of the +linkage. ```python from gridqueue import linkage_recall @@ -89,8 +90,8 @@ r.as_dict()["czulosc_klucza"] r.odzyskane["pola_klucza_rozne"].value_counts() ``` -Pola tożsamości użyte do odzyskania muszą być **rozłączne z kluczem**. Pole -wspólne z kluczem nie wykryje pary rozerwanej zmianą właśnie tego pola, bo -tożsamość rozjedzie się razem z kluczem. Zmierzone na parze edycji operatora -przesyłowego: dołożenie lokalizacji do zestawu tożsamości podnosi pozorną -czułość z 0,9652 do 0,9757, a w rzeczywistości ukrywa dziesięć par. +The identity fields used for recovery have to be **disjoint from the key**. A field +shared with the key will not detect a pair broken by a change in exactly that field, +because the identity diverges together with the key. Measured on a pair of editions of the +transmission operator: adding the location to the set of identity fields raises the apparent +recall from 0,9652 to 0,9757, and in reality hides ten pairs. diff --git a/docs/app/index.html b/docs/app/index.html index 2192eaf..8ce2d79 100644 --- a/docs/app/index.html +++ b/docs/app/index.html @@ -5,160 +5,278 @@ gridqueue, run it in your browser + +
-

Open research software

-

Statutory grid connection registers,
as a table you can actually use

+
+ Runs locally, nothing is uploaded + Open source, Apache 2.0 + Nine publishers, five jurisdictions +
+

Grid connection registers, as data you can use

Network operators across the European Union must publish the connection capacity - available at each node, at least quarterly. Most of them publish it as documents built for - printing. Drop one below and get harmonised rows back, with no installation and no upload.

+ available at each node, at least quarterly. Most publish it as documents built for printing. + Drop one below and get harmonised rows back, with no installation and no upload.

+ +
+ + + + + + + + + + + + + Published document + PDF, XLSX or CSV + built for printing + + + + + Adapter + one per publisher, + nine of them + + + + + 21 field schema + derived from the duty, + not from any document + + + + + Rows you can analyse + plus eight quality rules + and a validation report + + + EVERY STEP RUNS INSIDE THIS BROWSER TAB + + + +
The schema is the invariant part. Adapters are the part that differs per publisher, + which is why adding a tenth publisher does not change anything downstream of it.
+
+
@@ -174,11 +292,12 @@

Statutory grid connection registers,
as a table you can actually use

command line output by construction.

-
+
Starting Preparing the interpreter

First run downloads the interpreter and the libraries, about 30 MB. Later visits start from the browser cache.

+
  • WebAssembly interpreter
  • Data and imaging libraries
  • @@ -193,10 +312,12 @@

    Statutory grid connection registers,
    as a table you can actually use

    Give it a document

    - +
    + +

    Drop a disclosure file here

    PDF, XLSX or CSV, as published by one of the nine supported publishers

    @@ -206,14 +327,14 @@

    Give it a document

    No real disclosure needed. Shows the schema and the eight quality rules.
    -
    +

    Give it a document

  • PTE-REDES
  • GBNational Grid
-

Detection uses the file name first and, for PDFs, the text +

Detection uses the file name first and, for PDFs, the text of the first page. Keep the name the publisher gave the file.

@@ -245,7 +366,7 @@

Result

@@ -308,6 +429,8 @@

What this page will not do

function step(i, state){ const li = document.querySelector(`.steps li[data-step="${i}"]`); if (li) li.className = state; + const done = document.querySelectorAll(".steps li.done").length; + $("bar").style.width = Math.round(done / 4 * 100) + "%"; } function bootState(badgeText, badgeCls, title, hint){ $("bootBadge").textContent = badgeText; @@ -368,11 +491,25 @@

What this page will not do

} } +const fmt = (n) => Number(n).toLocaleString("en-US"); +function countUp(el, target){ + const dur = 620, t0 = performance.now(); + const tick = (t) => { + const p = Math.min(1, (t - t0) / dur); + const e = 1 - Math.pow(1 - p, 3); + el.textContent = fmt(Math.round(target * e)); + if (p < 1) requestAnimationFrame(tick); + }; + requestAnimationFrame(tick); +} function stats(items){ - $("stats").innerHTML = items.map(([k, v, small]) => - `

${k}

${v}
`).join(""); + $("stats").innerHTML = items.map(([k, v, kind]) => + `

${k}

` + + `
` + + `${kind === "num" ? "0" : v}
`).join(""); + document.querySelectorAll('#stats .v[data-to]').forEach(el => countUp(el, Number(el.dataset.to))); } -function table(el, cols, rows, numCols, caption){ +function table(el, cols, rows, numCols){ const th = cols.map(c => `${c}`).join(""); const tr = rows.map(r => "" + cols.map(c => { const v = r[c]; @@ -380,8 +517,7 @@

What this page will not do

const cls = (numCols && numCols.has(c) ? "num " : "") + (blank ? "nil" : ""); return `${blank ? "not disclosed" : String(v)}`; }).join("") + "").join(""); - el.innerHTML = `${th}${tr}` - + (caption ? `${caption}` : ""); + el.innerHTML = `${th}${tr}`; } function download(name, text, mime){ const b = new Blob([text], { type: mime }); @@ -389,7 +525,6 @@

What this page will not do

a.href = URL.createObjectURL(b); a.download = name; a.click(); URL.revokeObjectURL(a.href); } -const fmt = (n) => Number(n).toLocaleString("en-US"); async function runOn(filename, bytes){ if (!ready) { log("still loading, try again in a moment"); return; } @@ -456,11 +591,12 @@

What this page will not do

const d = JSON.parse(res); stats([ - ["Publisher", d.publisher, true], - ["Rows", fmt(d.rows)], - ["Schema fields populated", `${d.schema_filled} of ${d.schema_total}`], - ["Columns", fmt(d.cols)], - ["Quality violations", fmt(d.violations)], + ["Publisher", d.publisher, "text"], + ["Rows", d.rows, "num"], + ["Schema fields populated", + `${d.schema_filled} of ${d.schema_total}`, "text"], + ["Columns", d.cols, "num"], + ["Quality violations", d.violations, "num"], ]); const numeric = new Set(["moc_pobierana","moc_wprowadzana","moc_dostepna","moc_zarezerwowana", diff --git a/docs/cli.md b/docs/cli.md index bc54640..a48181d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,32 +1,33 @@ --- -title: Wiersz poleceń +title: Command line --- -# Wiersz poleceń +# Command line ```bash -gridqueue schema # specyfikacja 21 pól -gridqueue adapters # deklaracje publikujących +gridqueue schema # specification of the 21 fields +gridqueue adapters # publisher declarations gridqueue parse tauron.pdf --out tauron.parquet --report tauron.json -gridqueue parse --adapter uk_nationalgrid --out uk.parquet # pobiera z katalogu CKAN +gridqueue parse --adapter uk_nationalgrid --out uk.parquet # downloads from the CKAN catalogue gridqueue validate tauron.parquet --out walidacja.json gridqueue export tauron.parquet stoen.parquet --out panel.parquet --only-schema ``` -`parse` rozpoznaje publikującego z nazwy pliku, a gdy to nie wystarcza, z treści pierwszej -strony. `--adapter` wymusza wybór. `--report` zapisuje raport wydobycia: liczbę wierszy, strategię, -odtworzone numery porządkowe, pola wypełnione i napotkane anomalie. +`parse` recognizes the publisher from the file name and, where that is not enough, from the content +of the first page. `--adapter` forces the choice. `--report` writes the extraction report: the row +count, the strategy, the reconstructed ordinal numbers, the fields populated and the anomalies +encountered. -`validate` uruchamia osiem reguł kontroli jakości oraz audyt przesunięcia kolumn i zapisuje -naruszenia wraz z wierszami, które je powodują, naruszenie nie przerywa przebiegu. +`validate` runs the eight quality rules together with the column-shift audit and writes the +violations along with the rows that cause them; a violation does not abort the run. -`export` scala wyniki wielu adapterów w jeden panel. `--only-schema` pomija kolumny rozszerzeń -z przedrostkiem `_`. +`export` merges the results of several adapters into one panel. `--only-schema` omits the extension +columns carrying the `_` prefix. -## Pochodzenie wyniku +## Provenance of the result -Każdy wiersz niesie rekord pochodzenia: dokument źródłowy, stronę, wersję adaptera i wersję -gazetera użytego przy rozwiązywaniu lokalizacji. Ustawa wymaga kwartalnej wymiany dokumentów, -więc osoba odtwarzająca pracę na dokumentach z późniejszego kwartału pobierze inne dokumenty -i **powinna oczekiwać innych liczb wierszy**, dlatego edycja rejestru jest odnotowywana -w każdym wyniku, a nie zakładana. +Every row carries a provenance record: the source document, the page, the adapter version and the +version of the gazetteer used when the location was resolved. The statute requires the documents to +be replaced quarterly, so anyone reproducing the work on documents from a later quarter will +download different documents and **should expect different row counts**; this is why the register +edition is recorded in every result rather than assumed. diff --git a/docs/colab.md b/docs/colab.md index 5ec6397..c035cc7 100644 --- a/docs/colab.md +++ b/docs/colab.md @@ -2,52 +2,58 @@ title: Google Colab --- -# Uruchomienie w przeglądarce +# Running in the browser -[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) +[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) -Notatnik `notebooks/gridqueue_colab.ipynb` usuwa barierę instalacyjną: recenzent albo analityk -regulatora uruchamia pełny przebieg bez instalowania czegokolwiek, bez konta i bez akceleratora. +The notebook `notebooks/gridqueue_colab.ipynb` removes the installation barrier: a reviewer or an +analyst at the regulator runs the full workflow without installing anything, without an account and +without an accelerator. -## Co notatnik wykonuje +## What the notebook does -1. instaluje pakiet z **oznaczonego wydania**, nie z gałęzi głównej, więc wynik nie zależy od - bieżącego stanu repozytorium; -2. pobiera dwie kolejne edycje ujawnienia wprost od publikującego i wypisuje sumy kontrolne; -3. rozpoznaje publikującego **z zawartości dokumentu** i wydobywa wiersze wspólnego schematu; -4. ocenia osiem reguł kontroli jakości; -5. liczy przepływy w kolejce między edycjami oraz **precyzję dopasowania** na polach wyłączonych - z klucza; -6. porównuje odtworzone liczby z opublikowanymi w artykule i **przerywa wykonanie przy rozjeździe**. +1. installs the package from a **tagged release**, not from the main branch, so the result does not + depend on the current state of the repository; +2. downloads two consecutive editions of the disclosure directly from the publisher and prints the + checksums; +3. recognizes the publisher **from the content of the document** and extracts the rows of the common + schema; +4. evaluates the eight quality control rules; +5. computes the queue flows between the editions together with the **linkage precision** on the + fields held out of the key; +6. compares the reproduced figures with those published in the paper and **aborts execution on a + divergence**. -Punkt szósty jest odpowiednikiem asercji z katalogu `reproducibility/`. Rozjazd nie musi oznaczać -błędu, publikujący mógł wymienić edycję, ale musi być widoczny, a nie przemilczany. +Point six is the counterpart of the assertions in the `reproducibility/` directory. A divergence need +not mean an error, the publisher may have replaced the edition, but it has to be visible rather than +passed over in silence. -## Czego notatnik nie robi +## What the notebook does not do -Nie odtwarza dokładności wydobycia wobec zbioru odniesienia, bo ten wymaga odczytu przez człowieka. -Nie rozstrzyga współrzędnych, bo gazeter geometryczny jest osobnym pobraniem i podlega ODbL, -a notatnik nie powinien po cichu wciągać użytkownika w obowiązki licencyjne. Nie uruchamia też -przykładu przekrojowego na tym publikującym, bo **nie spełnia on kryterium pokrycia dat** -postawionego przed policzeniem wyniku, notatnik pokazuje to wprost, zamiast policzyć medianę -na kilkunastu procentach rekordów. +It does not reproduce the extraction accuracy against the reference set, because that set requires a +human reading. It does not resolve coordinates, because the geometric gazetteer is a separate +download and is subject to ODbL, and the notebook should not quietly draw the user into licensing +duties. It also does not run the cross-sectional example on this publisher, because **it does not +meet the date coverage criterion** set before the result was computed; the notebook shows this +openly instead of computing a median on a dozen or so percent of the records. -## Gdy pobranie się nie powiedzie +## When a download fails -Dwie sytuacje są przewidziane i obie kończą się komunikatem, nie wyjątkiem. +Two situations are anticipated and both end with a message rather than an exception. -**Kod 404.** Edycje przesuwają się w czasie, a starsze bywają usuwane po wymianie. Pobierz bieżący -wykaz ze strony publikującego, wgraj go przez panel plików i wpisz nazwę do słownika `pliki`. +**Code 404.** Editions move in time, and older ones are sometimes removed once they are replaced. +Download the current list from the publisher's site, upload it through the file panel and enter the +name in the `pliki` dictionary. -**Błąd weryfikacji certyfikatu.** Typowe w sieciach firmowych i instytucjonalnych z serwerem -pośredniczącym, który podmienia łańcuch certyfikatów; w Colab nie występuje. Notatnik **nie obchodzi -tej kontroli** i kieruje do wgrania pliku ręcznie. +**Certificate verification error.** Typical in corporate and institutional networks with an +intermediary server that substitutes the certificate chain; it does not occur in Colab. The notebook +**does not circumvent that control** and directs the user to upload the file manually. -## Pozycja notatnika wobec CI +## Where the notebook stands relative to CI -Ciągła integracja **nie uruchamia** notatnika, bo ten sięga po dokumenty wymieniane kwartalnie, -a zadanie zależne od zewnętrznej publikacji psułoby się bez związku z kodem. Osobne zadanie -sprawdza natomiast to, co sprawdzić można bez sieci: czy wszystkie komórki kodu są poprawne -składniowo i czy każda nazwa importowana z pakietu faktycznie w nim istnieje. To właśnie ta -druga kontrola odpowiada defektowi, który ujawniło pierwsze uruchomienie notatnika - -dokumentacja obiecywała metodę `as_frame`, której pakiet nie miał. +Continuous integration **does not run** the notebook, because it reaches for documents that are +replaced quarterly, and a job that depends on an external publication would break for reasons +unrelated to the code. A separate job does check what can be checked without network access: whether +all the code cells are syntactically correct and whether every name imported from the package really +exists in it. It is precisely that second check which answers the defect revealed by the first run of +the notebook: the documentation promised an `as_frame` method that the package did not have. diff --git a/docs/index.md b/docs/index.md index f19c01c..8bd8174 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,8 +4,8 @@ title: gridqueue # gridqueue -Harmonizator ustawowych ujawnień przyłączeniowych do sieci elektroenergetycznej. -Wersja **1.5.2** · [repozytorium](https://github.com/s-matysik/gridqueue) +Harmonizer of statutory grid-connection disclosures for the electricity network. +Version **1.5.2** · [repository](https://github.com/s-matysik/gridqueue) > **In English.** `gridqueue` parses the statutory grid-connection disclosures that Polish > distribution system operators must publish under Article 7(8l) of the Energy Law, and emits @@ -13,28 +13,28 @@ Wersja **1.5.2** · [repozytorium](https://github.com/s-matysik/gridqueue) > jurisdictions; the schema is derived from the legal obligation, not from any one document. > Failures are returned as missing-with-reason, never as guesses. -## Problem +## The problem -Operatorzy systemów dystrybucyjnych mają obowiązek publikować, kto ubiega się o przyłączenie, -gdzie, o jaką moc i na jakim etapie stoi postępowanie. W Polsce obowiązek dotyczy około -180 koncesjonowanych operatorów i **każdy publikuje we własnym formacie**, najczęściej jako -dokument do druku. Informacja jest jawna, ale nie jest przetwarzalna. +Distribution system operators have a duty to publish who is applying for a connection, where, for +what capacity and at what stage the proceeding stands. In Poland the duty covers approximately +180 licensed operators and **each one publishes in its own format**, most often as a document meant +for printing. The information is public, but it is not processable. -Niejednorodność dotyczy jednak **nośnika, nie pojęć**. Arkusz operatora przesyłowego zawiera -listę dopuszczalnych wartości pola publikującego, wymieniającą sześciu największych operatorów -w kraju, formularz jest więc uzgodnionym wzorcem sprawozdawczym, który każdy z nich wypełnia, -tylko jeden wydaje go jako arkusz, a drugi jako dokument do druku. Wspólny schemat tego pakietu -jest odtworzeniem tego uzgodnienia. +The heterogeneity concerns the **medium, not the concepts**, however. The transmission operator's +spreadsheet contains a list of the permitted values of the publisher field, naming the six largest +operators in the country; the form is therefore an agreed reporting template which each of them +fills in, only one issues it as a spreadsheet and another as a document meant for printing. The +common schema of this package is a reconstruction of that agreement. -## Czego pakiet nie robi +## What the package does not do -Nie jest indeksem publikacji operatorów ani mapą przeglądową. Nie jest też oszacowaniem dostępnej -mocy przyłączeniowej: rejestr ujawnia **kolejkę, nie zapas**. Nie jest rankingiem lokalizacji - -nie zawiera żadnego modelu preferencji. +It is not an index of operators' publications and not an overview map. Nor is it an estimate of the +available connection capacity: the register discloses the **queue, not the reserve**. It is not a +ranking of locations, it contains no model of preferences. -## Stan wydania +## State of the release -| publikujący | wierszy w panelu | pól z ujawnienia | pól łącznie z wyprowadzonym | +| publisher | rows in panel | fields from disclosure | fields including the derived one | |---|---:|---:|---:| | TAURON Dystrybucja S.A. | 10955 | 15 | 15 | | ENERGA-OPERATOR S.A. | 5382 | 17 | 17 | @@ -43,26 +43,26 @@ nie zawiera żadnego modelu preferencji. | National Grid Electricity Distribution | 694 | 10 | 10 | | Boryszew Green Energy&Gas Sp. z o.o. | 8 | 8 | 9 | -**Wszystkie 21 pól schematu jest wypełnionych w panelu.** Pole współrzędnych nie jest ujawniane -przez żadnego publikującego i powstaje przez wyprowadzenie z nazwy miejsca, dlatego w tabeli -rozdzielono pola z ujawnienia od pola wyprowadzonego, a w wyniku każdego rozwiązania zapisany jest -poziom pewności i poziom dokładności umiejscowienia. +**All 21 schema fields are populated in the panel.** The coordinate field is not disclosed by any +publisher and arises by derivation from the place name, which is why the table separates the fields +coming from the disclosure from the derived field, and why the result of every resolution records a +confidence level and a placement accuracy level. -## Strony +## Pages -* [**Uruchom w przeglądarce**](app/) bez instalacji: ta sama biblioteka w interpreterze - WebAssembly, dokument przetwarzany lokalnie i nigdzie nie wysyłany -* [Schemat 21 pól](schemat.md) -* [Adaptery i jak dodać publikującego](adaptery.md) -* [Metoda wydobycia](wydobycie.md) -* [Reguły kontroli jakości](jakosc.md) -* [Zmierzona walidacja](walidacja.md) -* [Analiza wzdłużna, porównanie edycji](wzdluzna.md) -* [Uruchomienie w Google Colab](colab.md) -* [Wiersz poleceń](cli.md) -* [Ograniczenia](ograniczenia.md) +* [**Run in the browser**](app/) with no installation: the same library in a WebAssembly + interpreter, the document processed locally and sent nowhere +* [The 21-field schema](schemat.md) +* [Adapters and how to add a publisher](adaptery.md) +* [Extraction method](wydobycie.md) +* [Quality control rules](jakosc.md) +* [Measured validation](walidacja.md) +* [Longitudinal analysis, comparison of editions](wzdluzna.md) +* [Running in Google Colab](colab.md) +* [Command line](cli.md) +* [Limitations](ograniczenia.md) -## Instalacja +## Installation ```bash git clone https://github.com/s-matysik/gridqueue @@ -71,15 +71,15 @@ pip install -e ".[test]" python -m pytest -q ``` -## Najkrótszy przykład +## The shortest example ```python from gridqueue import get_adapter, run_quality, audit_column_shift res = get_adapter("pl_tauron").parse("tauron_informacja.pdf") -df = res.frame # ramka w 21-polowym schemacie +df = res.frame # frame in the 21-field schema res.report["n_wierszy"] # 10955 audit_column_shift(df).udzial # 0.0 run_quality(df).as_dict()["naruszen_lacznie"] ``` -- [Warstwa analityczna](analiza.md) +- [Analytical layer](analiza.md) diff --git a/docs/jakosc.md b/docs/jakosc.md index f9bb0c0..22fe4c3 100644 --- a/docs/jakosc.md +++ b/docs/jakosc.md @@ -1,69 +1,75 @@ --- -title: Reguły jakości +title: Quality rules --- -# Reguły kontroli jakości +# Quality control rules -Osiem reguł. Każda zwraca **liczbę naruszeń, nie wyjątek**, bo naruszenie jest zwykle -właściwością ujawnienia, a nie błędem narzędzia. Reguły są wyprowadzone z przepisu: dwuletnia -ważność warunków przyłączenia wynika z art. 7 ust. 8i, a nie z preferencji projektanta. +Eight rules. Each returns **a count of violations, not an exception**, because a violation is +usually a property of the disclosure rather than a fault of the tool. The rules are derived from the +provision: the two-year validity of connection conditions follows from Article 7(8i), not from the +designer's preference. -Zmierzone na panelu 19 220 wierszy, schemat w wersji 1.0: +Measured on the panel of 19 220 rows, schema version 1.0: -| reguła | co sprawdza | TAURON | ENERGA | Stoen | PSE | National Grid | Boryszew | panel | udział | +| rule | what it checks | TAURON | ENERGA | Stoen | PSE | National Grid | Boryszew | panel | share | |---|---|---:|---:|---:|---:|---:|---:|---:|---:| -| R1 | monotoniczność dat postępowania | 45 | 163 | 0 | 3 | 0 | 0 | 211 | 1,098 % | -| R2 | dwuletnia ważność warunków przyłączenia | 583 | 174 | 7 | 12 | 0 | 0 | 776 | 4,037 % | -| R3 | dopuszczalność stanu procesu wobec dat | 1 | 138 | 0 | 0 | 0 | 1 | 140 | 0,728 % | -| R4 | spójność jednostek mocy | 0 | 13 | 0 | 0 | 0 | 0 | 13 | 0,068 % | -| R5 | zakresy wartości | 0 | 13 | 0 | 0 | 0 | 0 | 13 | 0,068 % | -| R6 | duplikaty identyfikatorów | 1 029 | 59 | 0 | 0 | 0 | 0 | 1 088 | 5,661 % | -| R7 | kompletność rdzenia schematu | 0 | 766 | 0 | 5 | 0 | 0 | 771 | 4,011 % | -| R8 | słownik kontrolowany | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0,000 % | +| R1 | monotonicity of the proceeding dates | 45 | 163 | 0 | 3 | 0 | 0 | 211 | 1,098 % | +| R2 | two-year validity of connection conditions | 583 | 174 | 7 | 12 | 0 | 0 | 776 | 4,037 % | +| R3 | admissibility of the process status against the dates | 1 | 138 | 0 | 0 | 0 | 1 | 140 | 0,728 % | +| R4 | consistency of the capacity units | 0 | 13 | 0 | 0 | 0 | 0 | 13 | 0,068 % | +| R5 | value ranges | 0 | 13 | 0 | 0 | 0 | 0 | 13 | 0,068 % | +| R6 | duplicate identifiers | 1 029 | 59 | 0 | 0 | 0 | 0 | 1 088 | 5,661 % | +| R7 | completeness of the schema core | 0 | 766 | 0 | 5 | 0 | 0 | 771 | 4,011 % | +| R8 | controlled vocabulary | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0,000 % | -Kolumna „panel" to liczba wierszy naruszających regułę w całym panelu; domyka się do sumy kolumn -publikujących, co jest sprawdzane asercją przy generowaniu tej strony. W wersji 0.3.x strona -podawała dla R7 liczby zawyżone, przyczynę opisuje akapit o R7 niżej. +The "panel" column is the number of rows violating the rule across the whole panel; it closes to the +sum of the publisher columns, which is checked by an assertion when this page is generated. In +version 0.3.x the page reported inflated figures for R7; the reason is described in the paragraph on +R7 below. -## Jak czytać wyniki +## How to read the results -**R2** jest sumą dwóch wzajemnie rozłącznych podkontroli i tak musi być raportowana: 361 dat -wygaśnięcia przypada później niż dwa lata od wydania warunków, **oraz** 415 umów zawarto po -upływie tych dwóch lat. Pierwszy składnik ma sygnaturę ustalonej reguły administracyjnej -publikującego, mediana przekroczenia 21 dni, drugi pozostaje otwartym ustaleniem. +**R2** is the sum of two mutually disjoint sub-checks and has to be reported as such: 361 expiry +dates fall later than two years after the conditions were issued, **and** 415 agreements were +concluded after those two years had elapsed. The first component has the signature of a settled +administrative rule of the publisher, with a median overrun of 21 days; the second remains an open +finding. -**R4 i R5** wskazują ten sam zbiór 13 wierszy z **ujemną mocą wprowadzaną**, najmniejsza wartość -−700 kW. Jeden z nich trafił do próby wzorcowej i odczyt wzrokowy wartość ujemną potwierdza, więc -jest to właściwość ujawnienia, nie błąd wydobycia. Reguła zadziałała w swojej właściwej roli: -jako detektor jakości źródła. +**R4 and R5** point to the same set of 13 rows with a **negative injected capacity**, the smallest +value being −700 kW. One of them ended up in the reference sample and the visual reading confirms the +negative value, so this is a property of the disclosure, not an extraction error. The rule did what +it is there for: it acted as a detector of source quality. -**R7 mierzy od wersji 1.0 rdzeń właściwy dla encji wiersza.** W wersji 0.3.x rdzeń wymagał -bezwarunkowo pola `moc_pobierana` i stosował wymagania encji WNIOSEK także do wierszy encji -WĘZEŁ. Obie decyzje zamieniały **właściwość schematu w pozorne naruszenie ujawnienia**: wniosek -czysto wytwórczy deklaruje moc wprowadzaną, nie pobieraną, a wiersz węzłowy nie ma ani -identyfikatora wniosku, ani mocy wniosku, bo realizuje inny punkt przepisu. Rdzeń wymaga teraz: +**R7 has, since version 1.0, measured the core appropriate to the entity of the row.** In version 0.3.x +the core required the `moc_pobierana` field unconditionally and applied the requirements of the +WNIOSEK entity to rows of the WĘZEŁ entity as well. Both decisions turned **a property of the schema +into an apparent violation of the disclosure**: a purely generating application declares injected +capacity, not consumed capacity, and a node row has neither an application identifier nor an +application capacity, because it discharges a different point of the provision. The core now +requires: -* dla encji **WNIOSEK**, `id_wniosku`, `lokalizacja_tekst`, `klasa_zasobu`, `status_procesu` - oraz **co najmniej jednego** z pary (`moc_pobierana`, `moc_wprowadzana`); -* dla encji **WĘZEŁ**, `id_wezla` oraz **co najmniej jednego** z pary - (`moc_dostepna`, `ograniczenie_flaga`), bo pkt 2 obowiązku bywa realizowany mocą dostępną albo - liczbą wolnych miejsc przyłączeniowych. +* for the **WNIOSEK** entity, `id_wniosku`, `lokalizacja_tekst`, `klasa_zasobu`, `status_procesu` + and **at least one** of the pair (`moc_pobierana`, `moc_wprowadzana`); +* for the **WĘZEŁ** entity, `id_wezla` and **at least one** of the pair + (`moc_dostepna`, `ograniczenie_flaga`), because point 2 of the duty is sometimes discharged with + available capacity and sometimes with a count of free connection slots. -Po tej zmianie R7 spada z 5 390 (28,044 %) do **771 (4,011 %)**, a wierszy -z kompletnym rdzeniem jest **18 449 z 19 220**. Pozostałe naruszenia są brakami -ujawnienia, nie artefaktem schematu: 570 wniosków bez żadnej mocy, -202 wniosków bez opisu lokalizacji oraz 2 węzły bez mocy dostępnej i bez -flagi ograniczenia. Encji WNIOSEK jest 19 055, encji WĘZEŁ 165. +After that change R7 falls from 5 390 (28,044 %) to **771 (4,011 %)**, and the number of rows +with a complete core is **18 449 of 19 220**. The remaining violations are gaps in the +disclosure, not an artefact of the schema: 570 applications with no capacity at all, +202 applications with no location description and 2 nodes with neither available capacity nor a +constraint flag. There are 19 055 rows of the WNIOSEK entity and 165 of the WĘZEŁ entity. -**R8** korzysta ze słownika kontrolowanego pochodzącego z zakładki list rozwijanych wzorca -sprawozdawczego, a więc z autorytatywnego źródła sektorowego, nie z naszej konwencji. +**R8** uses a controlled vocabulary taken from the drop-down list tab of the reporting template, that +is from an authoritative sector source rather than from a convention of our own. ```python from gridqueue import run_quality q = run_quality(df) q.as_dict()["naruszen_lacznie"] -q.as_frame() # jeden wiersz na regułę +q.as_frame() # one row per rule ``` -Udziały na tej stronie liczone są z surowych liczników (naruszenia / wiersze panelu), nie -z zaokrąglonych wartości pola `udzial`, żeby nie rozchodziły się na ostatniej cyfrze z figurami. +The shares on this page are computed from the raw counters (violations / panel rows) rather than from +the rounded values of the `udzial` field, so that they do not diverge from the figures in the last +digit. diff --git a/docs/ograniczenia.md b/docs/ograniczenia.md index 6bed270..8328acc 100644 --- a/docs/ograniczenia.md +++ b/docs/ograniczenia.md @@ -1,78 +1,81 @@ --- -title: Ograniczenia +title: Limitations --- -# Ograniczenia - -Podajemy je razem z liczbami, nie tylko w osobnej sekcji, bo bez nich część wyników byłaby użyta -niepoprawnie. - -## Czym rejestr nie jest - -* **Nie jest oszacowaniem dostępnej mocy przyłączeniowej.** Ujawnia **kolejkę, nie zapas**. - Pole mocy dostępnej należy do encji węzła z pkt 2 obowiązku i jest wypełnione tylko tam, gdzie - publikujący ten punkt realizuje mocą. -* **Nie jest odwzorowaniem stanu sieci.** Opisuje postępowania administracyjne, których część - nigdy nie dojdzie do realizacji. Rozstrzygnięcie procesu jest zdarzeniem prawnym, nie fizycznym. -* **Nie jest rankingiem lokalizacji.** Nie zawiera modelu preferencji. -* **Nie jest indeksem publikacji.** Istnieją narzędzia indeksujące strony operatorów w skali - europejskiej; ten pakiet schodzi warstwę niżej i parsuje sam dokument. - -## Niewspółmierność ujawnień tego samego przepisu - -Dwóch publikujących wykonuje ten sam punkt obowiązku w postaciach nieporównywalnych: jeden podaje -**moc dostępną**, drugi **liczbę wolnych miejsc przyłączeniowych**. Odwzorowaliśmy to drugie na -flagę ograniczenia i pole rozszerzenia, pozostawiając pole mocy puste, wpisanie liczby miejsc -w pole mocy byłoby fabrykacją jednostki. Jest to wynik empiryczny, nie niedogodność -implementacyjna. - -## Zakres pokrycia - -Sześciu publikujących wierszowo na tle około 180 koncesjonowanych operatorów systemów -dystrybucyjnych w Polsce. Czterech z nich należy do sześciu objętych uzgodnionym wzorcem -sprawozdawczym, co wyznacza sprawdzalny horyzont rozszerzenia, ale **nie uprawnia do żadnego -twierdzenia o rozkładzie formatów wśród pozostałych publikujących**. - -## Dostęp do źródeł - -* **Jeden duży operator pozostaje niedostępny, i nie z powodu certyfikatu.** Brakujący certyfikat - pośredni pozyskano ze wskazania AIA w certyfikacie serwera i po jego dołożeniu serwis odpowiada - kodem 200 przy pełnej weryfikacji. Blokadą jest **filtrowanie klienta po stronie serwera**: - na uczciwy nagłówek identyfikacyjny serwis zwraca stronę odrzucenia. Odtworzenie odcisku - przeglądarki byłoby obejściem kontroli postawionej świadomie przez operatora, więc go nie - podjęliśmy. -* Dwa zagraniczne portale zwracają 403 na poziomie wierszy. Korzystamy wyłącznie z ich publicznych - metadanych i tak to opisujemy. **Kontroli dostępu nie obchodzimy**; klient przedstawia się - uczciwie w nagłówku identyfikacyjnym. - -## Pomiar dokładności - -* Zbiór odniesienia jest **częściowo jednoanotatorski**: zgodność międzyanotatorską zmierzono na - podpróbce 35 wierszy, natomiast wzorce dwóch publikujących pozostają jednoanotatorskie. -* Próba jest **klastrowa**, ciągi kolejnych wierszy na losowo wybranych stronach, a nie prosta - próba losowa, więc efektywna precyzja jest niższa, niż dałaby ta sama liczba niezależnych - losowań. -* Wzorzec obejmuje **encję wniosku**; dokładności tabel węzłowych, w tym pola mocy dostępnej - i horyzontów pięcioletnich, nie mierzono osobno. -* Udziału procentowego z pierwszego przebiegu pomiaru **nie wolno cytować jako punktu odniesienia** - dla wartości końcowej, bo zmienił się zbiór mierzonych pól; porównywalne jest rozbicie per pole. - -## Lokalizacja - -* Lokalizacja u największego publikującego to **wewnętrzny kod stacji**; operator nie publikuje - słownika kodów, więc rozwiązywacz zwraca brak z przyczyną. **Nie zgaduje.** Pozyskanie słowników - kodów stacji jednym krokiem przekształciłoby ten rejestr z aprzestrzennego w przestrzenny. -* Nazwa ulicy nie wyznacza punktu, zob. [walidacja](walidacja.md). - -## Przenoszalność - -Sześć źródeł wierszowych w dwóch jurysdykcjach to **demonstracja przenoszalności, nie dowód -ogólności**. Adapter zagraniczny działa na danych **już tabelarycznych**, więc przenoszalność -wykazano na przypadku łatwiejszym niż polski; druga jurysdykcja publikująca dokumenty do druku -byłaby dowodem mocniejszym. - -## Licencja - -Do ustalenia. Licencje danych wejściowych są osobne i niezmienne: gazeter z OpenStreetMap na -licencji ODbL; publikacje ustawowe operatorów na ich własnych warunkach korzystania, -redystrybuowane wyłącznie tam, gdzie jest to dozwolone. +# Limitations + +We state them together with the figures, not only in a separate section, because without them part +of the results would be used incorrectly. + +## What the register is not + +* **It is not an estimate of the available connection capacity.** It discloses the **queue, not the + reserve**. The available capacity field belongs to the node entity from point 2 of the duty and is + populated only where the publisher discharges that point with a capacity figure. +* **It is not a representation of the state of the network.** It describes administrative + proceedings, some of which will never reach completion. The settlement of a process is a legal + event, not a physical one. +* **It is not a ranking of locations.** It contains no model of preferences. +* **It is not an index of publications.** There are tools that index operators' pages at European + scale; this package goes one layer lower and parses the document itself. + +## Incommensurability of disclosures under the same provision + +Two publishers discharge the same point of the duty in forms that cannot be compared: one reports +**available capacity**, the other **a count of free connection slots**. We mapped the latter onto a +constraint flag and an extension field, leaving the capacity field empty; entering a count of slots +into a capacity field would be fabricating a unit. This is an empirical finding, not an +implementation inconvenience. + +## Extent of coverage + +Six publishers at row level against approximately 180 licensed distribution system operators in +Poland. Four of them belong to the six covered by the agreed reporting template, which marks out a +verifiable horizon for extension, but **does not license any claim about the distribution of formats +among the remaining publishers**. + +## Access to the sources + +* **One large operator remains unavailable, and not because of a certificate.** The missing + intermediate certificate was obtained from the AIA pointer in the server certificate, and once it + had been added the service answers with code 200 under full verification. The blocker is + **server-side client filtering**: to an honest identifying header the service returns a rejection + page. Reproducing a browser fingerprint would circumvent a control the operator put in place + deliberately, so we did not attempt it. +* Two foreign portals return 403 at row level. We use only their public metadata and describe it as + such. **We do not circumvent access controls**; the client identifies itself honestly in the + identifying header. + +## Accuracy measurement + +* The reference set is **partly single-annotator**: inter-annotator agreement was measured on a + subsample of 35 rows, whereas the reference sets of two publishers remain single-annotator. +* The sample is **clustered**, runs of consecutive rows on randomly chosen pages rather than a simple + random sample, so the effective precision is lower than the same number of independent draws would + give. +* The reference set covers the **application entity**; the accuracy of the node tables, including the + available capacity field and the five-year horizons, was not measured separately. +* The percentage share from the first measurement run **must not be cited as a point of reference** + for the final value, because the set of measured fields changed; what is comparable is the + breakdown per field. + +## Location + +* The location at the largest publisher is an **internal substation code**; the operator does not + publish a dictionary of the codes, so the resolver returns missing-with-reason. **It does not + guess.** Obtaining the substation code dictionaries would in a single step turn this register from + an aspatial one into a spatial one. +* A street name does not determine a point, see [validation](walidacja.md). + +## Transferability + +Six row-level sources in two jurisdictions are a **demonstration of transferability, not a proof of +generality**. The foreign adapter works on data that is **already tabular**, so transferability was +shown on a case easier than the Polish one; a second jurisdiction publishing documents meant for +printing would be stronger proof. + +## Licence + +To be settled. The licences of the input data are separate and fixed: the OpenStreetMap gazetteer +under ODbL; the operators' statutory publications under their own terms of use, redistributed only +where that is permitted. diff --git a/docs/schemat.md b/docs/schemat.md index 5d1d1f3..cecb90c 100644 --- a/docs/schemat.md +++ b/docs/schemat.md @@ -1,59 +1,60 @@ --- -title: Schemat +title: Schema --- -# Schemat 21 pól +# The 21-field schema -Schemat odwzorowuje **strukturę obowiązku prawnego, nie układ dokumentu**. Dwie encje wynikają -z punktów przepisu: WNIOSEK (pkt 1, 3, 4) oraz WĘZEŁ (pkt 2). Rdzeń obowiązkowy liczy pięć pól, -pozostałe szesnaście jest opcjonalne i **deklarowane per publikujący**, schemat oparty na -najmniejszym wspólnym mianowniku odrzuciłby poziom napięcia i pozycję w kolejce, czyli dokładnie -te pola, których potrzebuje analityk sieci. +The schema models the **structure of the legal obligation, not the layout of the document**. Two +entities follow from the points of the provision: WNIOSEK (points 1, 3, 4) and WĘZEŁ (point 2). The +mandatory core counts five fields, the remaining sixteen are optional and **declared per publisher**; +a schema based on the smallest common denominator would discard the voltage level and the queue +position, that is precisely the fields a network analyst needs. -Schemat ma wersję **1.0**, zapisywaną w raporcie walidacji i w metadanych eksportu. -Jednostki kanoniczne: moc w **kW** bez wyjątku, źródła podające megawaty są przeliczane przy -wydobyciu, a jednostka źródłowa zostaje odnotowana w rozszerzeniu. Daty w **ISO 8601**, -współrzędne w **WGS84**. -Pola, których dany operator dostarcza więcej niż wymaga minimum, trafiają do kolumn -z przedrostkiem `_` i są jawnie deklarowane przez adapter. +The schema has version **1.0**, recorded in the validation report and in the export metadata. +Canonical units: capacity in **kW** without exception, sources reporting megawatts are converted at +extraction and the source unit is recorded in an extension. Dates in **ISO 8601**, +coordinates in **WGS84**. +Fields that a given operator supplies beyond the required minimum go into columns +with the `_` prefix and are declared explicitly by the adapter. -| pole | typ | grupa | rdzeń | jednostka | podstawa prawna | opis | +| field | type | group | core | unit | legal basis | description | |---|---|---|---|---|---|---| -| id_wniosku | string | tozsamosc | **tak** |, | pkt 1/3/4 | Identyfikator pozycji w rejestrze publikującego; unikalny w obrębie publikacji, nie globalnie. | -| id_wezla | string | tozsamosc | nie |, | pkt 2 | Identyfikator stacji elektroenergetycznej lub jej grupy, w podziale na które ustawa każe podawać dostępną moc. | -| nazwa_wezla | string | tozsamosc | nie |, | pkt 2 | Nazwa własna stacji/punktu zasilania, jeśli publikujący ją ujawnia. | -| lokalizacja_tekst | string | tozsamosc | **tak** |, | pkt 1/3/4 | Lokalizacja miejsca przyłączenia tak, jak ją podał publikujący (adres, miejscowość, kod stacji) -- bez interpretacji. | -| wspolrzedne | geopoint | tozsamosc | nie | WGS84 | pkt 1/2 | Współrzędne geograficzne (lat, lon); wynik rozwiązania lokalizacji albo dana źródłowa. | -| poziom_napiecia | string | tozsamosc | nie |, | pkt 1 (>1 kV) | Poziom napięcia przyłączenia; obowiązek dotyczy sieci powyżej 1 kV, więc pole rozstrzyga o zakresie ujawnienia. | -| klasa_zasobu | string | tozsamosc | **tak** |, | pkt 1/3/4 | Rodzaj instalacji, urządzeń lub sieci, zharmonizowany do słownika kontrolowanego (PV, FW, BESS, ODB, ...). | -| moc_wprowadzana | number | moc | alternatywa | kW | pkt 1/3 | Moc przyłączeniowa wprowadzana do sieci (generacja/eksport). | -| moc_pobierana | number | moc | alternatywa | kW | pkt 1/3/4 | Moc przyłączeniowa pobierana z sieci (odbiór/import); dla wniosków odbiorczych jest to główna wielkość wniosku. Nie jest polem rdzenia bezwarunkowo: rdzeń wymaga CO NAJMNIEJ JEDNEGO z pary (moc_pobierana, moc_wprowadzana) -- patrz CORE_ALTERNATIVES. | -| moc_dostepna | number | moc | alternatywa | kW | pkt 2 | Łączna dostępna moc przyłączeniowa w węźle. | -| moc_zarezerwowana | number | moc | nie | kW | pkt 2 | Moc zajęta wydanymi i ważnymi warunkami / rezerwą. | -| ograniczenie_flaga | boolean | moc | alternatywa |, | pkt 2 | Czy w węźle występuje czynnik ograniczający przyłączenie. | -| pozycja_w_kolejce | number | moc | nie |, | pkt 1 | Pozycja wniosku w kolejce przyłączeniowej, jeśli publikujący ją prowadzi. | -| status_procesu | string | proces | **tak** |, | pkt 1/3/4 | Etap postępowania, zharmonizowany do słownika kontrolowanego. | -| data_wniosku | date | proces | nie | ISO-8601 | pkt 3 | Data złożenia wniosku o określenie warunków przyłączenia. | -| data_warunkow | date | proces | nie | ISO-8601 | pkt 1/3 | Data określenia warunków przyłączenia; początek dwuletniego terminu ważności (art. 7 ust. 8i). | -| data_odmowy | date | proces | nie | ISO-8601 | pkt 4 | Data wydania odmowy określenia warunków przyłączenia. | -| powod_odmowy | string | proces | nie |, | pkt 4 | Uzasadnienie odmowy (przyczyny techniczne / ekonomiczne / inne). | -| data_umowy | date | proces | nie | ISO-8601 | pkt 1 | Data zawarcia umowy o przyłączenie. | -| data_energizacji | date | proces | nie | ISO-8601 | pkt 1 | Data rozpoczęcia dostarczania energii elektrycznej. | -| data_publikacji | date | proces | nie | ISO-8601 | art. 7 ust. 8m | Stan na dzień, dla którego publikujący sporządził ujawnienie; ustawa wymaga aktualizacji co najmniej raz na kwartał. | - -**Rdzeń jest warunkowy i osobny dla każdej encji.** Cztery pola oznaczone `tak` są wymagane -bezwarunkowo dla encji WNIOSEK. Pola oznaczone `alternatywa` wchodzą do rdzenia parami, z których -musi być wypełnione co najmniej jedno: `moc_pobierana` albo `moc_wprowadzana` dla encji WNIOSEK oraz -`moc_dostepna` albo `ograniczenie_flaga` dla encji WĘZEŁ. Wiersz encji WĘZEŁ wymaga ponadto -`id_wezla`, a nie `id_wniosku`. Encję wiersza niesie kolumna anotacyjna `_encja`; wiersz bez tej -anotacji traktowany jest jako WNIOSEK. - -Powód jest rzeczowy, nie techniczny: wniosek przyłączeniowy zawsze deklaruje moc, lecz nie zawsze tę -samą, wytwórczy wprowadzaną, odbiorczy pobieraną, dwukierunkowy obie, a pkt 2 obowiązku bywa -realizowany mocą dostępną albo liczbą wolnych miejsc przyłączeniowych. Wymaganie jednego konkretnego -pola czyniłoby z własności schematu pozorne naruszenie ujawnienia. +| id_wniosku | string | tozsamosc | **yes** |, | pkt 1/3/4 | Identifier of the position in the publisher's register; unique within the publication, not globally. | +| id_wezla | string | tozsamosc | no |, | pkt 2 | Identifier of the electricity substation or of its group, by which the statute requires the available capacity to be reported. | +| nazwa_wezla | string | tozsamosc | no |, | pkt 2 | Proper name of the substation / supply point, if the publisher discloses it. | +| lokalizacja_tekst | string | tozsamosc | **yes** |, | pkt 1/3/4 | Location of the connection point exactly as the publisher gave it (address, locality, substation code), with no interpretation. | +| wspolrzedne | geopoint | tozsamosc | no | WGS84 | pkt 1/2 | Geographic coordinates (lat, lon); the result of location resolution or a source datum. | +| poziom_napiecia | string | tozsamosc | no |, | pkt 1 (>1 kV) | Voltage level of the connection; the duty covers networks above 1 kV, so this field settles the scope of the disclosure. | +| klasa_zasobu | string | tozsamosc | **yes** |, | pkt 1/3/4 | Type of installation, equipment or network, harmonized to a controlled vocabulary (PV, FW, BESS, ODB, ...). | +| moc_wprowadzana | number | moc | alternative | kW | pkt 1/3 | Connection capacity injected into the network (generation/export). | +| moc_pobierana | number | moc | alternative | kW | pkt 1/3/4 | Connection capacity consumed from the network (offtake/import); for consumption applications this is the main quantity of the application. It is not a core field unconditionally: the core requires AT LEAST ONE of the pair (moc_pobierana, moc_wprowadzana), see CORE_ALTERNATIVES. | +| moc_dostepna | number | moc | alternative | kW | pkt 2 | Total available connection capacity at the node. | +| moc_zarezerwowana | number | moc | no | kW | pkt 2 | Capacity taken up by issued and valid conditions / by a reservation. | +| ograniczenie_flaga | boolean | moc | alternative |, | pkt 2 | Whether a factor constraining connection occurs at the node. | +| pozycja_w_kolejce | number | moc | no |, | pkt 1 | Position of the application in the connection queue, if the publisher keeps one. | +| status_procesu | string | proces | **yes** |, | pkt 1/3/4 | Stage of the proceeding, harmonized to a controlled vocabulary. | +| data_wniosku | date | proces | no | ISO-8601 | pkt 3 | Date on which the application for determination of connection conditions was filed. | +| data_warunkow | date | proces | no | ISO-8601 | pkt 1/3 | Date on which the connection conditions were determined; the start of the two-year validity period (Article 7(8i)). | +| data_odmowy | date | proces | no | ISO-8601 | pkt 4 | Date on which the refusal to determine connection conditions was issued. | +| powod_odmowy | string | proces | no |, | pkt 4 | Justification of the refusal (technical / economic / other reasons). | +| data_umowy | date | proces | no | ISO-8601 | pkt 1 | Date on which the connection agreement was concluded. | +| data_energizacji | date | proces | no | ISO-8601 | pkt 1 | Date on which the supply of electricity began. | +| data_publikacji | date | proces | no | ISO-8601 | art. 7 ust. 8m | The date as of which the publisher compiled the disclosure; the statute requires an update at least once per quarter. | + +**The core is conditional and separate for each entity.** The four fields marked `yes` are required +unconditionally for the WNIOSEK entity. The fields marked `alternative` enter the core in pairs, of +which at least one has to be populated: `moc_pobierana` or `moc_wprowadzana` for the WNIOSEK entity, and +`moc_dostepna` or `ograniczenie_flaga` for the WĘZEŁ entity. A row of the WĘZEŁ entity additionally +requires `id_wezla` rather than `id_wniosku`. The entity of the row is carried by the annotation +column `_encja`; a row without that annotation is treated as WNIOSEK. + +The reason is substantive, not technical: a connection application always declares a capacity, but not +always the same one, a generating one the injected capacity, a consuming one the consumed capacity, a +bidirectional one both, and point 2 of the duty is sometimes discharged with available capacity and +sometimes with a count of free connection slots. Requiring one specific field would turn a property of +the schema into an apparent violation of the disclosure. ```bash -gridqueue schema # ta sama specyfikacja z wiersza poleceń +gridqueue schema # the same specification from the command line ``` diff --git a/docs/walidacja.md b/docs/walidacja.md index 702a7f8..759a64e 100644 --- a/docs/walidacja.md +++ b/docs/walidacja.md @@ -1,59 +1,60 @@ --- -title: Walidacja +title: Validation --- -# Zmierzona walidacja +# Measured validation -Dokładność wydobycia jest **zmierzona, nie zadeklarowana**. Zbiór odniesienia powstał przez -wizualne odczytanie renderowanych wycinków stron (230-600 dpi, z naniesionymi granicami kolumn), -**niezależnie od wyjścia parsera**. +The extraction accuracy is **measured, not declared**. The reference set was produced by visually +reading rendered crops of the pages (230-600 dpi, with the column boundaries drawn in), +**independently of the parser output**. -## Dokładność per publikujący +## Accuracy per publisher -| publikujący | wierszy wzorca | porównań | wierszy w pełni poprawnych | +| publisher | reference rows | comparisons | fully correct rows | |---|---:|---:|---| -| TAURON Dystrybucja | 100 | 1 200 | **98 z 100**, 100 z 100 po wyłączeniu pary homoglifów | -| Stoen Operator | 100 | 1 200 | **99 z 100**, 100 z 100 po adjudykacji | -| PSE | 60 | 780 | **60 z 60** | -| ENERGA-OPERATOR | 60 | 780 | **60 z 60** | -| Boryszew Green Energy&Gas | 8 | 64 | **8 z 8** | +| TAURON Dystrybucja | 100 | 1 200 | **98 of 100**, 100 of 100 once the homoglyph pair is excluded | +| Stoen Operator | 100 | 1 200 | **99 of 100**, 100 of 100 after adjudication | +| PSE | 60 | 780 | **60 of 60** | +| ENERGA-OPERATOR | 60 | 780 | **60 of 60** | +| Boryszew Green Energy&Gas | 8 | 64 | **8 of 8** | -Dwie niezgodności u TAURONA to ta sama para homoglifów: wielkie `I` wobec małego `l` w kroju -bezszeryfowym. Rozstrzygnięcie wzrokowe jest tu niemożliwe **z zasady**, a nie tylko utrudnione - -oba znaki są renderowane glifami nierozróżnialnymi przy każdym powiększeniu. Jedynym dostępnym -dowodem jest warstwa tekstowa pliku. **Podajemy obie wartości i żadna nie zastępuje drugiej.** +The two discrepancies at TAURON are the same homoglyph pair: capital `I` against lower-case `l` in a +sans-serif typeface. A visual settlement is impossible here **in principle**, not merely difficult, +both characters are rendered with glyphs that cannot be told apart at any magnification. The only +available evidence is the text layer of the file. **We report both values and neither replaces the +other.** -Jedyna niezgodność u Stoena rozstrzygnęła się przy 600 dpi **na korzyść parsera**, był to błąd -anotatora. Jedna korekta wzorca ENERGI również wypadła na korzyść parsera. +The single discrepancy at Stoen settled at 600 dpi **in the parser's favour**; it was an annotator +error. One correction to the ENERGA reference set also fell in the parser's favour. -## Zgodność międzyanotatorska +## Inter-annotator agreement -Podpróbkę 35 wierszy odczytał **drugi anotator pracujący w zaślepieniu**: bez dostępu do wzorca -pierwszego anotatora, do tabeli dokładności, do raportu walidacji i do wyjścia parsera. +A subsample of 35 rows was read by **a second annotator working blind**: with no access to the first +annotator's reference set, to the accuracy table, to the validation report or to the parser output. -| miara | wartość | +| measure | value | |---|---:| -| porównań pole-wiersz | 400 | -| zgodność surowa | **0,9725** | -| zgodność oczekiwana losowo | 0,1120 | -| **kappa Cohena** | **0,9690** | -| zgodność parsera z wzorcem uzgodnionym | **400 z 400** | +| field-row comparisons | 400 | +| raw agreement | **0,9725** | +| agreement expected by chance | 0,1120 | +| **Cohen's kappa** | **0,9690** | +| agreement of the parser with the adjudicated reference set | **400 of 400** | -Wszystkie 11 niezgodności to **konwencja zapisu, nie różnica odczytu**: siedem dotyczy komórki -zawierającej tekst niebędący datą w polu daty, cztery, łącznika na końcu wiersza w nazwisku. -**Niezgodności percepcyjnych nie było ani jednej.** Wzorce PSE i ENERGI pozostają -jednoanotatorskie i dla nich zgodności nie mierzono. +All 11 discrepancies are **a convention of notation, not a difference of reading**: seven concern a +cell containing text that is not a date in a date field, four, a hyphen at the end of a line in a +surname. **There was not a single perceptual discrepancy.** The PSE and ENERGA reference sets remain +single-annotator and agreement was not measured for them. -Zastrzeżenie: podpróbka nie zawiera wierszy z parą homoglifów, więc wynik 400 z 400 dotyczy innego -zbioru wierszy i **nie unieważnia** pomiaru 98 z 100. +A caveat: the subsample contains no rows with the homoglyph pair, so the 400 of 400 result concerns a +different set of rows and **does not invalidate** the 98 of 100 measurement. -## Geolokalizacja +## Geolocation -Pole współrzędnych nie jest ujawniane przez żadnego publikującego; powstaje przez wyprowadzenie -z nazwy miejsca wobec gazetera z geometrią (13 149 nazw w 25 miejscowościach, 292 punkty adresowe, +The coordinate field is not disclosed by any publisher; it arises by derivation from the place name +against a gazetteer with geometry (13 149 names in 25 localities, 292 address points, OpenStreetMap, ODbL 1.0). -| publikujący | wierszy | ze współrzędnymi | pokrycie | +| publisher | rows | with coordinates | coverage | |---|---:|---:|---:| | Stoen Operator | 1 236 | 1 217 | **98,463%** | | Boryszew Green Energy&Gas | 8 | 8 | **100,000%** | @@ -63,31 +64,33 @@ OpenStreetMap, ODbL 1.0). | National Grid | 694 | 0 | 0,000% | | **panel** | **19 220** | **1 225** | **6,374%** | -Zera są **potwierdzone, nie naprawiane zgadywaniem**, i każde ma zapisaną przyczynę: u TAURONA -kod stacji bez opublikowanego słownika, u PSE i ENERGI przewaga wierszy bez zadeklarowanej -miejscowości, u National Grid nazwy punktów zasilania zamiast adresów ulic. +The zeros are **confirmed, not repaired by guessing**, and each one has a recorded reason: at TAURON +a substation code with no published dictionary, at PSE and ENERGA a preponderance of rows with no +declared locality, at National Grid the names of grid supply points instead of street addresses. -Weryfikacja na próbie warstwowej 102 punktów: zgodność nazwy ulicy z niezależnym geokodowaniem -**101 z 102 = 99,02%**; mediana odległości między dwoma niezależnie wybranymi punktami -reprezentatywnymi tej samej ulicy **259,2 m**, przy korelacji Spearmana z długością osi **0,714** - -źródła wskazują tę samą ulicę i różnią się tym, który jej punkt uznają za reprezentatywny. +Verification on a stratified sample of 102 points: agreement of the street name with independent +geocoding **101 of 102 = 99,02%**; the median distance between two independently chosen +representative points of the same street **259,2 m**, with a Spearman correlation with the length of +the axis of **0,714**, the sources indicate the same street and differ in which of its points they +take to be representative. -**Ograniczenie zasadnicze:** jest to weryfikacja wobec drugiego odczytu tej samej bazy, nie wobec -pomiaru terenowego. Źródła są skorelowane, więc pomiar nie wyklucza błędu wspólnego dla -OpenStreetMap. +**A fundamental limitation:** this is verification against a second reading of the same database, not +against a field measurement. The sources are correlated, so the measurement does not rule out an +error common to OpenStreetMap. -**Nazwa ulicy nie wyznacza punktu.** 431 z 6 057 nazw warszawskich (7,12%) ma rozłączne składowe -odległe o ponad 2 km. Rejestr podaje ulicę, lecz nie dzielnicę, więc tej niejednoznaczności -**nie da się usunąć z danych opublikowanych**, jest to ustalenie o zakresie obowiązku ujawnienia, -nie o jakości narzędzia. Każdy wynik niesie liczbę składowych i ich rozrzut, żeby odbiorca mógł -takie wiersze odfiltrować. +**A street name does not determine a point.** 431 of 6 057 Warsaw names (7,12%) have disjoint +components more than 2 km apart. The register gives the street but not the district, so this +ambiguity **cannot be removed from the published data**; it is a finding about the scope of the +disclosure duty, not about the quality of the tool. Every result carries the number of components and +their spread, so that the recipient can filter such rows out. -## Testy a pomiar wzrokowy +## Tests versus visual measurement -`python -m pytest -q` zgłasza **120 passed, 2 skipped** na 122 zebrane. Dwa pominięcia są -warunkowe: testy integracyjne adapterów PSE i ENERGI wymagają dokumentów źródłowych. +`python -m pytest -q` reports **120 passed, 2 skipped** out of 122 collected. The two skips are +conditional: the integration tests of the PSE and ENERGA adapters require the source documents. -Obie metody wychwytują **różne klasy defektów** i oba mechanizmy są w pakiecie obecne. Pięć -defektów odwzorowania przeszło przez cały zestaw testów, bo żaden nie rzucał wyjątku, w tym -jeden zmieniający status umowy na przeciwny w 88 wierszach dwóch publikujących. Wykryło je -porównanie wyjścia z wzorcem odczytanym z dokumentu. Wszystkie są objęte testami regresyjnymi. +The two methods catch **different classes of defect** and both mechanisms are present in the package. +Five mapping defects passed through the entire test suite, because none of them raised an exception, +among them one that reversed the agreement status in 88 rows of two publishers. They were detected by +comparing the output with the reference set read from the document. All of them are covered by +regression tests. diff --git a/docs/wydobycie.md b/docs/wydobycie.md index 0894e28..eb72391 100644 --- a/docs/wydobycie.md +++ b/docs/wydobycie.md @@ -1,40 +1,45 @@ --- -title: Metoda wydobycia +title: Extraction method --- -# Metoda wydobycia - -Zamiast wyrażeń regularnych na spłaszczonym tekście, wydobycie z **położenia słów na stronie**. - -* **`ruled`**, granice kolumn brane z pionowych **krawędzi wektorowych** zapisanych w pliku - (TAURON, Stoen, ENERGA). Pusta komórka jest odgrodzona linią, więc nie może zlać się - z sąsiednią. W dokumencie ENERGI siatki nie tworzą obiekty linii, lecz 176 cienkich - prostokątów, strategia działa na nich poprawnie. -* **`banded`**, granice z pionowych korytarzy bieli (Boryszew; dokument bez siatki). -* **arkusz**, PSE czytany wprost z komórek, **wraz z formatowaniem znaku**. Bez tego indeksy - górne oznaczające przypisy sklejają się z treścią, a w polach liczbowych niszczą wartość. - Odcięcie następuje po formatowaniu, nie po zgadywaniu końca napisu, zgadywanie okaleczyłoby - prawdziwe nazwy stacji kończące się literą. -* Wiersze wielolinijkowe scalane kolumna po kolumnie po numerze porządkowym. -* Zawijany nagłówek w wąskich kolumnach odczytywany geometrycznym przypisaniem słów nagłówka - do kolumn. - -## Dlaczego `pdfplumber` - -Daje bezpośredni dostęp do współrzędnych słów i krawędzi wektorowych. `camelot` w trybie lattice -odtwarza granice kolumn z rastra i wymaga Ghostscriptu, `tabula` wymaga JVM, w obu granica -kolumny jest **wynikiem detekcji na obrazie**, a nie liczbą z pliku. - -## Co to zmieniło, zmierzone - -Audyt zlicza wiersze, w których niepusta wartość stoi w polu, do którego nie może należeć. -W dokumencie TAURONA: **767 z 10 559 = 7,264%** przy wydobyciu regexowym, **0 z 10 955 = 0,000%** -przy wydobyciu z układu kolumn. Stary parser **gubił także wiersze**: numery porządkowe w nowym -wydobyciu biegną 1…10 955 bez luk i duplikatów, czyli odzyskiwał o 396 wierszy mniej. - -Wynik 0,000% należy czytać zgodnie z tym, co mierzy: audyt jest **detektorem wewnętrznej -sprzeczności typu**, nie porównaniem ze wzorcem. Bezbłędność mierzy zbiór odniesienia - -zob. [walidacja](walidacja.md). +# Extraction method + +Instead of regular expressions over flattened text, extraction from the **position of the words on +the page**. + +* **`ruled`**, column boundaries taken from the vertical **vector edges** recorded in the file + (TAURON, Stoen, ENERGA). An empty cell is fenced off by a line, so it cannot merge with the + neighbouring one. In the ENERGA document the grid is not made of line objects but of 176 thin + rectangles; the strategy works correctly on those. +* **`banded`**, boundaries from the vertical corridors of whitespace (Boryszew; a document with no + grid). +* **spreadsheet**, PSE read directly from the cells, **together with character formatting**. + Without that, the superscripts marking footnotes merge into the content, and in numeric fields + they destroy the value. The truncation happens on the basis of the formatting, not on the basis of + guessing where the string ends; guessing would mutilate genuine substation names that end with a + letter. +* Multi-line rows merged column by column following the ordinal number. +* Wrapped headers in narrow columns read by geometric assignment of the header words to the + columns. + +## Why `pdfplumber` + +It gives direct access to the coordinates of the words and to the vector edges. `camelot` in lattice +mode reconstructs the column boundaries from a raster image and requires Ghostscript, `tabula` +requires a JVM; in both, the column boundary is the **result of detection on an image** rather than +a number from the file. + +## What this changed, measured + +The audit counts the rows in which a non-empty value sits in a field it cannot belong to. +In the TAURON document: **767 of 10 559 = 7,264%** with regex extraction, **0 of 10 955 = 0,000%** +with extraction from the column layout. The old parser **also lost rows**: in the new extraction the +ordinal numbers run 1…10 955 with no gaps and no duplicates, which means it recovered 396 rows +fewer. + +The 0,000% result should be read as what it measures: the audit is a **detector of internal type +inconsistency**, not a comparison against a reference set. Freedom from error is measured by the +reference set, see [validation](walidacja.md). ```python from gridqueue import audit_column_shift diff --git a/docs/wzdluzna.md b/docs/wzdluzna.md index ee1112d..149558e 100644 --- a/docs/wzdluzna.md +++ b/docs/wzdluzna.md @@ -1,116 +1,120 @@ --- -title: Analiza wzdłużna +title: Longitudinal analysis --- -# Porównanie edycji rejestru - -Obowiązek ustawowy każe wymieniać ujawnienie co najmniej raz na kwartał, więc kolejne edycje -tego samego rejestru są naturalnym materiałem do analizy wzdłużnej. Jedna rzecz stoi temu -na drodze i trzeba ją zadeklarować, a nie obejść milczeniem. - -## Rejestr nie publikuje trwałego identyfikatora wniosku - -U części publikujących pole identyfikatora obiektu jest puste w niemal każdym wierszu - -u PSE w 866 z 876, a pakiet wstawia wtedy zastępnik oparty na liczbie porządkowej -w dokumencie. Taki zastępnik jest stabilny **w obrębie jednej edycji i bezwartościowy między -edycjami**: pozycja 869 w jednej edycji nie jest tym samym wnioskiem co pozycja 869 -w następnej, bo wiersze się przesuwają. Złączenie po identyfikatorze dałoby wynik pozornie -sensowny i całkowicie fałszywy. - -`compare_editions` używa więc **klucza treściowego** zbudowanego z publikującego, lokalizacji, -poziomu napięcia, klasy zasobu i obu mocy. Daty i status są z klucza celowo wyłączone: daty -bywają uzupełniane między edycjami, a status jest właśnie tym, czego zmianę mierzymy. - -Ograniczenie klucza treściowego: rozjeżdża się, gdy publikujący skoryguje którekolwiek z pól -wchodzących w jego skład, i wtedy ten sam wniosek wygląda jak zniknięcie w parze -z pojawieniem. Miara niżej pozwala ocenić, jak często to się zdarza. - -## Algorytm dopasowania, pełna specyfikacja - -Żeby wynik dało się odtworzyć i zakwestionować, podajemy reguły wprost. - -1. **Klucz** jest konkatenacją sześciu pól: publikujący, lokalizacja tekstowa, poziom napięcia, - klasa zasobu, moc wprowadzana, moc pobierana. Wartości brane są **po harmonizacji przez - adapter**, a więc po normalizacji białych znaków, jednostek i słowników kontrolowanych; - poza tym porównanie jest **dokładne, bez tolerancji**, także dla mocy. -2. **Brak wartości jest wartością.** Pole puste wchodzi do klucza jako pusty łańcuch, więc wiersz - z brakującą mocą dopasuje się tylko do wiersza, w którym ta moc też jest pusta. Uzupełnienie - mocy przez publikującego rozrywa zatem parę i daje jedno zniknięcie oraz jedno pojawienie. - To samo dotyczy zmiany poziomu napięcia albo klasy zasobu. -3. **Unikalność jest wymagana w obu edycjach.** Wiersze o powtarzającym się kluczu są odrzucane - przed dopasowaniem, zachowywany jest pierwszy, bo dla nich przypisanie jeden-do-wielu nie ma - jednoznacznego rozstrzygnięcia. Liczby są raportowane: `wierszy_w_kolizji_a` i `_b` podają, - ile wierszy stoi w grupach kolizyjnych, a `odrzuconych_jako_niejednoznaczne_a` i `_b`, ile - faktycznie wypada z dopasowania. -4. **Nowe i ubyłe** to po prostu różnice zbiorów kluczy, liczone po odrzuceniu kolizji. -5. **Daty i status są z klucza wyłączone**: daty bywają uzupełniane między edycjami, a status - jest właśnie tym, czego zmianę mierzymy. - -Na parze edycji PSE kolizje obejmują 56 wierszy w edycji lipcowej i 48 w sierpniowej, co po -odrzuceniu daje 31 i 27 wierszy wypadających z dopasowania, odpowiednio 3,5 % i 3,1 % wierszy. - -## Precyzja dopasowania zmierzona na polach wstrzymanych - -Macierz przejść jest świadectwem pośrednim, więc dokładamy świadectwo bezpośrednie. -`linkage_audit` porównuje każdą dopasowaną parę na **dziewięciu polach wyłączonych z klucza**: -nazwa podmiotu ubiegającego się, nazwa obiektu, data złożenia wniosku oraz sześć pól rozbicia -mocy na technologie. Klucz nie wymusza zgodności żadnego z nich, więc ich zgodność jest -niezależnym świadectwem, że para dotyczy tego samego wniosku. - -Para jest **fałszywa**, gdy rdzeń nazwy podmiotu ORAZ rdzeń nazwy obiektu są rozbieżne i żaden -nie zawiera się w drugim; **niepewna**, gdy rozbieżny jest dokładnie jeden z nich; **potwierdzona** -w pozostałych przypadkach. Rdzeń nazwy powstaje przez usunięcie formy prawnej, interpunkcji -i spacji, bo publikujący zmienia zapis formy prawnej między edycjami. Pole uzupełnione -jednostronnie, puste w jednej edycji, wypełnione w drugiej, nie jest liczone jako rozbieżność, -bo jest redakcją tego samego wniosku. - -Wynik na parze edycji PSE, na **wszystkich 804 parach**, nie na próbce: - -| klasa pary | liczba | udział | +# Comparison of register editions + +The statutory duty requires the disclosure to be replaced at least once per quarter, so consecutive +editions of the same register are natural material for longitudinal analysis. One thing stands in the +way of this and has to be declared rather than passed over in silence. + +## The register does not publish a persistent application identifier + +At some publishers the object identifier field is empty in almost every row, +at PSE in 866 of 876, and the package then inserts a surrogate based on the ordinal number +in the document. Such a surrogate is stable **within a single edition and worthless between +editions**: position 869 in one edition is not the same application as position 869 +in the next, because the rows shift. A join on the identifier would give a result that looks +sensible and is entirely false. + +`compare_editions` therefore uses a **content key** built from the publisher, the location, +the voltage level, the resource class and both capacities. Dates and status are deliberately excluded +from the key: dates are sometimes filled in between editions, and the status is precisely what we are +measuring the change of. + +A limitation of the content key: it diverges when the publisher corrects any of the fields +it is built from, and then the same application looks like a disappearance paired +with an appearance. The measure below makes it possible to judge how often this happens. + +## The linkage algorithm, full specification + +So that the result can be reproduced and challenged, we state the rules openly. + +1. **The key** is the concatenation of six fields: publisher, location text, voltage level, + resource class, injected capacity, consumed capacity. The values are taken **after harmonization by + the adapter**, that is after normalization of whitespace, units and controlled vocabularies; + apart from that the comparison is **exact, with no tolerance**, including for the capacities. +2. **A missing value is a value.** An empty field enters the key as an empty string, so a row + with a missing capacity will match only a row in which that capacity is also empty. Filling in + the capacity by the publisher therefore breaks the pair and gives one disappearance and one appearance. + The same applies to a change of the voltage level or the resource class. +3. **Uniqueness is required in both editions.** Rows with a repeating key are rejected + before linkage, the first being retained, because for them a one-to-many assignment has no + unambiguous settlement. The figures are reported: `wierszy_w_kolizji_a` and `_b` give + how many rows stand in colliding groups, and `odrzuconych_jako_niejednoznaczne_a` and `_b`, how many + actually drop out of the linkage. +4. **New and departed** are simply differences of the sets of keys, computed after the collisions have + been rejected. +5. **Dates and status are excluded from the key**: dates are sometimes filled in between editions, and + the status is precisely what we are measuring the change of. + +On the pair of PSE editions the collisions cover 56 rows in the July edition and 48 in the August one, +which after rejection leaves 31 and 27 rows dropping out of the linkage, respectively 3,5 % and 3,1 % of +the rows. + +## Linkage precision measured on held-out fields + +The transition matrix is indirect evidence, so we add direct evidence. +`linkage_audit` compares every linked pair on **nine fields excluded from the key**: +the name of the applying entity, the name of the object, the date the application was filed and six fields of the +capacity breakdown by technology. The key does not enforce the agreement of any of them, so their +agreement is independent evidence that the pair concerns the same application. + +A pair is **false** when the stem of the entity name AND the stem of the object name diverge and +neither is contained in the other; **uncertain** when exactly one of them diverges; **confirmed** +in the remaining cases. The stem of a name arises by removing the legal form, punctuation +and spaces, because the publisher changes the way the legal form is written between editions. A field +filled in on one side only, empty in one edition, populated in the other, is not counted as a divergence, +because it is an editing of the same application. + +The result on the pair of PSE editions, on **all 804 pairs**, not on a sample: + +| class of pair | count | share | |---|---:|---:| -| potwierdzona | 795 | 98,88 % | -| niepewna | 6 | 0,75 % | -| fałszywa | 3 | 0,37 % | +| confirmed | 795 | 98,88 % | +| uncertain | 6 | 0,75 % | +| false | 3 | 0,37 % | -Precyzja dopasowania mieści się więc w przedziale **98,88 % do 99,63 %**, zależnie od tego, czy -przypadki niepewne policzyć jako błędne, czy jako trafne. Trzy pary fałszywe to różne wnioski -dzielące lokalizację, napięcie, klasę i obie moci, na przykład dwa magazyny energii tej samej -mocy w tej samej miejscowości. Wynik przejść jest wobec nich odporny: po usunięciu dziewięciu -par wątpliwych udział przejść w przód zmienia się z 98,28 % na 98,25 %. +The linkage precision therefore falls in the range **98,88 % to 99,63 %**, depending on whether +the uncertain cases are counted as wrong or as right. The three false pairs are different applications +sharing location, voltage, class and both capacities, for example two energy storage facilities of the same +capacity in the same locality. The transition result is robust against them: after removing the nine +doubtful pairs the share of forward transitions changes from 98,28 % to 98,25 %. -Zastrzeżenie, którego nie pomijamy: nie jest to walidacja wobec prawdy zewnętrznej, bo dla tego -rejestru taka prawda nie istnieje, nie ma trwałego identyfikatora, wobec którego można by -dopasowanie sprawdzić. Jest to test spójności wewnętrznej na danych, których klucz nie dotyka. +A caveat we do not leave out: this is not validation against an external truth, because for this +register no such truth exists, there is no persistent identifier against which the +linkage could be checked. It is a test of internal consistency on data the key does not touch. -## Macierz przejść jako test dopasowania +## The transition matrix as a test of the linkage -Jeśli klucz dopasowuje właściwe wiersze, przejścia statusu powinny biec zgodnie z kierunkiem -postępowania administracyjnego. Jeśli dopasowuje losowo, będą rozłożone bez tego porządku. -Na parze edycji PSE z 31 lipca i 31 sierpnia 2026 roku **98,28 % przejść biegnie w przód** -(57 z 58), przy jednym przejściu wstecznym z umowy obowiązującej do warunków wydanych. -Jest to test niezależny od samego dopasowania i właśnie dlatego ma wartość. +If the key links the right rows, the status transitions should run in the direction of the +administrative proceeding. If it links at random, they will be distributed without that order. +On the pair of PSE editions of 31 July and 31 August 2026, **98,28 % of the transitions run forward** +(57 of 58), with one backward transition from an agreement in force to conditions issued. +This is a test independent of the linkage itself, and that is exactly why it has value. -## Rejestr nie jest monotoniczną migawką +## The register is not a monotonic snapshot -Drugi wynik tej samej pary edycji jest ostrzeżeniem dla każdego, kto chciałby czytać różnicę -między edycjami jako zmianę stanu kolejki: +The second result from the same pair of editions is a warning to anyone who might want to read the +difference between editions as a change in the state of the queue: -| wielkość | wartość | +| quantity | value | |---|---:| -| wierszy w edycji lipcowej | 892 | -| wierszy w edycji sierpniowej | 876 | -| kluczy unikalnych | 861 i 849 | -| wspólnych | 804 | -| nowych | 45 | -| ubyłych | 57 | -| zmian statusu | 58 | -| **nowych już w stanie zamkniętym** | **13** | -| **ubyłych o statusie czynnym** | **33** | - -Trzynaście wierszy pojawia się w nowszej edycji już jako wniosek wycofany, odmowa albo warunki -wygasłe, czyli rejestr **dopisuje sprawy zakończone wstecz**. Trzydzieści trzy wiersze -o statusie czynnym znikają, czego zakończeniem postępowania wyjaśnić nie można. Własność -`migawka_monotoniczna` zwraca w tej parze `False` i ma to być sygnał, nie szczegół techniczny. +| rows in the July edition | 892 | +| rows in the August edition | 876 | +| unique keys | 861 and 849 | +| common | 804 | +| new | 45 | +| departed | 57 | +| status changes | 58 | +| **new, already in a closed state** | **13** | +| **departed with an active status** | **33** | + +Thirteen rows appear in the newer edition already as a withdrawn application, a refusal or expired +conditions, which means the register **adds completed cases retrospectively**. Thirty-three rows +with an active status disappear, which cannot be explained by the proceeding having ended. The +`migawka_monotoniczna` property returns `False` on this pair and that is meant to be a signal, not a +technical detail. ```python from gridqueue import compare_editions, linkage_audit, get_adapter @@ -119,37 +123,38 @@ a = get_adapter("pl_pse").parse("edycja_2026_07_31.xlsx").frame b = get_adapter("pl_pse").parse("edycja_2026_08_31.xlsx").frame d = compare_editions(a, b, "2026-07-31", "2026-08-31") d.as_dict() -d.przejscia # macierz przejść statusu +d.przejscia # status transition matrix -linkage_audit(a, b).as_dict() # precyzja dopasowania +linkage_audit(a, b).as_dict() # linkage precision ``` -Pełny przebieg z figurą: `examples/longitudinal_use_case.py`. +A full run with a figure: `examples/longitudinal_use_case.py`. -## Uruchomienie bez instalacji +## Running without installation -Całą tę analizę odtwarza notatnik Colab na żywych danych publikującego, z asercją zgodności z liczbami opublikowanymi, patrz [Google Colab](colab.md). +This whole analysis is reproduced by the Colab notebook on the publisher's live data, with an assertion of agreement with the published figures, see [Google Colab](colab.md). -## Klucz musi być dobrany do encji +## The key has to be matched to the entity -Domyślny klucz treściowy jest zbudowany dla encji WNIOSEK. Na wierszach encji WĘZEŁ -**rozpada się**, bo pola wniosku, klasa zasobu i obie moce, są tam puste. Niedopasowanie -**nie zgłasza błędu**: po cichu produkuje kolizje, które w dalszej analizie wyglądają jak -zdarzenia w rejestrze. +The default content key is built for the WNIOSEK entity. On rows of the WĘZEŁ entity it +**falls apart**, because the application fields, the resource class and both capacities, are empty there. +A mismatch **does not report an error**: it quietly produces collisions, which in further analysis look like +events in the register. -Zmierzone na parze wydań publikującego hiszpańskiego (1 lipca i 1 sierpnia 2025, po 1 838 -wierszy każde): +Measured on a pair of issues of the Spanish publisher (1 July and 1 August 2025, 1 838 +rows each): -| klucz | kolizje | odrzucone jako niejednoznaczne | pary dopasowane | precyzja | czułość | +| key | collisions | rejected as ambiguous | linked pairs | precision | recall | |---|---:|---:|---:|---:|---:| -| `DEFAULT_KEY_FIELDS` (wniosek) | 916 | 660 | 1 178 |, |, | -| `NODE_KEY_FIELDS` (węzeł) | 0 | 0 | **1 838** | **1,000** | **1,000** | - -Dla porównania: na polskim rejestrze przesyłowym ta sama metoda daje precyzję 98,88-99,63 % -i czułość 0,9652. Różnica nie jest własnością metody, lecz **praktyki ujawniania**: publikujący -hiszpański wydaje stabilny identyfikator węzła, a polski nie publikuje trwałego identyfikatora -wniosku. Metoda mierzy więc także to, na ile rejestr nadaje się do śledzenia w czasie. +| `DEFAULT_KEY_FIELDS` (application) | 916 | 660 | 1 178 |, |, | +| `NODE_KEY_FIELDS` (node) | 0 | 0 | **1 838** | **1,000** | **1,000** | + +For comparison: on the Polish transmission register the same method gives a precision of 98,88-99,63 % +and a recall of 0,9652. The difference is not a property of the method but of the **disclosure +practice**: the Spanish publisher issues a stable node identifier, whereas the Polish one does not +publish a persistent application identifier. The method therefore also measures how far a register +lends itself to tracking over time. ```python from gridqueue import NODE_KEY_FIELDS, compare_editions, linkage_audit diff --git a/examples/longitudinal_use_case.py b/examples/longitudinal_use_case.py index d685143..6b33ca0 100644 --- a/examples/longitudinal_use_case.py +++ b/examples/longitudinal_use_case.py @@ -1,26 +1,27 @@ -"""Przykład badawczy: przepływy w kolejce przyłączeniowej między edycjami. +"""Research example: flows in the connection queue between editions. -Pytanie badawcze ----------------- -Jak zmienia się kolejka przyłączeniowa między dwiema edycjami tego samego -rejestru i czy rejestr zachowuje się jak **monotoniczna migawka**, to znaczy -czy sprawy wchodzą do niego i wychodzą zgodnie z przebiegiem postępowania, czy -też pojawiają się i znikają także poza tym porządkiem? +Research question +----------------- +How does the connection queue change between two editions of the same register, +and does the register behave like a **monotone snapshot**, that is, do cases +enter it and leave it in step with the course of the proceedings, or do they +also appear and disappear outside that order? -Dlaczego to pytanie jest warunkiem każdej analizy wzdłużnej na tym źródle: jeśli -rejestr nie jest monotoniczny, to różnica między edycjami nie jest tożsama ze -zmianą stanu kolejki i trzeba to zadeklarować zamiast milcząco założyć. +Why this question is a precondition of any longitudinal analysis on this source: +if the register is not monotone, then the difference between editions is not the +same thing as a change in the state of the queue, and that has to be declared +rather than silently assumed. -Uruchomienie:: +Running:: - python examples/longitudinal_use_case.py \\ - [etykieta_A] [etykieta_B] [katalog_wyjściowy] + python examples/longitudinal_use_case.py \\ + [label_A] [label_B] [output_directory] -Wytwarza:: +Produces:: - przeplywy_kolejki.csv podsumowanie przepływów - przejscia_statusu.csv macierz przejść statusu - przejscia_statusu.png figura macierzy przejść + przeplywy_kolejki.csv summary of the flows + przejscia_statusu.csv matrix of status transitions + przejscia_statusu.png figure of the transition matrix """ from __future__ import annotations @@ -35,23 +36,23 @@ get_adapter, linkage_audit) OPIS = { - "WNIOSEK_ZLOZONY": "wniosek złożony", - "WNIOSEK_NIEKOMPLETNY": "wniosek niekompletny", - "W_TRAKCIE_ANALIZY": "w trakcie analizy", - "WARUNKI_WYDANE": "warunki wydane", - "UMOWA_OBOWIAZUJACA": "umowa obowiązująca", - "PRZYLACZONY": "przyłączony", - "ODMOWA": "odmowa", - "WNIOSEK_WYCOFANY": "wniosek wycofany", - "WARUNKI_WYGASLE": "warunki wygasłe", + "WNIOSEK_ZLOZONY": "application lodged", + "WNIOSEK_NIEKOMPLETNY": "application incomplete", + "W_TRAKCIE_ANALIZY": "under analysis", + "WARUNKI_WYDANE": "conditions issued", + "UMOWA_OBOWIAZUJACA": "agreement in force", + "PRZYLACZONY": "connected", + "ODMOWA": "refusal", + "WNIOSEK_WYCOFANY": "application withdrawn", + "WARUNKI_WYGASLE": "conditions expired", } def wczytaj(sciezka: Path) -> pd.DataFrame: - """Wczytaj edycję, rozpoznając publikującego z dokumentu.""" + """Load an edition, recognising the publisher from the document.""" klucz = detect_publisher(str(sciezka)) if klucz is None: - raise SystemExit(f"nie rozpoznano publikującego dla {sciezka}") + raise SystemExit(f"publisher not recognised for {sciezka}") return get_adapter(klucz).parse(str(sciezka)).frame @@ -87,10 +88,10 @@ def figura(tr: pd.DataFrame, plik: Path, etykiety: tuple[str, str]) -> None: ha="right", fontsize=6.5) ax.set_yticks(range(len(idx))) ax.set_yticklabels([OPIS.get(s, s) for s in idx], fontsize=6.5) - ax.set_xlabel(f"status w edycji {etykiety[1]}", fontsize=7.5) - ax.set_ylabel(f"status w edycji {etykiety[0]}", fontsize=7.5) - ax.set_title("Przejścia statusu biegną zgodnie z porządkiem postępowania,\n" - "co niezależnie potwierdza dopasowanie klucza treściowego", + ax.set_xlabel(f"status in edition {etykiety[1]}", fontsize=7.5) + ax.set_ylabel(f"status in edition {etykiety[0]}", fontsize=7.5) + ax.set_title("Status transitions run in step with the order of the proceedings,\n" + "which independently confirms the linkage by the content key", fontsize=8, loc="left") ax.set_xticks(np.arange(-.5, len(kol), 1), minor=True) ax.set_yticks(np.arange(-.5, len(idx), 1), minor=True) @@ -131,33 +132,33 @@ def main(argv: list[str]) -> int: for k, v in podsum.items(): print(f"{k}: {v}") print() - print("Interpretacja:") + print("Interpretation:") u = d.udzial_przejsc_w_przod if u is not None: - print(f" {u * 100:.2f} % przejść biegnie zgodnie z porządkiem postępowania, " - "jest to niezależny test dopasowania klucza treściowego, bo klucz " - "dopasowujący losowo nie wytworzyłby tego porządku.") + print(f" {u * 100:.2f} % of transitions run in step with the order of the " + "proceedings; this is an independent test of the linkage by the content " + "key, because a key that linked at random would not produce that order.") if not podsum["migawka_monotoniczna"]: - print(f" Rejestr NIE jest monotoniczną migawką: {podsum['nowe_zamkniete']} " - f"wierszy pojawia się już w stanie zamkniętym, a {podsum['ubyle_czynne']} " - "wierszy o statusie czynnym znika. Różnicy między edycjami nie wolno " - "czytać jako samej zmiany stanu kolejki.") + print(f" The register is NOT a monotone snapshot: {podsum['nowe_zamkniete']} " + f"rows appear already in a closed state, and {podsum['ubyle_czynne']} " + "rows with an active status disappear. The difference between editions " + "must not be read as a change in the state of the queue alone.") pa = audyt.precyzja_dolna * 100 pg = audyt.precyzja_gorna * 100 - print(f" Precyzja dopasowania oceniona na polach WYŁĄCZONYCH z klucza " - f"(nazwa podmiotu, nazwa obiektu, data wniosku, rozbicie mocy na technologie) " - f"wynosi {pa:.2f}-{pg:.2f} % na wszystkich {audyt.par} parach: " - f"{audyt.potwierdzonych} potwierdzonych, {audyt.niepewnych} niepewnych, " - f"{audyt.falszywych} fałszywych. Nie jest to walidacja wobec prawdy zewnętrznej, " - f"bo takiej dla tego rejestru nie ma, klucz nie wymusza zgodności tych pól, " - f"więc ich zgodność jest niezależnym świadectwem.") - print(f" Wierszy odrzuconych z dopasowania jako niejednoznaczne: " - f"{podsum['odrzuconych_jako_niejednoznaczne_a']} i " + print(f" Linkage precision assessed on the fields EXCLUDED from the key " + f"(entity name, object name, application date, breakdown of capacity by technology) " + f"is {pa:.2f}-{pg:.2f} % over all {audyt.par} pairs: " + f"{audyt.potwierdzonych} confirmed, {audyt.niepewnych} uncertain, " + f"{audyt.falszywych} false. This is not validation against an external truth, " + f"because there is none for this register; the key does not force these fields " + f"to agree, so their agreement is independent evidence.") + print(f" Rows dropped from the linkage as ambiguous: " + f"{podsum['odrzuconych_jako_niejednoznaczne_a']} and " f"{podsum['odrzuconych_jako_niejednoznaczne_b']}; " - f"w kolizji klucza stoi odpowiednio {podsum['wierszy_w_kolizji_a']} i " - f"{podsum['wierszy_w_kolizji_b']} wierszy.") + f"in key collision there stand {podsum['wierszy_w_kolizji_a']} and " + f"{podsum['wierszy_w_kolizji_b']} rows respectively.") - print(f"\nzapisano do: {out}") + print(f"\nsaved to: {out}") return 0 diff --git a/examples/research_use_case.py b/examples/research_use_case.py index 49b3656..285e605 100644 --- a/examples/research_use_case.py +++ b/examples/research_use_case.py @@ -1,34 +1,34 @@ -"""Przykład badawczy: czas rozpatrywania wniosku przyłączeniowego. +"""Research example: processing time of a connection application. -Pytanie badawcze ----------------- -Czy czas od złożenia wniosku o przyłączenie do wydania warunków różni się między -klasami zasobu i między publikującymi? +Research question +----------------- +Does the time from lodging a connection application to the issue of connection +conditions differ between resource classes and between publishers? -Sens tego przykładu dla oceny narzędzia ---------------------------------------- -Adaptery są specyficzne dla źródła, ale **analiza badawcza już nie**. Poniższy -kod nie zawiera ani jednej gałęzi zależnej od publikującego: operuje wyłącznie -na polach wspólnego schematu (`data_wniosku`, `data_warunkow`, `klasa_zasobu`, -`publikujacy`) i wykonuje się identycznie na wyjściu każdego adaptera. Dokładnie -to jest produktem harmonizacji, nie sam fakt, że dokument dał się rozłożyć na -wiersze. +What this example shows about the tool +-------------------------------------- +Adapters are source specific, but **the research analysis is not**. The code +below contains not a single branch that depends on the publisher: it works only +on the fields of the common schema (`data_wniosku`, `data_warunkow`, +`klasa_zasobu`, `publikujacy`) and runs identically on the output of every +adapter. That, and not the mere fact that a document could be broken down into +rows, is what harmonisation produces. -Dane wejściowe --------------- -Panel wyprodukowany przez `gridqueue` (Parquet albo CSV), domyślnie -``gridqueue_panel.parquet`` w katalogu bieżącym. Panel buduje się poleceniem:: +Input data +---------- +A panel produced by `gridqueue` (Parquet or CSV), by default +``gridqueue_panel.parquet`` in the current directory. The panel is built with:: - gridqueue parse --out gridqueue_panel.parquet + gridqueue parse --out gridqueue_panel.parquet -Uruchomienie:: +Running:: - python examples/research_use_case.py [ścieżka_do_panelu] [katalog_wyjściowy] + python examples/research_use_case.py [path_to_panel] [output_directory] -Wytwarza:: +Produces:: - czas_rozpatrywania.csv tabela wynikowa (jeden wiersz na publikującego i klasę) - czas_rozpatrywania.png figura + czas_rozpatrywania.csv the result table (one row per publisher and class) + czas_rozpatrywania.png the figure """ from __future__ import annotations @@ -40,20 +40,20 @@ from gridqueue import SCHEMA_VERSION, __version__, core_complete_mask -#: Minimalna liczebność grupy, poniżej której mediany nie raportujemy. +#: Minimum group size below which we do not report medians. MIN_N = 30 -#: Czytelne nazwy klas zasobu ze słownika kontrolowanego schematu. +#: Readable names of the resource classes from the controlled vocabulary of the schema. NAZWY_KLAS = { - "ODB": "odbiór", - "PV": "fotowoltaika", - "FW": "wiatr", - "BESS": "magazyn energii", - "GAZ": "gaz", - "EW": "woda", - "MIX": "instalacja mieszana", - "SIEC": "sieć", - "BIOGAZ": "biogaz", + "ODB": "demand", + "PV": "photovoltaics", + "FW": "wind", + "BESS": "energy storage", + "GAZ": "gas", + "EW": "hydro", + "MIX": "mixed installation", + "SIEC": "network", + "BIOGAZ": "biogas", } @@ -64,7 +64,7 @@ def wczytaj_panel(sciezka: Path) -> pd.DataFrame: def czas_rozpatrywania(panel: pd.DataFrame) -> pd.DataFrame: - """Czas od złożenia wniosku do wydania warunków, w dniach.""" + """Time from lodging the application to the issue of conditions, in days.""" df = panel.copy() for kol in ("data_wniosku", "data_warunkow"): df[kol] = pd.to_datetime(df[kol], errors="coerce") @@ -73,11 +73,11 @@ def czas_rozpatrywania(panel: pd.DataFrame) -> pd.DataFrame: def zestawienie(df: pd.DataFrame) -> tuple[pd.DataFrame, dict]: - """Mediany i rozstępy ćwiartkowe per publikujący i klasa zasobu. + """Medians and interquartile ranges per publisher and resource class. - Wiersze z ujemną różnicą dat są odrzucane i zliczane osobno: niespójność - kolejności dat wykrywa reguła R1 kontroli jakości i nie powinna wchodzić do - statystyki opisowej jako wartość ujemna. + Rows with a negative date difference are dropped and counted separately: an + inconsistency in the order of dates is detected by quality rule R1 and should + not enter the descriptive statistics as a negative value. """ policzalne = df["czas_dni"].notna() ujemne = policzalne & (df["czas_dni"] < 0) @@ -113,9 +113,10 @@ def rysunek(tab: pd.DataFrame, plik: Path) -> None: matplotlib.use("Agg") import matplotlib.pyplot as plt - # Barwa przypisana NAZWIE publikującego, nie pozycji w posortowanej liście: - # inaczej dodanie publikującego przemalowałoby pozostałych, a figura rozeszłaby - # się z pozostałymi figurami projektu. Regresja z wydania 1.1.0, przywrócona tu. + # The colour is bound to the NAME of the publisher, not to the position in the + # sorted list: otherwise adding a publisher would repaint the others and the + # figure would drift away from the other figures of the project. A regression + # from release 1.1.0, restored here. BARWY = { "TAURON Dystrybucja S.A.": "#1b5e8c", "ENERGA-OPERATOR S.A.": "#2e8b78", @@ -138,9 +139,9 @@ def rysunek(tab: pd.DataFrame, plik: Path) -> None: for _, r in tab.iterrows()], fontsize=7) ax.invert_yaxis() ax.set_xlim(0, tab["kwartyl_3"].max() * 1.30) - ax.set_xlabel("dni: wniosek → warunki\n" - "kropka = mediana, pasmo = rozstęp ćwiartkowy", fontsize=8) - ax.set_title("Przyłączenia odbiorcze rozpatrywane są szybciej niż wytwórcze", + ax.set_xlabel("days: application → conditions\n" + "dot = median, band = interquartile range", fontsize=8) + ax.set_title("Demand connections are processed faster than generation ones", fontsize=9, loc="left") for s in ("top", "right"): ax.spines[s].set_visible(False) @@ -152,8 +153,8 @@ def main(argv: list[str]) -> int: panel_path = Path(argv[1]) if len(argv) > 1 else Path("gridqueue_panel.parquet") outdir = Path(argv[2]) if len(argv) > 2 else Path(".") if not panel_path.exists(): - print(f"Brak panelu: {panel_path}\n" - f"Zbuduj go: gridqueue parse --out {panel_path}", + print(f"No panel: {panel_path}\n" + f"Build it with: gridqueue parse --out {panel_path}", file=sys.stderr) return 2 outdir.mkdir(parents=True, exist_ok=True) @@ -170,7 +171,7 @@ def main(argv: list[str]) -> int: print() kolumny = ["publikujacy", "klasa_opis", "n", "mediana", "kwartyl_1", "kwartyl_3"] print(tab[kolumny].to_string(index=False)) - print(f"\nzapisano: {csv_path} oraz {outdir / 'czas_rozpatrywania.png'}") + print(f"\nsaved: {csv_path} and {outdir / 'czas_rozpatrywania.png'}") return 0 diff --git a/notebooks/gridqueue_colab.ipynb b/notebooks/gridqueue_colab.ipynb index 77828fd..0273c67 100644 --- a/notebooks/gridqueue_colab.ipynb +++ b/notebooks/gridqueue_colab.ipynb @@ -4,39 +4,41 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# gridqueue w Google Colab\n", + "# gridqueue in Google Colab\n", "\n", - "[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)]", - "(https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb)\n", + "[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb)\n", "\n", - "Ten notatnik uruchamia **pełny przebieg badawczy bez instalowania czegokolwiek lokalnie**: pobiera\n", - "dwie edycje ustawowego ujawnienia przyłączeniowego wprost od publikującego, przekształca je w wiersze\n", - "wspólnego schematu, ocenia jakość ujawnienia i odtwarza analizę wzdłużną opisaną w artykule.\n", + "This notebook runs the **full research workflow with nothing installed locally**: it downloads\n", + "two editions of the statutory connection disclosure straight from the publisher, turns them into rows\n", + "of the common schema, assesses the quality of the disclosure and reproduces the longitudinal analysis\n", + "described in the article.\n", "\n", - "**Co zobaczysz po uruchomieniu wszystkich komórek**\n", + "**What you will see after running all the cells**\n", "\n", - "1. dwa dokumenty urzędowe pobrane z adresów publikującego, z sumami kontrolnymi;\n", - "2. wiersze w 21-polowym schemacie wyprowadzonym ze struktury obowiązku prawnego;\n", - "3. raport ośmiu reguł kontroli jakości;\n", - "4. przepływy w kolejce między edycjami wraz z **precyzją dopasowania** zmierzoną na polach\n", - " wyłączonych z klucza;\n", - "5. porównanie odtworzonych liczb z wartościami opublikowanymi w artykule — komórka **przerywa\n", - " wykonanie**, jeśli się rozjadą.\n", + "1. two official documents downloaded from the publisher's addresses, with checksums;\n", + "2. rows in the 21-field schema derived from the structure of the legal duty;\n", + "3. a report of the eight quality control rules;\n", + "4. flows in the queue between editions together with the **linkage precision** measured on the\n", + " fields excluded from the key;\n", + "5. a comparison of the reproduced numbers with the values published in the article: the cell\n", + " **stops execution** if they diverge.\n", "\n", - "Czas pełnego przebiegu na darmowej maszynie Colab: poniżej minuty. Akcelerator nie jest potrzebny.\n", + "Time for a full run on a free Colab machine: under a minute. No accelerator is needed.\n", "\n", - "**Czego ten notatnik nie robi.** Nie odtwarza dokładności wydobycia wobec zbioru odniesienia, bo ten\n", - "wymaga odczytu przez człowieka, ani nie rozstrzyga współrzędnych, bo gazeter geometryczny jest\n", - "osobnym pobraniem na licencji ODbL. Jedno i drugie opisuje dokumentacja." + "**What this notebook does not do.** It does not reproduce the extraction accuracy against the\n", + "reference set, because that one requires a human reading, nor does it resolve coordinates, because the\n", + "geometric gazetteer is a separate download under the ODbL licence. Both are described in the\n", + "documentation." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 1. Instalacja\n", + "## 1. Installation\n", "\n", - "Jedno polecenie, z **oznaczonego wydania**, żeby wynik nie zależał od stanu gałęzi głównej." + "A single command, from a **tagged release**, so that the result does not depend on the state of the\n", + "main branch." ] }, { @@ -48,21 +50,21 @@ "%pip install -q git+https://github.com/s-matysik/gridqueue@v1.2.1\n", "\n", "import gridqueue as gq\n", - "print('gridqueue', gq.__version__, '| wersja schematu', gq.SCHEMA_VERSION)" + "print('gridqueue', gq.__version__, '| schema version', gq.SCHEMA_VERSION)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 2. Pobranie ujawnienia wprost od publikującego\n", + "## 2. Downloading the disclosure straight from the publisher\n", "\n", - "Pobieramy dwie kolejne edycje wykazu operatora przesyłowego, wydawane na podstawie art. 7 ust. 8l\n", - "ustawy Prawo energetyczne. Obowiązek wyznacza **minimalną** częstość kwartalną, a ten publikujący\n", - "wydaje ponadto migawki miesięczne — z nich korzystamy.\n", + "We download two consecutive editions of the list kept by the transmission system operator, issued\n", + "under art. 7(8l) of the Energy Law. The duty sets a **minimum** quarterly frequency, and this\n", + "publisher additionally issues monthly snapshots; those are the ones we use.\n", "\n", - "Jeśli któryś adres zwróci 404, to znaczy, że publikujący wymienił plik: edycje przesuwają się\n", - "w czasie i starsze bywają usuwane. Komórka wypisze wtedy, co zrobić." + "If one of the addresses returns 404, it means the publisher has replaced the file: editions move in\n", + "time and older ones are sometimes removed. The cell will then print what to do." ] }, { @@ -78,8 +80,8 @@ "EDYCJE = {'2026-07-31': '31_07_2026', '2026-08-31': '31_08_2026'}\n", "\n", "NAGL = {'User-Agent': 'gridqueue-colab/1.2 (statutory grid connection disclosure)'}\n", - "RADA = (\" Pobierz bieżący wykaz ze strony https://www.pse.pl, wgraj go przez panel plików\\n\"\n", - " \" Colab i wpisz jego nazwę do słownika `pliki` poniżej, na przykład:\\n\"\n", + "RADA = (\" Download the current list from https://www.pse.pl, upload it through the Colab\\n\"\n", + " \" file panel and enter its name in the `pliki` dictionary below, for example:\\n\"\n", " \" pliki['2026-08-31'] = pathlib.Path('moj_wykaz.xlsx')\")\n", "\n", "pliki = {}\n", @@ -88,19 +90,19 @@ " try:\n", " r = requests.get(url, headers=NAGL, timeout=180)\n", " except requests.exceptions.SSLError:\n", - " # Typowe w sieciach firmowych i instytucjonalnych z serwerem pośredniczącym,\n", - " # który podmienia łańcuch certyfikatów. W Colab nie występuje.\n", - " print(f'{etykieta}: weryfikacja certyfikatu nie powiodła się — najpewniej sieć\\n'\n", - " f' z serwerem pośredniczącym. Nie obchodzimy tej kontroli.')\n", + " # Typical in corporate and institutional networks with a proxy server that\n", + " # substitutes the certificate chain. Does not occur in Colab.\n", + " print(f'{etykieta}: certificate verification failed; most likely a network\\n'\n", + " f' with a proxy server. We do not work around this check.')\n", " print(RADA)\n", " continue\n", " except requests.exceptions.RequestException as e:\n", - " print(f'{etykieta}: połączenie nieudane ({type(e).__name__}).')\n", + " print(f'{etykieta}: connection failed ({type(e).__name__}).')\n", " print(RADA)\n", " continue\n", " if r.status_code != 200 or len(r.content) < 10_000:\n", - " # Edycje przesuwają się w czasie; starsze bywają usuwane po wymianie.\n", - " print(f'{etykieta}: HTTP {r.status_code} — publikujący wymienił plik.')\n", + " # Editions move in time; older ones are sometimes removed after a replacement.\n", + " print(f'{etykieta}: HTTP {r.status_code}; the publisher has replaced the file.')\n", " print(RADA)\n", " continue\n", " sciezka = pathlib.Path(f'pse_{znacznik}.xlsx')\n", @@ -109,20 +111,20 @@ " print(f'{etykieta}: {len(r.content):,} B | sha256 {hashlib.sha256(r.content).hexdigest()[:16]}…')\n", "\n", "if len(pliki) < 2:\n", - " print('\\nBrakuje edycji. Uzupełnij słownik `pliki` wgranymi dokumentami,')\n", - " print('a następnie uruchom kolejne komórki — reszta notatnika ich nie pobiera.')\n", + " print('\\nAn edition is missing. Complete the `pliki` dictionary with uploaded documents,')\n", + " print('then run the following cells; the rest of the notebook does not download them.')\n", "else:\n", - " print('\\nObie edycje pobrane.')" + " print('\\nBoth editions downloaded.')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 3. Rozpoznanie publikującego i wydobycie wierszy\n", + "## 3. Recognising the publisher and extracting the rows\n", "\n", - "Publikujący jest **rozpoznawany z zawartości dokumentu**, nie podawany ręcznie. Wydobycie opiera się\n", - "na położeniu słów i geometrii kolumn, a nie na dopasowaniu wzorców tekstowych." + "The publisher is **recognised from the content of the document**, not supplied by hand. The\n", + "extraction rests on the position of words and on column geometry, not on matching text patterns." ] }, { @@ -138,7 +140,7 @@ " klucz = detect_publisher(str(sciezka))\n", " wynik = get_adapter(klucz).parse(str(sciezka))\n", " ramki[etykieta] = wynik.frame\n", - " print(f'{etykieta}: rozpoznano {klucz} | {len(wynik.frame)} wierszy, {wynik.frame.shape[1]} kolumn')\n", + " print(f'{etykieta}: recognised {klucz} | {len(wynik.frame)} rows, {wynik.frame.shape[1]} columns')\n", "\n", "ramki['2026-08-31'].head(3).T" ] @@ -147,11 +149,11 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 4. Co zawiera schemat\n", + "## 4. What the schema contains\n", "\n", - "Dwadzieścia jeden pól odwzorowuje **strukturę obowiązku prawnego**, nie układ dokumentu: każde pole\n", - "niesie odsyłacz do punktu przepisu, który je uzasadnia. Kolumny zaczynające się od podkreślenia to\n", - "rozszerzenia zadeklarowane przez publikującego, poza schematem wspólnym." + "The twenty-one fields map the **structure of the legal duty**, not the layout of the document: every\n", + "field carries a reference to the point of the provision that justifies it. Columns beginning with an\n", + "underscore are extensions declared by the publisher, outside the common schema." ] }, { @@ -164,20 +166,20 @@ "\n", "df = ramki['2026-08-31']\n", "pokrycie = (df[list(FIELDS)].notna().mean() * 100).round(2).sort_values(ascending=False)\n", - "print(f'schemat {SCHEMA_VERSION}: {len(FIELDS)} pól, wypełnionych {(pokrycie > 0).sum()}')\n", - "print(f'kolumn rozszerzeń: {sum(1 for c in df.columns if c.startswith(\"_\"))}')\n", - "pokrycie[pokrycie > 0].to_frame('pokrycie [%]')" + "print(f'schema {SCHEMA_VERSION}: {len(FIELDS)} fields, filled in {(pokrycie > 0).sum()}')\n", + "print(f'extension columns: {sum(1 for c in df.columns if c.startswith(\"_\"))}')\n", + "pokrycie[pokrycie > 0].to_frame('coverage [%]')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 5. Reguły kontroli jakości\n", + "## 5. Quality control rules\n", "\n", - "Osiem reguł wyprowadzonych z przepisu, nie z oczekiwań analityka. Każda zwraca **liczbę naruszeń,\n", - "nie wyjątek**, bo naruszenie jest właściwością ujawnienia, a nie błędem wykonania — narzędzie mierzy\n", - "jakość źródła, zamiast ją ukrywać." + "Eight rules derived from the provision, not from the expectations of an analyst. Each returns **the\n", + "number of violations, not an exception**, because a violation is a property of the disclosure and not\n", + "an execution error: the tool measures the quality of the source instead of hiding it." ] }, { @@ -189,7 +191,7 @@ "from gridqueue import run_quality\n", "\n", "raport = run_quality(df)\n", - "print('naruszeń łącznie:', raport.as_dict()['naruszen_lacznie'], 'na', len(df), 'wierszy')\n", + "print('violations in total:', raport.as_dict()['naruszen_lacznie'], 'on', len(df), 'rows')\n", "raport.as_frame()" ] }, @@ -197,12 +199,12 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 6. Analiza wzdłużna — przepływy w kolejce\n", + "## 6. Longitudinal analysis: flows in the queue\n", "\n", - "To jest część, dla której potrzebne były dwie edycje. Jedna rzecz stoi na drodze i jest ustaleniem\n", - "samym w sobie: **rejestr nie publikuje trwałego identyfikatora wniosku**, a zastępnik oparty na\n", - "liczbie porządkowej jest bezwartościowy między edycjami, bo wiersze się przesuwają. Dopasowanie idzie\n", - "więc po **kluczu treściowym**, z którego celowo wyłączono daty i status." + "This is the part the two editions were needed for. One thing stands in the way and is a finding in\n", + "itself: **the register publishes no stable application identifier**, and a surrogate based on the\n", + "ordinal number is worthless between editions, because the rows shift. The linkage therefore goes by a\n", + "**content key**, from which dates and status have been deliberately excluded." ] }, { @@ -226,27 +228,27 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Dlaczego macierz przejść jest testem, a nie tylko wynikiem\n", + "### Why the transition matrix is a test and not just a result\n", "\n", - "Jeśli klucz treściowy dopasowuje właściwe wiersze, przejścia powinny biec zgodnie z kierunkiem\n", - "postępowania administracyjnego. Klucz dopasowujący losowo nie wytworzyłby tego porządku, więc wysoki\n", - "udział przejść w przód jest **niezależnym świadectwem poprawności dopasowania**.\n", + "If the content key links the right rows, the transitions should run in the direction of the\n", + "administrative proceedings. A key that linked at random would not produce that order, so a high share\n", + "of forward transitions is **independent evidence that the linkage is correct**.\n", "\n", - "Drugi wynik jest ostrzeżeniem dla każdego, kto chciałby czytać różnicę między edycjami jako zmianę\n", - "stanu kolejki: część wierszy pojawia się już w stanie zamkniętym, a część wierszy o statusie czynnym\n", - "znika. Rejestr **nie jest monotoniczną migawką** i narzędzie zgłasza to flagą." + "The second result is a warning for anyone who would read the difference between editions as a change\n", + "in the state of the queue: some rows appear already in a closed state, and some rows with an active\n", + "status disappear. The register **is not a monotone snapshot** and the tool reports this with a flag." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 7. Precyzja dopasowania\n", + "## 7. Linkage precision\n", "\n", - "Świadectwo pośrednie domykamy bezpośrednim. Audyt porównuje każdą dopasowaną parę na **dziewięciu\n", - "polach wyłączonych z klucza** — nazwa podmiotu, nazwa obiektu, data złożenia wniosku i sześć pól\n", - "rozbicia mocy na technologie. Klucz nie wymusza zgodności żadnego z nich, więc ich zgodność jest\n", - "świadectwem niezależnym." + "We close the indirect evidence with direct evidence. The audit compares every linked pair on **nine\n", + "fields excluded from the key**: entity name, object name, date the application was lodged and six\n", + "fields of the breakdown of capacity by technology. The key forces none of them to agree, so their\n", + "agreement is independent evidence." ] }, { @@ -259,22 +261,23 @@ "\n", "audyt = linkage_audit(ramki['2026-07-31'], ramki['2026-08-31'])\n", "a = audyt.as_dict()\n", - "print(f\"par: {a['par']} | potwierdzonych {a['potwierdzonych']}, \"\n", - " f\"niepewnych {a['niepewnych']}, fałszywych {a['falszywych']}\")\n", - "print(f\"precyzja: {a['precyzja_dolna']*100:.2f}–{a['precyzja_gorna']*100:.2f} %\")\n", - "print('\\nrozkład rozbieżności na polach wstrzymanych:')\n", - "audyt.rozbieznosci['kategoria'].value_counts().to_frame('liczba')" + "print(f\"pairs: {a['par']} | confirmed {a['potwierdzonych']}, \"\n", + " f\"uncertain {a['niepewnych']}, false {a['falszywych']}\")\n", + "print(f\"precision: from {a['precyzja_dolna']*100:.2f} to {a['precyzja_gorna']*100:.2f} %\")\n", + "print('\\ndistribution of divergences on the held-out fields:')\n", + "audyt.rozbieznosci['kategoria'].value_counts().to_frame('count')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 8. Zgodność z liczbami opublikowanymi w artykule\n", + "## 8. Agreement with the numbers published in the article\n", "\n", - "Ta komórka jest odpowiednikiem asercji z katalogu `reproducibility/`: **przerywa wykonanie**, jeśli\n", - "odtworzone liczby rozejdą się z opublikowanymi. Rozjazd nie musi oznaczać błędu — publikujący mógł\n", - "wymienić edycję — ale musi być widoczny, a nie przemilczany." + "This cell is the counterpart of the assertion in the `reproducibility/` directory: it **stops\n", + "execution** if the reproduced numbers diverge from the published ones. A divergence need not mean an\n", + "error, the publisher may have replaced the edition, but it has to be visible rather than passed over\n", + "in silence." ] }, { @@ -295,26 +298,27 @@ "\n", "if rozjazd:\n", " for k, (opub, otrzym) in rozjazd.items():\n", - " print(f'ROZJAZD {k}: w artykule {opub}, odtworzono {otrzym}')\n", - " raise AssertionError('odtworzone liczby nie odpowiadają opublikowanym — patrz wyżej')\n", - "print('Wszystkie liczby zgodne z artykułem.')\n", - "print(f\"udział przejść w przód: {d['udzial_przejsc_w_przod']*100:.2f} %\")\n", - "print(f\"precyzja dopasowania: {a['precyzja_dolna']*100:.2f}–{a['precyzja_gorna']*100:.2f} %\")" + " print(f'DIVERGENCE {k}: in the article {opub}, reproduced {otrzym}')\n", + " raise AssertionError('the reproduced numbers do not match the published ones; see above')\n", + "print('All numbers agree with the article.')\n", + "print(f\"share of forward transitions: {d['udzial_przejsc_w_przod']*100:.2f} %\")\n", + "print(f\"linkage precision: from {a['precyzja_dolna']*100:.2f} to {a['precyzja_gorna']*100:.2f} %\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 9. Analiza przekrojowa — dlaczego nie na tym publikującym\n", + "## 9. Cross-sectional analysis: why not on this publisher\n", "\n", - "Przykład przekrojowy z artykułu mierzy czas od złożenia wniosku do wydania warunków. Kryterium\n", - "włączenia postawiono **przed** policzeniem wyniku: pokrycie obu dat powyżej 80 % i co najmniej\n", - "30 obserwacji w grupie. Ten publikujący kryterium **nie spełnia** — komórka niżej pokazuje dlaczego,\n", - "i jest to uczciwsze niż policzenie mediany na kilkunastu procentach rekordów.\n", + "The cross-sectional example in the article measures the time from lodging the application to the issue\n", + "of conditions. The inclusion criterion was set **before** the result was computed: coverage of both\n", + "dates above 80 % and at least 30 observations in a group. This publisher does **not** meet the\n", + "criterion; the cell below shows why, and that is more honest than computing a median on a dozen or so\n", + "per cent of the records.\n", "\n", - "Żeby uruchomić analizę przekrojową, wgraj dokument publikującego, który kryterium spełnia, przez\n", - "panel plików Colab i podaj jego ścieżkę w komórce." + "To run the cross-sectional analysis, upload a document of a publisher that does meet the criterion\n", + "through the Colab file panel and give its path in the cell." ] }, { @@ -326,22 +330,23 @@ "for etykieta, r in ramki.items():\n", " pokr = {p: round(float(r[p].notna().mean()) * 100, 2) for p in ('data_wniosku', 'data_warunkow')}\n", " kwalifikuje = all(v > 80 for v in pokr.values())\n", - " stan = 'spełnione' if kwalifikuje else 'NIESPEŁNIONE'\n", + " stan = 'met' if kwalifikuje else 'NOT MET'\n", " print(f\"{etykieta}: data_wniosku {pokr['data_wniosku']} %, \"\n", - " f\"data_warunkow {pokr['data_warunkow']} % -> kryterium 80 %: {stan}\")\n", + " f\"data_warunkow {pokr['data_warunkow']} % -> 80 % criterion: {stan}\")\n", "\n", - "# Po wgraniu kwalifikującego dokumentu:\n", + "# After uploading a qualifying document:\n", "# df2 = get_adapter(detect_publisher('moj_plik.pdf')).parse('moj_plik.pdf').frame\n", - "# a następnie uruchom examples/research_use_case.py na wyeksportowanym panelu." + "# and then run examples/research_use_case.py on the exported panel." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 10. Eksport\n", + "## 10. Export\n", "\n", - "Panel zapisujemy w formacie kolumnowym i jako CSV. W Colab oba pliki są do pobrania z panelu plików." + "We save the panel in a columnar format and as CSV. In Colab both files can be downloaded from the\n", + "file panel." ] }, { @@ -354,7 +359,7 @@ "df.to_csv('panel_pse_2026-08-31.csv', index=False)\n", "delta.przejscia.to_csv('przejscia_statusu.csv')\n", "audyt.rozbieznosci.to_csv('audyt_dopasowania.csv', index=False)\n", - "print('zapisano: panel (parquet, csv), macierz przejść, rozbieżności audytu')" + "print('saved: panel (parquet, csv), transition matrix, audit divergences')" ] }, { @@ -363,11 +368,12 @@ "source": [ "---\n", "\n", - "**Licencje.** Kod pakietu: Apache-2.0. Dokumenty źródłowe są publikacjami urzędowymi i nie są przez\n", - "pakiet redystrybuowane — notatnik pobiera je wprost od publikującego. Gazeter geometryczny, gdyby go\n", - "użyć, podlega ODbL z obowiązkiem atrybucji i dziedziczenia. Szczegóły w `DATA_LICENSE.md`.\n", + "**Licences.** Package code: Apache-2.0. The source documents are official publications and are not\n", + "redistributed by the package: the notebook downloads them straight from the publisher. The geometric\n", + "gazetteer, should it be used, is subject to the ODbL with its attribution and share-alike duties.\n", + "Details in `DATA_LICENSE.md`.\n", "\n", - "**Dokumentacja:** https://s-matysik.github.io/gridqueue/ · **Repozytorium:** https://github.com/s-matysik/gridqueue" + "**Documentation:** https://s-matysik.github.io/gridqueue/ · **Repository:** https://github.com/s-matysik/gridqueue" ] } ], @@ -386,4 +392,4 @@ }, "nbformat": 4, "nbformat_minor": 0 -} \ No newline at end of file +} diff --git a/reproducibility/README.md b/reproducibility/README.md index bafaab8..a092967 100644 --- a/reproducibility/README.md +++ b/reproducibility/README.md @@ -1,53 +1,53 @@ -# Pakiet odtwarzalności +# Reproducibility package -Co tu jest i czego to dowodzi. +What is here and what it proves. -| plik | zawartość | +| file | content | |---|---| -| `manifest.csv` | jeden wiersz na dokument źródłowy: publikujący, jurysdykcja, adapter, adres, data pobrania, rozmiar, SHA-256 | -| `checksums.txt` | te same sumy w formacie `sha256sum -c` | -| `requirements-lock.txt` | wersje bibliotek odczytane ze środowiska, w którym policzono opublikowane liczby | -| `environment.yml` | środowisko do odtworzenia od zera | -| `run_validation.py` | odtwarza liczby pochodne z panelu: pokrycie pól, osiem reguł jakości, kompletność rdzenia | -| `run_figures.py` | odtwarza trzy figury wyliczane z panelu | +| `manifest.csv` | one row per source document: publisher, jurisdiction, adapter, address, download date, size, SHA-256 | +| `checksums.txt` | the same checksums in `sha256sum -c` format | +| `requirements-lock.txt` | library versions read from the environment in which the published numbers were computed | +| `environment.yml` | an environment for reproducing the work from scratch | +| `run_validation.py` | reproduces the derived numbers from the panel: field coverage, the eight quality rules, core completeness | +| `run_figures.py` | reproduces the three figures that are computed from the panel | -## Dokumenty źródłowe nie są tu redystrybuowane +## The source documents are not redistributed here -Dwa powody, oba rzeczowe. Część dokumentów jest objęta prawami publikujących, a wszystkie są -**wymieniane co najmniej raz na kwartał** na mocy art. 7 ust. 8l Prawa energetycznego, kopia -w repozytorium zestarzałaby się w ciągu trzech miesięcy i zaczęłaby fałszywie sugerować, że -opisuje stan bieżący. +Two reasons, both substantive. Some of the documents are covered by the rights of their publishers, +and all of them are **replaced at least once per quarter** under art. 7(8l) of the Energy Law; a copy +in the repository would go stale within three months and would start to suggest, falsely, that it +describes the current state. -Zamiast kopii jest manifest. Dla każdego dokumentu podaje adres, datę pobrania i SHA-256, więc -osoba odtwarzająca pracę może: +Instead of a copy there is a manifest. For every document it gives the address, the download date and +the SHA-256, so a person reproducing the work can: -1. pobrać plik z podanego adresu i sprawdzić sumę, zgodność oznacza identyczne wejście; -2. stwierdzić niezgodność sumy, co oznacza, że publikujący wydał **inną edycję rejestru**, i wtedy - należy oczekiwać innych liczb wierszy. To nie jest awaria odtwarzania, lecz właściwość - kwartalnego obowiązku. +1. download the file from the given address and check the checksum; a match means identical input; +2. find that the checksum does not match, which means that the publisher has issued **a different + edition of the register**, and that different row counts are then to be expected. This is not a + failure of reproduction but a property of the quarterly duty. ```bash -cd && sha256sum -c /ścieżka/do/checksums.txt +cd && sha256sum -c /path/to/checksums.txt ``` -## Odtworzenie +## Reproduction ```bash pip install git+https://github.com/s-matysik/gridqueue@v1.0.0 -gridqueue parse --out panel.parquet +gridqueue parse --out panel.parquet python reproducibility/run_validation.py panel.parquet python reproducibility/run_figures.py panel.parquet python examples/research_use_case.py panel.parquet ``` -`run_validation.py` kończy się kodem niezerowym, jeśli suma naruszeń po publikujących nie domyka -się do liczby panelowej, ta asercja wyłapała realną pomyłkę w wersji 0.3.x, gdzie tabela -w dokumentacji podwajała wynik. +`run_validation.py` exits with a non-zero code if the sum of violations across publishers does not +close to the panel figure; that assertion caught a real mistake in version 0.3.x, where the table in +the documentation doubled the result. -## Czego te skrypty nie odtwarzają +## What these scripts do not reproduce -**Dokładności wobec zbioru odniesienia.** Wzorzec powstał przez wzrokowy odczyt renderowanych -wycinków stron przez człowieka, niezależnie od wyjścia parsera. Jest opublikowany jako artefakt -pomiarowy i nie da się go wyliczyć kodem, gdyby się dało, nie byłby niezależny. +**Accuracy against the reference set.** The reference set was produced by a human reading rendered +page extracts visually, independently of the parser output. It is published as a measurement artefact +and cannot be computed by code; if it could, it would not be independent. -**Figury architektury.** Jest schematem rysowanym ręcznie i nie ma danych wejściowych. +**The architecture figure.** It is a hand-drawn diagram and has no input data. diff --git a/reproducibility/fetch_sources.py b/reproducibility/fetch_sources.py index ce68d6a..81f1aa1 100644 --- a/reproducibility/fetch_sources.py +++ b/reproducibility/fetch_sources.py @@ -1,24 +1,24 @@ #!/usr/bin/env python3 -"""Pobiera dokumenty źródłowe z adresów podanych w manifeście i sprawdza sumy. +"""Downloads the source documents from the addresses in the manifest and checks the checksums. -Dlaczego pobieranie zamiast dołączenia plików +Why downloading instead of shipping the files --------------------------------------------- -Dokumenty NIE są rozpowszechniane w tym repozytorium. Powód jest podany -w `DATA_LICENSE.md` i sprowadza się do tego, że status prawny ich redystrybucji -nie jest przez nas rozstrzygnięty, a publikujący wymieniają je co kwartał - -kopia w repozytorium po kilku miesiącach wprowadzałaby w błąd. - -Manifest podaje dla każdego pliku adres, datę pobrania i sumę SHA-256, więc -odtworzenie jest sprawdzalne: jeśli publikujący zastąpił dokument nowszą -edycją, suma się nie zgodzi i skrypt to ZGŁOSI, zamiast po cichu policzyć -wyniki na innych danych. - -Użycie ------- - python reproducibility/fetch_sources.py [katalog_docelowy] - -Kody wyjścia: 0, wszystko pobrane i zgodne; 1, czegoś brakuje albo suma -się nie zgadza; 2, manifest nieczytelny. +The documents are NOT distributed in this repository. The reason is given in +`DATA_LICENSE.md` and comes down to this: we have not settled the legal status of +redistributing them, and the publishers replace them every quarter, so a copy in +the repository would be misleading after a few months. + +For every file the manifest gives the address, the download date and the SHA-256 +checksum, so the reproduction is checkable: if the publisher has replaced the +document with a newer edition, the checksum will not match and the script will +REPORT that instead of quietly computing results on different data. + +Usage +----- + python reproducibility/fetch_sources.py [target_directory] + +Exit codes: 0, everything downloaded and matching; 1, something is missing or a +checksum does not match; 2, the manifest cannot be read. """ from __future__ import annotations @@ -34,16 +34,17 @@ MANIFEST = Path(__file__).with_name("manifest.csv") AGENT = "gridqueue-reproducibility/1.3 (statutory grid connection disclosure)" -#: Adresy, które wskazują stronę publikującego, a nie plik. Pobranie wymaga -#: ręcznego odszukania bieżącej edycji, publikujący nie wystawia trwałego -#: odsyłacza do pliku. +#: Addresses that point at the publisher's website rather than at a file. +#: Downloading one means finding the current edition by hand; the publisher +#: does not expose a stable link to the file. BEZ_TRWALEGO_ODSYLACZA = ("https://www.stoen.pl/", "https://www.elana-energetyka.pl/") -#: Zmienna środowiskowa wskazująca własny pakiet zaufanych wystawców. Potrzebna -#: w sieciach, w których ruch przechodzi przez pośrednika podstawiającego własny -#: certyfikat, wtedy weryfikacja łańcucha zawodzi mimo poprawnego serwera. -#: Wskazujemy pakiet, a NIE wyłączamy weryfikacji: wyłączenie sprawiłoby, że -#: pobrany plik przestaje być wiarygodny, a cały sens sum kontrolnych znika. +#: Environment variable pointing at a custom bundle of trusted issuers. Needed +#: in networks where traffic goes through a proxy that substitutes its own +#: certificate; chain verification then fails even though the server is sound. +#: We point at a bundle and do NOT switch verification off: switching it off +#: would make the downloaded file untrustworthy and void the whole point of the +#: checksums. ZMIENNA_CA = "GRIDQUEUE_CA_BUNDLE" @@ -55,10 +56,10 @@ def _kontekst_ssl() -> ssl.SSLContext | None: return ssl.create_default_context(cafile=paczka) -#: Sygnatury początku pliku. Adres, który przestał prowadzić do dokumentu, -#: zwykle zwraca stronę HTML z kodem 200, bez tego sprawdzenia skrypt -#: zdiagnozowałby to jako podmianę edycji, co jest myląco podobne, a wymaga -#: zupełnie innej reakcji użytkownika. +#: File header signatures. An address that no longer leads to the document +#: usually returns an HTML page with code 200; without this check the script +#: would diagnose that as a replaced edition, which looks confusingly similar +#: but calls for a completely different reaction from the user. SYGNATURY = {".pdf": b"%PDF", ".xlsx": b"PK\x03\x04", ".csv": None, ".json": None} @@ -85,7 +86,7 @@ def main(argv: list[str]) -> int: try: wiersze = list(csv.DictReader(MANIFEST.open(encoding="utf-8"))) except OSError as e: - print(f"nie można odczytać manifestu: {e}", file=sys.stderr) + print(f"cannot read the manifest: {e}", file=sys.stderr) return 2 ok, recznie, bledy = [], [], [] @@ -94,55 +95,55 @@ def main(argv: list[str]) -> int: docelowy = cel / plik if docelowy.exists() and sha256(docelowy) == suma: ok.append(plik) - print(f"[jest ] {plik}") + print(f"[have ] {plik}") continue if url in BEZ_TRWALEGO_ODSYLACZA: recznie.append((plik, url)) - print(f"[ręczn] {plik} <- {url} (brak trwałego odsyłacza do pliku)") + print(f"[hand ] {plik} <- {url} (no stable link to the file)") continue try: zad = urllib.request.Request(url, headers={"User-Agent": AGENT}) with urllib.request.urlopen(zad, timeout=180, context=_kontekst_ssl()) as odp: dane = odp.read() if not wyglada_na_dokument(dane, plik): - bledy.append((plik, "adres nie zwraca już dokumentu")) - print(f"[ADRES] {plik}: adres zwrócił treść, która nie jest dokumentem" + bledy.append((plik, "the address no longer returns the document")) + print(f"[ADDR ] {plik}: the address returned content that is not a document" f" ({len(dane)} B).") - print( " Publikujący prawdopodobnie przebudował serwis. Odszukaj") - print( " bieżącą edycję na jego stronie i zaktualizuj manifest.") + print( " The publisher has probably rebuilt the website. Find the") + print( " current edition there and update the manifest.") continue docelowy.write_bytes(dane) except urllib.error.URLError as e: powod = getattr(e, "reason", e) if isinstance(powod, ssl.SSLError) or "CERTIFICATE_VERIFY_FAILED" in str(powod): - bledy.append((plik, "weryfikacja certyfikatu nieudana")) - print(f"[CERT ] {plik}: weryfikacja łańcucha certyfikatów nie powiodła się.") - print(f" Jeśli Twoja sieć używa pośrednika z własnym certyfikatem,") - print(f" wskaż jego pakiet: {ZMIENNA_CA}=/ścieżka/do/ca-bundle.pem") - print( " Nie wyłączaj weryfikacji, sumy kontrolne straciłyby sens.") + bledy.append((plik, "certificate verification failed")) + print(f"[CERT ] {plik}: verification of the certificate chain failed.") + print(f" If your network uses a proxy with its own certificate,") + print(f" point at its bundle: {ZMIENNA_CA}=/path/to/ca-bundle.pem") + print( " Do not switch verification off; the checksums would lose their point.") else: - bledy.append((plik, f"pobranie nieudane: {powod}")) - print(f"[BŁĄD ] {plik}: {powod}") + bledy.append((plik, f"download failed: {powod}")) + print(f"[ERROR] {plik}: {powod}") continue except OSError as e: - bledy.append((plik, f"zapis nieudany: {e}")) - print(f"[BŁĄD ] {plik}: {e}") + bledy.append((plik, f"write failed: {e}")) + print(f"[ERROR] {plik}: {e}") continue faktyczna = sha256(docelowy) if faktyczna != suma: - bledy.append((plik, "suma kontrolna się nie zgadza")) - print(f"[SUMA ] {plik}: oczekiwano {suma[:12]}…, otrzymano {faktyczna[:12]}…") - print(" publikujący prawdopodobnie zastąpił dokument nowszą edycją;") - print(" wyniki z tego pliku NIE będą identyczne z opublikowanymi.") + bledy.append((plik, "the checksum does not match")) + print(f"[HASH ] {plik}: expected {suma[:12]}…, got {faktyczna[:12]}…") + print(" the publisher has probably replaced the document with a newer edition;") + print(" results from this file will NOT be identical with the published ones.") else: ok.append(plik) - print(f"[pobr ] {plik}") + print(f"[got ] {plik}") - print(f"\nzgodnych: {len(ok)}/{len(wiersze)} | do pobrania ręcznie: {len(recznie)}" - f" | błędów: {len(bledy)}") + print(f"\nmatching: {len(ok)}/{len(wiersze)} | to download by hand: {len(recznie)}" + f" | errors: {len(bledy)}") if recznie: - print("\nPliki bez trwałego odsyłacza, odszukaj bieżącą edycję na stronie") - print("publikującego i zapisz pod nazwą z manifestu:") + print("\nFiles with no stable link; find the current edition on the publisher's") + print("website and save it under the name from the manifest:") for plik, url in recznie: print(f" {plik} <- {url}") return 0 if not bledy and not recznie else 1 diff --git a/reproducibility/manifest.csv b/reproducibility/manifest.csv index 088d4e6..ac6896e 100644 --- a/reproducibility/manifest.csv +++ b/reproducibility/manifest.csv @@ -11,7 +11,7 @@ pse_art7_8l_20260731.xlsx,PSE S.A.,PL,pl_pse,174263,21dff45875f6fe7d943fd3df98a2 pse_lista_rozdzielni_brak_mozliwosci_20260204.xlsx,PSE S.A.,PL,pl_pse,16074,5fb56e497860b7584734386122910e5d10deae750b21d4b0557dc70a970e1348,https://www.pse.pl/documents/20182/51490/20260204_Lista_rozdzielni-brak_mozliwosci_przylaczenia.xlsx,2026-09-30 elana_informacje.pdf,Boryszew Green Energy&Gas Sp. z o.o.,PL,pl_boryszew,352611,19baec2f3616b27092c371db999ad6f1125e0be6c0b52d6344347f3712336541,https://www.elana-energetyka.pl/,2026-09-30 uk_connection_queue.csv,National Grid Electricity Distribution,GB,uk_nationalgrid,94762,a169b1c40dc09063ceafce0acaa51983bcee6244e8aa62fd2868791684e45117,"https://connecteddata.nationalgrid.co.uk/ (zbiór CKAN connection-queue, 45 zasobów CSV)",2026-09-29 -gazeter_wspolrzedne.json,"OpenStreetMap (gazeter, ODbL 1.0)",—,—,3227817,7c6ac4f1eccf619d1fe135030e58e12e6d39715962ca726268c7f2827fb505a3,https://overpass-api.de/api/interpreter,2026-09-30 +gazeter_wspolrzedne.json,"OpenStreetMap (gazeter, ODbL 1.0)",none,none,3227817,7c6ac4f1eccf619d1fe135030e58e12e6d39715962ca726268c7f2827fb505a3,https://overpass-api.de/api/interpreter,2026-09-30 pt_eredes_capacidade_rececao_rnd_2T2026.csv,E-REDES S.A.,PT,pt_eredes,151565,fe53b14dbcbb94e4125abb31a5f1c666bcdaefbfd4b83bc62afc0eac4c254780,https://e-redes.opendatasoft.com/api/explore/v2.1/catalog/datasets/capacidade-rececao-rnd/exports/csv?delimiter=%3B&use_labels=false,2026-10-07 es_edrd_capacidad_2025_08_01.pdf,e-Distribución Redes Digitales S.L.U.,ES,es_edistribucion,980147,09d6f393cbb5563743b1c2499f8d7dec2f22befcc4cd85a8ecc2fb19a9149f70,https://www.edistribucion.com/content/dam/edistribucion/conexion-a-la-red/descargables/nodos/EDRD_Capacidad_de_Acceso_2025_08_01.pdf,2026-10-08 ie_esb_heatmap_2026_07.xlsx,ESB Networks DAC,IE,ie_esbnetworks,6929289,5609fc4cd44c655e1d80114056efe637ee0c2d958b0099d4e6c6c4040821c5fa,https://media.esbnetworks.ie/media/docs/default-source/publications/customer-heatmap-download-july-2026.xlsx,2026-10-08 diff --git a/reproducibility/requirements-lock.txt b/reproducibility/requirements-lock.txt index 809c612..f5a6aa0 100644 --- a/reproducibility/requirements-lock.txt +++ b/reproducibility/requirements-lock.txt @@ -1,6 +1,6 @@ -# Wersje faktycznie użyte do wytworzenia opublikowanych liczb. -# Python 3.11.15 na Darwin arm64. -# Odczytane z importlib.metadata w środowisku wykonawczym. +# The versions actually used to produce the published numbers. +# Python 3.11.15 on Darwin arm64. +# Read from importlib.metadata in the execution environment. Pillow==12.3.0 matplotlib==3.11.1 numpy==2.4.6 diff --git a/reproducibility/run_figures.py b/reproducibility/run_figures.py index 4b5cf66..0101a22 100644 --- a/reproducibility/run_figures.py +++ b/reproducibility/run_figures.py @@ -1,19 +1,20 @@ -"""Odtworzenie figur, które zależą wyłącznie od panelu. +"""Reproduction of the figures that depend on the panel alone. -Zakres ------- -Odtwarzane są trzy figury wyliczane z panelu: pokrycie pól schematu, naruszenia -reguł kontroli jakości oraz wynik rozstrzygania lokalizacji. +Scope +----- +Three figures computed from the panel are reproduced: coverage of the schema +fields, violations of the quality control rules, and the outcome of location +resolution. -Dwóch figur ten skrypt NIE odtwarza i jest to zamierzone: +Two figures this script does NOT reproduce, and that is deliberate: -* figura architektury jest schematem rysowanym ręcznie, bez danych wejściowych; -* figura walidacji zależy od **zbioru odniesienia odczytanego wzrokowo przez - człowieka**, publikowanego jako osobny artefakt, a nie wyliczanego przez kod. +* the architecture figure is a hand-drawn diagram with no input data; +* the validation figure depends on **a reference set read visually by a human**, + published as a separate artefact rather than computed by code. -Uruchomienie:: +Running:: - python reproducibility/run_figures.py [katalog_wyjściowy] + python reproducibility/run_figures.py [output_directory] """ from __future__ import annotations @@ -78,7 +79,7 @@ def fig_pokrycie(panel: pd.DataFrame, plik: Path) -> None: for i in range(len(pola)): for j in range(len(publ)): v = Z[i, j] - txt = "\u2014" if v == 0 else ("<1" if v < 0.005 else + txt = "-" if v == 0 else ("<1" if v < 0.005 else ("100" if v >= 0.995 else f"{v*100:.0f}")) ax.text(j, i, txt, ha="center", va="center", fontsize=5.4, color="#ffffff" if v > 0.62 else ("#999999" if v == 0 else "#222222")) @@ -90,12 +91,12 @@ def fig_pokrycie(panel: pd.DataFrame, plik: Path) -> None: for s in ax.spines.values(): s.set_visible(False) niepokryte = [f for i, f in enumerate(pola) if Z[i].max() == 0] - tytul = (f"Każde z {len(pola)} pól schematu jest wypełnione przez co najmniej " - "jednego publikującego" if not niepokryte else - f"Pola niepokryte w panelu: {', '.join(niepokryte)}") + tytul = (f"Every one of the {len(pola)} schema fields is filled in by at least " + "one publisher" if not niepokryte else + f"Fields not covered in the panel: {', '.join(niepokryte)}") ax.set_title(tytul, fontsize=8, pad=22) - ax.text(0, -1.35, "pokrycie pola, % wierszy danego publikującego " - "\u2022 = pole rdzenia bezwarunkowego \u2014 = pole nieujawniane", + ax.text(0, -1.35, "field coverage, % of the rows of a given publisher " + "\u2022 = unconditional core field - = field not disclosed", fontsize=6, color=SZARY, transform=ax.transData) fig.tight_layout() fig.savefig(plik, dpi=300, bbox_inches="tight") @@ -131,7 +132,7 @@ def fig_jakosc(panel: pd.DataFrame, plik: Path) -> None: for yy, tot in zip(y, piv["razem"].values): if tot == 0: ax.plot([0], [yy], "o", ms=3.2, color="#444444", zorder=3) - ax.text(szer * 0.012, yy, "0 naruszeń", va="center", fontsize=6, color=SZARY) + ax.text(szer * 0.012, yy, "0 violations", va="center", fontsize=6, color=SZARY) else: ax.text(tot + szer * 0.012, yy, f"{_th(tot)} ({tot / n * 100:.3f} %)".replace(".", ","), @@ -139,9 +140,9 @@ def fig_jakosc(panel: pd.DataFrame, plik: Path) -> None: ax.set_yticks(y) ax.set_yticklabels([f"{k} {nm}" for k, nm in zip(piv["kod"], piv["nazwa"])], fontsize=6.5) ax.set_xlim(0, szer * 1.45) - ax.set_xlabel(f"wiersze naruszające regułę (panel {_th(n)} wierszy)", fontsize=7) - ax.set_title("Reguły wykrywają jakość źródła, nie błąd narzędzia, " - "i wskazują, który publikujący ją obniża", fontsize=8, loc="left") + ax.set_xlabel(f"rows violating the rule (panel of {_th(n)} rows)", fontsize=7) + ax.set_title("The rules detect the quality of the source, not an error of the tool, " + "and show which publisher lowers it", fontsize=8, loc="left") ax.legend(loc="lower right", fontsize=6, ncol=2, frameon=False, handlelength=1.1, columnspacing=1.0) ax.margins(y=0.06) @@ -152,33 +153,33 @@ def fig_jakosc(panel: pd.DataFrame, plik: Path) -> None: def fig_lokalizacja(panel: pd.DataFrame, plik: Path) -> None: def kat(wsp, powod): if pd.notna(wsp): - return "rozwiązane" + return "resolved" s = str(powod) if "kod_stacji" in s: - return "kod stacji bez słownika" + return "station code with no gazetteer" if "brak_deklaracji_miejscowosci" in s: - return "brak deklaracji miejscowości" + return "no locality declared" if "pusty_opis" in s: - return "pusty opis" + return "empty description" if "poza_gazeterem" in s: - return "miejscowość poza gazeterem" + return "locality outside the gazetteer" if "wiele_kandydatow" in s or "niejednoznaczna" in s: - return "wiele kandydatów" - return "inne" + return "several candidates" + return "other" d = panel.copy() d["pub"] = d["publikujacy"].map(lambda p: SKROT.get(p, p)) d["_kat"] = [kat(w, r) for w, r in zip(d["wspolrzedne"], d.get("_geo_powod", pd.Series([None] * len(d))))] - KAT = ["rozwiązane", "kod stacji bez słownika", "brak deklaracji miejscowości", - "pusty opis", "miejscowość poza gazeterem", "wiele kandydatów", "inne"] - KK = {"rozwiązane": "#2e8b78", "kod stacji bez słownika": "#1b5e8c", - "brak deklaracji miejscowości": "#8fb4cc", "pusty opis": "#cfd8dd", - "miejscowość poza gazeterem": "#c77a1e", "wiele kandydatów": "#7a4b9c", - "inne": "#aaaaaa"} + KAT = ["resolved", "station code with no gazetteer", "no locality declared", + "empty description", "locality outside the gazetteer", "several candidates", "other"] + KK = {"resolved": "#2e8b78", "station code with no gazetteer": "#1b5e8c", + "no locality declared": "#8fb4cc", "empty description": "#cfd8dd", + "locality outside the gazetteer": "#c77a1e", "several candidates": "#7a4b9c", + "other": "#aaaaaa"} CT = (d.groupby(["pub", "_kat"]).size().unstack(fill_value=0) .reindex(columns=[k for k in KAT if k in d["_kat"].unique()], fill_value=0)) CT = CT.reindex([p for p in BARWY if p in CT.index]) - assert int(CT.values.sum()) == len(d), "kategorie nie pokrywają wszystkich wierszy" + assert int(CT.values.sum()) == len(d), "the categories do not cover all rows" fig = plt.figure(figsize=(7.1, 2.85)) gs = fig.add_gridspec(1, 2, width_ratios=[1.6, 1.0], wspace=0.45) @@ -190,23 +191,23 @@ def kat(wsp, powod): ax.barh(ypos, frac[k].values, left=left, height=0.62, color=KK[k], label=k, zorder=2) left += frac[k].values for yy, p in zip(ypos, CT.index): - r = int(CT.loc[p, "rozwiązane"]) if "rozwiązane" in CT.columns else 0 + r = int(CT.loc[p, "resolved"]) if "resolved" in CT.columns else 0 ax.text(101.5, yy, f"{_th(r)} / {_th(int(CT.loc[p].sum()))}", va="center", fontsize=6) ax.set_yticks(ypos) ax.set_yticklabels(CT.index, fontsize=6.5) ax.set_xlim(0, 118) ax.set_xticks([0, 25, 50, 75, 100]) - ax.set_xlabel("udział wierszy publikującego, %", fontsize=7) - ax.set_title("Żaden publikujący nie ujawnia współrzędnych;\n" - "brak jest zwracany z przyczyną, nie zgadywany", fontsize=8, loc="left", pad=8) + ax.set_xlabel("share of the publisher's rows, %", fontsize=7) + ax.set_title("No publisher discloses coordinates;\n" + "a gap is returned with a reason, not guessed", fontsize=8, loc="left", pad=8) ax.legend(loc="upper center", bbox_to_anchor=(0.46, -0.30), ncol=3, fontsize=5.7, frameon=False, handlelength=1.0, columnspacing=0.9, handletextpad=0.4) ax2 = fig.add_subplot(gs[1]) pw = d.loc[d["wspolrzedne"].notna(), "_geo_pewnosc"].value_counts() - opis = {"EXACT": "dokładne", "UNIQUE_TOKEN": "unikalny człon", - "SKRZYZOWANIE": "skrzyżowanie", "REVERSED": "odwrócona kolejność", - "TOKEN_SUBSET": "podzbiór członów"} + opis = {"EXACT": "exact", "UNIQUE_TOKEN": "unique member", + "SKRZYZOWANIE": "intersection", "REVERSED": "reversed order", + "TOKEN_SUBSET": "subset of members"} klucze = [k for k in opis if k in pw.index] vv = [int(pw[k]) for k in klucze] yb = np.arange(len(klucze))[::-1] @@ -217,9 +218,9 @@ def kat(wsp, powod): ax2.set_yticks(yb) ax2.set_yticklabels([opis[k] for k in klucze], fontsize=6) ax2.set_xlim(0, max(vv) * 1.40) - ax2.set_xlabel("wiersze", fontsize=7) - ax2.set_title(f"Poziom pewności {_th(sum(vv))} rozwiązań:\n" - f"{vv[0] / sum(vv) * 100:.1f} % to dopasowanie dokładne".replace(".", ","), + ax2.set_xlabel("rows", fontsize=7) + ax2.set_title(f"Confidence level of {_th(sum(vv))} resolutions:\n" + f"{vv[0] / sum(vv) * 100:.1f} % are exact matches".replace(".", ","), fontsize=8, loc="left", pad=8) fig.savefig(plik, dpi=300, bbox_inches="tight") plt.close(fig) @@ -227,7 +228,7 @@ def kat(wsp, powod): def main(argv: list[str]) -> int: if len(argv) < 2: - print("użycie: python reproducibility/run_figures.py [katalog]", + print("usage: python reproducibility/run_figures.py [directory]", file=sys.stderr) return 2 p = Path(argv[1]) @@ -238,9 +239,9 @@ def main(argv: list[str]) -> int: fig_pokrycie(panel, out / "rys_pokrycie.png") fig_jakosc(panel, out / "rys_jakosc.png") fig_lokalizacja(panel, out / "rys_lokalizacja.png") - print(f"schemat {SCHEMA_VERSION}; rdzeń bezwarunkowy: {', '.join(CORE_FIELDS)}") - print(f"pól schematu: {len(FIELDS)}; wierszy panelu: {_th(len(panel))}") - print(f"zapisano trzy figury do: {out}") + print(f"schema {SCHEMA_VERSION}; unconditional core: {', '.join(CORE_FIELDS)}") + print(f"schema fields: {len(FIELDS)}; panel rows: {_th(len(panel))}") + print(f"saved three figures to: {out}") return 0 diff --git a/reproducibility/run_validation.py b/reproducibility/run_validation.py index 52f49e8..ee179eb 100644 --- a/reproducibility/run_validation.py +++ b/reproducibility/run_validation.py @@ -1,24 +1,26 @@ -"""Odtworzenie liczb walidacyjnych z panelu. +"""Reproduction of the validation numbers from the panel. -Co ten skrypt robi, a czego nie -------------------------------- -Odtwarza **liczby pochodne**: pokrycie pól, reguły kontroli jakości, audyt -przesunięcia kolumn i kompletność rdzenia. Robi to z gotowego panelu, więc -sprawdza odtwarzalność obliczeń, nie odtwarzalność wydobycia. +What this script does and what it does not +------------------------------------------ +It reproduces the **derived numbers**: field coverage, the quality control rules, +the column shift audit and core completeness. It does so from a finished panel, +so it checks the reproducibility of the computations, not the reproducibility of +the extraction. -Nie odtwarza **dokładności wobec zbioru odniesienia**, ta wymaga wzorca -odczytanego wzrokowo z dokumentu przez człowieka i jest opublikowana jako -artefakt, a nie wyliczana przez kod. +It does not reproduce **accuracy against the reference set**; that requires a +reference read visually from the document by a human and is published as an +artefact rather than computed by code. -Dokumenty źródłowe nie są redystrybuowane: część z nich jest objęta prawami -publikujących, a wszystkie są wymieniane kwartalnie na mocy obowiązku ustawowego. -``manifest.csv`` podaje dla każdego adres, datę pobrania i SHA-256, więc osoba -odtwarzająca pracę może pobrać dokładnie te pliki albo stwierdzić, że publikujący -wydał już inną edycję, i wtedy **powinna oczekiwać innych liczb wierszy**. +The source documents are not redistributed: some of them are covered by the +rights of their publishers, and all of them are replaced quarterly under the +statutory duty. ``manifest.csv`` gives the address, the download date and the +SHA-256 for each of them, so a person reproducing the work can download exactly +these files or find that the publisher has already issued a different edition, +and should then **expect different row counts**. -Uruchomienie:: +Running:: - python reproducibility/run_validation.py [katalog_wyjściowy] + python reproducibility/run_validation.py [output_directory] """ from __future__ import annotations @@ -37,7 +39,7 @@ def sprawdz_sumy(katalog: Path) -> dict: - """Porównaj SHA-256 dokumentów w podanym katalogu z manifestem.""" + """Compare the SHA-256 of the documents in the given directory with the manifest.""" man = pd.read_csv(KOREN / "manifest.csv") wynik = {"zgodne": [], "rozne": [], "brakujace": []} for _, r in man.iterrows(): @@ -94,7 +96,7 @@ def main(argv: list[str]) -> int: jak = pd.DataFrame(reguly) jak.to_csv(outdir / "reguly_jakosci.csv", index=False) - # kontrola spójności: suma po publikujących musi równać się panelowi + # consistency check: the sum over publishers has to equal the panel figure po_publ = (jak[jak["publikujacy"] != "PANEL RAZEM"] .groupby("kod")["naruszenia"].sum()) panelowe = (jak[jak["publikujacy"] == "PANEL RAZEM"] @@ -120,9 +122,9 @@ def main(argv: list[str]) -> int: (outdir / "podsumowanie.json").write_text( json.dumps(podsum, ensure_ascii=False, indent=1), encoding="utf-8") - # Porównanie z wartościami oczekiwanymi dla tego wydania. Celowo pomijamy - # numer wersji pakietu: sprawdzamy, czy LICZBY się zgadzają, a nie czy ktoś - # uruchomił dokładnie ten sam tag. + # Comparison with the values expected for this release. The package version + # number is deliberately left out: we check whether the NUMBERS agree, not + # whether somebody ran exactly the same tag. oczek_plik = Path(__file__).parent / "expected" / "expected_panel_stats.json" rozjazd: dict = {} if oczek_plik.exists(): @@ -136,19 +138,19 @@ def main(argv: list[str]) -> int: for k, v in podsum.items(): print(f"{k}: {v}") if rozjazd: - print("\nBŁĄD: wynik nie odpowiada wartościom oczekiwanym dla tego wydania.", + print("\nERROR: the result does not match the values expected for this release.", file=sys.stderr) for k, v in rozjazd.items(): - print(f" {k}: oczekiwano {v['oczekiwano']}, otrzymano {v['otrzymano']}", + print(f" {k}: expected {v['oczekiwano']}, got {v['otrzymano']}", file=sys.stderr) return 1 if oczek_plik.exists(): - print("\nzgodność z expected/expected_panel_stats.json: OK") + print("\nagreement with expected/expected_panel_stats.json: OK") if niezgodne: - print("\nUWAGA: suma naruszeń po publikujących nie domyka się do panelu.", + print("\nWARNING: the sum of violations over publishers does not close to the panel.", file=sys.stderr) return 1 - print(f"\nzapisano do: {outdir}") + print(f"\nsaved to: {outdir}") return 0 diff --git a/src/gridqueue.egg-info/PKG-INFO b/src/gridqueue.egg-info/PKG-INFO deleted file mode 100644 index 35538bf..0000000 --- a/src/gridqueue.egg-info/PKG-INFO +++ /dev/null @@ -1,265 +0,0 @@ -Metadata-Version: 2.4 -Name: gridqueue -Version: 1.5.2 -Summary: Harmonizator ustawowych ujawnien przylaczeniowych do sieci elektroenergetycznej -Requires-Python: >=3.10 -Description-Content-Type: text/markdown -License-File: LICENSE.txt -Requires-Dist: pandas>=2.0 -Requires-Dist: pdfplumber>=0.11 -Requires-Dist: requests>=2.31 -Requires-Dist: pyarrow>=14 -Requires-Dist: openpyxl>=3.1 -Provides-Extra: test -Requires-Dist: pytest>=8.0; extra == "test" -Dynamic: license-file - -# gridqueue - -[![testy](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/s-matysik/gridqueue/actions/workflows/ci.yml) -[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/s-matysik/gridqueue) -[![licencja Apache-2.0](https://img.shields.io/badge/licencja-Apache--2.0-green)](LICENSE.txt) -[![dokumentacja](https://img.shields.io/badge/dokumentacja-gh--pages-blue)](https://s-matysik.github.io/gridqueue/) -[![wydanie](https://img.shields.io/github/v/release/s-matysik/gridqueue)](https://github.com/s-matysik/gridqueue/releases) -[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) - -Harmonizator ustawowych ujawnień przyłączeniowych do sieci elektroenergetycznej. - -Operatorzy systemów dystrybucyjnych mają obowiązek publikować, kto ubiega się o przyłączenie, -gdzie, o jaką moc i na jakim etapie stoi postępowanie (art. 7 ust. 8l ustawy z dnia -10 kwietnia 1997 r., Prawo energetyczne). W Polsce obowiązek dotyczy około 180 koncesjonowanych -operatorów i **każdy publikuje we własnym formacie**, najczęściej jako PDF. Informacja jest -jawna, ale nie jest przetwarzalna. - -`gridqueue` zamienia te publikacje na jeden zbiór wierszy o **zmierzonej dokładności**. - -Stan wydania 0.3.1: **sześć adapterów, 19 220 wierszy panelu, wszystkie 21 pól schematu -wypełnione**. Publikujący: TAURON Dystrybucja 10 955 wierszy, ENERGA-OPERATOR 5 382, -Stoen Operator 1 236, PSE 945, National Grid (GB) 694, Boryszew Green Energy&Gas 8. -Dokumentacja: **https://s-matysik.github.io/gridqueue/** - -## Czym to nie jest - -Nie jest to indeks publikacji operatorów ani mapa przeglądowa. Istnieją narzędzia, które -indeksują i linkują do stron operatorów w skali europejskiej. `gridqueue` robi krok niżej: -**parsuje sam dokument ustawowy na wiersze**. W jurysdykcjach o dobrych danych (Wielka Brytania, -USA) dane są już tabelaryczne i ta warstwa jest zbędna, adapter brytyjski w tym pakiecie -sprowadza się do pobrania CSV. Polska jest przypadkiem, w którym nie jest. - -## Uruchomienie bez instalacji, Google Colab - -[![Otwórz w Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/s-matysik/gridqueue/blob/main/notebooks/gridqueue_colab.ipynb) - -Notatnik `notebooks/gridqueue_colab.ipynb` wykonuje **pełny przebieg badawczy w przeglądarce**: -pobiera dwie edycje ujawnienia wprost od publikującego, wydobywa wiersze, ocenia jakość, liczy -przepływy w kolejce wraz z precyzją dopasowania i **porównuje odtworzone liczby z opublikowanymi -w artykule, przerywając wykonanie przy rozjeździe**. Poniżej minuty na darmowej maszynie, bez -akceleratora i bez konfiguracji. - -Notatnik nie odtwarza dokładności wydobycia wobec zbioru odniesienia, bo ten wymaga odczytu przez -człowieka, ani nie rozstrzyga współrzędnych, bo gazeter jest osobnym pobraniem na licencji ODbL. - -## Instalacja - -Jedno polecenie, bez kompilacji i bez usług zewnętrznych: - -```bash -pip install git+https://github.com/s-matysik/gridqueue@v1.2.1 -``` - -Do pracy nad kodem, z ekstrasem testowym: - -```bash -git clone https://github.com/s-matysik/gridqueue && cd gridqueue -pip install -e ".[test]" -``` - -Zależności: `pandas`, `pdfplumber`, `openpyxl`, `requests`, `pyarrow`. Jednostka kanoniczna mocy -to **kW** bez wyjątku; źródła podające megawaty są przeliczane przy wydobyciu, a jednostka źródłowa -zostaje odnotowana w rozszerzeniu. - -## Szybki przykład - -```python -from gridqueue import get_adapter, run_quality, validate_frame, audit_column_shift - -res = get_adapter("pl_tauron").parse("tauron_informacja.pdf") -df = res.frame # ramka w 21-polowym schemacie -print(res.report["n_wierszy"]) # 10955 -print(audit_column_shift(df).udzial) # 0.0, udział wierszy z przesuniętymi kolumnami -print(run_quality(df).as_dict()["naruszen_lacznie"]) -``` - -Wiersz z rozwiązaną lokalizacją: - -```python -from gridqueue import resolver_from_osm_json -r = resolver_from_osm_json("ulice_warszawa.json") -res = r.resolve("WARSZAWA, WINCENTEGO ŚW.") -print(res.matched, res.pewnosc) # Świętego Wincentego REVERSED -print(r.resolve("SKB3").powod) # kod_stacji_bez_slownika, nie zgadujemy -``` - -## CLI - -```bash -gridqueue schema # specyfikacja 21 pól -gridqueue adapters # deklaracje publikujących -gridqueue parse tauron.pdf --out tauron.parquet --report tauron.json -gridqueue parse --adapter uk_nationalgrid --out uk.parquet # pobiera z katalogu CKAN -gridqueue validate tauron.parquet --out walidacja.json -gridqueue export tauron.parquet stoen.parquet --out panel.parquet --only-schema -``` - -## Schemat - -21 pól w trzech grupach odwzorowujących strukturę obowiązku (TOŻSAMOŚĆ / MOC / PROCES), -rdzeń obowiązkowy 5 pól (`id_wniosku`, `lokalizacja_tekst`, `klasa_zasobu`, `moc_pobierana`, -`status_procesu`), reszta opcjonalna i **deklarowana per publikujący**. Jednostki kanoniczne: -moc w kW, daty ISO 8601, współrzędne WGS84. Pola spoza schematu, których dany operator -dostarcza więcej niż wymaga minimum, trafiają do kolumn z przedrostkiem `_` i są jawnie -deklarowane przez adapter (`adapter.declaration()`). - -## Metoda wydobycia - -Zamiast wyrażeń regularnych na spłaszczonym tekście, wydobycie z **położenia słów na stronie**: - -* `ruled`, granice kolumn brane z pionowych krawędzi wektorowych (TAURON, Stoen); - pusta komórka jest odgrodzona linią, więc nie może zlać się z sąsiednią, -* `banded`, granice z pionowych korytarzy bieli (Boryszew; dokument bez siatki), -* wiersze wielolinijkowe scalane kolumna po kolumnie po numerze porządkowym, -* arkusze (PSE) czytane wprost z komórek, wraz z formatowaniem znaku, bez tego indeksy górne - oznaczające przypisy sklejają się z treścią, a w polach liczbowych niszczą wartość. - -Wybrano `pdfplumber`, bo daje bezpośredni dostęp do współrzędnych słów i krawędzi wektorowych -z `pdfminer.six`. `camelot` w trybie lattice odtwarza granice kolumn z rastra i wymaga -Ghostscriptu, `tabula` wymaga JVM, w obu granica kolumny jest wynikiem detekcji na obrazie, -a nie liczbą z pliku. - -## Przykład badawczy - -Adaptery są specyficzne dla źródła, ale **analiza badawcza już nie**. `examples/research_use_case.py` -liczy czas od złożenia wniosku do wydania warunków przyłączenia, w podziale na klasę zasobu -i publikującego, bez ani jednej gałęzi zależnej od publikującego, wyłącznie na polach wspólnego -schematu: - -```bash -gridqueue parse --out panel.parquet -python examples/research_use_case.py panel.parquet -``` - -Wynik na panelu sześciu publikujących (mediana, dni): przyłączenia **odbiorcze** 40 u TAURONA -i 57 u ENERGI, **fotowoltaika** 105 i 127, **magazyny energii** 119 i 146, **wiatr** 156 i 158. -Przyłączenia odbiorcze rozpatrywane są dwa do czterech razy szybciej niż wytwórcze, a różnica -między publikującymi utrzymuje się w obrębie klasy. Jest to wynik opisowy: rejestr opisuje -postępowania administracyjne, więc nie wolno z niego wnosić o przyczynach różnic ani o jakości -pracy publikującego, portfel wniosków, struktura sieci i praktyka ujawniania różnią się między -operatorami. - -## Analiza wzdłużna - -Rejestr **nie publikuje trwałego identyfikatora wniosku**, więc śledzenie sprawy między -edycjami wymaga klucza treściowego. `compare_editions` buduje go i zwraca przepływy oraz -macierz przejść statusu: - -```python -from gridqueue import compare_editions, linkage_audit, get_adapter - -a = get_adapter("pl_pse").parse("edycja_2026_07_31.xlsx").frame -b = get_adapter("pl_pse").parse("edycja_2026_08_31.xlsx").frame -d = compare_editions(a, b, "2026-07-31", "2026-08-31") -d.as_dict()["udzial_przejsc_w_przod"] # 0.9828 -d.as_dict()["migawka_monotoniczna"] # False - -linkage_audit(a, b).as_dict() # precyzja dopasowania: 0.9888-0.9963 -``` - -Dwa wyniki na parze edycji PSE, lipiec-sierpień 2026. **98,28 % przejść statusu biegnie -zgodnie z porządkiem postępowania**, jest to niezależny test dopasowania klucza, bo klucz -dopasowujący losowo nie wytworzyłby tego porządku. I drugi: **rejestr nie jest monotoniczną -migawką**, 13 wierszy pojawia się już w stanie zamkniętym, a 33 wiersze o statusie czynnym -znikają. Różnicy między edycjami nie wolno więc czytać jako samej zmiany stanu kolejki, -i narzędzie zgłasza to flagą, zamiast pozwolić użytkownikowi tego nie zauważyć. - -Ponieważ rejestr nie ma trwałego identyfikatora, samo dopasowanie też wymaga sprawdzenia. -`linkage_audit` porównuje każdą parę na dziewięciu polach **wyłączonych z klucza**, klucz nie -wymusza ich zgodności, więc zgodność jest świadectwem niezależnym. Na wszystkich 804 parach -precyzja wynosi **98,88-99,63 %**: 795 par potwierdzonych, 6 niepewnych, 3 fałszywe. - -```bash -python examples/longitudinal_use_case.py edycja_A.xlsx edycja_B.xlsx 2026-07-31 2026-08-31 -``` - -## Odtwarzalność - -`reproducibility/` zawiera manifest dokumentów źródłowych (adres, data pobrania, SHA-256), wersje -bibliotek oraz skrypty odtwarzające liczby pochodne i figury. Dokumenty nie są redystrybuowane, -bo są wymieniane co kwartał, manifest pozwala sprawdzić, czy pracujemy na tej samej edycji. - -## Reguły kontroli jakości - -Osiem reguł; każda zwraca liczbę naruszeń, nie wyjątek, bo naruszenie jest własnością -ujawnienia, a nie błędem narzędzia: monotoniczność dat postępowania, dwuletnia ważność -warunków przyłączenia (art. 7 ust. 8i), dopuszczalność stanu procesu wobec obecnych dat, -spójność jednostek mocy, zakresy wartości, duplikaty identyfikatorów, kompletność rdzenia, -słownik kontrolowany. - -Od wersji 1.0 reguła kompletności rdzenia ocenia **rdzeń właściwy dla encji wiersza**, a rdzeń -mocy jest **alternatywą**, nie konkretnym polem: wniosek wytwórczy deklaruje moc wprowadzaną, -odbiorczy pobieraną, a pkt 2 obowiązku bywa realizowany mocą dostępną albo liczbą wolnych miejsc -przyłączeniowych. W wersji 0.3.x rdzeń wymagał bezwarunkowo mocy pobieranej i stosował wymagania -encji wniosku także do wierszy węzłowych, co zamieniało własność schematu w pozorne naruszenie -ujawnienia, naruszeń tej reguły było 5 390 (28,044 %) wobec **771 (4,011 %)** teraz. - -## Testy - -```bash -python -m pytest -q # 153 passed, 2 skipped (155 zebranych) -``` - -Dwa pominięcia są warunkowe: to testy integracyjne adapterów PSE i ENERGI, wymagające -dokumentów źródłowych, pomijane gdy dokumentów nie ma w drzewie roboczym. Zestaw działa na -Pythonie 3.10-3.13 pod Linuksem, macOS i Windows, sprawdza to CI przy każdym zgłoszeniu zmiany. - -Pisanie testów i pomiar wzrokowy wychwytują **różne klasy defektów** i oba są w pakiecie obecne. -Pięć defektów odwzorowania przeszło przez cały zestaw testów, bo żaden nie rzucał wyjątku - -w tym jeden zmieniający status umowy na przeciwny w 88 wierszach dwóch publikujących. Wykryło je -porównanie wyjścia z wzorcem odczytanym z dokumentu. - -## Ograniczenia - -* Zbiór odniesienia do pomiaru dokładności jest **częściowo jednoanotatorski**. Zgodność - międzyanotatorską zmierzono na podpróbce 35 wierszy odczytanej niezależnie, w zaślepieniu: - zgodność surowa 0,9725, kappa Cohena 0,9690, zero niezgodności percepcyjnych. Wzorce PSE - i ENERGI pozostają jednoanotatorskie. -* Lokalizacja u TAURONA to wewnętrzny kod stacji; operator nie publikuje słownika kodów, - więc rozwiązywacz zwraca brak z powodem `kod_stacji_bez_slownika`. Nie zgaduje. -* **Żaden z publikujących nie podaje współrzędnych.** Pole `wspolrzedne` jest wypełniane - wyprowadzeniem z nazwy miejsca wobec gazetera z geometrią (13 149 nazw w 25 miejscowościach): - 1 225 z 19 220 wierszy panelu. Wartość dowodowa tego pola jest więc inna niż pól przepisanych - z dokumentu i jest tak opisana w wyniku. -* Nazwa ulicy nie wyznacza punktu: 431 z 6 057 nazw warszawskich (7,12%) ma rozłączne składowe - odległe o ponad 2 km. Rejestr podaje ulicę, lecz nie dzielnicę, więc **tej niejednoznaczności - nie da się usunąć z danych opublikowanych**. Każdy wynik niesie liczbę składowych i ich rozrzut, - żeby odbiorca mógł takie wiersze odfiltrować. -* Portale UK Power Networks i Electricity North West zwracają 403 na poziomie wierszy. - Korzystamy wyłącznie z ich publicznych metadanych i tak to opisujemy. Kontroli dostępu - nie obchodzimy; klient przedstawia się uczciwie w nagłówku `User-Agent`. - -## Cytowanie - -`CITATION.cff` w korzeniu repozytorium. Wpis autorski jest zbiorczy i wymaga uzupełnienia listą -autorów osobowych przed zgłoszeniem artykułu. - -## Licencja - -Apache-2.0 dla **kodu**. Dane wejściowe i wyjściowe mają odrębny status, dokumenty urzędowe nie są redystrybuowane, a gazeter geometryczny podlega ODbL z obowiązkiem atrybucji i share-alike. Szczegóły w [`DATA_LICENSE.md`](DATA_LICENSE.md). - -Historia zmian: [`CHANGELOG.md`](CHANGELOG.md)., patrz `LICENSE.txt`. Jest to wybór **roboczy**, podyktowany tym, że czasopismo -docelowe wymaga pliku licencji w repozytorium, a tekst Apache-2.0 nie wymaga wpisywania danych -właściciela praw w samym pliku. Zmiana na inną licencję z listy dopuszczonych (MIT, BSD, GPL) -jest jednym commitem, dopóki repozytorium nie ma zewnętrznych współautorów. - -Licencje danych wejściowych są osobne i niezmienne: gazeter z OpenStreetMap na licencji ODbL 1.0; -publikacje ustawowe operatorów na ich własnych warunkach korzystania, redystrybuowane wyłącznie -tam, gdzie jest to dozwolone. diff --git a/src/gridqueue.egg-info/SOURCES.txt b/src/gridqueue.egg-info/SOURCES.txt deleted file mode 100644 index 7eb1bf6..0000000 --- a/src/gridqueue.egg-info/SOURCES.txt +++ /dev/null @@ -1,41 +0,0 @@ -LICENSE.txt -README.md -pyproject.toml -src/gridqueue/__init__.py -src/gridqueue/analysis.py -src/gridqueue/cli.py -src/gridqueue/geoloc.py -src/gridqueue/layout.py -src/gridqueue/longitudinal.py -src/gridqueue/quality.py -src/gridqueue/registry.py -src/gridqueue/schema.py -src/gridqueue.egg-info/PKG-INFO -src/gridqueue.egg-info/SOURCES.txt -src/gridqueue.egg-info/dependency_links.txt -src/gridqueue.egg-info/entry_points.txt -src/gridqueue.egg-info/requires.txt -src/gridqueue.egg-info/top_level.txt -src/gridqueue/adapters/__init__.py -src/gridqueue/adapters/_ptpiree.py -src/gridqueue/adapters/base.py -src/gridqueue/adapters/es_edistribucion.py -src/gridqueue/adapters/ie_esbnetworks.py -src/gridqueue/adapters/pl_boryszew.py -src/gridqueue/adapters/pl_energa.py -src/gridqueue/adapters/pl_pse.py -src/gridqueue/adapters/pl_stoen.py -src/gridqueue/adapters/pl_tauron.py -src/gridqueue/adapters/pt_eredes.py -src/gridqueue/adapters/uk_nationalgrid.py -tests/test_adapters.py -tests/test_analysis.py -tests/test_es_ie.py -tests/test_geoloc.py -tests/test_geoloc_wspolrzedne.py -tests/test_layout.py -tests/test_longitudinal.py -tests/test_pse_energa.py -tests/test_pt_eredes.py -tests/test_quality.py -tests/test_schema.py \ No newline at end of file diff --git a/src/gridqueue.egg-info/dependency_links.txt b/src/gridqueue.egg-info/dependency_links.txt deleted file mode 100644 index 8b13789..0000000 --- a/src/gridqueue.egg-info/dependency_links.txt +++ /dev/null @@ -1 +0,0 @@ - diff --git a/src/gridqueue.egg-info/entry_points.txt b/src/gridqueue.egg-info/entry_points.txt deleted file mode 100644 index 145c7b5..0000000 --- a/src/gridqueue.egg-info/entry_points.txt +++ /dev/null @@ -1,2 +0,0 @@ -[console_scripts] -gridqueue = gridqueue.cli:main diff --git a/src/gridqueue.egg-info/requires.txt b/src/gridqueue.egg-info/requires.txt deleted file mode 100644 index 686aa45..0000000 --- a/src/gridqueue.egg-info/requires.txt +++ /dev/null @@ -1,8 +0,0 @@ -pandas>=2.0 -pdfplumber>=0.11 -requests>=2.31 -pyarrow>=14 -openpyxl>=3.1 - -[test] -pytest>=8.0 diff --git a/src/gridqueue.egg-info/top_level.txt b/src/gridqueue.egg-info/top_level.txt deleted file mode 100644 index b96d48d..0000000 --- a/src/gridqueue.egg-info/top_level.txt +++ /dev/null @@ -1 +0,0 @@ -gridqueue diff --git a/src/gridqueue/__init__.py b/src/gridqueue/__init__.py index e65b49a..7c34b36 100644 --- a/src/gridqueue/__init__.py +++ b/src/gridqueue/__init__.py @@ -1,10 +1,10 @@ -"""gridqueue -- harmonizator ustawowych ujawnień przyłączeniowych do sieci -elektroenergetycznej. +"""gridqueue -- harmonizer of statutory grid connection disclosures for the +electrical power network. -Narzędzie sprowadza publikacje operatorów systemów dystrybucyjnych, wymagane -art. 7 ust. 8l ustawy -- Prawo energetyczne, do jednego przetwarzalnego schematu. -Wartość narzędzia jest sprawdzalna przez inspekcję: albo dokument staje się -zbiorem wierszy o zmierzonej dokładności, albo nie. +The tool brings publications of distribution system operators, required under +Article 7(8l) of the Energy Law Act, to a single processable schema. +The value of the tool is verifiable by inspection: either the document becomes +a set of rows of measured accuracy, or it does not. """ from .schema import ( # noqa: F401 diff --git a/src/gridqueue/adapters/_ptpiree.py b/src/gridqueue/adapters/_ptpiree.py index bc39486..5489e45 100644 --- a/src/gridqueue/adapters/_ptpiree.py +++ b/src/gridqueue/adapters/_ptpiree.py @@ -1,27 +1,26 @@ -"""Wspólny szablon PTPiREE/PSE dla ujawnień z art. 7 ust. 8l pkt 1), 3) i 4). +"""Shared PTPiREE/PSE template for statutory disclosures under art. 7 ust. 8l pkt 1), 3) i 4). -Odkrycie, które to uzasadnia: arkusz PSE ``Informacje_publikowane_zgodnie_z_Art_7_ -ust_8l_ustawy_PE`` ma zakładkę "Listy rozwijane", a w niej listę wartości pola +The discovery that justifies this: the PSE spreadsheet ``Informacje_publikowane_zgodnie_z_Art_7_ +ust_8l_ustawy_PE`` has a tab "Listy rozwijane", and on it a list of values for the field "OSD/OSP": Energa-Operator S.A., ENEA Operator Sp. z o.o., TAURON Dystrybucja S.A., -PGE Dystrybucja S.A., Stoen Operator Sp. z o.o., PSE S.A. Szablon nie jest więc -formularzem jednego przedsiębiorstwa, tylko UZGODNIONYM WZORCEM BRANŻOWYM dla -sześciu największych operatorów. Publikacja Energa-Operatora (PDF) realizuje ten -sam wzorzec, co arkusz PSE (XLSX) -- różni się nośnikiem i dwiema kolumnami -brzegowymi, nie treścią. +PGE Dystrybucja S.A., Stoen Operator Sp. z o.o., PSE S.A. The template is therefore not +a form for a single company, but an AGREED INDUSTRY TEMPLATE for the six largest +operators. The Energa-Operator publication (PDF) implements the same template as the PSE +spreadsheet (XLSX): it differs in medium and two boundary columns, not in content. -Kolumny logiczne poniżej są tym wzorcem. Adapter konkretnego publikującego ma -jedno zadanie: powiedzieć, która kolumna FIZYCZNA jego dokumentu odpowiada której -kolumnie logicznej. Odwzorowanie na 21-polowy schemat jest wspólne, więc różnica -między publikującymi zostaje tam, gdzie jest naprawdę -- w układzie dokumentu. +The logical columns below are this template. The adapter for a given publisher has +one task: to say which PHYSICAL column of its document corresponds to which logical +column. The mapping onto the 21-field schema is shared, so the difference +between publishers stays where it really is: in the document layout. -Zmierzone układy fizyczne (odczytane z nagłówków, nie założone): +Measured physical layouts (read from headers, not assumed): PSE (XLSX, 27 kolumn): id_obiektu, nazwa_obiektu, osd_osp, podmiot, ... ENERGA (PDF, 28 kolumn): lp, id_obiektu, osd_osp, podmiot, ..., uwagi -Od kolumny "osd_osp" obie numeracje się pokrywają: PSE ma z przodu dwie kolumny -tożsamości (ID + nazwa obiektu), Energa jedną (ID) poprzedzoną liczbą porządkową, -a na końcu dokłada kolumnę "UWAGI". +From the "osd_osp" column onward both numberings coincide: PSE has two identity +columns at the front (ID + object name), Energa one (ID) preceded by a sequence +number, and at the end adds the "UWAGI" column. """ from __future__ import annotations @@ -33,16 +32,16 @@ from .base import harmonize_klasa, harmonize_status -#: Rozdzielacze wielu miejsc przyłączenia w jednej komórce mocy. +#: Separators for multiple connection points within a single capacity cell. _ROZDZ_MOC = re.compile(r"[\n\r;]+") def _rozbij_moc(value: Any) -> list[str]: - """Rozbij komórkę mocy na składowe dla wielu miejsc przyłączenia. + """Split a capacity cell into components for multiple connection points. - Liczba zwykła zwracana jest jako jedna składowa. Łańcuch rozdzielany jest po - złamaniu linii i średniku, i NIE po spacji, bo spacja jest u publikujących - separatorem tysięcznym. + A plain number is returned as a single component. A string is split on + line breaks and semicolons, and NOT on spaces, because publishers use the + space as the thousands separator. """ if value is None: return [] @@ -53,7 +52,7 @@ def _rozbij_moc(value: Any) -> list[str]: __all__ = ["LOGICAL", "PSE_XLSX_LAYOUT", "ENERGA_PDF_LAYOUT", "to_schema", "stan_na"] -#: kolumny logiczne wzorca PTPiREE/PSE +#: logical columns of the PTPiREE/PSE template LOGICAL: tuple[str, ...] = ( "lp", "id_obiektu", @@ -86,7 +85,7 @@ def _rozbij_moc(value: Any) -> list[str]: "uwagi", ) -#: fizyczny indeks kolumny -> kolumna logiczna. Arkusz PSE, 27 kolumn. +#: physical column index -> logical column. PSE spreadsheet, 27 columns. PSE_XLSX_LAYOUT: dict[int, str] = { 0: "id_obiektu", 1: "nazwa_obiektu", 2: "osd_osp", 3: "podmiot", 4: "lokalizacja", 5: "poziom_napiecia", 6: "wiele_miejsc", 7: "rodzaj", @@ -99,7 +98,7 @@ def _rozbij_moc(value: Any) -> list[str]: 26: "data_wygasniecia_umowy", } -#: fizyczny indeks kolumny -> kolumna logiczna. PDF Energa-Operatora, 28 kolumn. +#: physical column index -> logical column. Energa-Operator PDF, 28 columns. ENERGA_PDF_LAYOUT: dict[int, str] = { 0: "lp", 1: "id_obiektu", 2: "osd_osp", 3: "podmiot", 4: "lokalizacja", 5: "poziom_napiecia", 6: "wiele_miejsc", 7: "rodzaj", @@ -112,7 +111,7 @@ def _rozbij_moc(value: Any) -> list[str]: 26: "data_wygasniecia_umowy", 27: "uwagi", } -#: pola opcjonalne schematu, które wzorzec wypełnia u KAŻDEGO publikującego +#: optional schema fields that the template populates for EVERY publisher DECLARED_FIELDS: tuple[str, ...] = ( "id_wniosku", "lokalizacja_tekst", "poziom_napiecia", "klasa_zasobu", "moc_wprowadzana", "moc_pobierana", "status_procesu", "data_wniosku", @@ -120,34 +119,34 @@ def _rozbij_moc(value: Any) -> list[str]: "data_energizacji", "data_publikacji", ) -#: rozszerzenia poza 21-polowym schematem, wspólne dla wzorca +#: extensions beyond the 21-field schema, shared by the template DECLARED_EXTENSIONS: dict[str, str] = { - "_podmiot": "nazwa podmiotu ubiegającego się o przyłączenie", - "_osd_osp": "operator wskazany w dokumencie (pole wzorca)", - "_nazwa_obiektu": "nazwa własna obiektu (tylko PSE)", - "_wiele_miejsc": "czy wniosek dotyczy wielu miejsc przyłączenia / poziomów napięć", - "_rodzaj_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status etapu projektu tak, jak w dokumencie", - "_data_zaliczki": "data wpłaty zaliczki", - "_data_utraty_waznosci": "data utraty ważności / rezygnacji z warunków", - "_data_rozwiazania_umowy": "data rozwiązania/wypowiedzenia/odstąpienia od umowy", - "_data_wygasniecia_umowy": "data wygaśnięcia umowy z mocy prawa", - "_mz_pv": "moc zainstalowana PV [kW]", - "_mz_fw": "moc zainstalowana FW [kW]", - "_mz_mee_rozladowania": "moc zainstalowana magazynu -- rozładowanie [kW]", - "_mz_mee_ladowania": "moc zainstalowana magazynu -- ładowanie [kW]", - "_mz_odb": "moc zainstalowana odbioru [kW]", - "_mz_inne": "moc zainstalowana pozostałych źródeł [kW]", - "_uwagi": "kolumna UWAGI (tylko Energa)", - "_lp_dokumentu": "liczba porządkowa w dokumencie źródłowym", - "_encja": "WNIOSEK albo WEZEL -- którą encję obowiązku realizuje wiersz", + "_podmiot": "name of the entity applying for connection", + "_osd_osp": "operator indicated in the document (template field)", + "_nazwa_obiektu": "proper name of the object (PSE only)", + "_wiele_miejsc": "whether the application concerns multiple connection points / voltage levels", + "_rodzaj_raw": "installation type as given in the document", + "_status_raw": "project stage status as given in the document", + "_data_zaliczki": "date the deposit was paid", + "_data_utraty_waznosci": "date the connection conditions expired / were withdrawn", + "_data_rozwiazania_umowy": "date the agreement was terminated / cancelled / withdrawn from", + "_data_wygasniecia_umowy": "date the agreement expired by operation of law", + "_mz_pv": "installed PV capacity [kW]", + "_mz_fw": "installed FW capacity [kW]", + "_mz_mee_rozladowania": "installed storage capacity: discharge [kW]", + "_mz_mee_ladowania": "installed storage capacity: charge [kW]", + "_mz_odb": "installed consumption capacity [kW]", + "_mz_inne": "installed capacity of other sources [kW]", + "_uwagi": "UWAGI column (Energa only)", + "_lp_dokumentu": "sequence number in the source document", + "_encja": "WNIOSEK or WEZEL: which entity of the duty the row implements", } _NULLISH = {"", "-", "--", "---", "nan", "none", "brak", "nie dotyczy", "n/d"} def _blank(v: Any) -> bool: - """Czy wartość jest pusta. ``nan`` jest prawdziwe, więc ``if v`` nie wystarcza.""" + """Whether the value is blank. ``nan`` is truthy, so ``if v`` is not enough.""" if v is None: return True if isinstance(v, float) and v != v: @@ -165,19 +164,20 @@ def _clean(v: Any) -> Optional[str]: def _volt(v: Any) -> Optional[str]: - """Poziom napięcia w postaci kanonicznej " kV". - - Wzorzec dopuszcza WIELOKROTNOŚĆ ("110; 220; 400") -- tak stanowi lista - rozwijana arkusza PSE. Zapisujemy pełną treść, bo wybranie jednej wartości - byłoby utratą danej; konsekwencją jest to, że detektor sprzeczności typu - (``looks_like_voltage``) oznacza takie wiersze -- i tak ma być, bo miara - ma pozostać PORÓWNYWALNA z wcześniejszymi pomiarami, a nie wygodna. - - Wartości KLASOWE ("SN", "nn", "WN") nie są liczbami kilowoltów i nie wolno - dopisywać im jednostki: "SN kV" nie znaczy nic. Panel czterech dotychczasowych - publikujących zapisuje je jako samo "SN", więc trzymamy tę samą konwencję -- - inaczej ten sam poziom napięcia miałby dwie różne postaci w jednym panelu - i pole przestałoby być porównywalne między publikującymi. + """Voltage level in canonical form " kV". + + The template allows MULTIPLICITY ("110; 220; 400"): that is what the drop-down + list of the PSE spreadsheet provides for. We record the full content, because + choosing a single value would lose data; the consequence is that the + contradiction detector of type (``looks_like_voltage``) flags such rows; and + that is how it should be, because the metric must remain COMPARABLE with + earlier measurements, not convenient. + + CLASS values ("SN", "nn", "WN") are not numbers of kilovolts and must not have + a unit appended to them: "SN kV" means nothing. The panel of the four + publishers so far records them as plain "SN", so we keep the same convention; + otherwise the same voltage level would have two different forms within a single + panel and the field would stop being comparable between publishers. """ s = _clean(v) if s is None: @@ -190,18 +190,17 @@ def _volt(v: Any) -> Optional[str]: s = re.sub(r"\s+", " ", s).strip(" ;") if not s: return None - # liczby całkowite bez ".0" po przejściu przez pandas/openpyxl + # integers without ".0" after going through pandas/openpyxl s = re.sub(r"\b(\d+)\.0\b", r"\1", s) return f"{s} kV" def stan_na(text: str) -> Optional[str]: - """Data, na którą publikujący sporządził ujawnienie. + """The date as of which the publisher prepared the disclosure. - Postać bywa różna nawet u jednego publikującego: "Stan na 30.06.2026 r." - w zestawieniu wniosków i "(STAN NA DZIEŃ 31.08.2026 ROKU)" wersalikami na - stronie tytułowej ujawnienia węzłowego -- stąd dopasowanie bez rozróżniania - wielkości liter. + The form varies even within a single publisher: "Stan na 30.06.2026 r." + in the list of applications and "(STAN NA DZIEŃ 31.08.2026 ROKU)" in capitals on + the title page of the node disclosure: hence the case-insensitive match. """ m = re.search(r"stan\s+na\s+(?:dzie[nń]\s+)?(\d{1,2}\.\d{1,2}\.\d{4})", text or "", re.IGNORECASE) @@ -209,10 +208,10 @@ def stan_na(text: str) -> Optional[str]: def to_schema(raw, *, publisher_key: str, data_publikacji: Optional[str]): - """Odwzoruj ramkę w kolumnach logicznych wzorca na 21-polowy schemat. + """Map a frame in the template's logical columns onto the 21-field schema. - ``raw`` ma kolumny z ``LOGICAL`` (brakujące mogą nie występować). Jednostka - mocy we wzorcu to MW -- sprowadzamy do kanonicznych kW. + ``raw`` has columns from ``LOGICAL`` (missing ones may not be present). The + capacity unit in the template is MW: we convert to canonical kW. """ import pandas as pd @@ -222,21 +221,23 @@ def col(name: str): return pd.Series([None] * len(raw), index=raw.index, dtype="object") def mw(name: str): - """Moc z kolumny SUROWEJ, z obsługą wielu miejsc przyłączenia. - - Pułapka, która zawyżyła jeden wiersz o trzy rzędy wielkości: gdy wniosek - dotyczy kilku miejsc przyłączenia (kolumna "Wiele miejsc przyłączenia" - = TAK), publikujący wpisuje do jednej komórki kilka wartości rozdzielonych - ZŁAMANIEM LINII, czasem dodatkowo średnikiem. ``_clean`` zamieniał złamanie - linii na spację, a ``canonical_power_kw`` traktuje spację jako separator - tysięczny, więc "129⏎240" (129 MW + 240 MW) stawało się 129 240 MW. - W edycji, w której publikujący dopisał średniki, ta sama komórka nie - konwertowała się wcale i pole zostawało puste, czyli ten sam defekt - dawał raz absurd, raz milczący brak. - - Zwracamy SUMĘ składowych, bo pole schematu opisuje moc wniosku, a wniosek - jest jeden. Składowe zachowujemy w rozszerzeniu, żeby nie zgubić podziału - na miejsca przyłączenia. + """Capacity from the RAW column, with support for multiple connection points. + + The trap that inflated one row by three orders of magnitude: when an + application concerns several connection points (column "Wiele miejsc + przyłączenia" = TAK), the publisher enters into a single cell several + values separated by a LINE BREAK, sometimes additionally by a semicolon. + ``_clean`` turned the line break into a space, and ``canonical_power_kw`` + treats a space as the thousands separator, so "129⏎240" (129 MW + 240 MW) + became 129 240 MW. In the edition where the publisher added semicolons, + the same cell did not convert at all and the field stayed blank, meaning + the same defect produced an absurdity in one case, and a silent gap in the + other. + + We return the SUM of the components, because the schema field describes + the capacity of the application, and there is one application. We keep the + components in the extension, so as not to lose the breakdown by + connection point. """ if name not in raw.columns: return (pd.Series([None] * len(raw), index=raw.index, dtype="object"), @@ -259,17 +260,17 @@ def mw(name: str): pd.Series(skladowe, index=raw.index, dtype="object")) def dcol(name: str): - """Data z kolumny SUROWEJ, bez przejścia przez ``_clean``. - - Pułapka, która kosztowała wszystkie daty PSE: nośnikiem PSE jest XLSX, - a openpyxl zwraca komórki daty jako ``Timestamp``. ``_clean`` robi na - wartości ``str()``, więc Timestamp zamieniał się w "2023-08-07 00:00:00", - a ``canonical_date`` ma wzorce ZAKOTWICZONE i takiego łańcucha nie - dopasowuje -- zwracał None. Efekt: pola ``data_*`` pustoszały dla całego - publikującego, a reguły jakości R1 i R2 (monotoniczność dat, dwuletnia - ważność warunków) nie miały na czym pracować i pokazywały zero naruszeń. - ``canonical_date`` sam obsługuje ``datetime``/``date``, więc wystarczy - podać mu wartość nietkniętą. + """Date from the RAW column, without going through ``_clean``. + + The trap that cost all the PSE dates: the PSE medium is XLSX, and + openpyxl returns date cells as ``Timestamp``. ``_clean`` calls ``str()`` + on the value, so a Timestamp turned into "2023-08-07 00:00:00", and + ``canonical_date`` has ANCHORED patterns and does not match such a string: + it returned None. Effect: the ``data_*`` fields went empty for the entire + publisher, and quality rules R1 and R2 (date monotonicity, the two-year + validity of conditions) had nothing to work on and showed zero violations. + ``canonical_date`` itself handles ``datetime``/``date``, so it is enough to + pass it the untouched value. """ if name not in raw.columns: return pd.Series([None] * len(raw), index=raw.index, dtype="object") @@ -278,10 +279,10 @@ def dcol(name: str): out = pd.DataFrame(index=raw.index) ident = col("id_obiektu") lp = col("lp") - # Uwaga na pułapkę: ``Series.map`` zamienia zwrócone ``None`` na ``nan``, - # a ``nan`` jest w Pythonie PRAWDZIWE. Test pustości musi być jawny, inaczej - # zastępnik identyfikatora nigdy się nie uruchomi, a 866 z 876 wierszy PSE - # (te z "-" w polu ID Obiektu) zostaje bez identyfikatora. + # Watch out for the trap: ``Series.map`` turns a returned ``None`` into ``nan``, + # and ``nan`` is TRUTHY in Python. The emptiness test must be explicit, otherwise + # the identifier fallback never runs, and 866 of 876 PSE rows + # (those with "-" in the ID Obiektu field) are left without an identifier. out["id_wniosku"] = [ i if not _blank(i) else f"{publisher_key}:poz:{(str(l).rstrip('.') if not _blank(l) else str(k + 1))}" @@ -298,11 +299,11 @@ def dcol(name: str): out["data_odmowy"] = dcol("data_odmowy") out["powod_odmowy"] = col("uzasadnienie_odmowy") out["data_umowy"] = dcol("data_umowy") - # Energa zapisuje planowaną energizację NIERÓWNOŚCIĄ ("po 30.06.2026"), a nie - # datą. ``canonical_date`` jest zakotwiczony na początku łańcucha, więc słusznie - # zwraca None -- zapisanie 2026-06-30 gubiłoby słowo "po" i zamieniało termin - # dolny na termin dokładny. Żeby jednak nie utracić danej, surowy tekst idzie - # do rozszerzenia, a pole schematu zostaje puste. + # Energa records the planned energization as an INEQUALITY ("po 30.06.2026"), + # not a date. ``canonical_date`` is anchored at the start of the string, so it + # rightly returns None: recording 2026-06-30 would lose the word "po" and turn + # a lower bound into an exact date. However, to avoid losing the data, the raw + # text goes into the extension, and the schema field remains blank. _energ = col("data_energizacji") out["data_energizacji"] = dcol("data_energizacji") out["_energizacja_tekst"] = [ diff --git a/src/gridqueue/adapters/base.py b/src/gridqueue/adapters/base.py index 3ee65ec..c9ad1ce 100644 --- a/src/gridqueue/adapters/base.py +++ b/src/gridqueue/adapters/base.py @@ -1,14 +1,15 @@ -"""Wspólny interfejs adapterów publikujących. +"""Common interface for publishing adapters. -Adapter jest jedynym miejscem, w którym wolno wiedzieć cokolwiek o układzie -konkretnego dokumentu. Na zewnątrz każdy adapter wygląda tak samo: +The adapter is the only place that is allowed to know anything about the layout +of a specific document. From the outside, every adapter looks the same: adapter.parse(source) -> ParseResult(frame, report) -``frame`` jest w schemacie (moduł ``schema``), ``report`` jest raportem jakości -wydobycia -- liczbami, nie wyjątkami. Adapter DEKLARUJE, które pola opcjonalne -wypełnia i jakie rozszerzenia poza 21-polowym schematem wnosi; deklaracja jest -częścią kontraktu, bo pokrycie pól jest tu wynikiem pomiaru, a nie założeniem. +``frame`` is in the schema (``schema`` module), ``report`` is a quality report of +the extraction: numbers, not exceptions. The adapter DECLARES which optional fields +it fills in and what extensions beyond the 21-field schema it contributes; the declaration +is part of the contract, because field coverage here is the result of measurement, not +an assumption. """ from __future__ import annotations @@ -25,28 +26,28 @@ @dataclass class ParseResult: - frame: Any # pandas.DataFrame w schemacie + frame: Any # pandas.DataFrame in the schema report: dict[str, Any] = field(default_factory=dict) class Adapter: - """Klasa bazowa adaptera.""" + """Base adapter class.""" - #: identyfikator publikującego + #: publisher identifier publisher: str = "" - #: jurysdykcja (kod kraju) + #: jurisdiction (country code) jurisdiction: str = "" - #: pola schematu, które ten publikujący ujawnia (deklaracja, weryfikowana pomiarem) + #: schema fields that this publisher discloses (declaration, verified by measurement) declared_fields: tuple[str, ...] = () - #: rozszerzenia poza 21-polowym schematem -> opis; w ramce z przedrostkiem "_" + #: extensions beyond the 21-field schema -> description; in the frame with a "_" prefix declared_extensions: dict[str, str] = {} - #: wzorce nazw plików / treści, po których wykrywamy publikującego + #: filename / content patterns used to detect the publisher detect_patterns: tuple[str, ...] = () - def parse(self, source) -> ParseResult: # pragma: no cover - interfejs + def parse(self, source) -> ParseResult: # pragma: no cover - interface raise NotImplementedError - # -- pomoc wspólna ----------------------------------------------------- + # -- shared helpers ----------------------------------------------------- def blank_frame(self, n: int): import pandas as pd @@ -56,7 +57,7 @@ def blank_frame(self, n: int): ) def finalize(self, df, *, document: str = ""): - """Domknij ramkę: kolejność kolumn, metadane, typy kanoniczne.""" + """Close out the frame: column order, metadata, canonical types.""" import pandas as pd for c in FIELDS + META_COLUMNS: @@ -80,7 +81,7 @@ def declaration(self) -> dict[str, Any]: # -------------------------------------------------------------------------- -# harmonizacja słowników kontrolowanych +# harmonization of controlled vocabularies # -------------------------------------------------------------------------- @@ -91,22 +92,22 @@ def norm_text(s: Any) -> str: if s is None: return "" s = str(s).replace("\n", " ") - # znaki z kreska nie rozkladaja sie przez NFKD (l/L, d/D, o/O) -- mapujemy wprost + # characters with a stroke do not decompose via NFKD (l/L, d/D, o/O): we map them directly s = s.translate(_STROKE) s = unicodedata.normalize("NFKD", s) s = "".join(ch for ch in s if not unicodedata.combining(ch)) return re.sub(r"\s+", " ", s).strip().lower() -#: mapowanie oznaczeń rodzaju instalacji na słownik kontrolowany. -#: Skróty TAURONA pochodzą z legendy na ostatniej stronie jego dokumentu. +#: mapping of installation type designations to the controlled vocabulary. +#: TAURON's abbreviations come from the legend on the last page of its document. _KLASA_MAP: tuple[tuple[str, str], ...] = ( (r"^pv$|fotowolta|^solar$", "PV"), (r"^fw$|^mfw$|farma wiatrow|^wind$", "FW"), (r"^ew$|elektrownia wodn|^hydro$", "EW"), (r"biogaz|biomas|^jbm$", "BIOGAZ"), - # legenda TAURONA (ostatnia strona dokumentu): BG blok gazowy, BGP blok - # gazowo-parowy, SG silnik gazowy -- to sa jednostki GAZOWE, nie biogazowe + # TAURON legend (last page of the document): BG gas block, BGP gas-steam + # block, SG gas engine: these are GAS units, not biogas ones (r"^bg$|^bgp$|^sg$|blok gazow|silnik gazow", "GAZ"), (r"^jw$|jednostka weglow", "WEGIEL"), (r"^mee|magazyn energii|^bess$|^battery", "BESS"), @@ -123,11 +124,12 @@ def norm_text(s: Any) -> str: (r"wniosek wycofan|wycofan", "WNIOSEK_WYCOFANY"), (r"utracil\w* waznosc|utrata waznosci|wygasl", "WARUNKI_WYGASLE"), (r"odmow|refus", "ODMOWA"), - # "rozwiazan" bez dookreslenia: lista rozwijana wspolnego szablonu PTPiREE/PSE - # deklaruje status "UMOWA O PRZYŁĄCZENIE rozwiązana", ktorego nie lapaly ani - # "umowa rozwiazan" (brak przyleglosci), ani "rozwiazanie umowy". Bez tej - # poprawki rozwiazana umowa spadala na regule "umowa o przylaczenie" i byla - # raportowana jako UMOWA_OBOWIAZUJACA -- czyli status odwrotny do prawdziwego. + # "rozwiazan" without further determination: the drop-down list of the common + # PTPiREE/PSE template declares the status "UMOWA O PRZYŁĄCZENIE rozwiązana", + # which was not caught by either "umowa rozwiazan" (lacking adjacency), or + # "rozwiazanie umowy". Without this fix, a terminated agreement fell under + # the "umowa o przylaczenie" rule and was reported as UMOWA_OBOWIAZUJACA: + # i.e., the opposite status of the true one. (r"rozwiazan", "UMOWA_ROZWIAZANA"), (r"obiekt przylaczony|recently connected|^connected$|przylaczon", "PRZYLACZONY"), (r"umowa o przylaczenie|umowa obowiazuj|accepted not yet connected|^accepted", "UMOWA_OBOWIAZUJACA"), diff --git a/src/gridqueue/adapters/es_edistribucion.py b/src/gridqueue/adapters/es_edistribucion.py index fe59935..c577c28 100644 --- a/src/gridqueue/adapters/es_edistribucion.py +++ b/src/gridqueue/adapters/es_edistribucion.py @@ -1,52 +1,52 @@ -"""Adapter: e-Distribución Redes Digitales (ES), zdolność przyłączeniowa węzłów. - -Dlaczego to źródło jest dla pakietu ważniejsze niż kolejny plik tabelaryczny --------------------------------------------------------------------------- -Manuskrypt wskazywał jako najmocniejszy brakujący test **drugą jurysdykcję -publikującą dokumenty przeznaczone do druku**: dotąd oba źródła zagraniczne -wydawały dane już tabelaryczne, więc przenoszalność wykazano na przypadku -łatwiejszym niż polski. To źródło ten brak zamyka. Publikujący wydaje **PDF -miesięczny**, w serii obejmującej lata 2023-2025, na podstawie art. 33 ust. 9 -ustawy 24/2013, art. 5 ust. 4 dekretu 1183/2020 oraz art. 12 okólnika 1/2021 -regulatora CNMC, konstrukcja prawna jest więc taka sama jak polska: obowiązek -ustawowy, stała częstość, format pozostawiony publikującemu. - -Układ strony niesie linie wektorowe tabeli, więc wydobycie opiera się na nich, -a nie na odstępach między słowami. - -Semantyka kolumn ustalona arytmetyką, nie nagłówkiem ----------------------------------------------------- -Nagłówek ma komórki scalone w dwóch poziomach i sugeruje, że kolumny „Con -permiso de AyC" oraz „En trámite con capacidad" należą do grupy mocy przyjętej -i nierozstrzygniętej. **Jest to mylące.** Rozstrzyga arytmetyka dokumentu: - -* jedenaście podkolumn, dziewięć pozycji stacji oraz te dwie, **sumuje się do - mocy ZAJĘTEJ**, dokładnie, w 1838 z 1838 wierszy, w obu sprawdzonych wydaniach; -* rozbicie technologiczne sumuje się do mocy **przyjętej i nierozstrzygniętej** - we wszystkich wierszach o niezerowej wartości. - -Obie grupy są więc SKŁADNIKAMI mocy zajętej, a nie jej alternatywnymi -rozbiciami: część węzłów ma wypełnione tylko pozycje, część tylko dwie -pozostałe, a część obie, i dopiero suma wszystkich jedenastu zamyka się do -wartości łącznej. - -Ma to wartość wykraczającą poza odwzorowanie pól. Dla tego publikującego **nie -istnieje zbiór odniesienia odczytany niezależnie od parsera**, więc dokładności -wydobycia nie da się zmierzyć w sposób, w jaki zmierzono ją dla publikujących -polskich. Domknięcie sumy jest tu zastępczym, słabszym, ale sprawdzalnym -świadectwem: aby suma jedenastu komórek zgadzała się z dwunastą, wszystkie -dwanaście musi być odczytane poprawnie. Na dwóch wydaniach daje to 3676 -niezależnych sprawdzeń, wszystkie domknięte. Jest to świadectwo spójności -odczytu, NIE pomiar dokładności wobec wzorca, i tak należy je czytać. - -Jednostki ---------- -Publikujący podaje moce w **MW mocy czynnej**, więc przeliczenie na kanoniczne -kW jest zwykłą zmianą rzędu wielkości, bez założeń. Różni to to źródło od -portugalskiego, które podaje moc pozorną w MVA i dlatego pola mocy nie wypełnia. - -Źródło podaje też **współrzędne geograficzne każdej podstacji**, czego nie robi -żaden publikujący polski. +"""Adapter: e-Distribución Redes Digitales (ES), connection capacity of nodes. + +Why this source matters more to the package than another tabular file +--------------------------------------------------------------------- +The manuscript identified as the strongest missing test **a second jurisdiction +publishing documents intended for print**: so far both foreign sources +published data that was already tabular, so portability was demonstrated on a case +easier than the Polish one. This source closes that gap. The publisher issues a **monthly +PDF**, in a series covering the years 2023-2025, pursuant to Art. 33(9) +of Act 24/2013, Art. 5(4) of Decree 1183/2020, and Art. 12 of CNMC Circular 1/2021, +so the legal construction is the same as in Poland: a statutory +duty, fixed frequency, format left to the publisher. + +The page layout carries the vector lines of the table, so extraction relies on them, +not on the spacing between words. + +Column semantics fixed by arithmetic, not by the header +--------------------------------------------------------- +The header has cells merged across two levels and suggests that the columns „Con +permiso de AyC" and „En trámite con capacidad" belong to the group of accepted and +unresolved capacity. **This is misleading.** The arithmetic of the document is decisive: + +* eleven subcolumns, nine station positions plus these two, **sum up to the + OCCUPIED capacity**, exactly, in 1838 of 1838 rows, in both editions checked; +* the technology breakdown sums up to the **accepted and unresolved** capacity + in all rows with a nonzero value. + +Both groups are therefore COMPONENTS of the occupied capacity, not alternative +breakdowns of it: some nodes have only the positions filled in, some only the two +remaining ones, and some both, and only the sum of all eleven closes to +the total value. + +This has value beyond the mapping of fields. For this publisher there **is no +reference set read independently of the parser**, so the accuracy of +extraction cannot be measured the way it was measured for the Polish +publishers. The arithmetic closure is here a substitute, weaker but checkable +piece of evidence: for the sum of eleven cells to match the twelfth, all +twelve must be read correctly. Over two editions this gives 3676 +independent checks, all closed. This is evidence of consistency of +reading, NOT a measurement of accuracy against a reference, and it should be read as such. + +Units +----- +The publisher states capacities in **MW of active power**, so converting to the canonical +kW is a plain change of order of magnitude, without assumptions. This differentiates this source from +the Portuguese one, which states apparent power in MVA and therefore does not populate the capacity field. + +The source also provides **geographic coordinates for each substation**, which no +Polish publisher does. """ from __future__ import annotations @@ -59,14 +59,14 @@ PUBLISHER = "e-Distribución Redes Digitales S.L.U." JURISDICTION = "ES" -#: Indeksy kolumn w wydobytej tabeli. Ustalone na wydaniu z sierpnia 2025 -#: i zweryfikowane sumami; patrz nagłówek modułu. +#: Column indices in the extracted table. Fixed on the August 2025 edition +#: and verified by sums; see the module header. K_WSPOLNOTA, K_PROWINCJA, K_GMINA, K_PODSTACJA = 0, 1, 2, 3 K_SZEROKOSC, K_DLUGOSC, K_NAPIECIE = 4, 5, 6 K_DOSTEPNA, K_ZAJETA_TOTAL = 7, 8 -K_POZYCJE = tuple(range(9, 18)) # rozbicie mocy zajętej po pozycjach stacji +K_POZYCJE = tuple(range(9, 18)) # breakdown of occupied capacity by station position K_ZAJETA_Z_POZWOLENIEM, K_ZAJETA_W_TOKU = 18, 19 -K_PRZYJETA_TOTAL = 20 # przyjęta i nierozstrzygnięta +K_PRZYJETA_TOTAL = 20 # accepted and unresolved K_TECHNOLOGIE = (21, 22, 23, 24, 25) K_SCC, K_WEZEL_PRZESYLOWY, K_KOMENTARZ = 26, 27, 28 SZEROKOSC_WIERSZA = 29 @@ -75,7 +75,7 @@ def _liczba(v) -> float | None: - """Liczba w zapisie hiszpańskim: przecinek dziesiętny, kropka tysięcy.""" + """Number in Spanish notation: decimal comma, thousands dot.""" if v is None: return None s = str(v).strip().replace("\xa0", "").replace(" ", "") @@ -89,7 +89,7 @@ def _liczba(v) -> float | None: def _mw_na_kw(v) -> float | None: - """MW mocy czynnej -> kW mocy czynnej. Zmiana rzędu, nie wielkości fizycznej.""" + """MW of active power -> kW of active power. A change of order of magnitude, not of physical quantity.""" x = _liczba(v) return None if x is None else x * 1000.0 @@ -97,25 +97,25 @@ def _mw_na_kw(v) -> float | None: def _data_z_nazwy(nazwa: str) -> str | None: """'EDRD_Capacidad_de_Acceso_2025_08_01.pdf' -> '2025-08-01'. - Data brana jest z nazwy pliku, a nie ze strony tytułowej, bo nazwa jest - maszynowa i rozstrzygalna, a strona tytułowa podaje ją słownie po hiszpańsku. + The date is taken from the file name, not from the title page, because the name is + machine-readable and decidable, while the title page gives it in words, in Spanish. """ m = re.search(r"(\d{4})[_-](\d{2})[_-](\d{2})", nazwa) return f"{m.group(1)}-{m.group(2)}-{m.group(3)}" if m else None def suma_skladnikow_mocy_zajetej(wiersze) -> "tuple[int, int]": - """Ile wierszy domyka tożsamość arytmetyczną dokumentu. + """How many rows close the arithmetic identity of the document. - Jedenaście podkolumn mocy zajętej (dziewięć pozycji stacji plus „z - pozwoleniem" i „w toku") sumuje się do wartości łącznej. Funkcja zwraca - parę (domkniętych, wszystkich). + The eleven subcolumns of occupied capacity (nine station positions plus "with + permit" and "in progress") sum up to the total value. The function returns + a pair (closed, total). - Po co to jest: dla tego publikującego nie ma zbioru odniesienia odczytanego - niezależnie od parsera, więc dokładności wydobycia nie da się zmierzyć wobec - wzorca. Domknięcie sumy jest zastępczym świadectwem spójności odczytu - - słabszym niż wzorzec, ale sprawdzalnym na każdym wydaniu, bo wymaga - poprawnego odczytania wszystkich dwunastu komórek bloku. + What this is for: for this publisher there is no reference set read + independently of the parser, so the accuracy of extraction cannot be measured against + a reference. The arithmetic closure is a substitute piece of evidence of consistency of + reading, weaker than a reference, but checkable on every edition, because it requires + all twelve cells of the block to be read correctly. """ domkniete = 0 for w in wiersze: @@ -141,15 +141,15 @@ class EDistribucionAdapter(Adapter): "moc_dostepna", "moc_zarezerwowana", "ograniczenie_flaga", "data_publikacji", ) declared_extensions = { - "_wspolnota_autonomiczna": "wspólnota autonomiczna", - "_prowincja": "prowincja", - "_moc_przyjeta_nierozstrzygnieta_kw": "moc wniosków przyjętych i nierozstrzygniętych", - "_moc_zajeta_z_pozwoleniem_kw": "część mocy zajętej objęta pozwoleniem na przyłączenie", - "_moc_zajeta_w_toku_kw": "część mocy zajętej w toku postępowania", - "_rozbicie_technologiczne_kw": "moc nierozstrzygnięta w podziale na technologie", - "_rozbicie_pozycyjne_kw": "moc zajęta w podziale na pozycje stacji", - "_wezel_przesylowy": "węzeł sieci przesyłowej o największym oddziaływaniu", - "_komentarz": "komentarz publikującego", + "_wspolnota_autonomiczna": "autonomous community", + "_prowincja": "province", + "_moc_przyjeta_nierozstrzygnieta_kw": "capacity of accepted and unresolved applications", + "_moc_zajeta_z_pozwoleniem_kw": "part of the occupied capacity covered by a connection permit", + "_moc_zajeta_w_toku_kw": "part of the occupied capacity currently in proceedings", + "_rozbicie_technologiczne_kw": "unresolved capacity broken down by technology", + "_rozbicie_pozycyjne_kw": "occupied capacity broken down by station position", + "_wezel_przesylowy": "transmission network node with the greatest impact", + "_komentarz": "publisher's comment", } detect_patterns = (r"edrd[_ ]?capacidad", r"capacidad[_ ]de[_ ]acceso", r"e-?distribuci") @@ -191,8 +191,8 @@ def kom(i): poz = {i: _mw_na_kw(w[i]) for i in K_POZYCJE} rekordy.append({ - # Identyfikator musi rozróżniać poziomy napięcia tej samej podstacji: - # publikujący wydaje osobny wiersz dla każdego poziomu. + # The identifier must distinguish between voltage levels of the same substation: + # the publisher issues a separate row for each level. "id_wezla": f"{podstacja}|{napiecie}" if podstacja and napiecie else podstacja, "nazwa_wezla": podstacja, "lokalizacja_tekst": ", ".join(x for x in (kom(K_GMINA), kom(K_PROWINCJA)) if x) or None, @@ -220,20 +220,20 @@ def kom(i): notes = { "publikujacy": PUBLISHER, "jurysdykcja": JURISDICTION, - "tryb_wydania": "dokument przeznaczony do druku, wydanie miesięczne", + "tryb_wydania": "document intended for print, monthly edition", "stron": stron, "wierszy": int(len(df)), "wezlow_ograniczonych_przez_Scc": ograniczonych, "wierszy_bez_wspolrzednych": bez_wspolrzednych, "jednostka_mocy_zrodlowa": "MW", - "przeliczenie": "MW -> kW, obie wielkości to moc czynna", + "przeliczenie": "MW -> kW, both quantities are active power", "data_publikacji": data_pub, "tozsamosc_sumy_mocy_zajetej": f"{domkniete}/{sprawdzonych}", "uwaga_tozsamosc": ( - "Jedenaście podkolumn mocy zajętej sumuje się do wartości łącznej. " - "Jest to świadectwo SPÓJNOŚCI odczytu, nie pomiar dokładności wobec " - "wzorca odczytanego niezależnie od parsera, takiego wzorca dla tego " - "publikującego nie ma." + "The eleven subcolumns of occupied capacity sum up to the total value. " + "This is evidence of the CONSISTENCY of reading, not a measurement of accuracy against " + "a reference read independently of the parser; this publisher has no " + "such reference." ), } return ParseResult(frame=df, report=notes) diff --git a/src/gridqueue/adapters/ie_esbnetworks.py b/src/gridqueue/adapters/ie_esbnetworks.py index 7f254df..ca02478 100644 --- a/src/gridqueue/adapters/ie_esbnetworks.py +++ b/src/gridqueue/adapters/ie_esbnetworks.py @@ -1,28 +1,29 @@ -"""Adapter: ESB Networks (IE), mapa zdolności przyłączeniowej sieci. +"""Adapter: ESB Networks (IE), network connection capacity map. -Publikujący wydaje jeden arkusz obejmujący **całą sieć aż do poziomu stacji -SN/nn**, więc jest to najliczniejsze źródło w panelu i zarazem jedyne, które -schodzi poniżej poziomu stacji wysokiego napięcia. Jednostką wiersza jest grupa -transformatorów w stacji. +The publisher issues a single sheet covering **the entire network down to MV/LV +station level**, which makes it the most numerous source in the panel and also the +only one that goes below high-voltage station level. The row unit is a group of +transformers at a station. -Dwie jednostki w jednym źródle +Two units in one source ------------------------------ -Publikujący podaje stronę **odbiorczą w MVA** (moc pozorna), a stronę -**wytwórczą w MW** (moc czynna). Jednostką kanoniczną schematu jest kW mocy -czynnej, więc: - -* wartości wytwórcze są przeliczane (MW -> kW, ta sama wielkość fizyczna), -* wartości odbiorcze **nie są przeliczane** i trafiają do pól rozszerzenia - z jawnie zapisaną jednostką. - -Pole `moc_dostepna` niesie zatem dostępną moc **wytwórczą trwałą**, a nie sumę -obu stron. Zsumowanie MW z MVA dałoby liczbę bez sensu fizycznego, a wybór -jednej strony bez powiedzenia tego wprost byłby ukryciem decyzji. - -Źródło podaje współrzędne oraz dwie osobne flagi ograniczenia, dla strony -odbiorczej i wytwórczej. Do pola `ograniczenie_flaga` wchodzi **alternatywa -obu**, bo pole schematu jest jedno; obie wartości źródłowe pozostają -w rozszerzeniach. +The publisher gives the **demand side in MVA** (apparent power), and the +**generation side in MW** (active power). The canonical unit of the schema is kW +of active power, so: + +* generation values are converted (MW -> kW, the same physical quantity), +* demand values are **not converted** and go into extension fields + with the unit explicitly recorded. + +The `moc_dostepna` field therefore carries the available **firm generation** +capacity, not the sum of both sides. Summing MW with MVA would give a number with +no physical meaning, and choosing one side without saying so explicitly would be +hiding the decision. + +The source gives coordinates and two separate constraint flags, for the demand +side and the generation side. The `ograniczenie_flaga` field receives the +**disjunction of both**, because the schema has a single field; both source values +remain in the extensions. """ from __future__ import annotations @@ -36,7 +37,7 @@ JURISDICTION = "IE" ARKUSZ = "Heatmap data" -#: Nagłówek zajmuje dwa wiersze; nazwy właściwe są w drugim. +#: The header spans two rows; the proper names are in the second one. WIERSZ_NAGLOWKA = 2 KOL = { @@ -68,12 +69,12 @@ _TAK = {"yes", "y", "true", "constrained", "1"} _NIE = {"no", "n", "false", "unconstrained", "0"} -#: Kolumny ograniczenia niosą frazę "Constrained, otherwise capacity available = X kVA" -#: albo są puste. Przyjmujemy, że pusta komórka oznacza BRAK ograniczenia, a nie brak -#: deklaracji: kolumna jest wskaźnikiem binarnym, w którym wartość dodatnia niesie -#: objaśnienie, a ujemna jest wyrażona pustką. Jest to INTERPRETACJA, nie treść źródła -#: -- publikujący nigdzie tej konwencji nie opisuje -- więc surowa fraza zostaje -#: w rozszerzeniu, a decyzja jest odnotowana w raporcie adaptera. +#: The constraint columns carry the phrase "Constrained, otherwise capacity available = X kVA" +#: or are empty. We assume that an empty cell means NO constraint, not an absence of a +#: declaration: the column is a binary indicator, where a positive value carries an +#: explanation, and a negative one is expressed by emptiness. This is an INTERPRETATION, not +#: content of the source (the publisher nowhere describes this convention), so the raw +#: phrase remains in the extension, and the decision is recorded in the adapter report. _FRAZA_OGRANICZENIA = re.compile(r"constrained", re.IGNORECASE) _POJEMNOSC_W_FRAZIE = re.compile(r"=\s*([\d.,]+)\s*kVA", re.IGNORECASE) @@ -96,7 +97,7 @@ def _mw_na_kw(v) -> float | None: def _flaga(v) -> bool | None: - """Wskaźnik ograniczenia; pusta komórka to brak ograniczenia (patrz wyżej).""" + """Constraint indicator; an empty cell means no constraint (see above).""" if v is None or str(v).strip() == "": return False s = str(v).strip().lower() @@ -108,10 +109,10 @@ def _flaga(v) -> bool | None: def _pojemnosc_bez_ograniczenia(v) -> float | None: - """Z frazy 'Constrained, otherwise capacity available = X kVA' wyjmij X. + """Extract X from the phrase 'Constrained, otherwise capacity available = X kVA'. - Wartość jest w kVA, czyli w mocy pozornej, więc NIE jest przeliczana na kW - i zostaje w rozszerzeniu z jednostką w nazwie pola. + The value is in kVA, i.e. apparent power, so it is NOT converted to kW + and stays in the extension with the unit in the field name. """ if v is None: return None @@ -120,7 +121,7 @@ def _pojemnosc_bez_ograniczenia(v) -> float | None: def _alternatywa(a: bool | None, b: bool | None) -> bool | None: - """Alternatywa zachowująca nieokreśloność: None or False -> None, nie False.""" + """Disjunction preserving indeterminacy: None or False -> None, not False.""" if a is True or b is True: return True if a is False and b is False: @@ -136,26 +137,26 @@ class ESBNetworksAdapter(Adapter): "moc_dostepna", "moc_zarezerwowana", "ograniczenie_flaga", ) declared_extensions = { - "_jednostka_mocy_odbiorczej": "jednostka strony odbiorczej u publikującego (MVA)", - "_klasa_napiecia": "klasa napięcia wg publikującego", - "_konfiguracja_transformatorow": "konfiguracja grupy transformatorów", - "_moc_zainstalowana_mva": "moc zainstalowana transformatorów", - "_odbior_dostepna_mva": "dostępna moc odbiorcza", - "_odbior_trwala_mva": "trwała moc odbiorcza", - "_odbior_nadrzedna_mva": "dostępna moc odbiorcza stacji nadrzędnej", - "_odbior_ograniczenie": "ograniczenie po stronie odbiorczej", - "_wytw_ograniczenie": "ograniczenie po stronie wytwórczej", - "_odbior_ograniczenie_opis": "surowa fraza ograniczenia po stronie odbiorczej", - "_wytw_ograniczenie_opis": "surowa fraza ograniczenia po stronie wytwórczej", - "_odbior_bez_ograniczenia_kva": "moc odbiorcza dostępna, gdyby nie ograniczenie", - "_wytw_bez_ograniczenia_kva": "moc wytwórcza dostępna, gdyby nie ograniczenie", - "_wytw_dostepna_nietrwala_kw": "dostępna moc wytwórcza nietrwała", - "_wytw_zakontraktowana_kw": "moc wytwórcza zakontraktowana łącznie", - "_wytw_trwala_kw": "trwała moc wytwórcza", - "_zasilanie": "linia zasilająca", - "_stacja_nadrzedna": "stacja nadrzędna", - "_styk_przesylowy": "stacja styku z siecią przesyłową", - "_komentarz": "komentarz publikującego", + "_jednostka_mocy_odbiorczej": "unit of the demand side at the publisher (MVA)", + "_klasa_napiecia": "voltage class per the publisher", + "_konfiguracja_transformatorow": "configuration of the transformer group", + "_moc_zainstalowana_mva": "installed capacity of the transformers", + "_odbior_dostepna_mva": "available demand capacity", + "_odbior_trwala_mva": "firm demand capacity", + "_odbior_nadrzedna_mva": "available demand capacity of the parent station", + "_odbior_ograniczenie": "constraint on the demand side", + "_wytw_ograniczenie": "constraint on the generation side", + "_odbior_ograniczenie_opis": "raw constraint phrase on the demand side", + "_wytw_ograniczenie_opis": "raw constraint phrase on the generation side", + "_odbior_bez_ograniczenia_kva": "demand capacity available if not for the constraint", + "_wytw_bez_ograniczenia_kva": "generation capacity available if not for the constraint", + "_wytw_dostepna_nietrwala_kw": "available non-firm generation capacity", + "_wytw_zakontraktowana_kw": "total contracted generation capacity", + "_wytw_trwala_kw": "firm generation capacity", + "_zasilanie": "feeder line", + "_stacja_nadrzedna": "parent station", + "_styk_przesylowy": "station of interface with the transmission network", + "_komentarz": "publisher's comment", } detect_patterns = (r"customer.?heatmap", r"esb.?networks", r"heatmap.?data") @@ -202,7 +203,7 @@ def g(nazwa): "nazwa_wezla": str(stacja).strip(), "wspolrzedne": f"{lat},{lon}" if lat is not None and lon is not None else None, "poziom_napiecia": str(nap).strip() if nap else None, - # Strona wytwórcza jest w MW mocy czynnej -- jedyna przeliczalna. + # The generation side is in MW of active power, the only one that is convertible. "moc_dostepna": _mw_na_kw(g("wytw_dostepna_trwala_mw")), "moc_zarezerwowana": _mw_na_kw(g("wytw_zakontraktowana_mw")), "ograniczenie_flaga": ogr, @@ -234,21 +235,22 @@ def g(nazwa): notes = { "publikujacy": PUBLISHER, "jurysdykcja": JURISDICTION, - "tryb_wydania": "arkusz kalkulacyjny na stronie publikującego", + "tryb_wydania": "spreadsheet on the publisher's website", "wierszy": int(len(df)), "wierszy_bez_wspolrzednych": bez_wspolrzednych, "wezlow_ograniczonych": ograniczonych, "interpretacja_pustej_flagi": ( - "pusta komórka kolumny ograniczenia czytana jako BRAK ograniczenia; " - "publikujący tej konwencji nie opisuje, surowa fraza w rozszerzeniu" + "empty cell of the constraint column read as NO constraint; " + "the publisher does not describe this convention, raw phrase in the extension" ), "kolumny_nieznalezione": brakujace, "jednostka_strony_wytworczej": "MW", "jednostka_strony_odbiorczej": "MVA", "uwaga_jednostki": ( - "Pole moc_dostepna niesie dostępną moc WYTWÓRCZĄ trwałą, przeliczoną z MW " - "na kW. Strona odbiorcza jest podana w MVA (moc pozorna) i nie jest " - "przeliczana ani sumowana ze stroną wytwórczą; pozostaje w rozszerzeniach." + "The moc_dostepna field carries the available firm GENERATION capacity, " + "converted from MW to kW. The demand side is given in MVA (apparent power) " + "and is not converted nor summed with the generation side; it remains in " + "the extensions." ), } return ParseResult(frame=df, report=notes) diff --git a/src/gridqueue/adapters/pl_boryszew.py b/src/gridqueue/adapters/pl_boryszew.py index 0e1da35..ef8bae6 100644 --- a/src/gridqueue/adapters/pl_boryszew.py +++ b/src/gridqueue/adapters/pl_boryszew.py @@ -1,19 +1,19 @@ -"""Adapter: Boryszew Green Energy&Gas Sp. z o.o. (Elana, Toruń) -- mały OSD przemysłowy. - -Publikacja jest 4-stronicowym dokumentem prozą z tabelami BEZ SIATKI LINIOWEJ. -Nie ma tu żadnej struktury do odzyskania z linii -- granice kolumn istnieją tylko -jako pionowe korytarze bieli. Dlatego ten adapter używa strategii BANDED: -wykrywa korytarze w rozkładzie pokrycia osi x, a wiersze wielolinijkowe scala po -numerze porządkowym w pierwszej kolumnie. - -Dokument realizuje wszystkie cztery punkty art. 7 ust. 8l w osobnych sekcjach -numerowanych w tekście. Sekcje 1, 3 i 4 to encja WNIOSEK i trafiają do panelu. -Sekcja 2 to encja WĘZEŁ (dostępna moc przyłączeniowa per stacja na 6 lat) -- -zwracamy ją osobno w raporcie, bo nie ma rdzenia wnioskowego i nie wolno jej -mieszać z wierszami wnioskowymi bez łamania walidacji schematu. - -Przypadek ten jest w korpusie istotny jako dolny kraniec jakości ujawnień: -ten sam obowiązek ustawowy, publikacja bez żadnej struktury maszynowej. +"""Adapter: Boryszew Green Energy&Gas Sp. z o.o. (Elana, Toruń), a small industrial DSO. + +The publication is a 4-page prose document with tables WITHOUT A LINE GRID. +There is no structure here to recover from lines; column boundaries exist only +as vertical corridors of white space. Therefore this adapter uses the BANDED strategy: +it detects corridors in the x-axis coverage distribution, and merges multi-line rows by +the ordinal number in the first column. + +The document implements all four points of Art. 7(8l) in separate sections +numbered in the text. Sections 1, 3 and 4 are the APPLICATION entity and go into the panel. +Section 2 is the NODE entity (available connection capacity per station for 6 years); +we return it separately in the report, because it has no application core and must not +be mixed with application rows without breaking schema validation. + +This case is significant in the corpus as the lower bound of disclosure quality: +the same statutory duty, published without any machine-readable structure. """ from __future__ import annotations @@ -53,12 +53,12 @@ class BoryszewAdapter(Adapter): "data_energizacji", "data_publikacji", ) declared_extensions = { - "_rodzaj_podmiotu": "określenie przyłączanego obiektu (osoba prawna/fizyczna)", - "_data_zaliczki": "data wpłaty zaliczki", - "_sekcja": "punkt art. 7 ust. 8l, z którego pochodzi wiersz", - "_rodzaj_instalacji_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status rozpatrywania tak, jak w dokumencie", - "_uwaga_zrodlowa": "adnotacja publikującego (np. 'Nie dotyczy / istniejące przyłącze')", + "_rodzaj_podmiotu": "description of the connected entity (legal person/natural person)", + "_data_zaliczki": "date of the deposit payment", + "_sekcja": "the point of Art. 7(8l) that the row originates from", + "_rodzaj_instalacji_raw": "type of installation exactly as in the document", + "_status_raw": "processing status exactly as in the document", + "_uwaga_zrodlowa": "publisher's annotation (e.g. 'Nie dotyczy / istniejące przyłącze')", } detect_patterns = (r"boryszew", r"elana") @@ -107,7 +107,7 @@ def parse(self, source) -> ParseResult: report = { "publikujacy": self.publisher, - "strategia_wydobycia": "banded (korytarze bieli; brak siatki liniowej)", + "strategia_wydobycia": "banded (white-space corridors; no line grid)", "strony": n_pages, "sekcje": per_section, "n_wierszy": int(len(df)), @@ -121,7 +121,7 @@ def _section_frame(self, sec: int, lines: list[list[dict]]): import pandas as pd cols = LAYOUTS[sec] - # linie danych: od pierwszej zaczynającej się numerem porządkowym + # data lines: starting at the first one beginning with an ordinal number start = next((i for i, ln in enumerate(lines) if ln and _RE_LP.match(ln[0]["text"])), None) if start is None: @@ -134,11 +134,11 @@ def _section_frame(self, sec: int, lines: list[list[dict]]): n_raw = len(rows) width = max((len(r) for r in rows), default=0) if width != len(cols): - # dopasuj do deklarowanego układu: nadmiarowe kolumny doklej do ostatniej + # fit to the declared layout: append excess columns to the last one rows = [_fit(r, len(cols)) for r in rows] raw = pd.DataFrame([(r + [""] * len(cols))[: len(cols)] for r in rows], columns=cols) raw = raw.map(lambda v: re.sub(r"\s+", " ", str(v)).strip()) - # odrzuć wiersze-zaślepki ("brak" we wszystkich polach poza Lp.) + # discard placeholder rows ("brak" in all fields except Lp.) body = raw.drop(columns=["lp"]) keep = ~body.map(lambda v: norm_text(v) in {"", "brak", "-"}).all(axis=1) raw = raw[keep].reset_index(drop=True) @@ -208,7 +208,7 @@ def _data_aktualizacji(text: str) -> Optional[str]: def _parse_wezly(lines: list[list[dict]]) -> list[dict]: - """Sekcja 2 (pkt 2): dostępna moc przyłączeniowa per stacja na 6 lat.""" + """Section 2 (item 2): available connection capacity per station for 6 years.""" out: list[dict] = [] years: list[str] = [] for ln in lines: diff --git a/src/gridqueue/adapters/pl_energa.py b/src/gridqueue/adapters/pl_energa.py index 09f4ffe..92afd1a 100644 --- a/src/gridqueue/adapters/pl_energa.py +++ b/src/gridqueue/adapters/pl_energa.py @@ -1,36 +1,40 @@ -"""Adapter: ENERGA-OPERATOR S.A. (PL, OSD, sześć oddziałów, obszar północny). +"""Adapter: ENERGA-OPERATOR S.A. (PL, DSO, six branches, northern area). -Energa jest jedynym z dotychczas zmierzonych publikujących, który realizuje OBA -punkty obowiązku w rozłącznych dokumentach i w obu podaje dane w postaci tabelarycznej: +Energa is the only one, among those measured so far, of the publishers that +implements BOTH points of the duty in separate documents, and in both provides +data in tabular form: - pkt 1), 3), 4) -- "Informacje publikowane zgodnie z Art. 7 ust. 8l pkt 1), 3) - i 4) ustawy Prawo energetyczne", PDF, 37 stron, 28 kolumn. - To jest ten sam wzorzec PTPiREE/PSE co arkusz PSE (moduł - ``_ptpiree``), przeniesiony do PDF-a. Encja WNIOSEK. - pkt 2) -- dwa dokumenty "Informacja o wartości łącznej dostępnej - {odbiorczej|wytwórczej} mocy przyłączeniowej [MW]". Encja WĘZEŁ. - TO JEST PIERWSZE ŹRÓDŁO W PANELU, KTÓRE WYPEŁNIA ``moc_dostepna``. + pt. 1), 3), 4): "Information published pursuant to Art. 7(8l) pt. 1), 3) + and 4) of the Energy Law act", PDF, 37 pages, 28 columns. + This is the same PTPiREE/PSE pattern as the PSE sheet (module + ``_ptpiree``), moved into a PDF. APPLICATION entity. + pt. 2) : two documents "Information on the total value of available + {off-take|generation} connection capacity [MW]". NODE entity. + THIS IS THE FIRST SOURCE IN THE PANEL THAT FILLS ``moc_dostepna``. -Geometria pkt 1/3/4: dokument nie ma obiektów ``line``, ma natomiast 176 cienkich -prostokątów pełniących rolę linii siatki; pdfplumber wystawia je jako krawędzie, więc -strategia ``ruled`` działa bez zmian. Nagłówek szczegółowy jest złożony z bardzo -wąskich kolumn ze zawijanym tekstem -- płaski ``extract_text`` przeplata go między -kolumnami i jest bezużyteczny, dlatego układ odczytujemy przez przypisanie słów -nagłówka do kolumn geometrią, a nie z tekstu strony. +Geometry for pt. 1/3/4: the document has no ``line`` objects, but instead has 176 +thin rectangles acting as grid lines; pdfplumber reports them as edges, so the +``ruled`` strategy works without changes. The detailed header is composed of very +narrow columns with wrapped text; flat ``extract_text`` interleaves it between +columns and is useless, which is why we read the layout by assigning header words +to columns via geometry, rather than from the page text. -Geometria pkt 2: tabele 2.1 (skład grup węzłów koherentnych), 2.2 (słownik skrótów -stacji) i 2.3/2.4 (wartości mocy) też mają siatkę wektorową. +Geometry for pt. 2: tables 2.1 (composition of coherent node groups), 2.2 +(dictionary of station abbreviations) and 2.3/2.4 (capacity values) also have a +vector grid. -Rozstrzygnięcie merytoryczne przy dokumencie wytwórczym: są w nim DWIE tabele -wartości. Tabela 2.3 jest ujawnieniem ustawowym; tabela 2.4 jest -- słowami samego -dokumentu -- podana "dodatkowo", dla podejścia analitycznego jak w ekspertyzach wg -ustawy o morskich farmach wiatrowych. Do ``moc_dostepna`` bierzemy 2.3; 2.4 trafia -do rozszerzenia. Odwrotny wybór zawyżałby ujawnioną moc bez podstawy w dokumencie. +Substantive resolution for the generation document: it contains TWO value tables. +Table 2.3 is the statutory disclosure; table 2.4 is, in the words of the document +itself, provided "additionally", for the analytical approach as in the expert +opinions under the Act on Offshore Wind Farms. For ``moc_dostepna`` we take 2.3; +2.4 goes into the extension. The opposite choice would overstate the disclosed +capacity without basis in the document. -Rozbieżność dat, którą trzeba zgłosić, a nie wygładzić: plik pkt 1/3/4 nazywa się -``2026_08_31_pusop_wnioski_i_odmowy_eop.pdf`` i wisi w cyklu sierpniowym, ale jego -własny nagłówek deklaruje "Stan na 30.06.2026 r.". ``data_publikacji`` bierzemy -z DOKUMENTU (30.06.2026), bo to on jest ujawnieniem, a nie nazwa pliku. +Date discrepancy that must be reported, not smoothed over: the file for pt. 1/3/4 +is named ``2026_08_31_pusop_wnioski_i_odmowy_eop.pdf`` and sits in the August +cycle, but its own header declares "Stan na 30.06.2026 r.". We take +``data_publikacji`` FROM THE DOCUMENT (30.06.2026), because it is the document +that is the disclosure, not the file name. """ from __future__ import annotations @@ -55,16 +59,16 @@ class EnergaAdapter(Adapter): declared_fields = T.DECLARED_FIELDS + ("id_wezla", "nazwa_wezla", "moc_dostepna") declared_extensions = dict( T.DECLARED_EXTENSIONS, - _kierunek="kierunek mocy dostępnej: odbiorcza albo wytwórcza", - _nr_grupy="numer grupy węzłów koherentnych w dokumencie", - _stacje_grupy="stacje wchodzące w skład grupy (model sieci na rok bazowy)", - _zmiany_w_latach="zmiany składu grupy w kolejnych latach (kolumna uwag)", - _oddzial="oddział ENERGA-OPERATOR, w którego obszarze leży grupa", - _moc_dostepna_analityczna="wartość z tabeli 2.4 (podejście analityczne), rok bazowy [kW]", + _kierunek="direction of available capacity: off-take or generation", + _nr_grupy="number of the coherent node group in the document", + _stacje_grupy="stations forming the group (network model for the base year)", + _zmiany_w_latach="changes in group composition in subsequent years (remarks column)", + _oddzial="ENERGA-OPERATOR branch in whose area the group lies", + _moc_dostepna_analityczna="value from table 2.4 (analytical approach), base year [kW]", ) detect_patterns = (r"energa", r"eop") - #: lata horyzontu ujawnienia pkt 2 + #: years of the disclosure horizon for pt. 2 HORYZONT = ("2026", "2027", "2028", "2029", "2030", "2031", "2035") def __init__(self, data_publikacji: Optional[str] = None, rok_bazowy: str = "2026"): @@ -88,8 +92,8 @@ def parse(self, source) -> ParseResult: df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) report = { "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka z cienkich prostokątów), nagłówek odczytany geometrią", - "wzorzec": "PTPiREE/PSE dla pkt 1/3/4; autorski układ IEn dla pkt 2", + "strategia_wydobycia": "ruled (grid of thin rectangles), header read via geometry", + "wzorzec": "PTPiREE/PSE for pt. 1/3/4; IEn's own custom layout for pt. 2", "dokumenty": reports, "n_wierszy": int(len(df)), "data_publikacji": self.data_publikacji, @@ -111,7 +115,7 @@ def _detect_role(src) -> str: # ------------------------------------------------------------------ def _parse_wnioski(self, src): - """pkt 1/3/4 -- wzorzec PTPiREE w PDF-ie z siatką wektorową.""" + """pt. 1/3/4: PTPiREE pattern in a PDF with a vector grid.""" import pandas as pd import pdfplumber @@ -148,19 +152,19 @@ def _parse_wnioski(self, src): "n_kolumn_zrodlowych": sorted(n_cols_seen), "n_wierszy": int(len(out)), "stan_na": stan, - "uwaga_data": "nazwa pliku wskazuje cykl 31.08.2026, dokument deklaruje " - f"stan na {stan}; przyjęto deklarację dokumentu", + "uwaga_data": "the file name indicates the 31.08.2026 cycle, the document declares " + f"as of {stan}; the document's declaration was adopted", } # ------------------------------------------------------------------ def _parse_wezly(self, src, *, kierunek: str): - """pkt 2 -- wartości łącznej dostępnej mocy przyłączeniowej per grupa węzłów.""" + """pt. 2: values of the total available connection capacity per node group.""" import pandas as pd import pdfplumber - grupy: dict[str, dict] = {} # nr grupy -> skład - wartosci: dict[str, dict] = {} # nr grupy -> {rok: MW} z tabeli 2.3 - analit: dict[str, dict] = {} # nr grupy -> {rok: MW} z tabeli 2.4 + grupy: dict[str, dict] = {} # group no. -> composition + wartosci: dict[str, dict] = {} # group no. -> {year: MW} from table 2.3 + analit: dict[str, dict] = {} # group no. -> {year: MW} from table 2.4 oddzial_biezacy = None stan = None n_pages = 0 @@ -199,9 +203,10 @@ def _parse_wezly(self, src, *, kierunek: str): gi.get("stacje") or wartosci[n].get("_nazwa") for n, gi in zip(nry, g) ] out["poziom_napiecia"] = "110 kV" - # Kierunek mocy nie jest rodzajem instalacji: ujawnienie pkt 2 dotyczy - # WĘZŁA, nie zasobu. Dla mocy odbiorczej klasa jest jednoznaczna (ODB), - # dla wytwórczej dokument nie wskazuje technologii -- i tak zostaje. + # The capacity direction is not a kind of installation: the pt. 2 disclosure + # concerns the NODE, not the resource. For off-take capacity the class is + # unambiguous (ODB); for generation, the document does not indicate the + # technology, so it remains as is. out["klasa_zasobu"] = "ODB" if kierunek == "odbiorcza" else "NIEOKRESLONA" out["status_procesu"] = "NIEOKRESLONY" out["moc_dostepna"] = [ @@ -223,7 +228,7 @@ def _parse_wezly(self, src, *, kierunek: str): ] for rok in self.HORYZONT: self.declared_extensions[f"_moc_dostepna_{rok}"] = ( - f"dostępna moc przyłączeniowa w horyzoncie {rok} [kW]" + f"available connection capacity in the {rok} horizon [kW]" ) return out, { "plik": str(src), diff --git a/src/gridqueue/adapters/pl_pse.py b/src/gridqueue/adapters/pl_pse.py index 4b6bdaa..f4c9100 100644 --- a/src/gridqueue/adapters/pl_pse.py +++ b/src/gridqueue/adapters/pl_pse.py @@ -1,28 +1,29 @@ -"""Adapter: Polskie Sieci Elektroenergetyczne S.A. (PL, operator PRZESYŁOWY). - -Uwaga ustrojowa, którą trzeba zapisać w manuskrypcie, bo zmienia zakres wniosku: -PSE jest operatorem systemu PRZESYŁOWEGO, nie dystrybucyjnego. Nie naciągamy tu -niczego -- dokument sam deklaruje podstawę: plik nazywa się "Informacje -publikowane zgodnie z Art. 7 ust. 8l ustawy PE", a komórka A1 arkusza powtarza tę -deklarację. Art. 7 ust. 8l adresuje "przedsiębiorstwo energetyczne zajmujące się -przesyłaniem LUB dystrybucją", więc obowiązek obejmuje OSP tak samo jak OSD. - -Co z tego naprawdę wynika dla porównywalności: - * zakres napięć jest inny -- 110/220/400 kV zamiast SN/110 kV. To nie jest - niezgodność ze schematem (obowiązek dotyczy sieci powyżej 1 kV), tylko - zmierzona różnica w polu ``poziom_napiecia``; - * PSE realizuje pkt 1), 3) i 4) w jednym zestawieniu (encja WNIOSEK); - * pkt 2) (dostępna moc w stacjach) PSE ujawnia INACZEJ: nie jako moc w MW, lecz - jako "Listę rozdzielni, dla których brak jest dostępnych miejsc przyłączenia" - z LICZBĄ dostępnych miejsc. To jest informacja o węźle i o ograniczeniu, ale - NIE jest wartością mocy -- mapujemy ją na ``ograniczenie_flaga`` i rozszerzenie - ``_liczba_dostepnych_miejsc``, a pole ``moc_dostepna`` zostawiamy puste. - Wpisanie tam zera albo liczby miejsc byłoby fabrykacją jednostki. - -Nośnikiem jest XLSX, a nie PDF, więc geometria kolumn nie jest tu w ogóle problemem: -komórka arkusza ma tożsamość z definicji. Zachowujemy jednak ten sam audyt -sprzeczności typu, żeby liczba dla PSE była porównywalna z liczbami dla publikujących -PDF-owych -- i żeby było widać, ile z niej pochodzi z układu, a ile z samego źródła. +"""Adapter: Polskie Sieci Elektroenergetyczne S.A. (PL, TRANSMISSION operator). + +Structural note that must be recorded in the manuscript, because it changes the scope of +the claim: +PSE is the operator of the TRANSMISSION system, not the distribution system. We are not +stretching anything here: the document itself declares the basis: the file is named "Informacje +publikowane zgodnie z Art. 7 ust. 8l ustawy PE", and cell A1 of the worksheet repeats that +declaration. Art. 7 ust. 8l addresses an "energy undertaking engaged in transmission OR +distribution", so the duty covers the OSP just as much as the OSD. + +What this really means for comparability: + * the voltage range is different: 110/220/400 kV instead of MV/110 kV. This is not a + mismatch with the schema (the duty applies to networks above 1 kV), just a measured + difference in the ``poziom_napiecia`` field; + * PSE fulfills items 1), 3) and 4) in a single compilation (the APPLICATION entity); + * item 2) (available capacity at the stations) PSE discloses DIFFERENTLY: not as capacity + in MW, but as a "Listę rozdzielni, dla których brak jest dostępnych miejsc przyłączenia" + with the NUMBER of available slots. This is information about the node and about the + constraint, but it is NOT a capacity value: we map it to ``ograniczenie_flaga`` and the + extension ``_liczba_dostepnych_miejsc``, and we leave the ``moc_dostepna`` field empty. + Putting a zero or the number of slots there would be a fabrication of the unit. + +The carrier is XLSX, not PDF, so column geometry is not a problem here at all: the worksheet +cell has identity by definition. We nonetheless keep the same type-mismatch audit, so that +the count for PSE is comparable to the counts for PDF-based publishers, and so that it is +visible how much of it comes from the layout and how much from the source itself. """ from __future__ import annotations @@ -46,11 +47,11 @@ class PSEAdapter(Adapter): declared_fields = T.DECLARED_FIELDS + ("id_wezla", "nazwa_wezla", "ograniczenie_flaga") declared_extensions = dict( T.DECLARED_EXTENSIONS, - _liczba_dostepnych_miejsc="liczba wolnych miejsc przyłączenia w rozdzielni", - _symbol_stacji="symbol stacji w nomenklaturze PSE", - _zko_pse="Zakład Koordynacyjny Ośrodka PSE", - _rozdzielnia="oznaczenie rozdzielni w stacji", - _przypisy="odnośniki przypisów odcięte od treści komórek (pole=znacznik)", + _liczba_dostepnych_miejsc="number of free connection slots at the switching station", + _symbol_stacji="station symbol in PSE nomenclature", + _zko_pse="PSE Coordination Centre", + _rozdzielnia="identifier of the switching station within the station", + _przypisy="footnote references stripped from the cell contents (field=marker)", ) detect_patterns = (r"pse", r"art_7_ust_8l", r"polskie sieci elektroenergetyczne") @@ -59,11 +60,11 @@ def __init__(self, data_publikacji: Optional[str] = None): # ------------------------------------------------------------------ def parse(self, source) -> ParseResult: - """``source``: ścieżka do arkusza pkt 1/3/4 albo lista ścieżek. + """``source``: path to the worksheet for items 1/3/4, or a list of paths. - Rozpoznanie roli pliku po zawartości, nie po nazwie: arkusz o nazwie - "Wykaz wspólny" to zestawienie wniosków, arkusz "Lista zajętych rozdzielni" - to ujawnienie węzłowe. + Recognizing the role of the file by its content, not by its name: a worksheet named + "Wykaz wspólny" is the compilation of applications, the worksheet "Lista zajętych + rozdzielni" is the node-level disclosure. """ import pandas as pd @@ -76,13 +77,13 @@ def parse(self, source) -> ParseResult: elif any("rozdzielni" in s.lower() for s in xl.sheet_names): f, r = self._parse_wezly(xl, src) else: - raise ValueError(f"nierozpoznany arkusz PSE w {src!r}: {xl.sheet_names}") + raise ValueError(f"unrecognized PSE worksheet in {src!r}: {xl.sheet_names}") frames.append(f) reports.append(r) df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) report = { "publikujacy": self.publisher, - "strategia_wydobycia": "arkusz kalkulacyjny (tożsamość komórki z definicji)", + "strategia_wydobycia": "spreadsheet (cell identity by definition)", "wzorzec": "PTPiREE/PSE, art. 7 ust. 8l pkt 1), 3), 4)", "dokumenty": reports, "n_wierszy": int(len(df)), @@ -104,10 +105,10 @@ def _parse_wnioski(self, xl, src): body = d.iloc[hdr_row + 1:].reset_index(drop=True) body.columns = range(body.shape[1]) - # Ostatnie wiersze arkusza to LEGENDA przedrostków identyfikatora - # ("E- Wnioskodawca wystąpił z wnioskiem..."). Wiersz danych ma wypełnione - # pole wzorca "Nazwa OSD/OSP"; legenda go nie ma. Kryterium jest więc - # własnością wzorca, a nie zgadywaniem po pozycji. + # The last rows of the worksheet are the LEGEND of identifier prefixes + # ("E- Wnioskodawca wystąpił z wnioskiem..."). A data row has the pattern + # field "Nazwa OSD/OSP" filled in; the legend does not have it. The criterion is + # thus a property of the pattern, not a guess based on position. osd_col = 2 keep = body[osd_col].notna() & body[osd_col].map( lambda v: bool(str(v).strip()) if v is not None else False) @@ -120,9 +121,9 @@ def _parse_wnioski(self, xl, src): raw[logical] = body[phys] out = T.to_schema(raw, publisher_key="pse", data_publikacji=self.data_publikacji) - # Odnośniki przypisów wracają jako rozszerzenie, żeby odcięcie ich od - # treści nie było utratą danej. Klucz ``marks`` to (wiersz arkusza, - # kolumna arkusza), a ``keep`` mówi, które wiersze arkusza zostały. + # Footnote references come back as an extension, so that cutting them off from + # the content is not a loss of data. The ``marks`` key is (worksheet row, + # worksheet column), and ``keep`` tells which worksheet rows remained. wiersze_arkusza = [i for i, k in enumerate(keep.tolist(), start=hdr_row + 1) if k] znaczniki = [] for ri in wiersze_arkusza: @@ -148,7 +149,7 @@ def _parse_wnioski(self, xl, src): # ------------------------------------------------------------------ def _parse_wezly(self, xl, src): - """Lista rozdzielni bez wolnych miejsc przyłączenia (ujawnienie węzłowe).""" + """List of switching stations without free connection slots (node-level disclosure).""" import pandas as pd sheet = next(s for s in xl.sheet_names if "rozdzielni" in s.lower()) @@ -162,7 +163,7 @@ def _parse_wezly(self, xl, src): hdr = i break if hdr is None: - raise ValueError(f"nie znaleziono nagłówka listy rozdzielni w {src!r}") + raise ValueError(f"header of the switching-station list not found in {src!r}") cols = [str(v).strip() if isinstance(v, str) else "" for v in d.iloc[hdr].tolist()] body = d.iloc[hdr + 1:].reset_index(drop=True) body.columns = cols @@ -190,7 +191,7 @@ def c(frag): out["poziom_napiecia"] = [_volt_of(rozdz.iloc[i]) for i in idx] out["klasa_zasobu"] = "NIEOKRESLONA" out["status_procesu"] = "NIEOKRESLONY" - # moc_dostepna NIE jest wypełniana: źródło podaje LICZBĘ MIEJSC, nie moc. + # moc_dostepna is NOT filled in: the source gives the NUMBER OF SLOTS, not capacity. out["moc_dostepna"] = None out["ograniczenie_flaga"] = [ (float(miejsc.iloc[i]) == 0.0) if _num(miejsc.iloc[i]) is not None else None @@ -208,8 +209,8 @@ def c(frag): "encja": "WEZEL", "n_wierszy": int(len(out)), "stan_na": stan, - "uwaga": "źródło podaje liczbę wolnych miejsc przyłączenia, nie moc w MW; " - "moc_dostepna pozostaje pusta", + "uwaga": "the source gives the number of free connection slots, not capacity in " + "MW; moc_dostepna remains empty", } # ------------------------------------------------------------------ @@ -219,11 +220,11 @@ def _find_header_row(d) -> int: vals = [str(v).strip().lower() for v in d.iloc[i].tolist() if isinstance(v, str)] if any(v.startswith("id obiektu") for v in vals): return i - raise ValueError("nie znaleziono wiersza nagłówka arkusza PSE") + raise ValueError("header row of the PSE worksheet not found") @staticmethod def _read_vocab(xl) -> dict[str, list[str]]: - """Słowniki kontrolowane zadeklarowane przez sam dokument.""" + """Controlled vocabularies declared by the document itself.""" if _SHEET_VOCAB not in xl.sheet_names: return {} lr = xl.parse(_SHEET_VOCAB, header=None) @@ -237,23 +238,23 @@ def _read_vocab(xl) -> dict[str, list[str]]: def _read_sheet_bez_przypisow(src, sheet: str): - """Wczytaj arkusz, odłączając ODNOŚNIKI PRZYPISÓW od treści komórek. - - Dlaczego to nie jest kosmetyka. Pomiar dokładności na wzorcu odczytanym - wzrokowo pokazał siedem niezgodności u PSE i wszystkie miały jedną przyczynę: - PSE oznacza część wartości odnośnikiem przypisu zapisanym jako INDEKS GÓRNY - wewnątrz komórki -- lokalizacja "WYP" z przypisem M, "CPK" z przypisem K, - "SE EJ" z F, "Norki" z Y, oraz moce "300,1", "50,1" i "300" z przypisem E. - Płaski odczyt sklejał je w "WYPM", "CPKK", "300,1E" -- w polu tekstowym - powstawał zanieczyszczony ciąg, a w polu liczbowym wartość PRZEPADAŁA, bo - "300,1E" nie jest liczbą. - - Rozstrzygające jest to, że odnośnik daje się rozpoznać STRUKTURALNIE: - openpyxl wystawia komórkę jako ``CellRichText``, a fragment przypisu ma - ``font.vertAlign == "superscript"``. Odcinamy więc po FORMATOWANIU, a nie - przez zgadywanie, że końcowa wielka litera "pewnie jest przypisem" -- takie - zgadywanie okaleczyłoby prawdziwe nazwy stacji kończące się literą. - Sam odnośnik nie jest wyrzucany: wraca w rozszerzeniu ``_przypisy``. + """Read the worksheet, detaching FOOTNOTE REFERENCES from the cell contents. + + Why this is not cosmetic. An accuracy measurement against a reference set read + visually showed seven mismatches for PSE, and they all had a single cause: + PSE marks part of the values with a footnote reference written as a SUPERSCRIPT + inside the cell: the location "WYP" with footnote M, "CPK" with footnote K, + "SE EJ" with F, "Norki" with Y, and the capacities "300,1", "50,1" and "300" with + footnote E. A flat read glued them into "WYPM", "CPKK", "300,1E": in the text field + a contaminated string was produced, and in the numeric field the value WAS LOST, + because "300,1E" is not a number. + + What is decisive is that the reference can be recognized STRUCTURALLY: + openpyxl exposes the cell as ``CellRichText``, and the footnote fragment has + ``font.vertAlign == "superscript"``. So we cut it off based on FORMATTING, not + by guessing that a trailing capital letter "is probably a footnote": such + guessing would mutilate real station names ending in a letter. + The reference itself is not discarded: it comes back in the ``_przypisy`` extension. """ import pandas as pd from openpyxl import load_workbook diff --git a/src/gridqueue/adapters/pl_stoen.py b/src/gridqueue/adapters/pl_stoen.py index 53ca65d..ce3158c 100644 --- a/src/gridqueue/adapters/pl_stoen.py +++ b/src/gridqueue/adapters/pl_stoen.py @@ -1,20 +1,20 @@ -"""Adapter: Stoen Operator Sp. z o.o. (PL, obszar Warszawy). - -Trzy rozłączne zestawienia, po jednym na punkt obowiązku: - * pkt 1 -- podmioty ubiegające się o przyłączenie (10 kolumn, ~29 stron) - * pkt 3 -- złożone wnioski o określenie warunków (10 kolumn) - * pkt 4 -- wydane odmowy określenia warunków (11 kolumn) - -Wszystkie trzy mają pełną siatkę liniową i DWUPOZIOMOWY nagłówek powtarzany na -każdej stronie (drugi poziom rozbija "Lokalizacja" na miejscowość/adres oraz -"Moc przyłączeniowa [kW]" na Podstawa/Rezerwa). Typ zestawienia rozpoznajemy po -treści nagłówka, nie po nazwie pliku. - -Uwaga merytoryczna do zapisania w manuskrypcie: Stoen NIE rozróżnia kierunku mocy. -Kolumna "Podstawa" jest mocą przyłączeniową niezależnie od tego, czy instalacja -jest odbiorcza czy wytwórcza. Mapujemy ją na ``moc_pobierana`` (zgodnie ze -zmierzoną macierzą pokrycia) i deklarujemy brak rozróżnienia jako cechę źródła, -a nie jako lukę parsera. +"""Adapter: Stoen Operator Sp. z o.o. (PL, Warsaw area). + +Three disjoint listings, one per item of the duty: + * item 1: entities applying for connection (10 columns, ~29 pages) + * item 3: submitted applications for determination of conditions (10 columns) + * item 4: issued refusals to determine conditions (11 columns) + +All three have a full ruled line grid and a TWO-LEVEL header repeated on +each page (the second level splits "Lokalizacja" into locality/address and +"Moc przyłączeniowa [kW]" into Podstawa/Rezerwa). We recognize the listing type by +the header content, not by the file name. + +Substantive note to be recorded in the manuscript: Stoen does NOT distinguish the direction +of power. The "Podstawa" column is the connection capacity irrespective of whether the +installation is a demand-side or a generation installation. We map it to ``moc_pobierana`` +(according to the measured coverage matrix) and declare the lack of distinction as a feature +of the source, not as a parser gap. """ from __future__ import annotations @@ -66,13 +66,13 @@ class StoenAdapter(Adapter): "data_publikacji", ) declared_extensions = { - "_data_zaliczki": "data wpłaty zaliczki", - "_rodzaj_podmiotu": "rodzaj klienta (osoba prawna / fizyczna)", - "_miejscowosc": "miejscowość wydzielona z lokalizacji", - "_adres": "adres wydzielony z lokalizacji", - "_zestawienie": "który punkt art. 7 ust. 8l realizuje dany wiersz", - "_rodzaj_instalacji_raw": "rodzaj instalacji tak, jak w dokumencie", - "_status_raw": "status rozpatrywania wniosku tak, jak w dokumencie", + "_data_zaliczki": "date the deposit was paid", + "_rodzaj_podmiotu": "type of client (legal entity / natural person)", + "_miejscowosc": "locality extracted from the location", + "_adres": "address extracted from the location", + "_zestawienie": "which item of Art. 7(8l) a given row implements", + "_rodzaj_instalacji_raw": "installation type as given in the document", + "_status_raw": "application processing status as given in the document", } detect_patterns = (r"stoen",) @@ -81,7 +81,7 @@ def __init__(self, data_publikacji: Optional[str] = None): # ------------------------------------------------------------------ def parse(self, source) -> ParseResult: - """``source``: ścieżka do jednego PDF albo lista ścieżek.""" + """``source``: path to a single PDF or a list of paths.""" import pandas as pd sources = [source] if isinstance(source, (str, bytes)) or hasattr(source, "read") \ @@ -94,7 +94,7 @@ def parse(self, source) -> ParseResult: df = pd.concat(frames, ignore_index=True) if frames else self.blank_frame(0) report = { "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka wektorowa), nagłówek dwupoziomowy", + "strategia_wydobycia": "ruled (vector grid), two-level header", "dokumenty": reports, "n_wierszy": int(len(df)), "data_publikacji": self.data_publikacji, @@ -127,7 +127,7 @@ def _parse_one(self, src): if self.data_publikacji is None: self.data_publikacji = _stan_na(page.extract_text() or "") if layout is None: - raise ValueError(f"nie rozpoznano układu zestawienia Stoen w {src!r}") + raise ValueError(f"could not recognize the Stoen listing layout in {src!r}") cols = LAYOUTS[layout] raw = pd.DataFrame( diff --git a/src/gridqueue/adapters/pl_tauron.py b/src/gridqueue/adapters/pl_tauron.py index c0a1aca..d3634d1 100644 --- a/src/gridqueue/adapters/pl_tauron.py +++ b/src/gridqueue/adapters/pl_tauron.py @@ -1,18 +1,18 @@ """Adapter: TAURON Dystrybucja S.A. (PL). -Dokument: "Informacja o przyłączanych obiektach i wydanych odmowach", PDF ~99 stron, -tabela z pełną siatką liniową, 27 kolumn, nagłówek tylko na pierwszej stronie, -legenda rodzajów instalacji na stronie ostatniej. - -Kluczowa własność: daty SĄ w dokumencie rozdzielone na osobne kolumny (złożenie, -zaliczka, warunki, odmowa, utrata ważności, umowa, energizacja, rozwiązanie, -wygaśnięcie). Poprzedni parser regexowy zlewał je w jedno pole zbiorcze -- nie -dlatego, że dokument ich nie rozdziela, tylko dlatego, że spłaszczony tekst gubi -granice pustych komórek. Wydobycie po siatce odzyskuje je wprost. - -Lokalizacja jest podawana jako WEWNĘTRZNY KOD STACJI (np. "SKB3", "RCB4"). -Słownika kodów TAURON nie publikuje, więc rozwiązywacz lokalizacji zwraca dla -tego publikującego brak z jawnym powodem -- nie zgadujemy. +Document: "Informacja o przyłączanych obiektach i wydanych odmowach", PDF ~99 pages, +table with a full ruled line grid, 27 columns, header only on the first page, +legend of installation types on the last page. + +Key property: dates ARE separated in the document into separate columns (submission, +advance payment, conditions, refusal, expiry, agreement, energization, termination, +expiration). The previous regex-based parser merged them into one aggregate field, +not because the document does not separate them, but because the flattened text loses +the boundaries of empty cells. Grid-based extraction recovers them directly. + +The location is given as an INTERNAL STATION CODE (e.g. "SKB3", "RCB4"). +TAURON does not publish a dictionary of the codes, so the location resolver returns, +for this publisher, a lack of result with an explicit reason: we do not guess. """ from __future__ import annotations @@ -24,7 +24,7 @@ from ..schema import canonical_date, canonical_power_kw from .base import Adapter, ParseResult, harmonize_klasa, harmonize_status, norm_text -#: kolejność kolumn w dokumencie TAURONA (indeks -> znaczenie źródłowe) +#: column order in the TAURON document (index -> source meaning) COLUMNS = ( "lp", "id_obiektu", "nazwa_osd", "rodzaj_podmiotu", "lokalizacja_stacja", "poziom_napiecia", "wiele_miejsc", "rodzaj_instalacji", @@ -49,15 +49,15 @@ class TauronAdapter(Adapter): "data_umowy", "data_energizacji", "data_publikacji", ) declared_extensions = { - "_data_zaliczki": "data wpłaty zaliczki na poczet opłaty za przyłączenie", - "_data_utraty_waznosci": "data utraty ważności lub rezygnacji z warunków", - "_data_rozwiazania": "data rozwiązania/wypowiedzenia/odstąpienia od umowy", - "_data_wygasniecia": "data wygaśnięcia umowy z mocy prawa", - "_wiele_miejsc": "wniosek obejmuje wiele miejsc przyłączenia lub poziomów napięcia", - "_rodzaj_podmiotu": "osoba prawna / osoba fizyczna", - "_moc_zainstalowana_kw": "moc zainstalowana w rozbiciu na technologie (suma)", - "_rodzaj_instalacji_raw": "oznaczenie rodzaju instalacji tak, jak w dokumencie", - "_status_raw": "status etapu projektu tak, jak w dokumencie", + "_data_zaliczki": "date of payment of the advance toward the connection fee", + "_data_utraty_waznosci": "date of expiry or withdrawal from the conditions", + "_data_rozwiazania": "date of termination/notice/withdrawal from the agreement", + "_data_wygasniecia": "date of expiration of the agreement by operation of law", + "_wiele_miejsc": "the application covers multiple connection points or voltage levels", + "_rodzaj_podmiotu": "legal person / natural person", + "_moc_zainstalowana_kw": "installed capacity broken down by technology (sum)", + "_rodzaj_instalacji_raw": "installation type designation as given in the document", + "_status_raw": "project stage status as given in the document", } detect_patterns = (r"tauron", r"TAURON Dystrybucja") @@ -118,7 +118,7 @@ def parse(self, source) -> ParseResult: out["powod_odmowy"] = raw["uzasadnienie_odmowy"].replace("", None) out["data_publikacji"] = self.data_publikacji - # rozszerzenia deklarowane + # declared extensions out["_data_zaliczki"] = raw["data_zaliczki"].map(canonical_date) out["_data_utraty_waznosci"] = raw["data_utraty_waznosci"].map(canonical_date) out["_data_rozwiazania"] = raw["data_rozwiazania"].map(canonical_date) @@ -135,7 +135,7 @@ def parse(self, source) -> ParseResult: report = { "publikujacy": self.publisher, - "strategia_wydobycia": "ruled (siatka wektorowa)", + "strategia_wydobycia": "ruled (vector grid)", "strony": stats["strony"], "strony_bez_siatki": stats["strony_bez_siatki"], "n_geometrii_kolumn": len(stats["geometrie"]), diff --git a/src/gridqueue/adapters/pt_eredes.py b/src/gridqueue/adapters/pt_eredes.py index 981d4db..7fff50c 100644 --- a/src/gridqueue/adapters/pt_eredes.py +++ b/src/gridqueue/adapters/pt_eredes.py @@ -1,42 +1,42 @@ -"""Adapter: E-REDES (PT), zdolność przyjęcia krajowej sieci dystrybucyjnej. - -Źródło jest trzecim trybem wydania w panelu: nie dokument do druku i nie plik -na stronie, lecz **zbiór na portalu otwartych danych z interfejsem REST**. -Publikacja jest kwartalna, tak jak polski obowiązek, a jednostką wiersza jest -podstacja albo punkt cięcia sieci wysokiego napięcia. - -Co ten adapter wnosi do panelu ------------------------------- -Pierwsze zagraniczne źródło wypełniające encję **WĘZEŁ**. Dotąd moc dostępną -w węźle ujawniał wyłącznie jeden publikujący polski, więc kryterium „dostępna -moc przyłączeniowa" dało się policzyć w jednej jurysdykcji. Źródło portugalskie -podaje ponadto **skład grupy podstacji**, czyli dokładnie tę informację, która -w panelu polskim umożliwia przypisanie wniosków do węzła. - -Rozstrzygnięcie jednostek, przeczytaj, zanim zaczniesz porównywać ------------------------------------------------------------------- -Publikujący podaje zdolność przyjęcia i moce przyłączone w **MVA**, czyli -w mocy pozornej. Jednostką kanoniczną schematu jest **kW mocy czynnej**. Są to -różne wielkości fizyczne i przeliczenie jednej na drugą wymaga założenia -o współczynniku mocy, którego publikujący nie podaje. - -Dlatego pole `moc_dostepna` pozostaje **puste**, a wartości w MVA trafiają do -pól rozszerzenia wraz z jawnie zapisaną jednostką źródłową. Jest to ta sama -zasada, którą zastosowano wobec publikującego podającego liczbę wolnych miejsc -przyłączeniowych zamiast mocy: wpisanie liczby w pole o innej jednostce byłoby -fabrykacją, a nie harmonizacją. - -Rdzeń encji WĘZEŁ jest mimo to spełniony, bo realizuje go drugi człon -alternatywy, `ograniczenie_flaga`, ustawiana na podstawie zerowej zdolności -przyjęcia. Zero zdolności przyjęcia jest wartością ujawnioną i oznacza -ograniczenie, a nie brak danych. - -Format wejścia --------------- -Eksport CSV z portalu (separator średnik, nagłówki techniczne, nie etykiety). -Adapter celowo czyta PLIK, a nie odpytuje interfejsu przy parsowaniu: dzięki -temu wynik jest odtwarzalny z manifestu z sumą kontrolną, tak jak u pozostałych -publikujących. +"""Adapter: E-REDES (PT), national distribution network reception capacity. + +The source is the third release mode in the panel: not a document for printing and not a +file on a page, but **a dataset on an open data portal with a REST interface**. +Publication is quarterly, just like the Polish duty, and the row unit is +a substation or a high-voltage network cutting point. + +What this adapter contributes to the panel +------------------------------------------ +The first foreign source populating the **NODE** entity. Until now, available capacity +at the node was disclosed only by one Polish publisher, so the criterion "available +connection capacity" could be computed in a single jurisdiction. The Portuguese source +additionally provides the **composition of the substation group**, which is exactly the +information that, in the Polish panel, allows applications to be assigned to a node. + +Resolving units, read this before you start comparing +----------------------------------------------------- +The publisher provides reception capacity and connected capacities in **MVA**, that is, +in apparent power. The schema's canonical unit is **kW of active power**. These are +different physical quantities and converting one into the other requires an assumption +about the power factor, which the publisher does not provide. + +For this reason the `moc_dostepna` field remains **empty**, and the MVA values go into +extension fields together with the explicitly recorded source unit. This is the same +principle that was applied to the publisher reporting the number of free connection +slots instead of capacity: entering a number in a field with a different unit would be +fabrication, not harmonization. + +The core of the NODE entity is nonetheless satisfied, because it is realized by the +second branch of the alternative, `ograniczenie_flaga`, set based on zero reception +capacity. Zero reception capacity is a disclosed value and means a constraint, not a +missing datum. + +Input format +------------ +CSV export from the portal (semicolon separator, technical headers, not labels). +The adapter deliberately reads a FILE, rather than querying the interface during parsing: +this makes the result reproducible from a manifest with a checksum, just as with the +other publishers. """ from __future__ import annotations @@ -48,13 +48,13 @@ PUBLISHER = "E-REDES S.A." JURISDICTION = "PT" -#: Jednostka, w której publikujący podaje moce. NIE jest to jednostka kanoniczna -#: schematu (kW mocy czynnej) i nie jest na nią przeliczana. +#: The unit in which the publisher provides capacities. This is NOT the schema's +#: canonical unit (kW of active power) and it is not converted to it. SOURCE_POWER_UNIT = "MVA" -#: Kolumny zdolności przyjęcia w podziale na poziomy napięcia, od najwyższego. -#: Służą wyłącznie do ustalenia poziomu napięcia, na którym zdolność występuje; -#: ich wartości nie wchodzą do pola mocy z powodu różnicy jednostek. +#: Reception capacity columns broken down by voltage level, from the highest. +#: They serve solely to determine the voltage level at which the capacity occurs; +#: their values do not go into the capacity field because of the unit difference. _KOLUMNY_NAPIEC = [ ("capacidade_de_recepcao_at_mva_ultimo_trimestre", "AT"), ("capacidade_de_recepcao_mt_30kv_mva_ultimo_trimestre", "30 kV"), @@ -69,7 +69,7 @@ def _liczba(v) -> float | None: - """Liczba z zapisu portalowego; przecinek dziesiętny dopuszczony.""" + """Number from the portal notation; decimal comma allowed.""" if v is None: return None s = str(v).strip().replace("\xa0", "").replace(" ", "") @@ -83,7 +83,7 @@ def _liczba(v) -> float | None: def _kwartal_na_date(v) -> str | None: - """'2T2026' -> '2026-06-30'. Publikacja kwartalna, dzień ostatni kwartału.""" + """'2T2026' -> '2026-06-30'. Quarterly publication, last day of the quarter.""" s = str(v or "").strip().upper() if len(s) == 6 and s[1] == "T" and s[0].isdigit() and s[2:].isdigit(): kw, rok = int(s[0]), int(s[2:]) @@ -101,16 +101,16 @@ class EredesAdapter(Adapter): "ograniczenie_flaga", "data_publikacji", ) declared_extensions = { - "_jednostka_mocy_zrodlowa": "jednostka, w której publikujący podaje moce (MVA)", - "_moc_dostepna_mva": "zdolność przyjęcia SN+WN w MVA, tak jak w źródle", - "_moc_przylaczona_mva": "moc przyłączona w MVA", - "_moc_zakontraktowana_mva": "moc zakontraktowana w MVA", - "_moc_w_potwierdzaniu_mva": "moc w trakcie potwierdzania w MVA", - "_typ_instalacji": "podstacja albo punkt cięcia sieci wysokiego napięcia", - "_dystrykt": "dystrykt administracyjny", - "_gmina": "gmina", - "_nuts3": "jednostka statystyczna NUTS 3", - "_wezel_rnt": "węzeł sieci przesyłowej, z którym połączona jest podstacja", + "_jednostka_mocy_zrodlowa": "unit in which the publisher provides capacities (MVA)", + "_moc_dostepna_mva": "reception capacity MV+HV in MVA, as in the source", + "_moc_przylaczona_mva": "connected capacity in MVA", + "_moc_zakontraktowana_mva": "contracted capacity in MVA", + "_moc_w_potwierdzaniu_mva": "capacity in the process of confirmation in MVA", + "_typ_instalacji": "substation or high-voltage network cutting point", + "_dystrykt": "administrative district", + "_gmina": "municipality", + "_nuts3": "NUTS 3 statistical unit", + "_wezel_rnt": "transmission network node to which the substation is connected", } detect_patterns = (r"capacidade.?rececao", r"e.?redes", r"\brnd\b") @@ -136,12 +136,12 @@ def parse(self, source) -> ParseResult: rekordy.append({ "id_wezla": kod or None, "nazwa_wezla": (w.get("instalacao") or "").strip() or None, - # Skład grupy podstacji, odpowiednik listy stacji w wierszu - # węzłowym publikującego polskiego, więc trafia w to samo pole. + # Composition of the substation group, the equivalent of the station list in the + # node row of the Polish publisher, so it goes into the same field. "lokalizacja_tekst": (w.get("grupo_de_subestacoes_rari") or "").strip() or None, "poziom_napiecia": ", ".join(napiecia) or None, - "moc_dostepna": None, # jednostka źródłowa to MVA, patrz nagłówek modułu - "moc_zarezerwowana": None, # jw. + "moc_dostepna": None, # source unit is MVA, see module header + "moc_zarezerwowana": None, # as above. "ograniczenie_flaga": ograniczenie, "data_publikacji": _kwartal_na_date(w.get("data_ultimo_trimestre")), "_encja": "WEZEL", @@ -165,17 +165,17 @@ def parse(self, source) -> ParseResult: notes = { "publikujacy": PUBLISHER, "jurysdykcja": JURISDICTION, - "tryb_wydania": "portal otwartych danych, eksport CSV z interfejsu REST", + "tryb_wydania": "open data portal, CSV export from REST interface", "wierszy": int(len(df)), "wierszy_bez_kodu_instalacji": bez_kodu, "wezlow_o_zerowej_zdolnosci_przyjecia": zerowa, "jednostka_mocy_zrodlowa": SOURCE_POWER_UNIT, "moc_dostepna_pusta_z_powodu_jednostki": True, "uwaga_jednostki": ( - "Publikujący podaje moce w MVA (moc pozorna); jednostką kanoniczną schematu " - "jest kW mocy czynnej. Przeliczenie wymagałoby nieujawnionego współczynnika " - "mocy, więc pole moc_dostepna pozostaje puste, a wartości źródłowe są " - "w polach rozszerzenia z jawną jednostką." + "The publisher provides capacities in MVA (apparent power); the schema's canonical unit " + "is kW of active power. Conversion would require an undisclosed power " + "factor, so the moc_dostepna field remains empty, and the source values are " + "in extension fields with an explicit unit." ), } return ParseResult(frame=df, report=notes) diff --git a/src/gridqueue/adapters/uk_nationalgrid.py b/src/gridqueue/adapters/uk_nationalgrid.py index 707615f..5897fed 100644 --- a/src/gridqueue/adapters/uk_nationalgrid.py +++ b/src/gridqueue/adapters/uk_nationalgrid.py @@ -1,14 +1,14 @@ -"""Adapter: National Grid Electricity Distribution (UK) -- zbiór "Connection Queue". +"""Adapter: National Grid Electricity Distribution (UK), the "Connection Queue" dataset. -Ten adapter istnieje po to, żeby udowodnić przenoszalność schematu, a nie żeby -sparsować kolejny PDF. Brytyjski publikujący wystawia te same informacje jako -45 osobnych plików CSV w katalogu CKAN -- dane są już tabelaryczne, więc CAŁA -warstwa wydobycia po układzie strony jest tu zbędna. To jest dokładnie ta -asymetria, którą narzędzie ma pokazać: w jurysdykcji o dobrych danych parser -jest niepotrzebny, w Polsce jest warunkiem dostępu do treści obowiązku. +This adapter exists to prove the portability of the schema, not to +parse another PDF. The British publisher issues the same information as +45 separate CSV files in the CKAN catalog; the data is already tabular, so the ENTIRE +extraction layer after the page layout is unnecessary here. This is exactly the +asymmetry that the tool is meant to show: in a jurisdiction with good data the parser +is unnecessary, in Poland it is a precondition for access to the content of the duty. -Dostęp: publiczny endpoint ``package_search`` CKAN, bez klucza. Klient -przedstawia się uczciwie w nagłówku User-Agent; nie podszywamy się pod przeglądarkę. +Access: public ``package_search`` CKAN endpoint, no key required. The client +identifies itself honestly in the User-Agent header; we do not impersonate a browser. """ from __future__ import annotations @@ -36,15 +36,15 @@ class NationalGridAdapter(Adapter): "status_procesu", ) declared_extensions = { - "_licence_area": "obszar licencyjny operatora", + "_licence_area": "operator's licence area", "_gsp": "Grid Supply Point", - "_machine_id": "identyfikator jednostki w ramach lokalizacji", - "_machine_export_kw": "moc eksportowa pojedynczej jednostki", - "_machine_import_kw": "moc importowa pojedynczej jednostki", - "_tanm": "Transmission Area Network Management (flaga ograniczenia)", - "_danm": "Distribution Area Network Management (flaga ograniczenia)", - "_plik_zrodlowy": "nazwa zasobu CSV w katalogu CKAN", - "_status_raw": "status tak, jak w źródle", + "_machine_id": "unit identifier within the location", + "_machine_export_kw": "export capacity of a single unit", + "_machine_import_kw": "import capacity of a single unit", + "_tanm": "Transmission Area Network Management (constraint flag)", + "_danm": "Distribution Area Network Management (constraint flag)", + "_plik_zrodlowy": "name of the CSV resource in the CKAN catalog", + "_status_raw": "status exactly as in the source", } detect_patterns = (r"connection.?queue", r"national.?grid") @@ -54,7 +54,7 @@ def __init__(self, dataset: str = "connection-queue", timeout: int = 90): # ------------------------------------------------------------------ def fetch(self) -> tuple["Any", dict]: - """Pobierz wszystkie zasoby CSV zbioru z katalogu CKAN.""" + """Download all CSV resources of the dataset from the CKAN catalog.""" import pandas as pd import requests @@ -65,7 +65,7 @@ def fetch(self) -> tuple["Any", dict]: r.raise_for_status() pkgs = [p for p in r.json()["result"]["results"] if p["name"] == self.dataset] if not pkgs: - raise LookupError(f"nie znaleziono zbioru {self.dataset!r} w katalogu CKAN") + raise LookupError(f"dataset {self.dataset!r} not found in the CKAN catalog") pkg = pkgs[0] resources = [res for res in pkg["resources"] if (res.get("format") or "").upper() == "CSV"] @@ -78,7 +78,7 @@ def fetch(self) -> tuple["Any", dict]: d["_plik_zrodlowy"] = res.get("name") or res["url"].rsplit("/", 1)[-1] frames.append(d) ok.append(res.get("name")) - except Exception as exc: # zapisujemy, nie ukrywamy + except Exception as exc: # we record it, not hide it failed.append({"zasob": res.get("name"), "blad": f"{type(exc).__name__}: {exc}"}) raw = pd.concat(frames, ignore_index=True) if frames else pd.DataFrame() meta = { @@ -93,7 +93,7 @@ def fetch(self) -> tuple["Any", dict]: # ------------------------------------------------------------------ def parse(self, source=None) -> ParseResult: - """``source``: None -> pobierz z CKAN; ścieżka/DataFrame -> użyj lokalnie.""" + """``source``: None -> download from CKAN; path/DataFrame -> use locally.""" import pandas as pd if source is None: @@ -146,7 +146,7 @@ def col(*names): report = { "publikujacy": self.publisher, - "strategia_wydobycia": "CSV z katalogu CKAN (dane już tabelaryczne)", + "strategia_wydobycia": "CSV from the CKAN catalog (data already tabular)", "n_wierszy": int(len(out)), "katalog": meta, } diff --git a/src/gridqueue/analysis.py b/src/gridqueue/analysis.py index 5ae8150..8b577d4 100644 --- a/src/gridqueue/analysis.py +++ b/src/gridqueue/analysis.py @@ -1,20 +1,20 @@ -"""Analizy badawcze na zharmonizowanym panelu. - -Dwie rodziny funkcji, obie wyprowadzone z pytań, które rejestr pozwala zadać -dopiero po harmonizacji: - -* **obciążenie węzła**, zestawienie mocy objętej wnioskami z ujawnioną mocą - dostępną w węźle. Jest to policzalna wersja kryterium „dostępna moc - przyłączeniowa", które przeglądy literatury opisują jako niemierzalne - z powodu braku danych. Wymaga publikującego, który ujawnia JEDNOCZEŚNIE moc - dostępną w węźle i skład stacji wchodzących do węzła; -* **czas rozpatrywania z cenzurowaniem**, wnioski bez daty rozstrzygnięcia nie - są brakiem danych, tylko obserwacjami uciętymi na dacie publikacji. Liczenie - mediany wyłącznie na przypadkach kompletnych ZANIŻA ją, i to tym silniej, im - dłuższy jest rzeczywisty czas rozpatrywania. - -Żadna z tych funkcji nie jest specyficzna dla publikującego: specyficzne są -adaptery, a to jest warstwa nad schematem. +"""Research analyses on the harmonized panel. + +Two families of functions, both derived from questions that the register allows to ask +only after harmonization: + +* **node loading**, a comparison of the capacity covered by applications against the disclosed + available capacity at the node. This is a measurable version of the "available connection + capacity" criterion, which literature reviews describe as unmeasurable + due to lack of data. It requires a publisher who discloses SIMULTANEOUSLY the capacity + available at the node and the composition of stations making up the node; +* **processing time with censoring**, applications without a resolution date are + not missing data, only observations censored at the publication date. Computing the + median using only complete cases UNDERSTATES it, and does so more strongly, the + longer the actual processing time is. + +Neither of these functions is specific to the publisher: adapters are specific, +and this is a layer on top of the schema. """ from __future__ import annotations @@ -38,33 +38,33 @@ "KMResult", ] -#: Przedrostki oznaczeń stacji, usuwane przed porównaniem nazw. Nie niosą -#: tożsamości obiektu, a występują niekonsekwentnie po obu stronach złączenia. +#: Prefixes of station designations, removed before comparing names. They do not carry +#: object identity, and occur inconsistently on both sides of the join. PRZEDROSTKI_STACJI: tuple[str, ...] = ("GPZ", "SE", "RS", "RPZ", "STACJA") _NIEALFANUM = re.compile(r"[^a-z0-9 ]+") -#: Wpisy opisujące obiekt PLANOWANY NA LINII między stacjami, a nie obiekt -#: w węźle. Przypisanie ich do węzła byłoby arbitralne: linia łączy dwa węzły, -#: a dopasowanie po nazwie wybrałoby ten koniec, który akurat występuje -#: w wykazie stacji. Pełna moc takiego wniosku nie obciąża żadnego z nich -#: w całości, więc wpis zostaje nieprzypisany i jawnie oznaczony. +#: Entries describing an object PLANNED ON A LINE between stations, rather than an object +#: at a node. Assigning them to a node would be arbitrary: the line connects two nodes, +#: and matching by name would pick whichever end happens to appear +#: in the station list. The full capacity of such an application does not load either of them +#: in full, so the entry remains unassigned and is explicitly flagged. _RELACJA_LINII = re.compile( r"\b(w\s+lini(?:i|ach)|relacj(?:i|a)|odczep\s+z\s+lini)", re.IGNORECASE) -#: Litery, których rozkład kanoniczny NIE oddziela znaku diakrytycznego: Unicode -#: traktuje je jako osobne litery, więc NFKD ich nie rozkłada i naiwne czyszczenie -#: zamienia je na spację, rozcinając wyraz ("Białogard" -> "bia ogard"). +#: Letters whose canonical decomposition does NOT separate the diacritical mark: Unicode +#: treats them as separate letters, so NFKD does not decompose them, and naive cleaning +#: turns them into a space, splitting the word ("Białogard" -> "bia ogard"). _NIEROZKLADALNE = {"ł": "l", "Ł": "L", "đ": "d", "Đ": "D", "ø": "o", "Ø": "O", "ß": "ss", "æ": "ae", "Æ": "AE", "œ": "oe", "Œ": "OE"} def normalizuj_nazwe(v) -> str: - """Nazwa stacji sprowadzona do postaci porównywalnej. + """Station name reduced to a comparable form. - Usuwa znaki diakrytyczne, sprowadza do małych liter, odrzuca przedrostki - oznaczeń i zbędne znaki. Porównanie odbywa się na TOKENACH, nie na znakach, - żeby „Kutno" nie pasowało do „Kutnowska". + Removes diacritical marks, converts to lowercase, drops designation + prefixes and extraneous characters. The comparison is performed on TOKENS, not characters, + so that "Kutno" does not match "Kutnowska". """ if v is None or (isinstance(v, float) and v != v): return "" @@ -83,7 +83,7 @@ def _tokeny(s: str) -> tuple[str, ...]: def _podciag(igla: Sequence[str], stog: Sequence[str]) -> bool: - """Czy `igla` jest ciągłym podciągiem tokenów `stog`.""" + """Whether `igla` is a contiguous subsequence of the tokens of `stog`.""" n, m = len(igla), len(stog) if n == 0 or n > m: return False @@ -96,23 +96,23 @@ def station_node_map( kolumna_grupy: str = "_nr_grupy", separator: str = ",", ) -> pd.DataFrame: - """Odwzorowanie stacja → grupa stacji, odczytane z wierszy encji WEZEL. + """Mapping: station -> station group, read from WEZEL entity rows. - Publikujący, który realizuje punkt 2 obowiązku w podziale na GRUPY stacji, - wymienia skład grupy w polu lokalizacji. To jedyne miejsce, w którym - przynależność stacji do węzła jest w ogóle ujawniona, stąd ta funkcja. + A publisher that carries out point 2 of the duty by splitting stations into GROUPS + lists the composition of the group in the location field. This is the only place where + a station's membership in a node is disclosed at all, hence this function. - Kluczem jest GRUPA, nie identyfikator wiersza węzłowego. Publikujący - wystawia tę samą grupę osobno dla kierunku wytwórczego i odbiorczego, więc - odwzorowanie po identyfikatorze wiersza czyniłoby każdą stację - dwuznaczną, co byłoby artefaktem układu dokumentu, nie własnością sieci. - Gdy kolumna grupy nie występuje, kluczem staje się identyfikator węzła. + The key is the GROUP, not the node-row identifier. The publisher + issues the same group separately for the generation direction and the offtake direction, so + mapping by row identifier would make every station + ambiguous, which would be an artifact of the document layout, not a property of the network. + When the group column is not present, the key becomes the node identifier. - Zwraca ramkę: publikujacy, grupa, nazwa_wezla, stacja, stacja_norm. + Returns a frame: publikujacy, grupa, nazwa_wezla, stacja, stacja_norm. """ if kolumna_encji in df.columns: wez = df[df[kolumna_encji] == "WEZEL"] - else: # bez anotacji encji rozpoznajemy węzeł po obecności mocy dostępnej + else: # without entity annotation, we recognize a node by the presence of available capacity wez = df[df["moc_dostepna"].notna()] if "moc_dostepna" in df else df.iloc[0:0] klucz = kolumna_grupy if kolumna_grupy in df.columns else "id_wezla" wiersze = [] @@ -145,22 +145,22 @@ def assign_to_nodes( mapa: pd.DataFrame, kolumna_encji: str = "_encja", ) -> pd.DataFrame: - """Przypisuje wiersze wnioskowe do grup stacji przez nazwę stacji. + """Assigns application rows to station groups by station name. - Przypisanie jest NAZWOWE, nie topologiczne: opiera się na zgodności nazw - ujawnionych przez publikującego, a nie na modelu sieci. Jego trafność nie - jest tu walidowana wobec zewnętrznego wzorca, bo taki nie istnieje. + The assignment is BY NAME, not topological: it relies on the match of names + disclosed by the publisher, rather than on a network model. Its accuracy is not + validated here against an external reference, because none exists. - Zwracany status rozróżnia cztery przypadki, bo brak przypisania - i przypisanie niepewne to nie to samo: + The returned status distinguishes four cases, because no assignment + and an uncertain assignment are not the same thing: - ``EXACT`` nazwa stacji równa lokalizacji wniosku po normalizacji - ``EXTENDED`` lokalizacja zawiera nazwę stacji jako ciągły podciąg tokenów - ``LINE`` obiekt planowany na linii między stacjami, nie w węźle - ``AMBIGUOUS`` pasuje więcej niż jedna grupa, przypisania nie dokonujemy - ``NONE`` brak trafienia albo brak lokalizacji + ``EXACT`` station name equal to the application's location after normalization + ``EXTENDED`` location contains the station name as a contiguous subsequence of tokens + ``LINE`` object planned on a line between stations, not at a node + ``AMBIGUOUS`` more than one group matches, no assignment is made + ``NONE`` no match, or no location - Dodaje kolumny `_grupa`, `_grupa_nazwa`, `_grupa_dopasowanie`. + Adds the columns `_grupa`, `_grupa_nazwa`, `_grupa_dopasowanie`. """ if not len(mapa): out = df.copy() @@ -219,20 +219,20 @@ def node_loading( statusy_czynne: Iterable[str] | None = None, kolumna_encji: str = "_encja", ) -> pd.DataFrame: - """Obciążenie węzła: moc czynnej kolejki wobec ujawnionej mocy dostępnej. + """Node loading: the capacity of the active queue against the disclosed available capacity. - Iloraz większy od jedności oznacza, że sama kolejka przekracza moc, którą - publikujący deklaruje jako dostępną. Jest to policzalna postać kryterium - „dostępna moc przyłączeniowa". + A ratio greater than one means that the queue alone exceeds the capacity that the + publisher declares as available. This is a measurable form of the "available connection + capacity" criterion. - Wymaga ramki po `assign_to_nodes`. Gdy publikujący podaje moc dostępną - osobno dla kierunku wytwórczego i odbiorczego, `kierunek` wybiera właściwe - wiersze węzłowe; domyślnie wyprowadzany jest z `pole_mocy`. + Requires a frame after `assign_to_nodes`. When the publisher reports available capacity + separately for the generation direction and the offtake direction, `kierunek` selects the + correct node rows; by default it is derived from `pole_mocy`. - Węzły o zerowej mocy dostępnej zwracane są z ilorazem ``NaN`` i flagą - `moc_dostepna_zero`: iloraz jest tam NIEOKREŚLONY, a nie nieskończony, - i uśrednianie go byłoby błędem. Wiersz zachowuje jednak moc wnioskowaną, - bo kolejka do węzła bez wolnej mocy jest informacją, nie brakiem danych. + Nodes with zero available capacity are returned with a ``NaN`` ratio and the + `moc_dostepna_zero` flag: the ratio there is UNDEFINED, not infinite, + and averaging it would be an error. The row nonetheless retains the capacity applied for, + because a queue at a node with no free capacity is information, not missing data. """ if statusy_czynne is None: statusy_czynne = ("WNIOSEK_ZLOZONY", "WNIOSEK_NIEKOMPLETNY", @@ -272,15 +272,15 @@ def processing_time( do: str = "data_warunkow", na_dzien=None, ) -> pd.DataFrame: - """Czas rozpatrywania wraz z klasyfikacją cenzurowania. + """Processing time together with censoring classification. - Wniosek bez daty rozstrzygnięcia NIE jest brakiem danych: jest obserwacją - uciętą na dacie publikacji edycji. Funkcja zwraca kolumnę `czas_dni` dla - obu rodzajów obserwacji oraz `zdarzenie` równe 1 dla rozstrzygniętych i 0 - dla uciętych, w postaci, której oczekuje estymator przeżycia. + An application without a resolution date is NOT missing data: it is an observation + censored at the edition's publication date. The function returns the column `czas_dni` for + both kinds of observations, as well as `zdarzenie` equal to 1 for resolved ones and 0 + for censored ones, in the form expected by the survival estimator. - `na_dzien` domyślnie bierze maksimum z pola daty publikacji, a gdy go brak - - maksimum z dat rozstrzygnięć. + `na_dzien` by default takes the maximum of the publication-date field, and when that is + absent, the maximum of the resolution dates. """ d = df.copy() for c in (od, do): @@ -307,7 +307,7 @@ def processing_time( @dataclass class KMResult: - """Krzywa przeżycia Kaplana-Meiera z przedziałem Greenwooda.""" + """Kaplan-Meier survival curve with the Greenwood interval.""" tabela: pd.DataFrame = field(repr=False) mediana: float @@ -325,12 +325,12 @@ def as_dict(self) -> dict: def kaplan_meier(czas, zdarzenie, alpha: float = 0.05) -> KMResult: - """Estymator Kaplana-Meiera z wariancją Greenwooda. + """Kaplan-Meier estimator with Greenwood's variance. - Zaimplementowany wprost, żeby nie wprowadzać zależności od biblioteki - analizy przeżycia dla jednego estymatora. Przedział dla mediany wyznaczany - jest metodą odwrócenia przedziału krzywej: granicami są skrajne czasy, dla - których pas ufności krzywej obejmuje poziom 0,5. + Implemented directly, so as not to introduce a dependency on a survival-analysis + library for a single estimator. The interval for the median is determined + by the curve-interval-inversion method: the bounds are the extreme times for + which the curve's confidence band covers the level of 0.5. """ d = pd.DataFrame({"t": pd.to_numeric(pd.Series(czas), errors="coerce"), "e": pd.to_numeric(pd.Series(zdarzenie), errors="coerce")}).dropna() diff --git a/src/gridqueue/cli.py b/src/gridqueue/cli.py index 702d501..6c64af0 100644 --- a/src/gridqueue/cli.py +++ b/src/gridqueue/cli.py @@ -1,4 +1,4 @@ -"""Interfejs wiersza poleceń: ``gridqueue parse | validate | export``.""" +"""Command-line interface: ``gridqueue parse | validate | export``.""" from __future__ import annotations @@ -40,7 +40,7 @@ def cmd_parse(args) -> int: key = args.adapter or (detect_publisher(args.source[0]) if args.source else None) if key is None: - print("nie rozpoznano publikującego; podaj --adapter", file=sys.stderr) + print("publisher not recognized; provide --adapter", file=sys.stderr) return 2 adapter = get_adapter(key) source = args.source if len(args.source) > 1 else (args.source[0] if args.source else None) @@ -107,34 +107,34 @@ def cmd_adapters(args) -> int: def build_parser() -> argparse.ArgumentParser: ap = argparse.ArgumentParser( prog="gridqueue", - description="Harmonizator ustawowych ujawnień przyłączeniowych (art. 7 ust. 8l PE)") + description="Harmonizer of statutory connection disclosures (Art. 7(8l) of the Energy Law)") ap.add_argument("--version", action="version", version=f"gridqueue {__version__}") sub = ap.add_subparsers(dest="cmd", required=True) - p = sub.add_parser("parse", help="sparsuj dokument publikującego do schematu") - p.add_argument("source", nargs="*", help="ścieżka(-i) do dokumentu; brak = pobierz z sieci") - p.add_argument("--adapter", choices=sorted(REGISTRY), help="wymuś adapter") - p.add_argument("--out", required=True, help="plik wyjściowy (.csv/.parquet/.json)") - p.add_argument("--report", help="plik raportu JSON") + p = sub.add_parser("parse", help="parse a publisher document into the schema") + p.add_argument("source", nargs="*", help="path(s) to the document; none = fetch from the network") + p.add_argument("--adapter", choices=sorted(REGISTRY), help="force an adapter") + p.add_argument("--out", required=True, help="output file (.csv/.parquet/.json)") + p.add_argument("--report", help="JSON report file") p.set_defaults(func=cmd_parse) - p = sub.add_parser("validate", help="waliduj zbiór wobec schematu i reguł jakości") + p = sub.add_parser("validate", help="validate a dataset against the schema and quality rules") p.add_argument("input") - p.add_argument("--out", help="plik raportu JSON") + p.add_argument("--out", help="JSON report file") p.set_defaults(func=cmd_validate) - p = sub.add_parser("export", help="złóż panel z wielu zbiorów") + p = sub.add_parser("export", help="assemble a panel from multiple datasets") p.add_argument("input", nargs="+") p.add_argument("--out", required=True) p.add_argument("--only-schema", action="store_true", - help="pomiń rozszerzenia (kolumny z przedrostkiem _)") + help="omit extensions (columns with the _ prefix)") p.set_defaults(func=cmd_export) - p = sub.add_parser("schema", help="wypisz specyfikację schematu") + p = sub.add_parser("schema", help="print the schema specification") p.add_argument("--out") p.set_defaults(func=cmd_schema) - p = sub.add_parser("adapters", help="wypisz deklaracje adapterów") + p = sub.add_parser("adapters", help="print adapter declarations") p.set_defaults(func=cmd_adapters) return ap diff --git a/src/gridqueue/geoloc.py b/src/gridqueue/geoloc.py index f3cfc69..102e4e7 100644 --- a/src/gridqueue/geoloc.py +++ b/src/gridqueue/geoloc.py @@ -1,48 +1,48 @@ -"""Rozwiązywacz lokalizacji z JAWNYM poziomem pewności. - -Reguła nadrzędna: rozwiązywacz nigdy nie zgaduje po cichu. Każdy wynik niesie -poziom pewności, a odsetek rozwiązanych jest raportowaną metryką, nie założeniem. - -Poziomy pewności (malejąco): - EXACT -- znormalizowany opis jest identyczny z nazwą w gazeterze - UNIQUE_TOKEN -- dokładnie jedna nazwa w gazeterze zawiera rozpoznawalny token - wyróżniający z opisu - TOKEN_SUBSET -- zbiór tokenów opisu zawiera się w tokenach dokładnie jednej nazwy - REVERSED -- dopasowanie po odwróceniu kolejności członów nazwy - ("WINCENTEGO ŚW." -> "Świętego Wincentego", "BEMA J." -> "Józefa Bema") - SKRZYZOWANIE -- opis wskazuje skrzyżowanie dwóch ulic ("WALICÓW / GRZYBOWSKA"); - rozwiązane, gdy co najmniej dwa człony trafiają w gazeter - NONE -- brak dopasowania; pole ``powod`` mówi dlaczego - -Dla publikujących, którzy podają lokalizację jako WEWNĘTRZNY KOD STACJI -(TAURON: "SKB3", "RCB4"), rozwiązywacz zwraca NONE z powodem -``kod_stacji_bez_slownika`` -- nie próbuje zgadywać, bo operator nie publikuje -słownika kodów i każde dopasowanie byłoby konfabulacją. - -Rozszerzenie o współrzędne (wersja 0.2) ---------------------------------------- -Wynik niesie teraz punkt oraz DRUGI, niezależny poziom -- ``dokladnosc`` -(patrz :data:`DOKLADNOSC`). Dwa poziomy odpowiadają na dwa różne pytania: - - ``pewnosc`` -- jak pewna jest IDENTYFIKACJA nazwy miejsca, - ``dokladnosc`` -- jak precyzyjnie zwrócony punkt reprezentuje to miejsce. - -Są rozłączne z założenia: dopasowanie EXACT do ulicy o długości 6 km daje punkt -o dokładności ``PUNKT_NA_OSI_ULICY`` z rozmyciem rzędu kilometra, a dopasowanie -UNIQUE_TOKEN do krótkiej ulicy -- punkt lepszy. Długość osi dopasowanej ulicy -jest zwracana w ``dlugosc_ulicy_m`` właśnie po to, by rozmycie dało się -policzyć, a nie tylko zadeklarować. - -Zachowane jest rozróżnienie między **nierozwiązaniem nazwy** -(``pewnosc == "NONE"``) a **rozwiązaniem nazwy bez dostępnej geometrii** +"""Location resolver with an EXPLICIT confidence level. + +Overriding rule: the resolver never guesses silently. Every result carries a +confidence level, and the share of resolved cases is a reported metric, not an assumption. + +Confidence levels (descending): + EXACT : the normalized description is identical to a name in the gazetteer + UNIQUE_TOKEN : exactly one name in the gazetteer contains a recognizable + distinguishing token from the description + TOKEN_SUBSET : the set of tokens in the description is contained in the tokens of exactly one name + REVERSED : matched after reversing the order of the name's parts + ("WINCENTEGO ŚW." -> "Świętego Wincentego", "BEMA J." -> "Józefa Bema") + SKRZYZOWANIE : the description indicates an intersection of two streets ("WALICÓW / GRZYBOWSKA"); + resolved when at least two parts hit the gazetteer + NONE : no match; the ``powod`` field says why + +For publishers that give the location as an INTERNAL STATION CODE +(TAURON: "SKB3", "RCB4"), the resolver returns NONE with the reason +``kod_stacji_bez_slownika``: it does not try to guess, because the operator does not publish +a code dictionary and any match would be confabulation. + +Extension with coordinates (version 0.2) +---------------------------------------- +The result now carries a point and a SECOND, independent level: ``dokladnosc`` +(see :data:`DOKLADNOSC`). The two levels answer two different questions: + + ``pewnosc`` : how certain the IDENTIFICATION of the place name is, + ``dokladnosc`` : how precisely the returned point represents that place. + +They are disjoint by design: an EXACT match to a 6 km long street gives a point +with accuracy ``PUNKT_NA_OSI_ULICY`` and a blur on the order of a kilometer, while a +UNIQUE_TOKEN match to a short street gives a better point. The length of the matched +street's axis is returned in ``dlugosc_ulicy_m`` for exactly this reason: so that the blur +can be computed, not merely declared. + +The distinction is preserved between **failing to resolve the name** +(``pewnosc == "NONE"``) and **resolving the name without available geometry** (``pewnosc != "NONE"``, ``dokladnosc == "BRAK_GEOMETRII"``, -``powod == "nazwa_rozwiazana_bez_geometrii"``) -- to dwa różne stany wiedzy -i mieszanie ich zawyżałoby albo zaniżałoby pokrycie. Predykaty: -``Resolution.rozwiazane`` (nazwa) i ``Resolution.ma_wspolrzedne`` (punkt). +``powod == "nazwa_rozwiazana_bez_geometrii"``): these are two different states of knowledge, +and mixing them would overstate or understate coverage. Predicates: +``Resolution.rozwiazane`` (name) and ``Resolution.ma_wspolrzedne`` (point). -Numer domu nie jest interpolowany wzdłuż osi ulicy bez znanego zakresu -numeracji -- byłoby to zgadywanie. ``punkt_dla_numeru`` zwraca punkt wyłącznie -z indeksu punktów adresowych, jeśli taki jest wczytany. +The house number is not interpolated along the street axis without a known numbering +range: that would be guessing. ``punkt_dla_numeru`` returns a point only +from the address point index, if one has been loaded. """ from __future__ import annotations @@ -61,24 +61,24 @@ PEWNOSC = ("EXACT", "UNIQUE_TOKEN", "TOKEN_SUBSET", "REVERSED", "SKRZYZOWANIE", "NONE") -#: Poziom DOKLADNOSCI UMIEJSCOWIENIA -- odpowiada na inne pytanie niz ``pewnosc``. -#: ``pewnosc`` mowi, jak pewna jest IDENTYFIKACJA nazwy; ``dokladnosc`` mowi, -#: jak precyzyjnie zwrocony punkt reprezentuje wskazane miejsce. Rozdzielenie -#: jest konieczne, bo nazwa moze byc zidentyfikowana bezblednie (EXACT), a punkt -#: i tak byc tylko srodkiem kilkukilometrowej ulicy. +#: Level of placement ACCURACY (DOKLADNOSC): answers a different question than ``pewnosc``. +#: ``pewnosc`` says how certain the IDENTIFICATION of the name is; ``dokladnosc`` says +#: how precisely the returned point represents the indicated place. The separation +#: is necessary because a name can be identified flawlessly (EXACT), while the point +#: can still be only the center of a street several kilometers long. #: -#: PUNKT_ADRESOWY -- znany punkt adresowy (ulica + numer domu) -#: PUNKT_SKRZYZOWANIA -- przeciecie osi dwoch wskazanych ulic -#: PUNKT_NA_OSI_ULICY -- punkt w 50% dlugosci osi ulicy (niepewnosc ~ dlugosc/4) -#: CENTROID_MIEJSCOWOSCI -- rozwiazano tylko miejscowosc, nie ulice -#: BRAK_GEOMETRII -- nazwa ROZWIAZANA, ale gazeter nie ma dla niej wspolrzednych -#: BRAK -- nazwa nierozwiazana, wiec nie ma czego umiejscawiac +#: PUNKT_ADRESOWY : known address point (street + house number) +#: PUNKT_SKRZYZOWANIA : intersection of the axes of two indicated streets +#: PUNKT_NA_OSI_ULICY : point at 50% of the street axis length (uncertainty ~ length/4) +#: CENTROID_MIEJSCOWOSCI : only the locality was resolved, not the street +#: BRAK_GEOMETRII : name RESOLVED, but the gazetteer has no coordinates for it +#: BRAK : name not resolved, so there is nothing to place DOKLADNOSC = ( "PUNKT_ADRESOWY", "PUNKT_SKRZYZOWANIA", "PUNKT_NA_OSI_ULICY", "CENTROID_MIEJSCOWOSCI", "BRAK_GEOMETRII", "BRAK", ) -#: przedrostki i człony, które nie wyróżniają ulicy +#: prefixes and parts that do not distinguish a street _STOP = { "ul", "ulica", "al", "aleja", "aleje", "pl", "plac", "os", "osiedle", "rondo", "sw", "swietego", "swietej", "im", "imienia", "gen", "generala", "gen.", @@ -87,7 +87,7 @@ "bulwar", "park", "most", "wybrzeze", "brak", "dzialka", "nr", "dz", "obreb", } -#: kod stacji: 2-6 znaków wielkich liter/cyfr bez spacji, albo opis projektowanej stacji +#: station code: 2-6 uppercase letters/digits without spaces, or a description of a planned station _RE_STATION_CODE = re.compile(r"^[A-ZĄĆĘŁŃÓŚŻŹ]{2,5}\d{0,2}$") @@ -123,40 +123,40 @@ class Resolution: lon: Optional[float] pewnosc: str powod: str = "" - #: poziom dokladnosci umiejscowienia -- patrz DOKLADNOSC + #: placement accuracy level: see DOKLADNOSC dokladnosc: str = "BRAK" - #: miejscowosc, w ktorej gazeterze szukano (None dla gazetera jednoobszarowego) + #: locality whose gazetteer was searched (None for a single-area gazetteer) miejscowosc: Optional[str] = None - #: dlugosc osi dopasowanej ulicy w metrach, jesli gazeter ja niesie; - #: jest to jawna miara rozmycia punktu PUNKT_NA_OSI_ULICY + #: length of the matched street's axis in meters, if the gazetteer carries it; + #: this is an explicit measure of the blur of a PUNKT_NA_OSI_ULICY point dlugosc_ulicy_m: Optional[float] = None - #: liczba ROZLACZNYCH skladowych geometrii o tej nazwie w tej miejscowosci + #: number of DISJOINT geometry components with this name in this locality n_skladowych: Optional[int] = None - #: najwieksza odleglosc miedzy centroidami tych skladowych [m]. Duza - #: wartosc oznacza, ze nazwa ulicy NIE wyznacza jednego miejsca: w jednym - #: miescie istnieje kilka odleglych ulic o tej samej nazwie, a punkt lezy - #: na najdluzszej skladowej. Rejestry ustawowe nie podaja dzielnicy, wiec - #: tej niejednoznacznosci nie da sie usunac z danych opublikowanych -- - #: dlatego jest RAPORTOWANA, nie ukrywana. + #: largest distance between the centroids of these components [m]. A large + #: value means the street name does NOT determine a single place: within one + #: city there are several distant streets with the same name, and the point lies + #: on the longest component. Statutory registers do not give the district, so + #: this ambiguity cannot be removed from the published data; + #: that is why it is REPORTED, not hidden. rozrzut_skladowych_m: Optional[float] = None @property def rozwiazane(self) -> bool: - """Czy NAZWA zostala zidentyfikowana (niezaleznie od dostepnosci geometrii).""" + """Whether the NAME has been identified (regardless of geometry availability).""" return self.pewnosc != "NONE" @property def ma_wspolrzedne(self) -> bool: - """Czy wynik niesie punkt. Rozlaczne z ``rozwiazane``: nazwa moze byc - rozwiazana, a geometrii moze nie byc (``dokladnosc == BRAK_GEOMETRII``).""" + """Whether the result carries a point. Disjoint from ``rozwiazane``: the name may be + resolved while the geometry may be missing (``dokladnosc == BRAK_GEOMETRII``).""" return self.lat is not None and self.lon is not None class LocationResolver: - """Dopasowanie opisu miejsca do gazetera nazw ulic/miejsc. + """Matching of a place description against a gazetteer of street/place names. - ``gazetteer``: mapa nazwa -> (lat, lon) albo nazwa -> None (gdy współrzędnych - nie ma, a interesuje nas samo rozstrzygnięcie identyfikacji). + ``gazetteer``: a map name -> (lat, lon) or name -> None (when there are no + coordinates, and only the identification outcome matters to us). """ def __init__(self, gazetteer: dict[str, Optional[tuple[float, float]]]): @@ -175,13 +175,13 @@ def __init__(self, gazetteer: dict[str, Optional[tuple[float, float]]]): # ------------------------------------------------------------------ def _coords(self, name: str) -> tuple[Optional[float], Optional[float]]: - """Wspolrzedne wpisu gazetera. + """Coordinates of a gazetteer entry. - Obslugiwane postacie wpisu (zgodnosc wstecz zachowana): - ``None`` -- brak geometrii - ``(lat, lon)`` -- goly punkt - ``{"lat":..,"lon":..}`` -- wpis rozszerzony, moze dodatkowo niesc - ``os`` (lista [lat, lon]) i ``dlugosc_m`` + Supported entry forms (backward compatibility preserved): + ``None`` : no geometry + ``(lat, lon)`` : bare point + ``{"lat":..,"lon":..}`` : extended entry, may additionally carry + ``os`` (list [lat, lon]) and ``dlugosc_m`` """ c = self.gazetteer.get(name) if isinstance(c, dict): @@ -198,23 +198,23 @@ def _meta(self, name: str) -> dict: return c if isinstance(c, dict) else {} def axis(self, name: str) -> Optional[list[tuple[float, float]]]: - """Os ulicy jako lista (lat, lon), jesli gazeter ja niesie.""" + """Street axis as a list of (lat, lon), if the gazetteer carries it.""" os_ = self._meta(name).get("os") if not os_ or len(os_) < 2: return None return [(float(p[0]), float(p[1])) for p in os_] - #: prog udzialu wyjasnionych tokenow opisu; ponizej progu dopasowanie - #: nie-EXACT jest odrzucane jako opis slowny, nie nazwa ulicy + #: threshold for the share of explained description tokens; below the threshold a + #: non-EXACT match is rejected as a verbal description, not a street name PROG_POKRYCIA_TOKENOW = 0.5 - #: od tylu tokenow opisu prog jest stosowany (krotkie opisy sa nazwami ulic) + #: from this many description tokens the threshold is applied (short descriptions are street names) MIN_TOKENOW_DLA_PROGU = 4 def _udzial_wyjasnionych(self, ts: list[str], name: str) -> float: - """Jaka czesc tokenow opisu wyjasnia dopasowana nazwa. + """What fraction of the description's tokens is explained by the matched name. - Token uchodzi za wyjasniony, gdy jest rowny tokenowi nazwy albo jest - jego przedrostkiem (obsluga inicjalow: "a." -> "augusta"). + A token counts as explained when it equals a token of the name or is + a prefix of it (handling of initials: "a." -> "augusta"). """ if not ts: return 0.0 @@ -223,13 +223,13 @@ def _udzial_wyjasnionych(self, ts: list[str], name: str) -> float: return ile / len(ts) def _opis_slowny(self, ts: list[str], name: str) -> bool: - """Czy dopasowanie opiera sie na jednym tokenie dlugiego opisu slownego. + """Whether the match relies on a single token of a long verbal description. - Zmierzone na panelu: opis "Bezposrednie sasiedztwo Lotniska Chopina w - Warszawie" trafial w ulice "Fryderyka Chopina" przez sam token - "chopina", dajac punkt w srodmiesciu zamiast przy lotnisku. Dopasowanie - wyjasniajace mniej niz polowe tokenow dlugiego opisu nie jest - identyfikacja ulicy i jest odrzucane z jawnym powodem. + Measured on the panel: the description "Bezposrednie sasiedztwo Lotniska Chopina w + Warszawie" matched the street "Fryderyka Chopina" through the single token + "chopina", giving a point in the city center instead of near the airport. A match + explaining less than half the tokens of a long description is not an + identification of a street and is rejected with an explicit reason. """ if len(ts) < self.MIN_TOKENOW_DLA_PROGU: return False @@ -249,13 +249,14 @@ def _hit(self, query: str, name: str, level: str, # ------------------------------------------------------------------ def punkt_dla_numeru(self, name: str, numer: Optional[str]) -> Optional[tuple[float, float]]: - """Umiejscowienie numeru domu. - - Jesli gazeter niesie punkt adresowy dla pary (ulica, numer) -- zwraca go. - W przeciwnym razie zwraca ``None``: interpolacja numeru wzdluz osi bez - znanego zakresu numeracji bylaby zgadywaniem, a rozwiazywacz nie zgaduje. - Os ulicy jest zachowana w gazeterze wlasnie po to, by punkt adresowy dal - sie do niej odniesc, gdy zbior punktow adresowych bedzie dostepny. + """Placement of a house number. + + If the gazetteer carries an address point for the pair (street, number), it is + returned. Otherwise returns ``None``: interpolating the number along the axis + without a known numbering range would be guessing, and the resolver does not + guess. The street axis is kept in the gazetteer for exactly this reason: so + that the address point can be referenced against it once a set of address + points becomes available. """ if not numer: return None @@ -269,11 +270,12 @@ def punkt_dla_numeru(self, name: str, numer: Optional[str]) -> Optional[tuple[fl @staticmethod def _przeciecie(a: list[tuple[float, float]], b: list[tuple[float, float]]) -> Optional[tuple[float, float]]: - """Punkt przeciecia (albo najmniejszego zblizenia) dwoch osi ulic. + """Intersection point (or closest approach) of two street axes. - Liczone na osiach z gazetera, w przyblizeniu rownopolowym wokol - szerokosci srodkowej -- na skali miasta blad tej aproksymacji jest - rzedu metrow i nie ma znaczenia wobec rozmycia samego wejscia. + Computed on the axes from the gazetteer, with an equirectangular approximation + around the median latitude: at the scale of a city the error of this + approximation is on the order of meters and is negligible compared to the + blur of the input itself. """ import math @@ -307,15 +309,15 @@ def xy(p): # ------------------------------------------------------------------ def resolve(self, query: Optional[str], *, is_station_code: bool = False, sprawdzaj_kod_stacji: bool = True) -> Resolution: - """Rozwiąż opis miejsca. - - ``sprawdzaj_kod_stacji=False`` wyłącza heurystykę kodu stacji. Jest to - potrzebne, gdy wywołujący już rozstrzygnął, że opis NIE jest kodem - stacji -- na przykład :class:`MultiLocalityResolver` sprawdza kod na - pełnym opisie, a potem przekazuje tu sam człon ulicy. Bez tego - przełącznika krótkie nazwy ulic zapisane wersalikami ("MARSA", "TAMKA", - "DŁUGA") wpadały w wzorzec kodu stacji: zmierzone 25 fałszywych braków - na 1 236 wierszach rejestru Stoen Operator. + """Resolve a place description. + + ``sprawdzaj_kod_stacji=False`` disables the station code heuristic. This is + needed when the caller has already determined that the description is NOT a + station code; for example :class:`MultiLocalityResolver` checks the code on + the full description and then passes only the street part here. Without this + switch, short street names written in uppercase ("MARSA", "TAMKA", + "DŁUGA") fell into the station code pattern: measured 25 false negatives + on 1,236 rows of the Stoen Operator register. """ q = (query or "").strip() if not q: @@ -323,11 +325,11 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, if is_station_code or (sprawdzaj_kod_stacji and _RE_STATION_CODE.match(q)): return Resolution(q, None, None, None, "NONE", "kod_stacji_bez_slownika") - # odetnij człon miejscowości, jeśli podany jako "MIASTO, adres" + # strip the locality part, if given as "CITY, address" street = q.split(",", 1)[1] if "," in q else q nq = normalize(street) - # 1) dokładne + # 1) exact if nq in self._by_norm: return self._hit(q, self._by_norm[nq][0], "EXACT") nq_full = normalize(street.split(" nr ")[0]) @@ -338,11 +340,12 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, if not ts: return Resolution(q, None, None, None, "NONE", "brak_tokenow_wyrozniajacych") - # 2) unikalny token + # 2) unique token cands = {t: self._by_token.get(t, []) for t in ts} - # Odrzucenie przez prog pokrycia tokenow NIE konczy rozwiazywania: - # dalsze strategie (odwrocenie czlonow, skrzyzowanie) moga opis wyjasnic - # w calosci. Flaga sluzy tylko do nadania powodu, gdy nic nie zadziala. + # Rejection via the token coverage threshold does NOT end resolution: + # further strategies (reversing the parts, intersection) may explain the + # description in full. The flag only serves to assign a reason when nothing + # works. odrzucono_opis = False unique = [names[0] for t, names in cands.items() if len(names) == 1] @@ -352,7 +355,7 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, else: return self._hit(q, unique[0], "UNIQUE_TOKEN") - # 3) podzbiór tokenów + # 3) token subset fs = frozenset(ts) subset_hits = [n for tsx, names in self._by_tokenset.items() if fs and fs <= tsx for n in names] @@ -362,7 +365,7 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, else: return self._hit(q, subset_hits[0], "TOKEN_SUBSET") - # 4) odwrócona kolejność członów + # 4) reversed order of parts rev = self._resolve_reversed(street, ts) if rev is not None: if self._opis_slowny(ts, rev): @@ -370,8 +373,8 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, else: return self._hit(q, rev, "REVERSED") - # 5) skrzyżowanie: publikujący podaje dwie ulice ("WALICÓW / GRZYBOWSKA"). - # Miejsce jest określone -- to węzeł sieci ulic, nie jedna ulica. + # 5) intersection: the publisher gives two streets ("WALICÓW / GRZYBOWSKA"). + # The place is determined: it is a node of the street network, not a single street. parts = [p for p in re.split(r"[/\\]", street) if p.strip()] if len(parts) > 1: hits = [] @@ -383,7 +386,8 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, lat, lon = hits[0].lat, hits[0].lon dokl = "PUNKT_NA_OSI_ULICY" if lat is not None else "BRAK_GEOMETRII" powod = f"dopasowano {len(hits)} z {len(parts)} członów" - # jesli gazeter niesie osie obu ulic, punktem jest ich przeciecie + # if the gazetteer carries the axes of both streets, the point is their + # intersection ax = [self.axis(h.matched) for h in hits[:2]] if all(ax): xp = self._przeciecie(ax[0], ax[1]) @@ -405,12 +409,13 @@ def resolve(self, query: Optional[str], *, is_station_code: bool = False, # ------------------------------------------------------------------ def _resolve_reversed(self, street: str, ts: list[str]) -> Optional[str]: - """Domyka przypadki typu "WINCENTEGO ŚW." / "BEMA J.". + """Closes cases of the type "WINCENTEGO ŚW." / "BEMA J.". - Publikujący zapisują nazwisko na początku i skracają imię lub tytuł do - inicjału. Szukamy nazw gazetera, których zbiór tokenów zawiera WSZYSTKIE - pełne tokeny opisu (niezależnie od kolejności), a pozostałe tokeny opisu - są przedrostkami tokenów kandydata (obsługa inicjałów "J." -> "jozefa"). + Publishers write the surname first and shorten the given name or title to an + initial. We look for gazetteer names whose token set contains ALL the full + tokens of the description (regardless of order), while the remaining tokens + of the description are prefixes of the candidate's tokens (handling of + initials "J." -> "jozefa"). """ full = [t for t in ts if len(t) > 2] inits = [t for t in ts if len(t) <= 2] @@ -427,7 +432,7 @@ def _resolve_reversed(self, street: str, ts: list[str]) -> Optional[str]: n for n in pool if all(any(tok.startswith(i) for tok in tokens(n)) for i in inits) } - # dopuść też nieskrócone odwrócenie: dokładnie ten sam multizbiór tokenów + # also allow an unabbreviated reversal: exactly the same multiset of tokens exact_rev = {n for n in pool if frozenset(tokens(n)) == frozenset(ts)} if len(exact_rev) == 1: return next(iter(exact_rev)) @@ -459,30 +464,32 @@ def summarize(resolutions: list[Resolution]) -> dict: class MultiLocalityResolver: - """Rozwiązywacz dla gazetera z podziałem na miejscowości. - - Rejestry przyłączeniowe podają lokalizację jako ``MIEJSCOWOŚĆ, ulica``. - Jedna płaska przestrzeń nazw ulic byłaby tu błędem: ta sama nazwa ulicy - występuje w kilkunastu miejscowościach aglomeracji i płaski gazeter musiałby - albo zgadywać, albo zwracać ``wiele_kandydatow``. Ta klasa trzyma osobny - :class:`LocationResolver` na miejscowość i kieruje zapytanie do właściwego. - - Zachowana jest nadrzędna zasada pakietu: **brak z przyczyną zamiast - zgadywania**. Dochodzą dwa nowe, jawne powody braku: - - ``miejscowosc_poza_gazeterem`` -- podanej miejscowości nie ma w gazeterze; - to ograniczenie ZASIĘGU, nie porażka - dopasowania, i jest raportowane osobno - ``nazwa_rozwiazana_bez_geometrii`` -- nazwa dopasowana, ale wpis gazetera - nie ma współrzędnych - - Gdy ulicy nie udało się rozwiązać, a miejscowość owszem, zwracany jest - **brak** (``pewnosc == "NONE"``) -- centroid miejscowości NIE jest - podstawiany w pole ``wspolrzedne``, bo byłby punktem o innym znaczeniu niż - reszta kolumny. Centroid jest natomiast udostępniony w polu - ``lat``/``lon`` z ``dokladnosc == "CENTROID_MIEJSCOWOSCI"`` tylko wtedy, gdy - wywołujący jawnie poprosi (``dopusc_centroid=True``), i wtedy rozpoznaje go - po polu ``dokladnosc``. + """Resolver for a gazetteer split by locality. + + Connection registers give the location as ``LOCALITY, street``. + A single flat namespace of street names would be an error here: the same street + name occurs in a dozen or so localities of the agglomeration, and a flat gazetteer + would have to either guess or return ``wiele_kandydatow``. This class keeps a + separate :class:`LocationResolver` per locality and routes the query to the right + one. + + The package's overriding principle is preserved: **a no-match with a reason + instead of guessing**. Two new, explicit no-match reasons are added: + + ``miejscowosc_poza_gazeterem`` : the given locality is not in the gazetteer; + this is a COVERAGE limitation, not a + matching failure, and is reported + separately + ``nazwa_rozwiazana_bez_geometrii`` : the name was matched, but the gazetteer + entry has no coordinates + + When the street could not be resolved but the locality could, a + **no-match** is returned (``pewnosc == "NONE"``): the locality centroid is NOT + substituted into the ``wspolrzedne`` field, because it would be a point with a + different meaning than the rest of the column. The centroid is instead made + available in the ``lat``/``lon`` field with ``dokladnosc == "CENTROID_MIEJSCOWOSCI"`` + only when the caller explicitly asks for it (``dopusc_centroid=True``), and it can + then be recognized by the ``dokladnosc`` field. """ def __init__(self, miejscowosci: dict[str, dict], @@ -493,7 +500,7 @@ def __init__(self, miejscowosci: dict[str, dict], for key, m in miejscowosci.items(): k = normalize(key) self.resolvery[k] = LocationResolver(m.get("ulice", {})) - # opcjonalny indeks punktow adresowych: "|" -> [lat, lon] + # optional index of address points: "|" -> [lat, lon] pa = m.get("punkty_adresowe") or {} if pa: idx = {} @@ -505,9 +512,9 @@ def __init__(self, miejscowosci: dict[str, dict], self.centroidy[k] = (float(m["lat"]), float(m["lon"])) self._alias[k] = k self._alias.setdefault(normalize(m.get("nazwa") or key), k) - # alias czlonu glownego: "SEKOCIN NOWY"/"SEKOCIN STARY" -> pierwszy czlon, - # gdy jest jednoznaczny; gdy nie jest, alias nie powstaje i zapytanie - # o "SEKOCIN" konczy sie jawnym brakiem zamiast wyborem na chybil trafil + # alias of the main part: "SEKOCIN NOWY"/"SEKOCIN STARY" -> the first part, + # when it is unambiguous; when it is not, the alias is not created and a query + # for "SEKOCIN" ends in an explicit no-match instead of a random choice heads: dict[str, list[str]] = defaultdict(list) for k in list(self.resolvery): parts = k.split() @@ -522,26 +529,26 @@ def __init__(self, miejscowosci: dict[str, dict], # ------------------------------------------------------------------ def rozdziel(self, tekst: Optional[str]) -> tuple[Optional[str], str]: - """Rozdziel ``"MIEJSCOWOŚĆ, ulica"`` na (miejscowość, ulica).""" + """Split ``"LOCALITY, street"`` into (locality, street).""" t = (tekst or "").strip() if "," in t: a, b = t.split(",", 1) return a.strip(), b.strip() return None, t - #: numer domu na koncu opisu: "25", "85A", "12/14", "3 bis" + #: house number at the end of the description: "25", "85A", "12/14", "3 bis" _RE_NUMER = re.compile(r"\s+(\d+\s*[a-zA-Z]?(?:\s*/\s*\d+\s*[a-zA-Z]?)?)\s*$") @classmethod def rozdziel_numer(cls, street: str) -> tuple[str, Optional[str]]: - """Odetnij numer domu z końca opisu ulicy. - - Zwraca ``(ulica, numer)`` albo ``(ulica, None)``. Sama obecność liczby - na końcu nie dowodzi, że to numer domu -- w nazwach ulic liczby są - częste ("Aleja 4 Czerwca 1989", "11 Listopada"). Dlatego wynik tego - cięcia jest w :meth:`resolve` przyjmowany tylko wtedy, gdy reszta opisu - dopasowuje się do TEJ SAMEJ nazwy ulicy, a numer trafia w indeks - punktów adresowych. Inaczej opis pozostaje nietknięty. + """Strip the house number from the end of a street description. + + Returns ``(street, number)`` or ``(street, None)``. The mere presence of a + number at the end does not prove that it is a house number: numbers are + common in street names ("Aleja 4 Czerwca 1989", "11 Listopada"). That is why + the result of this cut is accepted in :meth:`resolve` only when the rest of + the description matches the SAME street name, and the number hits the address + point index. Otherwise the description is left untouched. """ m = cls._RE_NUMER.search(street or "") if not m: @@ -563,12 +570,12 @@ def resolve(self, query: Optional[str], *, if miejscowosc: m_txt = miejscowosc if not m_txt: - # Bez ZADEKLAROWANEJ miejscowosci dopasowanie nazwy ulicy do gazetera - # konkretnego miasta jest zgadywaniem, nie rozwiazaniem. Zmierzone: - # przy podstawianiu domyslnej miejscowosci opisy TAURONA typu - # "Stacja projektowana" trafialy w warszawska "ul. Projektowana", - # a "Wrzoski (planowany)" w drogowe "planowany lacznik". Dlatego - # domyslna miejscowosc jest opcjonalna i domyslnie WYLACZONA. + # Without a DECLARED locality, matching a street name against the + # gazetteer of a specific city is guessing, not resolving. Measured: + # when substituting the default locality, TAURON descriptions of the + # type "Stacja projektowana" matched the Warsaw "ul. Projektowana", + # and "Wrzoski (planowany)" matched the road "planowany lacznik". That + # is why the default locality is optional and OFF by default. if not self.domyslna: return Resolution(q, None, None, None, "NONE", "brak_deklaracji_miejscowosci") @@ -587,10 +594,10 @@ def resolve(self, query: Optional[str], *, sub = self.resolvery[key] r = sub.resolve(street, sprawdzaj_kod_stacji=False) - # numer domu: jesli nie podano wprost, spróbuj odciąć z końca opisu. - # Cięcie jest przyjmowane tylko wtedy, gdy reszta wskazuje TĘ SAMĄ ulicę - # (albo gdy pełny opis w ogóle się nie dopasował) -- inaczej liczba jest - # częścią nazwy ulicy, nie numerem domu. + # house number: if not given explicitly, try to cut it off the end of the + # description. The cut is accepted only when the rest indicates the SAME + # street (or when the full description did not match at all); otherwise the + # number is part of the street name, not a house number. num = numer if num is None: rest, kand = self.rozdziel_numer(street) @@ -632,9 +639,9 @@ def summarize(resolutions: list[Resolution]) -> dict: def resolver_from_gazeter_json(path, *, domyslna: Optional[str] = None) -> MultiLocalityResolver: - """Zbuduj :class:`MultiLocalityResolver` z gazetera ze współrzędnymi. + """Build a :class:`MultiLocalityResolver` from a gazetteer with coordinates. - Oczekiwany układ pliku: ``{"miejscowosci": {KLUCZ: {"nazwa","lat","lon", + Expected file layout: ``{"miejscowosci": {KLUCZ: {"nazwa","lat","lon", "ulice": {nazwa: {"lat","lon","dlugosc_m","os"}}}}}``. """ import json @@ -646,7 +653,7 @@ def resolver_from_gazeter_json(path, *, domyslna: Optional[str] = None) -> Multi def resolver_from_osm_json(path) -> LocationResolver: - """Zbuduj rozwiązywacz z pliku JSON z nazwami ulic (lista nazw albo mapa).""" + """Build a resolver from a JSON file with street names (list of names or a map).""" import json with open(path, encoding="utf-8") as fh: diff --git a/src/gridqueue/layout.py b/src/gridqueue/layout.py index 061511f..dfd4926 100644 --- a/src/gridqueue/layout.py +++ b/src/gridqueue/layout.py @@ -1,28 +1,30 @@ -"""Wydobycie oparte na UKŁADZIE STRONY, nie na wyrażeniach regularnych. - -Wyrażenie regularne działa na tekście spłaszczonym przez ekstraktor PDF: kolejność -słów jest kolejnością rysowania, a granice kolumn są odtwarzane ze spacji. Gdy -komórka jest pusta albo zawiera spację, sąsiednie pola się zlewają i wartość wsiąka -do złego pola. W poprzedniej wersji parsera TAURONA dotyczyło to 767 z 10 559 -wierszy (7,3%). - -Tu robimy odwrotnie: czytamy POŁOŻENIE każdego słowa (x0, x1, top, bottom) i -najpierw ustalamy geometrię tabeli, a dopiero potem przypisujemy słowa do komórek. -Dwie strategie, wybierane po tym, co dokument faktycznie zawiera: - - RULED -- dokument ma linie siatki (pionowe krawędzie prostokątów). Granice - kolumn są WPROST narysowane przez wytwórcę dokumentu; pusta komórka - nie może zlać się z sąsiednią, bo jest odgrodzona linią. - BANDED -- dokument nie ma linii. Granice wyprowadzamy z rozkładu pokrycia osi x - przez słowa: kolumna to spójny przedział pokryty słowami, granica to - pionowy korytarz bieli obecny na całej wysokości bloku tabeli. - -Wybór pdfplumber zamiast camelot/tabula: camelot w trybie lattice wymaga Ghostscriptu -i konwersji do rastra (granice kolumn odtwarzane z obrazu, nie z wektorów), tabula -wymaga JVM. pdfplumber daje bezpośredni dostęp do współrzędnych słów i krawędzi -wektorowych z pdfminer.six, więc granica kolumny jest liczbą z pliku, a nie wynikiem -detekcji krawędzi na bitmapie -- co jest dokładnie tą własnością, od której zależy -teza tego narzędzia. +"""Extraction based on PAGE LAYOUT, not on regular expressions. + +The regular expression operates on text flattened by the PDF extractor: word order +is drawing order, and column boundaries are reconstructed from spaces. When a +cell is empty or contains a space, adjacent fields merge together and the value +soaks into the wrong field. In the previous version of the TAURON parser this +affected 767 of 10 559 rows (7.3%). + +Here we do the opposite: we read the POSITION of each word (x0, x1, top, bottom) +and first establish the geometry of the table, and only then assign words to +cells. Two strategies, chosen according to what the document actually contains: + + RULED : the document has grid lines (vertical edges of rectangles). Column + boundaries are drawn DIRECTLY by the document's producer; an empty + cell cannot merge with its neighbour because it is fenced off by a + line. + BANDED : the document has no lines. Boundaries are derived from the distribution + of x-axis coverage by the words: a column is a contiguous interval + covered by words, a boundary is a vertical corridor of whitespace + present across the entire height of the table block. + +The choice of pdfplumber over camelot/tabula: camelot in lattice mode requires +Ghostscript and conversion to raster (column boundaries reconstructed from an +image, not from vectors), tabula requires a JVM. pdfplumber gives direct access +to word coordinates and vector edges from pdfminer.six, so a column boundary is +a number from the file, not the result of edge detection on a bitmap, which is +exactly the property on which this tool's thesis depends. """ from __future__ import annotations @@ -45,13 +47,13 @@ # -------------------------------------------------------------------------- -# geometria kolumn +# column geometry # -------------------------------------------------------------------------- @dataclass class ColumnGeometry: - """Granice kolumn na stronie: n+1 współrzędnych x dla n kolumn.""" + """Column boundaries on the page: n+1 x coordinates for n columns.""" bounds: list[float] strategy: str # "ruled" | "banded" @@ -62,11 +64,11 @@ def n_cols(self) -> int: return max(0, len(self.bounds) - 1) def column_of(self, x0: float, x1: float) -> Optional[int]: - """Kolumna, do której należy słowo o rozpiętości [x0, x1]. + """The column to which a word with the span [x0, x1] belongs. - Decyduje ŚRODEK słowa, nie jego lewa krawędź: słowo przycięte przez linię - siatki (co zdarza się przy wąskich kolumnach) trafia tam, gdzie leży jego - większa część. + The CENTER of the word decides, not its left edge: a word cut by a grid + line (which happens with narrow columns) ends up where the larger part + of it lies. """ mid = 0.5 * (x0 + x1) for i in range(self.n_cols): @@ -80,11 +82,11 @@ def column_of(self, x0: float, x1: float) -> Optional[int]: def detect_ruled_columns(page, *, min_len: float = 5.0, tol: float = 1.5) -> ColumnGeometry: - """Granice kolumn z pionowych krawędzi wektorowych strony. + """Column boundaries from the page's vertical vector edges. - Krawędzie krótsze niż ``min_len`` to zwykle ozdobniki / ramki nagłówka, nie - linie siatki. Krawędzie odległe o mniej niż ``tol`` to dwie strony tej samej - grubej linii -- scalane do średniej. + Edges shorter than ``min_len`` are usually decorations / header frames, not + grid lines. Edges less than ``tol`` apart are two sides of the same thick + line, merged to their average. """ xs = sorted( e["x0"] for e in page.edges @@ -106,11 +108,11 @@ def detect_banded_columns( min_gap: float = 4.0, resolution: float = 0.5, ) -> ColumnGeometry: - """Granice kolumn z pionowych korytarzy bieli w bloku słów. + """Column boundaries from vertical corridors of whitespace in the word block. - Buduje wektor pokrycia osi x (czy jakiekolwiek słowo zajmuje daną pozycję), - znajduje przerwy dłuższe niż ``min_gap`` i stawia granicę w ich środku. - Używane, gdy dokument nie ma linii siatki. + Builds an x-axis coverage vector (whether any word occupies a given position), + finds gaps longer than ``min_gap`` and places a boundary at their center. + Used when the document has no grid lines. """ if not words: return ColumnGeometry([], "banded") @@ -140,7 +142,7 @@ def detect_banded_columns( # -------------------------------------------------------------------------- -# przypisanie słów do komórek +# assigning words to cells # -------------------------------------------------------------------------- @@ -150,7 +152,7 @@ def assign_words_to_columns( *, line_tol: float = 2.0, ) -> list[list[str]]: - """Ułóż słowa w wiersze wizualne, a w wierszu -- w komórki wg geometrii kolumn.""" + """Arrange words into visual rows, and within a row into cells according to column geometry.""" ws = sorted(words, key=lambda w: (round(w["top"], 1), w["x0"])) lines: list[list[dict]] = [] for w in ws: @@ -175,12 +177,12 @@ def merge_continuation_rows( *, joiner: str = " ", ) -> list[list[str]]: - """Scal wiersze wielolinijkowe. + """Merge multi-line rows. - ``is_row_start`` rozstrzyga, czy linia rozpoczyna nowy rekord (u polskich - publikujących: pierwsza komórka to numer porządkowy). Linie pomiędzy są - dopisywane do ostatniego rekordu, kolumna po kolumnie -- dzięki temu zawinięty - adres nie przenosi się do sąsiedniego pola. + ``is_row_start`` decides whether a line begins a new record (for Polish + publishers: the first cell is a sequence number). Lines in between are + appended to the last record, column by column: this way a wrapped + address does not spill over into the neighbouring field. """ rows: list[list[str]] = [] for ln in lines: @@ -197,11 +199,11 @@ def merge_continuation_rows( def extract_ruled_page(page, geom: Optional[ColumnGeometry] = None, *, intersection_tolerance: float = 5.0) -> list[list[Optional[str]]]: - """Wiersze strony z tabeli o narysowanej siatce. + """Rows of a page from a table with a drawn grid. - Granice pionowe podajemy jawnie (z ``detect_ruled_columns``), poziome zostawiamy - detekcji linii -- dzięki temu komórka wielolinijkowa jest scalana przez samą - siatkę, bez heurystyki ciągłości. + Vertical boundaries are given explicitly (from ``detect_ruled_columns``), horizontal + ones are left to line detection: this way a multi-line cell is merged by the + grid itself, without a continuity heuristic. """ if geom is None: geom = detect_ruled_columns(page) @@ -218,7 +220,7 @@ def extract_ruled_page(page, geom: Optional[ColumnGeometry] = None, *, # -------------------------------------------------------------------------- -# audyt przesunięcia kolumn +# column shift audit # -------------------------------------------------------------------------- _RE_DATE = re.compile(r"^\s*\d{2}[./-]\d{2}[./-]\d{4}\s*$|^\s*\d{4}-\d{2}-\d{2}\s*$") @@ -238,18 +240,19 @@ def looks_like_number(v: Any) -> bool: return bool(_RE_NUM.match(str(v))) -#: liczba doklejona na początku pola tekstowego -- ślad wsiąknięcia sąsiedniej -#: kolumny liczbowej w pole opisowe (najczęstsza postać przesunięcia kolumn) +#: a number stuck onto the beginning of a text field: a trace of the neighbouring +#: numeric column soaking into the descriptive field (the most common form of column shift) _RE_LEADING_NUM = re.compile(r"^\s*-?\d+(?:[.,]\d+)?(?:\s+-?\d+(?:[.,]\d+)?)*\s+\S") def looks_like_text(v: Any) -> bool: - """Czy wartość może stać w polu opisowym. + """Whether the value can stand in a descriptive field. - Odrzuca nie tylko czyste liczby i daty, ale też ciągi rozpoczynające się od - tokenu liczbowego przed tekstem ("0,1 0,1 WARUNKI PRZYŁĄCZENIA ..."). Ta - postać jest podpisem przesunięcia kolumn w wydobyciu regexowym: pusta komórka - mocy znika ze spłaszczonego tekstu i wartość mocy dokleja się do statusu. + Rejects not only pure numbers and dates, but also strings that start with a + numeric token before the text ("0,1 0,1 WARUNKI PRZYŁĄCZENIA ..."). This + form is the signature of column shift in regex-based extraction: an empty + capacity cell disappears from the flattened text and the capacity value + sticks onto the status. """ s = str(v).strip() if not s or looks_like_number(s) or looks_like_date(s): @@ -257,9 +260,9 @@ def looks_like_text(v: Any) -> bool: return not bool(_RE_LEADING_NUM.match(s)) -#: poziom napięcia jest polem o wąskiej, znanej dziedzinie: skrót klasy (nn/SN/WN/NN) -#: albo wartość z jednostką ("110 kV", "15 kV"). Liczba bez jednostki albo zdanie -#: oznaczają, że do pola wsiąkła treść sąsiedniej kolumny. +#: voltage level is a field with a narrow, known domain: a class abbreviation (nn/SN/WN/NN) +#: or a value with a unit ("110 kV", "15 kV"). A number without a unit or a sentence +#: means that the content of the neighbouring column has soaked into the field. _RE_VOLT = re.compile( r"^\s*(?:nn|sn|wn|nn/sn|sn/nn|nN)\s*$" r"|^\s*\d+(?:[.,]\d+)?\s*[kKmM]?[vV]\s*$" @@ -272,7 +275,7 @@ def looks_like_voltage(v: Any) -> bool: return bool(_RE_VOLT.match(str(v))) if v is not None else False -#: predykaty dziedziny dla kolumn schematu -- "czy ta wartość MOŻE stać w tym polu" +#: domain predicates for schema columns: "can this value stand in this field" DOMAIN_PREDICATES: dict[str, Callable[[Any], bool]] = { "moc_wprowadzana": looks_like_number, "moc_pobierana": looks_like_number, @@ -293,7 +296,7 @@ def looks_like_voltage(v: Any) -> bool: @dataclass class ShiftAudit: - """Wynik audytu przesunięcia kolumn.""" + """Result of the column shift audit.""" n_wierszy: int n_przesunietych: int @@ -320,12 +323,13 @@ def audit_column_shift( nullish: Optional[set[str]] = None, n_examples: int = 5, ) -> ShiftAudit: - """Policz wiersze, w których jakaś niepusta wartość stoi w polu, do którego - nie może należeć (liczba w polu daty, tekst statusu w polu mocy itd.). + """Count rows in which some non-empty value stands in a field it cannot + belong to (a number in a date field, status text in a capacity field, etc.). - To jest operacyjna definicja "przesuniętej kolumny": nie porównujemy z wzorcem, - tylko sprawdzamy WEWNĘTRZNĄ sprzeczność typu. Ta sama miara jest liczona dla - starego i nowego wydobycia, więc porównanie jest uczciwe. + This is the operational definition of a "shifted column": we do not compare + against a reference, we only check an INTERNAL type contradiction. The same + measure is computed for the old and the new extraction, so the comparison + is fair. """ preds = predicates if predicates is not None else DOMAIN_PREDICATES nl = nullish or {"", "-", "--", "---", "nan", "none", "brak", "nie dotyczy"} diff --git a/src/gridqueue/longitudinal.py b/src/gridqueue/longitudinal.py index 59f711b..c27990e 100644 --- a/src/gridqueue/longitudinal.py +++ b/src/gridqueue/longitudinal.py @@ -1,28 +1,28 @@ -"""Porównanie dwóch edycji tego samego rejestru. - -Dlaczego to nie jest zwykłe złączenie po identyfikatorze --------------------------------------------------------- -Rejestry ustawowe **nie publikują trwałego identyfikatora wniosku**. U części -publikujących pole identyfikatora jest puste w niemal każdym wierszu, a pakiet -wstawia wtedy zastępnik oparty na liczbie porządkowej w dokumencie. Taki -zastępnik jest stabilny w obrębie jednej edycji i **bezwartościowy między -edycjami**: wiersz numer 869 w jednej edycji nie jest tym samym wnioskiem co -wiersz 869 w następnej, bo pozycje się przesuwają. - -Śledzenie wniosku w czasie wymaga więc klucza zastępczego zbudowanego z treści. -Nie jest to obejście, lecz właściwość ujawnienia, którą trzeba zadeklarować: -klucz treściowy rozjeżdża się, gdy publikujący skoryguje którekolwiek z pól -wchodzących w jego skład, i wtedy ten sam wniosek wygląda jak zniknięcie -w parze z pojawieniem. - -Walidacja dopasowania ---------------------- -Macierz przejść statusu daje na to niezależny test. Jeśli klucz dopasowuje -właściwe wiersze, przejścia powinny biec **zgodnie z kierunkiem postępowania -administracyjnego** (złożony → w analizie → warunki wydane → umowa). Jeśli -dopasowuje losowo, przejścia będą rozłożone bez tego porządku. Własność -``udzial_przejsc_w_przod`` zwraca tę miarę, żeby nie trzeba jej było liczyć -ręcznie. +"""Comparison of two editions of the same register. + +Why this is not an ordinary join by identifier +---------------------------------------------- +Statutory registers **do not publish a persistent application identifier**. For some +publishers the identifier field is empty in almost every row, and the package +then inserts a surrogate based on the ordinal number in the document. Such +a surrogate is stable within a single edition and **worthless between +editions**: row number 869 in one edition is not the same application as +row 869 in the next, because positions shift. + +Tracking an application over time therefore requires a surrogate key built from content. +This is not a workaround but a property of the disclosure that has to be declared: +the content key drifts apart when the publisher corrects any of the fields +that make it up, and then the same application looks like a disappearance +paired with an appearance. + +Linkage validation +------------------ +The status-transition matrix gives an independent test for this. If the key matches +the correct rows, transitions should proceed **in the direction of the administrative +proceeding** (filed → under review → conditions issued → agreement). If +it matches at random, transitions will be scattered without this order. The property +``udzial_przejsc_w_przod`` returns this measure, so that it does not need to be computed +by hand. """ from __future__ import annotations @@ -52,8 +52,8 @@ "linkage_recall", ] -#: Pola domyślnego klucza treściowego. Celowo BEZ dat i bez statusu: daty bywają -#: uzupełniane między edycjami, a status jest właśnie tym, czego zmianę mierzymy. +#: Fields of the default content key. Deliberately WITHOUT dates and without status: dates are +#: sometimes filled in between editions, and status is exactly what we are measuring the change of. DEFAULT_KEY_FIELDS: tuple[str, ...] = ( "publikujacy", "lokalizacja_tekst", @@ -64,23 +64,23 @@ ) -#: Klucz dla wierszy encji WEZEL. Domyślny `DEFAULT_KEY_FIELDS` jest zbudowany -#: dla encji WNIOSEK i na wierszach węzłowych ROZPADA SIĘ: pola `klasa_zasobu`, -#: `moc_wprowadzana` i `moc_pobierana` są tam puste, więc klucz traci -#: rozróżnialność. Zmierzone na parze wydań publikującego hiszpańskiego: -#: kluczem domyślnym 916 z 1838 wierszy wpada w kolizję i 660 zostaje -#: odrzuconych jako niejednoznaczne, a kluczem poniżej kolizji jest ZERO, -#: wszystkie 1838 par dopasowuje się jednoznacznie, przy precyzji i czułości -#: równych 1,000. +#: Key for rows of the NODE entity. The default `DEFAULT_KEY_FIELDS` is built +#: for the APPLICATION entity and on node rows it FALLS APART: the fields `klasa_zasobu`, +#: `moc_wprowadzana` and `moc_pobierana` are empty there, so the key loses +#: distinguishability. Measured on a pair of editions of the Spanish publisher: +#: with the default key, 916 out of 1838 rows collide and 660 are +#: rejected as ambiguous, while with the key below the collision count is ZERO, +#: all 1838 pairs match unambiguously, with precision and recall +#: equal to 1,000. #: -#: Wniosek ogólniejszy: klucz treściowy musi być dobrany do ENCJI, tak samo jak -#: rdzeń schematu. Użycie klucza wnioskowego do wierszy węzłowych nie zgłasza -#: błędu, po cichu produkuje kolizje, które w dalszej analizie wyglądają jak -#: zdarzenia w rejestrze. +#: More general conclusion: the content key must be matched to the ENTITY, just like +#: the schema core. Using the application key for node rows does not raise +#: an error, it silently produces collisions that in further analysis look like +#: events in the register. NODE_KEY_FIELDS: tuple = ("publikujacy", "id_wezla") -#: Porządek etapów postępowania. Służy wyłącznie do oceny, czy przejścia biegną -#: w przód, nie jest słownikiem kontrolowanym schematu. +#: Order of the proceeding stages. Used solely to assess whether transitions proceed +#: forward, it is not a controlled vocabulary of the schema. STATUS_ORDER: dict[str, int] = { "WNIOSEK_ZLOZONY": 0, "WNIOSEK_NIEKOMPLETNY": 1, @@ -90,14 +90,14 @@ "PRZYLACZONY": 5, } -#: Stany kończące postępowanie bez przyłączenia. +#: States ending the proceeding without connection. TERMINAL_NEGATIVE: frozenset = frozenset( {"ODMOWA", "WNIOSEK_WYCOFANY", "WARUNKI_WYGASLE"} ) def _jako_tekst(v) -> str: - """Wartosc jako lancuch; brak jako lancuch pusty, niezaleznie od wersji pandas.""" + """Value as a string; missing value as empty string, regardless of pandas version.""" if v is None: return "" if isinstance(v, float) and v != v: @@ -106,7 +106,7 @@ def _jako_tekst(v) -> str: def _jako_tekst_zero_jak_brak(v) -> str: - """Jak `_jako_tekst`, ale wartość liczbowa równa zeru daje łańcuch pusty.""" + """Like `_jako_tekst`, but a numeric value equal to zero yields an empty string.""" s = _jako_tekst(v) if s == "": return "" @@ -121,23 +121,23 @@ def surrogate_key( fields: Sequence[str] = DEFAULT_KEY_FIELDS, zero_jako_brak: bool = False, ) -> pd.Series: - """Klucz treściowy wiersza, do dopasowania między edycjami. - - `zero_jako_brak` zrównuje wartość 0 z brakiem wartości. Publikujący bywa - niekonsekwentny: tę samą nieujawnioną moc zapisuje raz jako pustą komórkę, - raz jako zero, i wtedy klucz rozpada parę, która dotyczy jednego wniosku. - Na parze edycji operatora przesyłowego włączenie tej opcji odzyskuje - 12 z 51 par traconych przez klucz. Domyślnie WYŁĄCZONE, bo zero jest - wartością ujawnioną, a brak jej nieujawnieniem, zrównanie ich jest - decyzją analityka, nie własnością danych, i musi być widoczne w kodzie. + """Content key of the row, for matching between editions. + + `zero_jako_brak` equates the value 0 with the absence of a value. The publisher is sometimes + inconsistent: it records the same undisclosed capacity once as an empty cell, + once as zero, and then the key splits apart a pair that concerns one application. + On a pair of editions of the transmission operator, enabling this option recovers + 12 out of 51 pairs lost by the key. Disabled by default, because zero is + a disclosed value, and its absence is non-disclosure; equating them is + an analyst's decision, not a property of the data, and it must be visible in the code. """ uzyte = [f for f in fields if f in df.columns] if not uzyte: - raise ValueError(f"żadne z pól klucza nie występuje w ramce: {list(fields)}") - # Konwersja wprost, zamiast .astype(str): w pandas 2 brak stawal sie lancuchem - # "nan", a w pandas 3 pozostaje wartoscia brakujaca i zlaczenie rzuca TypeError. - # Jawna konwersja daje ten sam klucz w obu wersjach i czyni regule "brak jest - # wartoscia" wlasnoscia kodu, a nie ubocznym skutkiem rzutowania typu. + raise ValueError(f"none of the key fields occurs in the dataframe: {list(fields)}") + # Explicit conversion, instead of .astype(str): in pandas 2 a missing value became the string + # "nan", while in pandas 3 it remains a missing value and concatenation raises TypeError. + # An explicit conversion gives the same key in both versions and makes the rule "missing is + # a value" a property of the code, rather than a side effect of type casting. konw = _jako_tekst_zero_jak_brak if zero_jako_brak else _jako_tekst kolumny = [df[c].map(konw) for c in uzyte] return reduce(lambda a, b: a + "|" + b, kolumny) @@ -145,7 +145,7 @@ def surrogate_key( @dataclass class EditionDelta: - """Wynik porównania dwóch edycji.""" + """Result of comparing two editions.""" edycja_a: str edycja_b: str @@ -166,11 +166,11 @@ class EditionDelta: @property def udzial_przejsc_w_przod(self) -> Optional[float]: - """Udział przejść biegnących zgodnie z porządkiem postępowania. + """Share of transitions proceeding in accordance with the order of the proceeding. - Wysoka wartość jest dowodem, że klucz treściowy dopasowuje właściwe - wiersze; niska oznacza dopasowanie losowe i unieważnia porównanie. - Zwraca ``None``, gdy nie ma ani jednego uporządkowanego przejścia. + A high value is evidence that the content key matches the correct + rows; a low one indicates random matching and invalidates the comparison. + Returns ``None`` when there is not a single ordered transition. """ w_przod = uporzadkowanych = 0 for a in self.przejscia.index: @@ -218,11 +218,11 @@ def compare_editions( edycja_b: str = "B", fields: Sequence[str] = DEFAULT_KEY_FIELDS, ) -> EditionDelta: - """Porównaj dwie edycje rejestru i zwróć przepływy oraz przejścia statusu. + """Compare two editions of the register and return the flows and status transitions. - Wiersze o powtarzającym się kluczu są odrzucane przed dopasowaniem (pierwszy - zachowany), bo dla nich przypisanie jest niejednoznaczne; liczba kluczy - unikalnych wobec liczby wierszy pokazuje, ile wiersze na tym tracą. + Rows with a repeating key are discarded before matching (the first is + kept), because for them the assignment is ambiguous; the number of unique + keys against the number of rows shows how much the rows lose by this. """ a = a.copy() b = b.copy() @@ -267,8 +267,8 @@ def compare_editions( ) -#: Pola, których NIE ma w kluczu i które służą do niezależnej oceny dopasowania. -#: Jeśli para jest fałszywa, te pola się rozjadą, klucz ich nie wymusza. +#: Fields that are NOT in the key and that serve for an independent assessment of the match. +#: If the pair is false, these fields will diverge, the key does not enforce them. HELD_OUT_FIELDS: tuple = ( "_podmiot", "_nazwa_obiektu", @@ -295,23 +295,23 @@ def _norm_txt(v) -> str: def _rdzen_nazwy(v) -> str: - """Nazwa sprowadzona do rdzenia: bez formy prawnej, interpunkcji i spacji. + """Name reduced to its core: without legal form, punctuation and spaces. - Bez tego „Stigma sp.z o.o." i „Stigma Sp. z o.o." byłyby różnymi podmiotami, - a publikujący zmienia zapis formy prawnej między edycjami. + Without this, „Stigma sp.z o.o." and „Stigma Sp. z o.o." would be different entities, + and the publisher changes the notation of the legal form between editions. """ return _NIEALFANUM.sub("", _FORMA_PRAWNA.sub("", _norm_txt(v))) @dataclass class LinkageAudit: - """Ocena dopasowania par na polach WYŁĄCZONYCH z klucza. + """Assessment of pair matching on fields EXCLUDED from the key. - Nie jest to walidacja wobec prawdy zewnętrznej, bo takiej dla tego rejestru - nie ma, jest to test wewnętrznej spójności: klucz nie wymusza zgodności - tych pól, więc ich zgodność jest niezależnym świadectwem, że para dotyczy - tego samego wniosku. Zgłaszamy obie granice, bo przypadki niepewne nie - rozstrzygają się same. + This is not a validation against an external ground truth, because there is none + for this register, it is a test of internal consistency: the key does not enforce agreement + of these fields, so their agreement is independent evidence that the pair concerns + the same application. We report both bounds, because uncertain cases do not + resolve themselves. """ par: int @@ -322,12 +322,12 @@ class LinkageAudit: @property def precyzja_dolna(self) -> float: - """Niepewne liczone jako błędne.""" + """Uncertain counted as incorrect.""" return self.potwierdzonych / self.par if self.par else float("nan") @property def precyzja_gorna(self) -> float: - """Niepewne liczone jako trafne.""" + """Uncertain counted as correct.""" return (self.par - self.falszywych) / self.par if self.par else float("nan") def as_dict(self) -> dict: @@ -347,19 +347,19 @@ def linkage_audit( fields: Sequence[str] = DEFAULT_KEY_FIELDS, held_out: Sequence[str] = HELD_OUT_FIELDS, ) -> LinkageAudit: - """Oceń dopasowanie kluczem treściowym na polach z klucza wyłączonych. + """Assess the matching done with the content key on fields excluded from the key. - Para jest klasyfikowana jako: + A pair is classified as: - * **fałszywa**, rdzeń nazwy podmiotu ORAZ rdzeń nazwy obiektu są rozbieżne - i żaden nie zawiera się w drugim; to dwa różne wnioski, które przypadkiem - dzielą lokalizację, napięcie, klasę i obie moce; - * **niepewna**, rozbieżny jest dokładnie jeden z tych dwóch; - * **potwierdzona**, oba zgodne albo nieobecne. + * **false**, the core of the entity name AND the core of the object name are divergent + and neither is contained in the other; these are two different applications that by chance + share the location, voltage, class and both capacities; + * **uncertain**, exactly one of these two is divergent; + * **confirmed**, both agree or are absent. - Pola uzupełnione jednostronnie (puste w jednej edycji, wypełnione w drugiej) - nie są liczone jako rozbieżność, bo publikujący uzupełnia rekordy między - edycjami i jest to zmiana TEGO SAMEGO wniosku, nie świadectwo innego. + Fields filled in on one side only (empty in one edition, filled in the other) + are not counted as a divergence, because the publisher fills in records between + editions and this is a change of THE SAME application, not evidence of a different one. """ a = a.copy() b = b.copy() @@ -412,22 +412,22 @@ def _rozne(x: str, y: str) -> bool: ) -#: Pola tożsamości używane do odzyskania par, których klucz treściowy nie połączył. -#: Muszą być ROZŁĄCZNE z polami klucza. Pole wspólne z kluczem nie wykryje pary -#: rozerwanej zmianą właśnie tego pola, bo sama tożsamość też się wtedy rozjedzie: -#: dołożenie lokalizacji do tego zestawu obniża zmierzoną czułość z 0,9652 do -#: 0,9757, co wygląda na poprawę, a jest przeoczeniem dziesięciu par. +#: Identity fields used to recover pairs that the content key did not link. +#: They must be DISJOINT from the key fields. A field shared with the key will not detect a pair +#: broken by a change of that very field, because the identity itself would then also drift apart: +#: adding the location to this set lowers the measured recall from 0,9652 to +#: 0,9757, which looks like an improvement, but is an oversight of ten pairs. RECALL_FIELDS: tuple = ("_podmiot", "_nazwa_obiektu") @dataclass class LinkageRecall: - """Czułość dopasowania: ile par klucz treściowy POMINĄŁ. + """Recall of the matching: how many pairs the content key SKIPPED. - `linkage_audit` mierzy precyzję, czy połączone pary są tą samą sprawą. - Nie mówi nic o parach, których klucz nie połączył, a te są groźniejsze: - rozerwana para pojawia się jako jeden wiersz „ubyły" i jeden „nowy", - więc wygląda jak zdarzenie w rejestrze, a jest artefaktem dopasowania. + `linkage_audit` measures precision, whether the linked pairs are the same case. + It says nothing about pairs that the key did not link, and these are more dangerous: + a broken pair appears as one "departed" row and one "new" row, + so it looks like an event in the register, when it is an artifact of the matching. """ kluczy_a: int @@ -438,7 +438,7 @@ class LinkageRecall: @property def czulosc_klucza(self) -> float: - """Udział par faktycznie połączonych wśród par możliwych do połączenia.""" + """Share of pairs actually linked among the pairs that could be linked.""" mozliwe = self.dopasowanych + self.odzyskanych return self.dopasowanych / mozliwe if mozliwe else float("nan") @@ -454,16 +454,16 @@ def linkage_recall( fields: Sequence[str] = DEFAULT_KEY_FIELDS, pola_tozsamosci: Sequence[str] = RECALL_FIELDS, ) -> LinkageRecall: - """Szuka par pominiętych przez klucz treściowy, po polach tożsamości. + """Looks for pairs skipped by the content key, using identity fields. - Bierze wiersze NIEDOPASOWANE kluczem i próbuje je połączyć po polach, które - do klucza nie wchodzą, nazwie podmiotu, nazwie obiektu i lokalizacji. - Para odzyskana tą drogą dotyczy tego samego wniosku, któremu zmieniono - którąś z wartości wchodzących do klucza; zwracana ramka podaje, które - pole klucza się różni, więc wynik jest sprawdzalny, a nie deklarowany. + Takes rows UNMATCHED by the key and tries to link them by fields that + do not enter the key: entity name, object name and location. + A pair recovered this way concerns the same application for which one of + the values entering the key has been changed; the returned frame states which + key field differs, so the result is checkable, not merely declared. - Odzyskiwane są wyłącznie dopasowania JEDNOZNACZNE: jeśli ta sama tożsamość - występuje po którejkolwiek stronie więcej niż raz, para nie jest liczona. + Only UNAMBIGUOUS matches are recovered: if the same identity + occurs more than once on either side, the pair is not counted. """ aa, bb = a.copy(), b.copy() aa["_klucz"] = surrogate_key(aa, fields) diff --git a/src/gridqueue/quality.py b/src/gridqueue/quality.py index bbe0f80..374bef9 100644 --- a/src/gridqueue/quality.py +++ b/src/gridqueue/quality.py @@ -1,26 +1,26 @@ -"""Kontrola jakości zbioru: reguły z przepisu i z semantyki postępowania. - -Każda reguła zwraca LICZBĘ NARUSZEŃ, nie wyjątek. Naruszenie nie jest błędem -narzędzia -- jest własnością ujawnienia i właśnie po to ten moduł istnieje. -Raport jakości jest wynikiem naukowym: mówi, na ile publikacja ustawowa jest -wewnętrznie spójna. - -Reguły: - R1 monotonicznosc_dat -- wniosek <= warunki <= umowa <= energizacja - R2 waznosc_warunkow_2lata -- warunki przyłączenia są ważne 2 lata - (art. 7 ust. 8i); data utraty ważności nie może - wypaść później niż 2 lata po ich określeniu - R3 dopuszczalnosc_przejsc -- status musi być zgodny z zestawem obecnych dat - R4 spojnosc_jednostek_mocy -- wartości mocy w kW muszą mieścić się w zakresie - fizycznym przyłączeń >1 kV (wykrywa pomyłkę MW/kW) - R5 zakresy_wartosci -- moce nieujemne, daty w oknie 1990-2100 - R6 duplikaty_identyfikatorow -- ten sam id_wniosku w wielu wierszach - R7 kompletnosc_rdzenia -- rdzeń WŁAŚCIWEJ DLA WIERSZA ENCJI: dla WNIOSKU - 4 pola niepuste oraz co najmniej jedno z pary - (moc_pobierana, moc_wprowadzana); dla WEZLA - id_wezla oraz co najmniej jedno z pary +"""Quality control of the dataset: rules derived from statute and from the semantics of the process. + +Each rule returns a NUMBER OF VIOLATIONS, not an exception. A violation is not a bug +in the tool; it is a property of the disclosure, and that is exactly why this module exists. +The quality report is a scientific result: it tells how internally consistent +the statutory publication is. + +Rules: + R1 monotonicznosc_dat : application <= conditions <= agreement <= energization + R2 waznosc_warunkow_2lata : connection conditions are valid for 2 years + (art. 7 ust. 8i); the expiry date must not + fall later than 2 years after they were determined + R3 dopuszczalnosc_przejsc : status must be consistent with the set of dates present + R4 spojnosc_jednostek_mocy : capacity values in kW must fall within the physical + range of connections >1 kV (detects an MW/kW mix-up) + R5 zakresy_wartosci : capacities non-negative, dates in the 1990-2100 window + R6 duplikaty_identyfikatorow : the same id_wniosku in multiple rows + R7 kompletnosc_rdzenia : core of the ENTITY PROPER TO THE ROW: for WNIOSEK + 4 fields non-empty plus at least one of the pair + (moc_pobierana, moc_wprowadzana); for WEZEL + id_wezla plus at least one of the pair (moc_dostepna, ograniczenie_flaga) - R8 slownik_kontrolowany -- klasa_zasobu i status_procesu ze słownika + R8 slownik_kontrolowany : klasa_zasobu and status_procesu from the dictionary """ from __future__ import annotations @@ -57,11 +57,11 @@ def as_dict(self) -> dict: "naruszen_lacznie": sum(r["naruszenia"] for r in self.reguly)} def as_frame(self): - """Jeden wiersz na regule: kod, nazwa, naruszenia, udzial. + """One row per rule: kod, nazwa, naruszenia, udzial. - Kolumna `szczegoly` jest celowo pominieta, jej zawartosc rozni sie - strukturalnie miedzy regulami, wiec w ramce bylaby kolumna obiektow. - Pelne szczegoly zwraca `as_dict()`. + The `szczegoly` column is deliberately omitted; its content differs + structurally between rules, so in the dataframe it would be a column of objects. + Full details are returned by `as_dict()`. """ import pandas as pd @@ -73,7 +73,7 @@ def as_frame(self): def _plus_years(d: _dt.date, n: int) -> _dt.date: - """Data przesunieta o n lat; 29 lutego w roku nieprzestepnym -> 28 lutego.""" + """Date shifted by n years; 29 February in a non-leap year -> 28 February.""" try: return d.replace(year=d.year + n) except ValueError: @@ -105,7 +105,7 @@ def r1_monotonicznosc_dat(df) -> tuple[int, dict]: cnt += 1 if cnt: pary[f"{a}>{b}"] = cnt - # wiersz liczony raz + # row counted once mask = [False] * len(df) for i in range(len(have) - 1): a, b = have[i], have[i + 1] @@ -118,14 +118,14 @@ def r1_monotonicznosc_dat(df) -> tuple[int, dict]: def r2_waznosc_warunkow(df) -> tuple[int, dict]: - """Warunki przyłączenia są ważne dwa lata (art. 7 ust. 8i). + """Connection conditions are valid for two years (art. 7 ust. 8i). - Jeśli publikujący podaje datę utraty ważności, musi ona wypadać nie później - niż dwa lata po dacie określenia warunków. Sprawdzamy też umowy zawarte po - upływie dwóch lat od warunków, które ich nie utraciły. + If the publisher provides an expiry date, it must fall no later + than two years after the date the conditions were determined. We also check agreements + concluded after two years have elapsed from the conditions that did not expire. """ if "data_warunkow" not in df.columns: - return 0, {"uwaga": "brak pola data_warunkow"} + return 0, {"uwaga": "missing field data_warunkow"} col_utr = "_data_utraty_waznosci" if "_data_utraty_waznosci" in df.columns else None n_utr_bad = n_umowa_bad = 0 n_sprawdzonych_utr = 0 @@ -157,22 +157,22 @@ def r2_waznosc_warunkow(df) -> tuple[int, dict]: det["nadwyzka_dni_min"] = nadwyzki[0] det["nadwyzka_dni_max"] = nadwyzki[-1] det["poza_tolerancja_30_dni"] = sum(1 for x in nadwyzki if x > 30) - # Liczba MUSI byc policzona, nie wpisana. Wczesniej stala tu literalna - # "334" -- akurat tyle wypadalo na panelu czterech publikujacych, ale - # ten sam string wracal przy KAZDYM wywolaniu, takze per publikujacy - # i na panelu szesciu, gdzie n_utr_bad ma inna wartosc. Diagnostyka - # podawala wtedy liczbe niezgodna z wlasnym wynikiem reguly. + # The number MUST be computed, not hardcoded. Previously a literal + # "334" stood here; that happened to be exactly how many came up on the panel of four + # publishers, but the same string came back on EVERY call, including per publisher + # and on the panel of six, where n_utr_bad has a different value. The diagnostics + # then reported a number inconsistent with the rule's own result. det["interpretacja"] = ( - "systematyczne przesuniecie o stala liczbe dni wskazuje na regule " - f"administracyjna publikujacego, a nie na {n_utr_bad} niezaleznych " - "naruszen terminu" + "a systematic shift by a constant number of days indicates an administrative " + f"rule of the publisher, rather than {n_utr_bad} independent " + "violations of the deadline" ) return n_utr_bad + n_umowa_bad, det -#: jakie daty MUSZĄ / NIE MOGĄ istnieć przy danym statusie +#: which dates MUST / MUST NOT exist for a given status _STATUS_WYMAGA: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = { - # status: (pola wymagane, pola zakazane) + # status: (required fields, forbidden fields) "WARUNKI_WYDANE": (("data_warunkow",), ("data_odmowy",)), "ODMOWA": (("data_odmowy",), ("data_umowy", "data_energizacji")), "UMOWA_OBOWIAZUJACA": (("data_umowy",), ("data_odmowy",)), @@ -184,13 +184,13 @@ def r2_waznosc_warunkow(df) -> tuple[int, dict]: def r3_dopuszczalnosc_przejsc(df) -> tuple[int, dict]: - """Status musi byc zgodny z zestawem obecnych dat. + """Status must be consistent with the set of dates present. - Wymog obecnosci daty stosujemy TYLKO do pol, ktore dany publikujacy w ogole - ujawnia. Brytyjski rejestr nie publikuje zadnych dat postepowania -- zadanie - od niego "daty umowy" nie jest kontrola spojnosci, tylko bledem kategorii. - Pola ujawniane wyznaczamy empirycznie: kolumna z co najmniej jedna wartoscia - niepusta w obrebie publikujacego. + We apply the requirement that a date be present ONLY to fields that the given publisher + actually discloses. The British register does not publish any process dates; demanding + "agreement date" from it is not a consistency check but a category error. + We determine the disclosed fields empirically: a column with at least one non-empty + value within the publisher. """ if "status_procesu" not in df.columns: return 0, {} @@ -210,9 +210,9 @@ def r3_dopuszczalnosc_przejsc(df) -> tuple[int, dict]: spec = _STATUS_WYMAGA.get(st) if not spec: continue - # Klucz moze nie istniec: groupby pomija grupe o pustej nazwie publikujacego, - # wiec wiersz bez tej adnotacji nie ma wlasnego wpisu. Wtedy stosujemy zbior - # globalny zamiast rzucac KeyError i tracic cala regule. + # The key may not exist: groupby skips the group with an empty publisher name, + # so a row without that annotation has no entry of its own. In that case we use the + # global set instead of raising a KeyError and losing the whole rule. dost = (ujawniane.get(df["publikujacy"].iloc[i], globalne) if ujawniane is not None else globalne) wymagane = tuple(c for c in spec[0] if c in dost) @@ -230,9 +230,9 @@ def r3_dopuszczalnosc_przejsc(df) -> tuple[int, dict]: return n_bad, {"szczegoly": dict(sorted(szczegoly.items(), key=lambda kv: -kv[1])[:20])} -#: zakres fizyczny przyłączeń >1 kV w kW. Dolny próg 1 kW odrzuca wartości, -#: które najpewniej podano w MW zamiast kW; górny 5 GW -- powyżej największej -#: pojedynczej jednostki wytwórczej w KSE. +#: physical range of connections >1 kV in kW. The lower threshold of 1 kW rejects values +#: that were most likely given in MW instead of kW; the upper bound of 5 GW is +#: above the largest single generating unit in the KSE. _MOC_MIN_KW, _MOC_MAX_KW = 1.0, 5_000_000.0 @@ -295,13 +295,13 @@ def r6_duplikaty_identyfikatorow(df) -> tuple[int, dict]: def r7_kompletnosc_rdzenia(df) -> tuple[int, dict]: - """Rdzeń schematu: wszystkie CORE_FIELDS niepuste oraz z każdej grupy - CORE_ALTERNATIVES co najmniej jedno pole niepuste. + """Schema core: all CORE_FIELDS non-empty, and from each group of + CORE_ALTERNATIVES at least one field non-empty. - Grupa alternatywna istnieje, bo wniosek przyłączeniowy zawsze deklaruje moc, - lecz nie zawsze tę samą: wytwórczy wprowadzaną, odbiorczy pobieraną, - dwukierunkowy obie. Wymaganie jednej konkretnej zamieniałoby własność - schematu w pozorne naruszenie ujawnienia. + The alternative group exists because a connection application always declares a capacity, + but not always the same one: a generation one declares export capacity, a consumption one + import capacity, a bidirectional one both. Requiring one specific field would turn a + property of the schema into an apparent disclosure violation. """ if ENTITY_COLUMN in df.columns: enc = df[ENTITY_COLUMN].map( @@ -325,7 +325,7 @@ def r7_kompletnosc_rdzenia(df) -> tuple[int, dict]: per[f"{nazwa}/{c}"] = cnt for grupa in spec["alternatywy"]: obecne = [c for c in grupa if c in sub.columns] - etykieta = f"{nazwa}/co najmniej jedno z: " + ", ".join(grupa) + etykieta = f"{nazwa}/at least one of: " + ", ".join(grupa) if not obecne: per[etykieta] = int(len(sub)) continue @@ -353,20 +353,20 @@ def r8_slownik_kontrolowany(df) -> tuple[int, dict]: RULES: tuple[Rule, ...] = ( - Rule("R1", "monotoniczność dat postępowania", "semantyka procesu (art. 7 ust. 8l pkt 1)", + Rule("R1", "monotonicity of process dates", "process semantics (art. 7 ust. 8l pkt 1)", r1_monotonicznosc_dat), - Rule("R2", "dwuletnia ważność warunków przyłączenia", "art. 7 ust. 8i", + Rule("R2", "two-year validity of connection conditions", "art. 7 ust. 8i", r2_waznosc_warunkow), - Rule("R3", "dopuszczalność stanu procesu wobec dat", "semantyka procesu", + Rule("R3", "admissibility of process state given the dates", "process semantics", r3_dopuszczalnosc_przejsc), - Rule("R4", "spójność jednostek mocy", "art. 7 ust. 8l (sieć >1 kV)", + Rule("R4", "consistency of capacity units", "art. 7 ust. 8l (network >1 kV)", r4_spojnosc_jednostek), - Rule("R5", "zakresy wartości", "kontrola techniczna", r5_zakresy_wartosci), - Rule("R6", "duplikaty identyfikatorów", "wymóg identyfikowalności pozycji", + Rule("R5", "value ranges", "technical control", r5_zakresy_wartosci), + Rule("R6", "duplicate identifiers", "requirement for identifiability of records", r6_duplikaty_identyfikatorow), - Rule("R7", "kompletność rdzenia schematu", "art. 7 ust. 8l pkt 1/3/4", + Rule("R7", "completeness of the schema core", "art. 7 ust. 8l pkt 1/3/4", r7_kompletnosc_rdzenia), - Rule("R8", "słownik kontrolowany", "harmonizacja międzyoperatorska", + Rule("R8", "controlled dictionary", "inter-operator harmonization", r8_slownik_kontrolowany), ) @@ -376,7 +376,7 @@ def run_quality(df, rules: Optional[tuple[Rule, ...]] = None) -> QualityReport: for rule in (rules or RULES): try: n, det = rule.fn(df) - except Exception as exc: # reguła nie może wywrócić raportu + except Exception as exc: # a rule must not break the report n, det = -1, {"blad": f"{type(exc).__name__}: {exc}"} out.append({ "kod": rule.kod, diff --git a/src/gridqueue/registry.py b/src/gridqueue/registry.py index 41c0980..15a49e3 100644 --- a/src/gridqueue/registry.py +++ b/src/gridqueue/registry.py @@ -1,4 +1,4 @@ -"""Rejestr adapterów i wykrywanie publikującego.""" +"""Adapter registry and publisher detection.""" from __future__ import annotations @@ -34,15 +34,15 @@ def get_adapter(key: str, **kwargs) -> Adapter: if key not in REGISTRY: - raise KeyError(f"nieznany adapter {key!r}; dostępne: {sorted(REGISTRY)}") + raise KeyError(f"unknown adapter {key!r}; available: {sorted(REGISTRY)}") return REGISTRY[key](**kwargs) def detect_publisher(source, *, sniff_bytes: int = 4000) -> Optional[str]: - """Rozpoznaj publikującego po nazwie pliku, a jeśli trzeba -- po treści. + """Recognize the publisher by file name, and if needed, by content. - Kolejność jest celowa: nazwa pliku jest tania i zwykle wystarcza, treść - pierwszej strony rozstrzyga resztę. Zwraca klucz rejestru albo None. + The order is intentional: the file name is cheap and usually sufficient, the content + of the first page resolves the rest. Returns the registry key or None. """ name = str(source).lower() for key, cls in REGISTRY.items(): @@ -66,5 +66,5 @@ def detect_publisher(source, *, sniff_bytes: int = 4000) -> Optional[str]: def declarations() -> list[dict]: - """Deklaracje pól opcjonalnych wszystkich zarejestrowanych publikujących.""" + """Declarations of optional fields of all registered publishers.""" return [cls().declaration() for cls in REGISTRY.values()] diff --git a/src/gridqueue/schema.py b/src/gridqueue/schema.py index 4b6ea42..cb6b9aa 100644 --- a/src/gridqueue/schema.py +++ b/src/gridqueue/schema.py @@ -1,40 +1,40 @@ -"""Wspólny schemat ujawnień przyłączeniowych (statutory connection-queue disclosure). +"""Common schema for connection-queue disclosures (statutory connection-queue disclosure). -Schemat jest wyprowadzony ze STRUKTURY OBOWIĄZKU PRAWNEGO, nie z układu konkretnego -dokumentu. Art. 7 ust. 8l ustawy z dnia 10 kwietnia 1997 r. -- Prawo energetyczne -nakłada na operatora systemu dystrybucyjnego cztery rozłączne obowiązki ujawnieniowe: +The schema is derived from the STRUCTURE OF THE STATUTORY DUTY, not from the layout of a +particular document. Article 7(8l) of the Act of 10 April 1997, the Energy Law, +imposes four separate disclosure duties on the distribution system operator: - pkt 1 -- podmioty ubiegające się o przyłączenie źródeł (kto, gdzie, jaka moc, - jaki zasób, na jakim etapie) -> encja WNIOSEK - pkt 2 -- łączna dostępna moc przyłączeniowa i jej planowane zmiany w okresie - kolejnych 5 lat, w podziale na stacje lub ich grupy - -> encja WĘZEŁ - pkt 3 -- złożone wnioski o określenie warunków przyłączenia -> encja WNIOSEK - pkt 4 -- wydane odmowy określenia warunków przyłączenia -> encja WNIOSEK + point 1 : entities applying for the connection of sources (who, where, how much capacity, + what resource, at what stage) -> APPLICATION entity + point 2 : total available connection capacity and its planned changes over the + next 5 years, broken down by station or group of stations + -> NODE entity + point 3 : applications filed for determination of connection conditions -> APPLICATION entity + point 4 : refusals issued for determination of connection conditions -> APPLICATION entity -Z tego wynikają trzy osie, które schemat odwzorowuje jako grupy pól: +From this follow three axes, which the schema maps as field groups: - TOŻSAMOŚĆ -- co jest przyłączane i gdzie (id_wniosku, id_wezla, nazwa_wezla, + IDENTITY : what is being connected and where (id_wniosku, id_wezla, nazwa_wezla, lokalizacja_tekst, wspolrzedne, poziom_napiecia, klasa_zasobu) - MOC -- ile mocy w którą stronę i ile jej jeszcze jest + CAPACITY : how much capacity, in which direction, and how much of it is still left (moc_wprowadzana, moc_pobierana, moc_dostepna, moc_zarezerwowana, ograniczenie_flaga, pozycja_w_kolejce) - PROCES -- gdzie w postępowaniu administracyjnym stoi sprawa + PROCESS : where the case stands in the administrative proceedings (status_procesu, data_wniosku, data_warunkow, data_odmowy, powod_odmowy, data_umowy, data_energizacji, data_publikacji) -Oś PROCES jest bezpośrednim odwzorowaniem ścieżki proceduralnej ustawy: wniosek -> -(zaliczka) -> warunki przyłączenia albo odmowa -> umowa o przyłączenie -> -rozpoczęcie dostarczania energii. Warunki przyłączenia są ważne dwa lata -(art. 7 ust. 8i), co czyni parę (data_warunkow, data_umowy) sprawdzalną regułą, -a nie tylko dwiema kolumnami. +The PROCESS axis is a direct mapping of the statute's procedural path: application -> +(advance payment) -> connection conditions or refusal -> connection agreement -> +start of energy supply. Connection conditions are valid for two years +(Article 7(8i)), which makes the pair (data_warunkow, data_umowy) a checkable rule, +not just two columns. -RDZEŃ OBOWIĄZKOWY (5 pól) to minimum, bez którego ujawnienie nie realizuje -żadnego z pkt 1/3/4: nie da się powiedzieć, czyj to wniosek, gdzie, na co, -o jaką moc i na jakim etapie. +The MANDATORY CORE (5 fields) is the minimum without which the disclosure fulfills +none of points 1/3/4: it is impossible to say whose application it is, where, for what, +how much capacity, and at what stage. -Jednostki kanoniczne: moc w kW (nie MW -- publikujący używają obu), daty w ISO -8601 (YYYY-MM-DD), współrzędne w WGS84 jako (lat, lon). +Canonical units: capacity in kW (not MW, publishers use both), dates in ISO +8601 (YYYY-MM-DD), coordinates in WGS84 as (lat, lon). """ from __future__ import annotations @@ -60,17 +60,17 @@ ] # -------------------------------------------------------------------------- -# normalizacja jednostek kanonicznych +# normalization of canonical units # -------------------------------------------------------------------------- _NUM_RE = re.compile(r"^-?\d+(?:[.,]\d+)?$") def canonical_power_kw(value: Any, unit: str = "kW") -> Optional[float]: - """Sprowadź moc do kW. Zwraca None dla pustych/nieparsowalnych wartości. + """Convert power to kW. Returns None for empty/unparsable values. - Akceptuje polski separator dziesiętny (przecinek) i spacje tysięczne - (także NBSP i wąską spację, których używają generatory PDF). + Accepts the Polish decimal separator (comma) and thousands spaces + (also NBSP and narrow space, which PDF generators use). """ if value is None: return None @@ -84,7 +84,7 @@ def canonical_power_kw(value: Any, unit: str = "kW") -> Optional[float]: if s in {"", "-", "--", "---", "brak", "nie dotyczy", "n/d", "N/D"}: return None s = s.replace(",", ".") - # dopuść wielokrotne kropki tysięczne typu 1.234.5 -> odrzuć + # allow for multiple thousands dots like 1.234.5 -> reject if not _NUM_RE.match(s.replace(".", "", max(0, s.count(".") - 1))): try: num = float(s) @@ -102,12 +102,12 @@ def canonical_power_kw(value: Any, unit: str = "kW") -> Optional[float]: return num * 1000.0 if u in {"w", "wat", "watt"}: return num / 1000.0 - raise ValueError(f"nieznana jednostka mocy: {unit!r}") + raise ValueError(f"unknown power unit: {unit!r}") -# Publikujacy nie trzymaja sie wlasnego wzorca [dd.mm.rrrr]: w zestawieniu wnioskow -# Stoena wystepuja daty z jednocyfrowym dniem ("2.04.2026"), wiec wzorzec musi je -# przyjmowac -- inaczej poprawnie wydobyta data przepada na normalizacji. +# Publishers do not stick to their own [dd.mm.rrrr] pattern: in Stoena's register of +# applications there are dates with a single-digit day ("2.04.2026"), so the pattern +# must accept them, otherwise a correctly extracted date is lost at normalization. _DATE_PATTERNS = ( ("%d.%m.%Y", re.compile(r"^\d{1,2}\.\d{1,2}\.\d{4}$")), ("%Y-%m-%d", re.compile(r"^\d{4}-\d{1,2}-\d{1,2}$")), @@ -124,7 +124,7 @@ def canonical_power_kw(value: Any, unit: str = "kW") -> Optional[float]: def canonical_date(value: Any) -> Optional[str]: - """Sprowadź datę do ISO 8601 (YYYY-MM-DD). None dla pustych/nieparsowalnych.""" + """Convert a date to ISO 8601 (YYYY-MM-DD). None for empty/unparsable values.""" if value is None: return None if isinstance(value, _dt.datetime): @@ -155,7 +155,7 @@ def _is_null(v: Any) -> bool: # -------------------------------------------------------------------------- -# specyfikacja pól +# field specification # -------------------------------------------------------------------------- @@ -166,7 +166,7 @@ class Field: group: str # "tozsamosc" | "moc" | "proces" core: bool unit: Optional[str] - podstawa: str # który punkt art. 7 ust. 8l uzasadnia pole + podstawa: str # which point of Article 7(8l) justifies the field opis: str check: Optional[Callable[[Any], bool]] = field(default=None, repr=False) @@ -205,62 +205,62 @@ def _is_bool(v: Any) -> bool: SCHEMA: tuple[Field, ...] = ( - # ---------------- TOŻSAMOŚĆ ---------------- + # ---------------- IDENTITY ---------------- Field("id_wniosku", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Identyfikator pozycji w rejestrze publikującego; unikalny w obrębie " - "publikacji, nie globalnie."), + "Identifier of the entry in the publisher's register; unique within the " + "publication, not globally."), Field("id_wezla", "string", "tozsamosc", False, None, "pkt 2", - "Identyfikator stacji elektroenergetycznej lub jej grupy, w podziale na " - "które ustawa każe podawać dostępną moc."), + "Identifier of the power station or its group, broken down by " + "which the statute requires the available capacity to be reported."), Field("nazwa_wezla", "string", "tozsamosc", False, None, "pkt 2", - "Nazwa własna stacji/punktu zasilania, jeśli publikujący ją ujawnia."), + "Proper name of the station/supply point, if the publisher discloses it."), Field("lokalizacja_tekst", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Lokalizacja miejsca przyłączenia tak, jak ją podał publikujący " - "(adres, miejscowość, kod stacji) -- bez interpretacji."), + "Location of the connection point exactly as given by the publisher " + "(address, locality, station code), without interpretation."), Field("wspolrzedne", "geopoint", "tozsamosc", False, "WGS84", "pkt 1/2", - "Współrzędne geograficzne (lat, lon); wynik rozwiązania lokalizacji albo " - "dana źródłowa.", _is_geopoint), + "Geographic coordinates (lat, lon); result of location resolution or " + "source data.", _is_geopoint), Field("poziom_napiecia", "string", "tozsamosc", False, None, "pkt 1 (>1 kV)", - "Poziom napięcia przyłączenia; obowiązek dotyczy sieci powyżej 1 kV, więc " - "pole rozstrzyga o zakresie ujawnienia."), + "Voltage level of the connection; the duty applies to networks above 1 kV, so " + "the field determines the scope of the disclosure."), Field("klasa_zasobu", "string", "tozsamosc", True, None, "pkt 1/3/4", - "Rodzaj instalacji, urządzeń lub sieci, zharmonizowany do słownika " - "kontrolowanego (PV, FW, BESS, ODB, ...)."), - # ---------------- MOC ---------------- + "Type of installation, equipment or network, harmonized to the controlled " + "vocabulary (PV, FW, BESS, ODB, ...)."), + # ---------------- CAPACITY ---------------- Field("moc_wprowadzana", "number", "moc", False, "kW", "pkt 1/3", - "Moc przyłączeniowa wprowadzana do sieci (generacja/eksport).", _num_nonneg), + "Connection capacity fed into the network (generation/export).", _num_nonneg), Field("moc_pobierana", "number", "moc", False, "kW", "pkt 1/3/4", - "Moc przyłączeniowa pobierana z sieci (odbiór/import); dla wniosków " - "odbiorczych jest to główna wielkość wniosku. Nie jest polem rdzenia " - "bezwarunkowo: rdzeń wymaga CO NAJMNIEJ JEDNEGO z pary " - "(moc_pobierana, moc_wprowadzana) -- patrz CORE_ALTERNATIVES.", _num_nonneg), + "Connection capacity drawn from the network (consumption/import); for " + "consumption applications this is the main quantity of the application. It is " + "not unconditionally a core field: the core requires AT LEAST ONE " + "of the pair (moc_pobierana, moc_wprowadzana), see CORE_ALTERNATIVES.", _num_nonneg), Field("moc_dostepna", "number", "moc", False, "kW", "pkt 2", - "Łączna dostępna moc przyłączeniowa w węźle.", _num_nonneg), + "Total available connection capacity at the node.", _num_nonneg), Field("moc_zarezerwowana", "number", "moc", False, "kW", "pkt 2", - "Moc zajęta wydanymi i ważnymi warunkami / rezerwą.", _num_nonneg), + "Capacity taken up by issued and valid connection conditions / reservation.", _num_nonneg), Field("ograniczenie_flaga", "boolean", "moc", False, None, "pkt 2", - "Czy w węźle występuje czynnik ograniczający przyłączenie.", _is_bool), + "Whether there is a factor at the node limiting the connection.", _is_bool), Field("pozycja_w_kolejce", "number", "moc", False, None, "pkt 1", - "Pozycja wniosku w kolejce przyłączeniowej, jeśli publikujący ją prowadzi."), - # ---------------- PROCES ---------------- + "Position of the application in the connection queue, if the publisher maintains one."), + # ---------------- PROCESS ---------------- Field("status_procesu", "string", "proces", True, None, "pkt 1/3/4", - "Etap postępowania, zharmonizowany do słownika kontrolowanego."), + "Stage of the proceedings, harmonized to the controlled vocabulary."), Field("data_wniosku", "date", "proces", False, "ISO-8601", "pkt 3", - "Data złożenia wniosku o określenie warunków przyłączenia.", _is_iso_date), + "Date the application for determination of connection conditions was filed.", _is_iso_date), Field("data_warunkow", "date", "proces", False, "ISO-8601", "pkt 1/3", - "Data określenia warunków przyłączenia; początek dwuletniego terminu " - "ważności (art. 7 ust. 8i).", _is_iso_date), + "Date the connection conditions were determined; the start of the two-year " + "validity period (Article 7(8i)).", _is_iso_date), Field("data_odmowy", "date", "proces", False, "ISO-8601", "pkt 4", - "Data wydania odmowy określenia warunków przyłączenia.", _is_iso_date), + "Date the refusal to determine connection conditions was issued.", _is_iso_date), Field("powod_odmowy", "string", "proces", False, None, "pkt 4", - "Uzasadnienie odmowy (przyczyny techniczne / ekonomiczne / inne)."), + "Justification for the refusal (technical / economic / other reasons)."), Field("data_umowy", "date", "proces", False, "ISO-8601", "pkt 1", - "Data zawarcia umowy o przyłączenie.", _is_iso_date), + "Date the connection agreement was concluded.", _is_iso_date), Field("data_energizacji", "date", "proces", False, "ISO-8601", "pkt 1", - "Data rozpoczęcia dostarczania energii elektrycznej.", _is_iso_date), + "Date electricity supply began.", _is_iso_date), Field("data_publikacji", "date", "proces", False, "ISO-8601", "art. 7 ust. 8m", - "Stan na dzień, dla którego publikujący sporządził ujawnienie; " - "ustawa wymaga aktualizacji co najmniej raz na kwartał.", _is_iso_date), + "Status as of the date for which the publisher prepared the disclosure; " + "the statute requires updates at least once per quarter.", _is_iso_date), ) SCHEMA_VERSION: str = "1.0" @@ -269,18 +269,20 @@ def _is_bool(v: Any) -> bool: CORE_FIELDS: tuple[str, ...] = tuple(f.name for f in SCHEMA if f.core) OPTIONAL_FIELDS: tuple[str, ...] = tuple(f.name for f in SCHEMA if not f.core) -# Rdzeń warunkowy, osobny dla każdej encji obowiązku. +# Conditional core, separate for each entity of the duty. # -# Schemat ma dwie encje, bo przepis ma dwa punkty o różnym przedmiocie, i rdzeń -# jednej z nich nie jest wymaganiem wobec drugiej. Ocenianie wiersza encji -# WEZEL wymaganiami encji WNIOSEK mierzyłoby niezgodność encji, nie braki -# ujawnienia. +# The schema has two entities, because the provision has two points with a different +# subject, and the core of one of them is not a requirement for the other. Assessing a +# WEZEL entity row against the requirements of the WNIOSEK entity would measure entity +# mismatch, not disclosure gaps. # -# W obu encjach część wymagań jest ALTERNATYWĄ, nie konkretnym polem. Wniosek -# przyłączeniowy zawsze deklaruje moc, lecz nie zawsze tę samą: wytwórczy -# wprowadzaną, odbiorczy pobieraną, dwukierunkowy (np. magazyn) obie. Analogicznie -# pkt 2 bywa realizowany mocą dostępną albo liczbą wolnych miejsc przyłączeniowych -# (wtedy flagą ograniczenia) -- obie postaci spotkaliśmy u różnych publikujących. +# In both entities, part of the requirements is an ALTERNATIVE, not a specific field. A +# connection application always declares a capacity, but not always the same one: a +# generation application declares export capacity, a consumption application import +# capacity, a bidirectional one (e.g. storage) both. Similarly, point 2 is sometimes +# implemented via the available capacity or via the number of free connection slots +# (in that case via the constraint flag); we have encountered both forms from different +# publishers. ENTITY_COLUMN: str = "_encja" DEFAULT_ENTITY: str = "WNIOSEK" @@ -295,7 +297,7 @@ def _is_bool(v: Any) -> bool: }, } -# zachowane dla zgodności wstecznej z 0.3.x; odnosi się do encji WNIOSEK +# kept for backward compatibility with 0.3.x; refers to the WNIOSEK entity CORE_ALTERNATIVES: tuple[tuple[str, ...], ...] = tuple( CORE_BY_ENTITY["WNIOSEK"]["alternatywy"]) @@ -320,13 +322,13 @@ def _mask_dla_encji(df, sub_idx, spec): def core_complete_mask(df): - """Maska wierszy z kompletnym rdzeniem WŁAŚCIWEJ DLA SIEBIE ENCJI. + """Mask of rows with a complete core FOR THEIR OWN ENTITY. - Encja czytana jest z kolumny anotacyjnej ``_encja``; wiersze bez tej anotacji - traktowane są jako ``WNIOSEK`` (tak wiersze emitują adaptery, które encji nie - rozróżniają, bo ich publikujący realizuje wyłącznie pkt 1/3/4). Brak kolumny - wymaganej traktowany jest jak kolumna pusta -- rdzeń jest wymaganiem wobec - WIERSZA, nie wobec kształtu ramki. + The entity is read from the annotation column ``_encja``; rows without this + annotation are treated as ``WNIOSEK`` (this is how rows are emitted by adapters that + do not distinguish entities, because their publisher fulfills only points 1/3/4). A + missing required column is treated like an empty column: the core is a requirement on + the ROW, not on the shape of the frame. """ import pandas as _pd @@ -348,11 +350,11 @@ def core_complete_mask(df): for g in ("tozsamosc", "moc", "proces") } -# kolumny towarzyszące, nie należące do schematu (metadane panelu / anotacje) +# accompanying columns, not part of the schema (panel metadata / annotations) META_COLUMNS: tuple[str, ...] = ("publikujacy", "jurysdykcja", "dokument_zrodlowy") ANNOTATION_PREFIX = "_" -# słowniki kontrolowane +# controlled vocabularies KLASY_ZASOBU = ( "PV", "FW", "EW", "BIOGAZ", "GAZ", "WEGIEL", "BESS", "ODB", "MIX", "SIEC", "INNE", "NIEOKRESLONA", @@ -365,48 +367,48 @@ def core_complete_mask(df): # -------------------------------------------------------------------------- -# walidator instancji +# instance validator # -------------------------------------------------------------------------- def validate_instance(row: dict[str, Any], *, strict_vocab: bool = False) -> list[str]: - """Zwróć listę komunikatów o naruszeniach dla pojedynczego wiersza. + """Return a list of violation messages for a single row. - Pusta lista = wiersz zgodny ze schematem. Walidator NIE rzuca wyjątku -- - ujawnienia bywają niekompletne z winy publikującego i to jest wynik pomiaru, - a nie błąd wykonania. + Empty list = row conforms to the schema. The validator does NOT raise an exception: + disclosures are sometimes incomplete through the publisher's fault, and that is a + measurement result, not a runtime error. """ problems: list[str] = [] unknown = set(row) - set(FIELDS) - set(META_COLUMNS) unknown = {k for k in unknown if not k.startswith(ANNOTATION_PREFIX)} if unknown: - problems.append(f"pola spoza schematu: {sorted(unknown)}") + problems.append(f"fields outside the schema: {sorted(unknown)}") for name in CORE_FIELDS: if name not in row or _is_null(row.get(name)): - problems.append(f"brak pola rdzenia: {name}") + problems.append(f"missing core field: {name}") for name, value in row.items(): f = BY_NAME.get(name) if f is None or _is_null(value): continue if f.dtype == "number": if not isinstance(value, (int, float)) or isinstance(value, bool): - problems.append(f"{name}: oczekiwano liczby, jest {type(value).__name__}") + problems.append(f"{name}: expected a number, got {type(value).__name__}") continue if f.check is not None and not f.check(value): - problems.append(f"{name}: wartość nie przechodzi kontroli typu ({value!r})") + problems.append(f"{name}: value does not pass the type check ({value!r})") if strict_vocab: kz = row.get("klasa_zasobu") if not _is_null(kz) and kz not in KLASY_ZASOBU: - problems.append(f"klasa_zasobu spoza słownika: {kz!r}") + problems.append(f"klasa_zasobu outside the vocabulary: {kz!r}") st = row.get("status_procesu") if not _is_null(st) and st not in STATUSY: - problems.append(f"status_procesu spoza słownika: {st!r}") + problems.append(f"status_procesu outside the vocabulary: {st!r}") return problems def validate_frame(df, *, strict_vocab: bool = True) -> dict[str, Any]: - """Walidacja całej ramki. Zwraca raport (liczby), nie wyjątek.""" - import pandas as pd # lokalny import: schema.py ma być użyteczny bez pandas + """Validation of the entire frame. Returns a report (figures), not an exception.""" + import pandas as pd # local import: schema.py is meant to be usable without pandas report: dict[str, Any] = { "n_wierszy": int(len(df)), @@ -454,17 +456,17 @@ def validate_frame(df, *, strict_vocab: bool = True) -> dict[str, Any]: def empty_frame(): - """Pusta ramka w schemacie (wszystkie 21 pól + kolumny metadanych).""" + """Empty frame in the schema (all 21 fields + metadata columns).""" import pandas as pd return pd.DataFrame({c: pd.Series(dtype="object") for c in FIELDS + META_COLUMNS}) def _encja_pola(nazwa: str) -> str: - """Encja, w której pole występuje: WNIOSEK, WEZEL albo obie. + """Entity in which the field occurs: WNIOSEK, WEZEL, or obie. - Wyprowadzone z CORE_BY_ENTITY oraz z przynależności pola do punktu obowiązku: - punkt 2 opisuje węzeł, punkty 1, 3 i 4 opisują wniosek. + Derived from CORE_BY_ENTITY and from the field's membership in a point of the duty: + point 2 describes the node, points 1, 3 and 4 describe the application. """ wezlowe = {"id_wezla", "nazwa_wezla", "moc_dostepna", "moc_zarezerwowana", "ograniczenie_flaga"} @@ -475,12 +477,12 @@ def _encja_pola(nazwa: str) -> str: def _status_rdzenia(nazwa: str) -> str: - """Trójwartościowy status: rdzeń bezwarunkowy, alternatywa rdzenia, rozszerzenie. + """Three-valued status: unconditional core, core alternative, extension. - Rdzeń jest WARUNKOWY: pole bezwarunkowe dla jednej encji nie musi być - wymagane dla drugiej, a pary alternatyw wymagają wypełnienia co najmniej - jednego członu. Dwuwartościowa kolumna `rdzen` tego nie oddaje i dlatego - istnieje ta druga. + The core is CONDITIONAL: a field unconditional for one entity need not be required + for the other, and alternative pairs require at least one member to be filled in. + The two-valued column `rdzen` does not capture this, and that is why this second + one exists. """ for encja, spec in CORE_BY_ENTITY.items(): if nazwa in spec["wymagane"]: @@ -493,7 +495,7 @@ def _status_rdzenia(nazwa: str) -> str: def schema_table(): - """Specyfikacja jako ramka -- artefakt do manuskryptu.""" + """Specification as a frame, an artifact for the manuscript.""" import pandas as pd return pd.DataFrame( diff --git a/tests/test_adapters.py b/tests/test_adapters.py index 8616a8b..46ecd1b 100644 --- a/tests/test_adapters.py +++ b/tests/test_adapters.py @@ -11,27 +11,27 @@ from gridqueue.schema import FIELDS, META_COLUMNS -def test_rejestr_ma_dziewiec_adapterow_w_pieciu_jurysdykcjach(): +def test_the_registry_has_nine_adapters_in_five_jurisdictions(): assert set(REGISTRY) == {"pl_tauron", "pl_stoen", "pl_boryszew", "pl_pse", "pl_energa", "uk_nationalgrid", "pt_eredes", "es_edistribucion", "ie_esbnetworks"} assert {get_adapter(k).jurisdiction for k in REGISTRY} == {"PL", "UK", "PT", "ES", "IE"} -def test_deklaracje_pol_sa_podzbiorem_schematu(): +def test_field_declarations_are_a_subset_of_the_schema(): for d in declarations(): assert set(d["pola_deklarowane"]) <= set(FIELDS), d["publikujacy"] assert all(k.startswith("_") for k in d["rozszerzenia"]), d["publikujacy"] -def test_kazdy_adapter_deklaruje_rdzen_SWOJEJ_encji(): - """Rdzeń jest warunkowy per encja, więc i ta kontrola musi być. +def test_every_adapter_declares_the_core_of_ITS_OWN_entity(): + """The core is conditional per entity, so this check has to be conditional too. - Poprzednia wersja wymagała od KAŻDEGO adaptera rdzenia encji WNIOSEK. - Jest to ten sam błąd kategorialny, który naprawiono w regule R7: publikujący - realizujący wyłącznie punkt 2 obowiązku ujawnia węzły, a nie wnioski, więc - nie ma ani identyfikatora wniosku, ani jego mocy. Adapter portugalski - pokazał, że test niósł nieaktualny kontrakt. + The previous version required the core of the WNIOSEK entity from EVERY + adapter. This is the same category error that was fixed in rule R7: a + publisher carrying out point 2 of the duty alone discloses nodes, not + applications, so it has neither an application identifier nor its capacity. + The Portuguese adapter showed that the test carried an outdated contract. """ rdzen_wniosku = {"id_wniosku", "lokalizacja_tekst", "klasa_zasobu", "status_procesu"} rdzen_wezla = {"id_wezla"} @@ -42,7 +42,7 @@ def test_kazdy_adapter_deklaruje_rdzen_SWOJEJ_encji(): assert wniosek or wezel, key -def test_get_adapter_odrzuca_nieznany_klucz(): +def test_get_adapter_rejects_an_unknown_key(): with pytest.raises(KeyError): get_adapter("pl_nieistniejacy") @@ -73,7 +73,7 @@ def test_harmonize_status(raw, expected): assert harmonize_status(raw) == expected -def test_norm_text_usuwa_diakrytyki(): +def test_norm_text_strips_diacritics(): assert norm_text("Świętego Wincentego\n") == "swietego wincentego" @@ -84,7 +84,7 @@ def test_detect_layout_stoen(): assert detect_layout("cokolwiek innego") is None -def test_finalize_ustawia_kolejnosc_i_metadane(): +def test_finalize_sets_the_column_order_and_the_metadata(): a = get_adapter("pl_tauron") df = a.finalize(pd.DataFrame({"id_wniosku": ["x"], "_extra": [1]}), document="d.pdf") assert list(df.columns)[:21] == list(FIELDS) @@ -99,7 +99,7 @@ def test_as_bool(): assert _as_bool(None) is None and _as_bool("maybe") is None -def test_nationalgrid_mapuje_ramke_bez_sieci(): +def test_nationalgrid_maps_a_frame_with_no_network_access(): raw = pd.DataFrame({ "Licence Area": ["South Wales"], "GSP": ["Aberthaw Power Station"], "TANM": [False], "DANM": [True], "Status": ["Accepted not yet Connected"], @@ -122,12 +122,12 @@ def test_nationalgrid_mapuje_ramke_bez_sieci(): assert r["jurysdykcja"] == "UK" -def test_adapter_bazowy_nie_implementuje_parse(): +def test_the_base_adapter_does_not_implement_parse(): with pytest.raises(NotImplementedError): Adapter().parse("x") -def test_cli_schema_i_adapters(capsys, tmp_path): +def test_cli_schema_and_adapters(capsys, tmp_path): assert main(["schema", "--out", str(tmp_path / "s.csv")]) == 0 assert len(pd.read_csv(tmp_path / "s.csv")) == 21 capsys.readouterr() @@ -135,7 +135,7 @@ def test_cli_schema_i_adapters(capsys, tmp_path): assert len(json.loads(capsys.readouterr().out)) == len(REGISTRY) -def test_cli_validate_i_export(tmp_path, capsys): +def test_cli_validate_and_export(tmp_path, capsys): p = tmp_path / "a.csv" pd.DataFrame({ "id_wniosku": ["a", "b"], "lokalizacja_tekst": ["x", "y"], @@ -151,6 +151,6 @@ def test_cli_validate_i_export(tmp_path, capsys): assert len(pd.read_parquet(out)) == 4 -def test_cli_parser_wymaga_podkomendy(): +def test_the_cli_parser_requires_a_subcommand(): with pytest.raises(SystemExit): build_parser().parse_args([]) diff --git a/tests/test_analysis.py b/tests/test_analysis.py index 3e53fe8..0074d10 100644 --- a/tests/test_analysis.py +++ b/tests/test_analysis.py @@ -1,4 +1,4 @@ -"""Testy warstwy analitycznej: obciążenie węzła i czas z cenzurowaniem.""" +"""Tests of the analytical layer: node loading and time with censoring.""" import pandas as pd import pytest @@ -22,31 +22,31 @@ def _wniosek(lok, moc, status="WARUNKI_WYDANE"): "status_procesu": status, "moc_wprowadzana": moc, "moc_pobierana": None} -class TestNormalizacja: - def test_litera_l_z_kreska_nie_rozcina_wyrazu(self): - """NFKD nie rozkłada 'ł', bez jawnej podmiany wyraz pękłby na spacji.""" +class TestNormalization: + def test_the_barred_l_does_not_cut_the_word_in_two(self): + """NFKD does not decompose 'ł'; without an explicit substitution the word would break at a space.""" assert normalizuj_nazwe("Białogard") == "bialogard" assert normalizuj_nazwe("Łęczyca") == "leczyca" assert normalizuj_nazwe("Kołobrzeg 6 Dywizji") == "kolobrzeg 6 dywizji" - def test_przedrostek_oznaczenia_nie_niesie_tozsamosci(self): + def test_a_designation_prefix_carries_no_identity(self): assert normalizuj_nazwe("GPZ Kościerzyna") == normalizuj_nazwe("Kościerzyna") assert normalizuj_nazwe("SE Dunowo") == normalizuj_nazwe("Dunowo") -class TestOdwzorowanie: - def test_grupa_a_nie_wiersz_jest_kluczem(self): - """Ta sama grupa w dwóch kierunkach to jeden obiekt, nie dwa.""" +class TestMapping: + def test_the_group_not_the_row_is_the_key(self): + """The same group in two directions is one object, not two.""" df = pd.DataFrame([ _wezel(1, "Alfa", "Stacja A, Stacja B", 1000.0, "wytworcza"), _wezel(1, "Alfa", "Stacja A, Stacja B", 2000.0, "odbiorcza"), ]) mapa = station_node_map(df) assert mapa["grupa"].nunique() == 1 - assert len(mapa) == 2 # dwie stacje, nie cztery + assert len(mapa) == 2 # two stations, not four - def test_obiekt_na_linii_nie_jest_przypisywany_do_wezla(self): - """Stacja planowana na linii leży MIĘDZY węzłami, przypisanie byłoby arbitralne.""" + def test_an_object_on_a_line_is_not_assigned_to_a_node(self): + """A station planned on a line lies BETWEEN nodes, so any assignment would be arbitrary.""" df = pd.DataFrame([ _wezel(1, "Alfa", "Stacja A", 1000.0), _wniosek("planowany RS w linii 110 kV relacji Stacja A - Stacja C", 50.0), @@ -56,7 +56,7 @@ def test_obiekt_na_linii_nie_jest_przypisywany_do_wezla(self): assert wn["_grupa_dopasowanie"] == "LINE" assert pd.isna(wn["_grupa"]) - def test_stacja_w_dwoch_grupach_jest_niejednoznaczna(self): + def test_a_station_in_two_groups_is_ambiguous(self): df = pd.DataFrame([ _wezel(1, "Alfa", "Ostrów", 1000.0), _wezel(2, "Beta", "Ostrów", 1000.0), @@ -67,8 +67,8 @@ def test_stacja_w_dwoch_grupach_jest_niejednoznaczna(self): assert pd.isna(out.iloc[-1]["_grupa"]) -class TestObciazenie: - def test_iloraz_i_kierunek(self): +class TestLoading: + def test_the_ratio_and_the_direction(self): df = pd.DataFrame([ _wezel(1, "Alfa", "Stacja A", 100.0, "wytworcza"), _wezel(1, "Alfa", "Stacja A", 400.0, "odbiorcza"), @@ -80,8 +80,8 @@ def test_iloraz_i_kierunek(self): assert L.iloc[0]["obciazenie"] == pytest.approx(2.5) assert L.iloc[0]["kierunek"] == "wytworcza" - def test_zerowa_moc_daje_wynik_nieokreslony_a_nie_nieskonczony(self): - """Dzielenie przez zero w tej dziedzinie nie znaczy 'nieskończenie dużo'.""" + def test_zero_capacity_gives_an_undefined_not_an_infinite_result(self): + """Division by zero in this domain does not mean 'infinitely much'.""" df = pd.DataFrame([ _wezel(1, "Alfa", "Stacja A", 0.0), _wniosek("Stacja A", 10.0), @@ -90,9 +90,9 @@ def test_zerowa_moc_daje_wynik_nieokreslony_a_nie_nieskonczony(self): L = node_loading(out, pole_mocy="moc_wprowadzana") assert bool(L.iloc[0]["moc_dostepna_zero"]) is True assert pd.isna(L.iloc[0]["obciazenie"]) - assert L.iloc[0]["moc_wnioskowana"] == 10.0 # kolejka widoczna mimo braku mocy + assert L.iloc[0]["moc_wnioskowana"] == 10.0 # the queue stays visible despite the absence of capacity - def test_status_zakonczony_nie_obciaza_wezla(self): + def test_a_closed_status_does_not_load_the_node(self): df = pd.DataFrame([ _wezel(1, "Alfa", "Stacja A", 100.0), _wniosek("Stacja A", 50.0, status="ODMOWA"), @@ -102,7 +102,7 @@ def test_status_zakonczony_nie_obciaza_wezla(self): assert L.iloc[0]["moc_wnioskowana"] == 0.0 -class TestCzasICenzurowanie: +class TestTimeAndCensoring: def _ramka(self): return pd.DataFrame([ {"data_wniosku": "2026-01-01", "data_warunkow": "2026-01-31"}, @@ -111,15 +111,15 @@ def _ramka(self): {"data_wniosku": "2026-03-01", "data_warunkow": "2026-02-01"}, ]) - def test_wniosek_w_toku_jest_obserwacja_uciets_nie_brakiem(self): + def test_a_pending_application_is_a_censored_observation_not_a_gap(self): d = processing_time(self._ramka(), na_dzien="2026-06-30") assert d.loc[0, "zdarzenie"] == 1 and d.loc[0, "czas_dni"] == 30 assert d.loc[1, "zdarzenie"] == 0 and d.loc[1, "czas_dni"] == 180 - assert pd.isna(d.loc[2, "zdarzenie"]) # bez daty wniosku nie ma czego liczyć - assert pd.isna(d.loc[3, "czas_dni"]) # data wsteczna odrzucona + assert pd.isna(d.loc[2, "zdarzenie"]) # with no application date there is nothing to compute + assert pd.isna(d.loc[3, "czas_dni"]) # a backdated value is rejected - def test_pominiecie_cenzurowanych_zanizza_mediane(self): - """Właściwość, dla której ta funkcja istnieje.""" + def test_dropping_the_censored_observations_lowers_the_median(self): + """The property this function exists for.""" czas = [10, 20, 30, 400, 400, 400] zdarz = [1, 1, 1, 0, 0, 0] km = kaplan_meier(czas, zdarz) @@ -127,11 +127,11 @@ def test_pominiecie_cenzurowanych_zanizza_mediane(self): assert km.cenzurowanych == 3 assert pd.isna(km.mediana) or km.mediana >= kompletne - def test_km_bez_cenzurowania_daje_mediane_empiryczna(self): + def test_km_without_censoring_gives_the_empirical_median(self): km = kaplan_meier([5, 10, 15, 20], [1, 1, 1, 1]) - assert km.mediana == 10 # pierwszy czas, dla którego S <= 0,5 + assert km.mediana == 10 # the first time at which S <= 0.5 assert km.zdarzen == 4 and km.cenzurowanych == 0 - def test_pusta_ramka_nie_rzuca_wyjatku(self): + def test_an_empty_frame_raises_no_exception(self): km = kaplan_meier([], []) assert km.n == 0 and pd.isna(km.mediana) diff --git a/tests/test_es_ie.py b/tests/test_es_ie.py index 057ce76..59e3507 100644 --- a/tests/test_es_ie.py +++ b/tests/test_es_ie.py @@ -1,7 +1,7 @@ -"""Testy adapterów hiszpańskiego i irlandzkiego. +"""Tests of the Spanish and the Irish adapter. -Obie rodziny testów pilnują decyzji o jednostkach, bo to w nich tkwi ryzyko -cichego błędu: źródła mieszają moc czynną z pozorną w obrębie jednego pliku. +Both families of tests guard the decisions about units, because that is where the +risk of a silent error sits: the sources mix active and apparent power within one file. """ import openpyxl @@ -16,38 +16,38 @@ _pojemnosc_bez_ograniczenia) -class TestHiszpanskieLiczby: - def test_przecinek_dziesietny_i_kropka_tysiecy(self): +class TestSpanishNumbers: + def test_decimal_comma_and_thousands_dot(self): assert _liczba_es("37,7") == pytest.approx(37.7) assert _liczba_es("1.234,5") == pytest.approx(1234.5) assert _liczba_es("") is None and _liczba_es("-") is None - def test_megawaty_przechodza_w_kilowaty(self): - """MW i kW to ta sama wielkość fizyczna, więc przeliczenie jest dozwolone.""" + def test_megawatts_are_converted_into_kilowatts(self): + """MW and kW are the same physical quantity, so the conversion is allowed.""" assert _mw_na_kw("37,7") == pytest.approx(37_700.0) assert _mw_na_kw(None) is None - def test_data_bierze_sie_z_nazwy_pliku(self): + def test_the_date_is_taken_from_the_file_name(self): assert _data_z_nazwy("EDRD_Capacidad_de_Acceso_2025_08_01.pdf") == "2025-08-01" assert _data_z_nazwy("bez_daty.pdf") is None -class TestIrlandzkieFlagi: - def test_fraza_ograniczenia_daje_prawde(self): +class TestIrishFlags: + def test_the_constraint_phrase_yields_true(self): assert _flaga("Constrained, otherwise capacity available =122 kVA") is True - def test_pusta_komorka_to_brak_ograniczenia(self): - """Interpretacja, nie treść źródła, pinujemy ją, żeby zmiana była widoczna.""" + def test_an_empty_cell_means_no_constraint(self): + """An interpretation, not the content of the source; we pin it so that a change is visible.""" assert _flaga(None) is False assert _flaga("") is False - def test_pojemnosc_wyjmowana_z_frazy_zostaje_w_kva(self): - """kVA to moc pozorna, więc wartość NIE jest przeliczana na kW.""" + def test_the_capacity_taken_from_the_phrase_stays_in_kva(self): + """kVA is apparent power, so the value is NOT converted into kW.""" assert _pojemnosc_bez_ograniczenia( "Constrained, otherwise capacity available =122 kVA") == pytest.approx(122.0) assert _pojemnosc_bez_ograniczenia("Constrained") is None - def test_alternatywa_zachowuje_nieokreslonosc(self): + def test_the_alternative_preserves_indeterminacy(self): assert _alternatywa(True, None) is True assert _alternatywa(False, False) is False assert _alternatywa(None, False) is None @@ -76,7 +76,7 @@ def _arkusz_ie(tmp_path, wiersze): return p -class TestIrlandzkieOdwzorowanie: +class TestIrishMapping: def _wiersz(self, **zm): w = {"Station Name": "ARDNACRUSHA", "Transformer GroupID": "T1", "Primary kV": "110 kV", "Voltage Class": "HV", @@ -86,39 +86,40 @@ def _wiersz(self, **zm): w.update(zm) return w - def test_moc_dostepna_bierze_strone_wytworcza_w_MW(self, tmp_path): - """Strona odbiorcza jest w MVA i NIE wolno jej sumować ani przeliczać.""" + def test_available_capacity_takes_the_generation_side_in_MW(self, tmp_path): + """The demand side is in MVA and must NOT be summed or converted.""" d = get_adapter("ie_esbnetworks").parse(_arkusz_ie(tmp_path, [self._wiersz()])).frame assert d.loc[0, "moc_dostepna"] == pytest.approx(25_000.0) assert d.loc[0, "_odbior_dostepna_mva"] == pytest.approx(12.0) assert d.loc[0, "_jednostka_mocy_odbiorczej"] == "MVA" - def test_rdzen_wezla_spelniony(self, tmp_path): + def test_the_node_core_is_satisfied(self, tmp_path): d = get_adapter("ie_esbnetworks").parse(_arkusz_ie(tmp_path, [self._wiersz()])).frame assert bool(core_complete_mask(d).iloc[0]) is True assert d.loc[0, "_encja"] == "WEZEL" - def test_identyfikator_rozroznia_grupy_tej_samej_stacji(self, tmp_path): + def test_the_identifier_distinguishes_groups_of_the_same_station(self, tmp_path): d = get_adapter("ie_esbnetworks").parse(_arkusz_ie(tmp_path, [ self._wiersz(), self._wiersz(**{"Transformer GroupID": "T2"})])).frame assert d["id_wezla"].nunique() == 2 - def test_wspolrzedne_skladane_w_jedno_pole(self, tmp_path): + def test_the_coordinates_are_combined_into_one_field(self, tmp_path): d = get_adapter("ie_esbnetworks").parse(_arkusz_ie(tmp_path, [self._wiersz()])).frame assert d.loc[0, "wspolrzedne"] == "52.7,-8.6" - def test_brak_wspolrzednych_daje_brak_a_nie_zero(self, tmp_path): + def test_missing_coordinates_give_a_gap_not_a_zero(self, tmp_path): d = get_adapter("ie_esbnetworks").parse(_arkusz_ie(tmp_path, [ self._wiersz(**{"Latitude": None, "Longitude": None})])).frame assert d.loc[0, "wspolrzedne"] is None -class TestTozsamoscArytmetyczna: - """Suma jedenastu podkolumn domyka się do mocy zajętej. +class TestArithmeticIdentity: + """The sum of eleven subcolumns closes to the occupied capacity. - Dla tego publikującego nie ma zbioru odniesienia odczytanego niezależnie - od parsera, więc domknięcie sumy jest jedynym sprawdzalnym świadectwem - spójności odczytu. Test pinuje kontrakt funkcji, nie wartość z dokumentu. + For this publisher there is no reference set read independently of the + parser, so arithmetic closure is the only checkable evidence that the + reading is consistent. The test pins the contract of the function, not a + value from the document. """ def _wiersz(self, laczna, pozycje=(), z_pozwoleniem="", w_toku=""): @@ -130,18 +131,18 @@ def _wiersz(self, laczna, pozycje=(), z_pozwoleniem="", w_toku=""): w[18], w[19] = z_pozwoleniem, w_toku return w - def test_obie_grupy_sa_skladnikami_a_nie_alternatywami(self): - """Wiersz z wypełnionymi OBIEMA grupami domyka się dopiero ich sumą.""" + def test_both_groups_are_components_and_not_alternatives(self): + """A row with BOTH groups filled in closes only on their sum.""" w = self._wiersz("97,3", pozycje=("24,6",), z_pozwoleniem="72,7") assert suma_skladnikow_mocy_zajetej([w]) == (1, 1) - def test_same_pozycje_tez_domykaja(self): + def test_the_positions_alone_also_close(self): assert suma_skladnikow_mocy_zajetej( [self._wiersz("40,4", pozycje=("40,0",), w_toku="0,4")]) == (1, 1) - def test_niedomkniety_wiersz_jest_wykrywany(self): + def test_a_row_that_does_not_close_is_detected(self): assert suma_skladnikow_mocy_zajetej( [self._wiersz("100,0", pozycje=("10,0",))]) == (0, 1) - def test_wiersz_bez_wartosci_lacznej_nie_jest_liczony(self): + def test_a_row_without_a_total_value_is_not_counted(self): assert suma_skladnikow_mocy_zajetej([self._wiersz("")]) == (0, 0) diff --git a/tests/test_geoloc.py b/tests/test_geoloc.py index 1ecf87a..2cbb051 100644 --- a/tests/test_geoloc.py +++ b/tests/test_geoloc.py @@ -18,7 +18,7 @@ def r(): return LocationResolver(GAZ) -def test_normalize_i_tokens(): +def test_normalize_and_tokens(): assert normalize("Świętego Wincentego") == "swietego wincentego" assert tokens("ul. Świętego Wincentego 12") == ["wincentego"] @@ -37,43 +37,43 @@ def test_unique_token(r): assert res.matched == "Aleje Jerozolimskie" -def test_reversed_z_inicjalem(r): +def test_reversed_with_initial(r): res = r.resolve("Warszawa, BEMA J.") assert res.pewnosc in {"UNIQUE_TOKEN", "REVERSED"} assert res.matched == "Józefa Bema" -def test_reversed_ze_skrotem_tytulu(r): +def test_reversed_with_title_abbreviation(r): res = r.resolve("Warszawa, WINCENTEGO ŚW.") assert res.pewnosc in {"UNIQUE_TOKEN", "REVERSED"} assert res.matched == "Świętego Wincentego" -def test_kod_stacji_nie_jest_zgadywany(r): +def test_station_code_is_not_guessed(r): res = r.resolve("SKB3") assert res.pewnosc == "NONE" assert res.powod == "kod_stacji_bez_slownika" assert res.matched is None -def test_kod_stacji_wymuszony_flaga(r): +def test_station_code_forced_by_a_flag(r): res = r.resolve("Grochowska", is_station_code=True) assert res.pewnosc == "NONE" assert res.powod == "kod_stacji_bez_slownika" -def test_pusty_opis(r): +def test_empty_description(r): assert r.resolve(None).powod == "pusty_opis" assert r.resolve(" ").powod == "pusty_opis" -def test_brak_kandydatow(r): +def test_no_candidates(r): res = r.resolve("Warszawa, Nieistniejąca") assert res.pewnosc == "NONE" assert res.powod in {"brak_kandydatow", "wiele_kandydatow"} -def test_summarize_liczy_odsetek(r): +def test_summarize_computes_the_share(r): rs = r.resolve_series(["Warszawa, Grochowska", "SKB3", "Warszawa, Nieistniejąca"]) s = LocationResolver.summarize(rs) assert s["n"] == 3 @@ -83,13 +83,13 @@ def test_summarize_liczy_odsetek(r): assert s["powody_braku"]["kod_stacji_bez_slownika"] == 1 -def test_skrzyzowanie(r): +def test_intersection(r): res = r.resolve("Warszawa, Marszałkowska/Nowy Świat") assert res.pewnosc == "SKRZYZOWANIE" assert res.matched is not None and "/" in res.matched assert res.rozwiazane -def test_skrzyzowanie_wymaga_dwoch_czlonow(r): +def test_intersection_requires_two_members(r): res = r.resolve("Warszawa, Nieistniejąca/Takze Nieistniejąca") assert res.pewnosc == "NONE" diff --git a/tests/test_geoloc_wspolrzedne.py b/tests/test_geoloc_wspolrzedne.py index f68d8cc..2225a4f 100644 --- a/tests/test_geoloc_wspolrzedne.py +++ b/tests/test_geoloc_wspolrzedne.py @@ -1,4 +1,4 @@ -"""Testy rozszerzenia rozwiązywacza o współrzędne i poziom dokładności.""" +"""Tests of the resolver extension with coordinates and an accuracy level.""" import pytest @@ -9,7 +9,7 @@ Resolution, ) -# gazeter w postaci rozszerzonej: wpis niesie punkt, długość i oś +# gazetteer in its extended form: an entry carries a point, a length and an axis GAZ_WAW = { "Grochowska": {"lat": 52.24, "lon": 21.09, "dlugosc_m": 5200.0, "os": [[52.245, 21.05], [52.235, 21.13]]}, @@ -17,7 +17,7 @@ "os": [[52.205, 21.012], [52.240, 21.012]]}, "Świętokrzyska": {"lat": 52.235, "lon": 21.01, "dlugosc_m": 1500.0, "os": [[52.235, 20.995], [52.235, 21.030]]}, - # wpis BEZ geometrii -- nazwa rozwiązywalna, punktu nie ma + # an entry with NO geometry: the name is resolvable, the point is not there "Bezgeometryczna": None, } GAZ_PIASECZNO = { @@ -38,14 +38,14 @@ def mr(): return MultiLocalityResolver(MIEJSC) -# --- poziom dokładności jest osobnym polem ------------------------------- +# --- the accuracy level is a separate field ------------------------------ -def test_dokladnosc_jest_z_kontrolowanego_slownika(mr): +def test_the_accuracy_comes_from_a_controlled_vocabulary(mr): r = mr.resolve("WARSZAWA, Grochowska") assert r.dokladnosc in DOKLADNOSC -def test_punkt_na_osi_ulicy(mr): +def test_a_point_on_the_street_axis(mr): r = mr.resolve("WARSZAWA, Grochowska") assert r.pewnosc == "EXACT" assert r.dokladnosc == "PUNKT_NA_OSI_ULICY" @@ -54,8 +54,8 @@ def test_punkt_na_osi_ulicy(mr): assert r.dlugosc_ulicy_m == 5200.0 -def test_pewnosc_i_dokladnosc_sa_niezalezne(mr): - """EXACT na długiej ulicy nie oznacza dokładnego punktu -- rozmycie jest jawne.""" +def test_confidence_and_accuracy_are_independent(mr): + """EXACT on a long street does not mean an exact point; the blur is explicit.""" dluga = mr.resolve("WARSZAWA, Grochowska") krotka = mr.resolve("PIASECZNO, Puławska") assert dluga.pewnosc == krotka.pewnosc == "EXACT" @@ -63,17 +63,17 @@ def test_pewnosc_i_dokladnosc_sa_niezalezne(mr): assert dluga.dlugosc_ulicy_m > krotka.dlugosc_ulicy_m -# --- rozróżnienie: brak nazwy vs brak geometrii -------------------------- +# --- the distinction: no name vs no geometry ----------------------------- -def test_nazwa_rozwiazana_bez_geometrii(mr): +def test_a_name_resolved_without_geometry(mr): r = mr.resolve("WARSZAWA, Bezgeometryczna") - assert r.rozwiazane is True # nazwa zidentyfikowana - assert r.ma_wspolrzedne is False # ale punktu nie ma + assert r.rozwiazane is True # the name has been identified + assert r.ma_wspolrzedne is False # but there is no point assert r.dokladnosc == "BRAK_GEOMETRII" assert r.powod == "nazwa_rozwiazana_bez_geometrii" -def test_nazwa_nierozwiazana_to_inny_stan_niz_brak_geometrii(mr): +def test_an_unresolved_name_is_a_different_state_than_missing_geometry(mr): r = mr.resolve("WARSZAWA, Nieistniejąca") assert r.rozwiazane is False assert r.ma_wspolrzedne is False @@ -81,19 +81,19 @@ def test_nazwa_nierozwiazana_to_inny_stan_niz_brak_geometrii(mr): assert r.powod != "nazwa_rozwiazana_bez_geometrii" -# --- zasada: brak z przyczyną zamiast zgadywania ------------------------- +# --- the principle: a gap with a reason instead of a guess --------------- -def test_kod_stacji_nadal_nie_jest_zgadywany(mr): +def test_a_station_code_is_still_not_guessed(mr): r = mr.resolve("SKB3") assert r.pewnosc == "NONE" and r.powod == "kod_stacji_bez_slownika" assert r.lat is None and r.lon is None -def test_krotka_nazwa_ulicy_wersalikami_nie_jest_kodem_stacji(): - """Regresja: "WARSZAWA, MARSA" -- człon ulicy pasuje do wzorca kodu stacji. +def test_a_short_street_name_in_capitals_is_not_a_station_code(): + """Regression: in "WARSZAWA, MARSA" the street member matches the station code pattern. - Kod stacji jest rozstrzygany na PEŁNYM opisie; człon po przecinku jest z - definicji nazwą ulicy. Zmierzone: 25 fałszywych braków na 1 236 wierszach. + A station code is decided on the FULL description; the member after the comma + is by definition a street name. Measured: 25 false gaps on 1,236 rows. """ m = MultiLocalityResolver({ "WARSZAWA": {"nazwa": "Warszawa", "lat": 52.23, "lon": 21.0, @@ -101,40 +101,41 @@ def test_krotka_nazwa_ulicy_wersalikami_nie_jest_kodem_stacji(): r = m.resolve("WARSZAWA, MARSA") assert r.pewnosc == "EXACT" and r.matched == "Marsa" assert r.ma_wspolrzedne - # a sam kod stacji nadal jest odrzucany + # and the station code on its own is still rejected assert m.resolve("SKB3").powod == "kod_stacji_bez_slownika" -def test_miejscowosc_poza_gazeterem_jest_osobnym_powodem(mr): +def test_a_locality_outside_the_gazetteer_is_a_separate_reason(mr): r = mr.resolve("KRAKÓW, Grochowska") assert r.pewnosc == "NONE" assert r.powod == "miejscowosc_poza_gazeterem" assert r.lat is None -def test_ta_sama_nazwa_w_dwoch_miejscowosciach_nie_jest_mieszana(mr): - """Rozdzielenie przestrzeni nazw: 'Grochowska' istnieje w obu i daje różne punkty.""" +def test_the_same_name_in_two_localities_is_not_conflated(mr): + """Separation of name spaces: 'Grochowska' exists in both and gives different points.""" a = mr.resolve("WARSZAWA, Grochowska") b = mr.resolve("PIASECZNO, Grochowska") assert a.pewnosc == b.pewnosc == "EXACT" assert (a.lat, a.lon) != (b.lat, b.lon) -def test_niejednoznaczna_miejscowosc_nie_jest_rozstrzygana_losowo(mr): - """'SĘKOCIN' pasuje do Nowego i Starego -- jawny brak, nie wybór na chybił trafił.""" +def test_an_ambiguous_locality_is_not_settled_at_random(mr): + """'SĘKOCIN' matches both Nowy and Stary: an explicit gap, not a hit-or-miss choice.""" r = mr.resolve("SĘKOCIN, Jakakolwiek") assert r.pewnosc == "NONE" assert r.powod.startswith("miejscowosc_niejednoznaczna") assert r.lat is None -def test_bez_zadeklarowanej_miejscowosci_nie_zgaduje(mr): - """Opis bez członu miejscowości nie jest dopasowywany do gazetera miasta. +def test_with_no_declared_locality_it_does_not_guess(mr): + """A description with no locality member is not matched against a city gazetteer. - Regresja zmierzona na panelu: przy podstawianiu domyślnej miejscowości opisy - TAURONA "Stacja projektowana" trafiały w warszawską "ul. Projektowana", - a "Wrzoski (planowany)" w drogowe "planowany łącznik" -- 21 fałszywych - rozwiązań na 11 649 wierszy publikujących bez członu miejscowości. + A regression measured on the panel: when a default locality was substituted, + the TAURON descriptions "Stacja projektowana" matched the Warsaw street + "ul. Projektowana", and "Wrzoski (planowany)" matched the road feature + "planowany łącznik": 21 false resolutions on 11,649 rows of publishers with + no locality member. """ for opis in ["Stacja projektowana", "Wrzoski (planowany)", "Langage B"]: r = mr.resolve(opis) @@ -143,41 +144,41 @@ def test_bez_zadeklarowanej_miejscowosci_nie_zgaduje(mr): assert r.lat is None and r.lon is None -def test_domyslna_miejscowosc_dziala_gdy_jawnie_wlaczona(): +def test_the_default_locality_works_when_it_is_switched_on_explicitly(): m = MultiLocalityResolver(MIEJSC, domyslna="WARSZAWA") r = m.resolve("Grochowska") assert r.pewnosc == "EXACT" and r.ma_wspolrzedne -def test_centroid_miejscowosci_tylko_na_jawne_zadanie(mr): +def test_the_locality_centroid_only_on_an_explicit_request(mr): bez = mr.resolve("PIASECZNO, Nieistniejąca") assert bez.lat is None z = mr.resolve("PIASECZNO, Nieistniejąca", dopusc_centroid=True) assert z.dokladnosc == "CENTROID_MIEJSCOWOSCI" assert (z.lat, z.lon) == (52.0747, 21.0271) - assert z.rozwiazane is False # nazwa ulicy nadal nierozwiązana + assert z.rozwiazane is False # the street name is still unresolved -# --- skrzyżowanie: punkt przecięcia osi ---------------------------------- +# --- intersection: the crossing point of the axes ------------------------ -def test_skrzyzowanie_daje_punkt_przeciecia_osi(mr): +def test_an_intersection_gives_the_crossing_point_of_the_axes(mr): r = mr.resolve("WARSZAWA, Marszałkowska/Świętokrzyska") assert r.pewnosc == "SKRZYZOWANIE" assert r.dokladnosc == "PUNKT_SKRZYZOWANIA" - # osie: Marszałkowska lon=21.012 (pion), Świętokrzyska lat=52.235 (poziom) + # axes: Marszałkowska lon=21.012 (vertical), Świętokrzyska lat=52.235 (horizontal) assert abs(r.lat - 52.235) < 1e-3 assert abs(r.lon - 21.012) < 1e-3 -# --- numer domu nie jest interpolowany ---------------------------------- +# --- the house number is not interpolated -------------------------------- -def test_numer_domu_bez_indeksu_nie_jest_zgadywany(mr): +def test_a_house_number_without_an_index_is_not_guessed(mr): r = mr.resolve("WARSZAWA, Grochowska", numer="12") - assert r.dokladnosc == "PUNKT_NA_OSI_ULICY" # NIE PUNKT_ADRESOWY + assert r.dokladnosc == "PUNKT_NA_OSI_ULICY" # NOT PUNKT_ADRESOWY assert (r.lat, r.lon) == (52.24, 21.09) -def test_numer_domu_z_indeksem_punktow_adresowych(mr): +def test_a_house_number_with_an_index_of_address_points(mr): res_waw = mr.resolvery["warszawa"] res_waw.punkty_adresowe = {("grochowska", "12"): (52.2411, 21.0912)} r = mr.resolve("WARSZAWA, Grochowska", numer="12") @@ -186,12 +187,13 @@ def test_numer_domu_z_indeksem_punktow_adresowych(mr): del res_waw.punkty_adresowe -# --- próg pokrycia tokenów: opis słowny nie jest nazwą ulicy ------------- +# --- token coverage threshold: a verbal description is not a street name - -def test_opis_slowny_nie_jest_dopasowywany_do_ulicy(): - """Zmierzone na panelu: "Bezpośrednie sąsiedztwo Lotniska Chopina w Warszawie" - trafiało w "Fryderyka Chopina" przez sam token "chopina" -- punkt wypadał - w Śródmieściu zamiast przy lotnisku. 1 fałszywe rozwiązanie na 1 218. +def test_a_verbal_description_is_not_matched_to_a_street(): + """Measured on the panel: "Bezpośrednie sąsiedztwo Lotniska Chopina w Warszawie" + matched "Fryderyka Chopina" through the token "chopina" alone, so the point + fell in the city centre instead of next to the airport. 1 false resolution + on 1,218. """ m = MultiLocalityResolver({ "WARSZAWA": {"nazwa": "Warszawa", "lat": 52.23, "lon": 21.0, @@ -203,12 +205,12 @@ def test_opis_slowny_nie_jest_dopasowywany_do_ulicy(): assert r.lat is None -def test_prog_pokrycia_nie_przerywa_dalszych_strategii(): - """Odrzucenie po progu musi przepuścić opis do reguły skrzyżowań. +def test_the_coverage_threshold_does_not_cut_off_the_later_strategies(): + """A rejection by the threshold has to pass the description on to the intersection rule. - Regresja: "SOBIESKIEGO JANA III/ IDZIKOWSKIEGO" ma 4 tokeny, więc próg się - stosuje; token "idzikowskiego" jest unikalny i wyjaśnia 1 z 4 tokenów. - Natychmiastowy zwrot braku gubił poprawne skrzyżowanie. + Regression: "SOBIESKIEGO JANA III/ IDZIKOWSKIEGO" has 4 tokens, so the + threshold applies; the token "idzikowskiego" is unique and explains 1 of the + 4 tokens. Returning a gap immediately lost the correct intersection. """ m = MultiLocalityResolver({ "WARSZAWA": {"nazwa": "Warszawa", "lat": 52.23, "lon": 21.0, "ulice": { @@ -221,18 +223,19 @@ def test_prog_pokrycia_nie_przerywa_dalszych_strategii(): assert r.dokladnosc == "PUNKT_SKRZYZOWANIA" -def test_krotki_opis_nie_podlega_progowi(mr): - """Próg dotyczy tylko opisów od 4 tokenów -- krótkie opisy to nazwy ulic.""" +def test_a_short_description_is_not_subject_to_the_threshold(mr): + """The threshold applies only to descriptions of 4 tokens or more; short descriptions are street names.""" r = mr.resolve("WARSZAWA, Grochowska") assert r.pewnosc == "EXACT" and r.ma_wspolrzedne -# --- niejednoznaczność nazwy w obrębie miejscowości ---------------------- +# --- ambiguity of a name within one locality ----------------------------- -def test_rozrzut_skladowych_jest_raportowany(): - """Nazwa ulicy powtórzona w kilku częściach miasta: punkt leży na najdłuższej - składowej, a rozrzut składowych jest zwracany jako jawna miara ryzyka. - Rejestry ustawowe nie podają dzielnicy, więc tego nie da się rozstrzygnąć. +def test_the_spread_of_the_components_is_reported(): + """A street name repeated in several parts of a city: the point lies on the + longest component, and the spread of the components is returned as an + explicit measure of risk. Statutory registers do not give the district, so + this cannot be settled. """ m = MultiLocalityResolver({ "WARSZAWA": {"nazwa": "Warszawa", "lat": 52.23, "lon": 21.0, @@ -245,30 +248,30 @@ def test_rozrzut_skladowych_jest_raportowany(): assert r.rozrzut_skladowych_m == 25993.4 -# --- zgodność wstecz ----------------------------------------------------- +# --- backward compatibility ---------------------------------------------- -def test_stary_gazeter_krotkiego_formatu_dziala(): +def test_the_old_short_format_gazetteer_works(): r = LocationResolver({"Grochowska": (52.24, 21.09)}) res = r.resolve("WARSZAWA, Grochowska") assert (res.lat, res.lon) == (52.24, 21.09) assert res.dokladnosc == "PUNKT_NA_OSI_ULICY" -def test_stary_gazeter_bez_wspolrzednych_dziala(): +def test_the_old_gazetteer_without_coordinates_works(): r = LocationResolver({"Grochowska": None}) res = r.resolve("WARSZAWA, Grochowska") assert res.pewnosc == "EXACT" and res.lat is None assert res.dokladnosc == "BRAK_GEOMETRII" -# --- podsumowanie -------------------------------------------------------- +# --- summary ------------------------------------------------------------- -def test_summarize_rozdziela_rozwiazane_od_ze_wspolrzednymi(mr): +def test_summarize_separates_the_resolved_from_those_with_coordinates(mr): rs = mr.resolve_series([ - "WARSZAWA, Grochowska", # EXACT + punkt - "WARSZAWA, Bezgeometryczna", # EXACT bez punktu - "SKB3", # kod stacji - "KRAKÓW, Grochowska", # poza gazeterem + "WARSZAWA, Grochowska", # EXACT + point + "WARSZAWA, Bezgeometryczna", # EXACT without a point + "SKB3", # station code + "KRAKÓW, Grochowska", # outside the gazetteer ]) s = MultiLocalityResolver.summarize(rs) assert s["n"] == 4 diff --git a/tests/test_layout.py b/tests/test_layout.py index d5846ca..0d5e36b 100644 --- a/tests/test_layout.py +++ b/tests/test_layout.py @@ -11,21 +11,21 @@ def _w(text, x0, x1, top): return {"text": text, "x0": x0, "x1": x1, "top": top, "bottom": top + 8} -def test_column_of_uzywa_srodka_slowa(): +def test_column_of_uses_the_word_centre(): g = ColumnGeometry([0.0, 10.0, 20.0, 30.0], "ruled") assert g.n_cols == 3 assert g.column_of(1.0, 4.0) == 0 - assert g.column_of(9.0, 12.0) == 1 # środek 10.5 -> kolumna 1 + assert g.column_of(9.0, 12.0) == 1 # centre 10.5 -> column 1 assert g.column_of(21.0, 29.0) == 2 -def test_column_of_przycina_do_skrajnych_kolumn(): +def test_column_of_clamps_to_the_outermost_columns(): g = ColumnGeometry([0.0, 10.0], "ruled") assert g.column_of(-5.0, -1.0) == 0 assert g.column_of(50.0, 60.0) == 0 -def test_detect_banded_columns_znajduje_korytarze_bieli(): +def test_detect_banded_columns_finds_whitespace_corridors(): words = [_w("a", 0, 20, 0), _w("b", 40, 60, 0), _w("c", 80, 100, 0)] g = detect_banded_columns(words, min_gap=5.0) assert g.strategy == "banded" @@ -34,18 +34,18 @@ def test_detect_banded_columns_znajduje_korytarze_bieli(): assert cells == [["a", "b", "c"]] -def test_detect_banded_columns_pusta_lista(): +def test_detect_banded_columns_empty_list(): assert detect_banded_columns([]).n_cols == 0 -def test_assign_words_to_columns_pusta_komorka_zostaje_pusta(): - """Sedno metody: brak wartości w kolumnie nie przesuwa sąsiadów.""" +def test_assign_words_to_columns_an_empty_cell_stays_empty(): + """The heart of the method: a missing value in a column does not shift its neighbours.""" g = ColumnGeometry([0.0, 30.0, 60.0, 90.0], "ruled") - words = [_w("PV", 1, 10, 0), _w("2026", 61, 80, 0)] # środkowa kolumna pusta + words = [_w("PV", 1, 10, 0), _w("2026", 61, 80, 0)] # middle column empty assert assign_words_to_columns(words, g) == [["PV", "", "2026"]] -def test_merge_continuation_rows_scala_zawiniety_adres(): +def test_merge_continuation_rows_joins_a_wrapped_address(): lines = [ ["1.", "Toruń, ul. Marii", "0,150", "Elektrownia"], ["", "Skłodowskiej-", "", "fotowoltaiczna"], @@ -59,7 +59,7 @@ def test_merge_continuation_rows_scala_zawiniety_adres(): assert rows[1][1] == "Toruń, ul. Równinna 8" -def test_predykaty_dziedziny(): +def test_domain_predicates(): assert looks_like_date("04.05.2026") and looks_like_date("2026-05-04") assert not looks_like_date("maj 2026") assert looks_like_number("0,7") and looks_like_number("12 000") and looks_like_number(3) @@ -69,7 +69,7 @@ def test_predykaty_dziedziny(): assert not looks_like_voltage("110") and not looks_like_voltage("Osoba prawna") -def test_audit_column_shift_wykrywa_moc_w_polu_statusu(): +def test_audit_column_shift_detects_capacity_in_the_status_field(): df = pd.DataFrame({ "status_procesu": ["UMOWA obowiązująca", "1,5 10,0 UMOWA O PRZYŁĄCZENIE"], "moc_pobierana": [1.0, None], @@ -81,6 +81,6 @@ def test_audit_column_shift_wykrywa_moc_w_polu_statusu(): assert 0.49 < a.udzial < 0.51 -def test_audit_column_shift_ignoruje_puste(): +def test_audit_column_shift_ignores_empty_values(): df = pd.DataFrame({"status_procesu": ["", "-", None], "moc_pobierana": [None] * 3}) assert audit_column_shift(df).n_przesunietych == 0 diff --git a/tests/test_longitudinal.py b/tests/test_longitudinal.py index 6c3d402..2e9d9ea 100644 --- a/tests/test_longitudinal.py +++ b/tests/test_longitudinal.py @@ -1,4 +1,4 @@ -"""Testy porównania edycji i wielokrotnych komórek mocy.""" +"""Tests of the edition comparison and of multi-valued capacity cells.""" import pandas as pd import pytest @@ -17,72 +17,72 @@ def _wiersz(**kw): return baza -class TestRozbijMoc: - """Wiele miejsc przyłączenia w jednej komórce.""" +class TestSplitCapacity: + """Several connection points in a single cell.""" - def test_zlamanie_linii_daje_skladowe(self): + def test_a_line_break_yields_components(self): assert _rozbij_moc("129\n240") == ["129", "240"] - def test_srednik_i_zlamanie_linii_razem(self): + def test_a_semicolon_and_a_line_break_together(self): assert _rozbij_moc("129; \n240") == ["129", "240"] - def test_trzy_skladowe(self): + def test_three_components(self): assert _rozbij_moc("27; \n45; \n21") == ["27", "45", "21"] - def test_nie_rozbija_po_spacji(self): - """Spacja jest u publikujących separatorem TYSIĘCZNYM, nie rozdzielaczem.""" + def test_it_does_not_split_on_a_space(self): + """For these publishers a space is a THOUSANDS separator, not a delimiter.""" assert _rozbij_moc("129 240") == ["129 240"] - def test_liczba_zwykla_to_jedna_skladowa(self): + def test_a_plain_number_is_one_component(self): assert _rozbij_moc(1830.0) == ["1830.0"] - def test_kreska_i_pustka_odrzucone(self): + def test_a_dash_and_an_empty_value_are_rejected(self): assert _rozbij_moc("-") == [] assert _rozbij_moc(None) == [] - def test_regresja_sklejenia_trzech_rzedow_wielkosci(self): - """Pinuje defekt z wersji 1.0: "129⏎240" sklejało się w 129 240 MW. + def test_regression_of_a_three_orders_of_magnitude_merge(self): + """Pins the defect from version 1.0: "129⏎240" merged into 129 240 MW. - Przyczyną było zamienianie złamania linii na spację przed konwersją, - a spacja jest traktowana jako separator tysięczny. Poprawne odczytanie - to dwie składowe sumujące się do 369 MW. + The cause was replacing the line break with a space before the + conversion, and a space is treated as a thousands separator. The correct + reading is two components summing to 369 MW. """ czesci = _rozbij_moc("129\n240") assert sum(float(c) for c in czesci) == 369.0 - assert "".join(czesci) == "129240" # tak wyglądał błąd + assert "".join(czesci) == "129240" # this is what the defect looked like class TestSurrogateKey: - def test_identyczne_wiersze_daja_ten_sam_klucz(self): + def test_identical_rows_give_the_same_key(self): df = pd.DataFrame([_wiersz(), _wiersz()]) k = surrogate_key(df) assert k.iloc[0] == k.iloc[1] - def test_zmiana_mocy_rozjezdza_klucz(self): + def test_a_change_of_capacity_pulls_the_key_apart(self): df = pd.DataFrame([_wiersz(), _wiersz(moc_pobierana=2000.0)]) k = surrogate_key(df) assert k.iloc[0] != k.iloc[1] - def test_status_nie_wchodzi_do_klucza(self): - """Inaczej każda zmiana statusu wyglądałaby jak zniknięcie i pojawienie.""" + def test_the_status_does_not_enter_the_key(self): + """Otherwise every status change would look like a disappearance and an appearance.""" df = pd.DataFrame([_wiersz(), _wiersz(status_procesu="WARUNKI_WYDANE")]) k = surrogate_key(df) assert k.iloc[0] == k.iloc[1] - def test_brak_pol_klucza_jest_bledem(self): - with pytest.raises(ValueError, match="żadne z pól klucza"): + def test_missing_key_fields_are_an_error(self): + with pytest.raises(ValueError, match="none of the key fields"): surrogate_key(pd.DataFrame({"cos_innego": [1]}), fields=("moc_dostepna",)) class TestCompareEditions: - def test_przeplywy(self): + def test_the_flows(self): a = pd.DataFrame([_wiersz(lokalizacja_tekst="A"), _wiersz(lokalizacja_tekst="B")]) b = pd.DataFrame([_wiersz(lokalizacja_tekst="B"), _wiersz(lokalizacja_tekst="C")]) d = compare_editions(a, b, "lipiec", "sierpien") assert (d.wspolnych, d.nowych, d.ubylych) == (1, 1, 1) assert d.as_dict()["wierszy_netto"] == 0 - def test_przejscie_w_przod_liczone_jako_w_przod(self): + def test_a_forward_transition_is_counted_as_forward(self): a = pd.DataFrame([_wiersz(status_procesu="W_TRAKCIE_ANALIZY")]) b = pd.DataFrame([_wiersz(status_procesu="WARUNKI_WYDANE")]) d = compare_editions(a, b) @@ -90,21 +90,21 @@ def test_przejscie_w_przod_liczone_jako_w_przod(self): assert d.udzial_przejsc_w_przod == 1.0 assert d.przejscia_wstecz == 0 - def test_przejscie_wstecz_wykryte(self): + def test_a_backward_transition_is_detected(self): a = pd.DataFrame([_wiersz(status_procesu="UMOWA_OBOWIAZUJACA")]) b = pd.DataFrame([_wiersz(status_procesu="WARUNKI_WYDANE")]) d = compare_editions(a, b) assert d.przejscia_wstecz == 1 assert d.udzial_przejsc_w_przod == 0.0 - def test_odmowa_liczona_jako_zakonczenie_w_przod(self): + def test_a_refusal_is_counted_as_a_forward_closure(self): a = pd.DataFrame([_wiersz(status_procesu="W_TRAKCIE_ANALIZY")]) b = pd.DataFrame([_wiersz(status_procesu="ODMOWA")]) d = compare_editions(a, b) assert d.udzial_przejsc_w_przod == 1.0 - def test_niemonotonicznosc_migawki(self): - """Nowy wiersz od razu zamknięty i ubyły wiersz czynny, obie flagi.""" + def test_non_monotonicity_of_the_snapshot(self): + """A new row already closed and a vanished row still active, both flags.""" a = pd.DataFrame([_wiersz(lokalizacja_tekst="X", status_procesu="WARUNKI_WYDANE")]) b = pd.DataFrame([_wiersz(lokalizacja_tekst="Y", status_procesu="WNIOSEK_WYCOFANY")]) d = compare_editions(a, b).as_dict() @@ -112,7 +112,7 @@ def test_niemonotonicznosc_migawki(self): assert d["ubyle_czynne"] == 1 assert d["migawka_monotoniczna"] is False - def test_brak_zmian_daje_udzial_none(self): + def test_no_changes_give_a_share_of_none(self): a = pd.DataFrame([_wiersz()]) d = compare_editions(a, a.copy()) assert d.zmian_statusu == 0 @@ -120,7 +120,7 @@ def test_brak_zmian_daje_udzial_none(self): class TestLinkageAudit: - """Ocena dopasowania na polach WYŁĄCZONYCH z klucza.""" + """Assessment of the linkage on fields EXCLUDED from the key.""" def _para(self, **zmiany_b): a = pd.DataFrame([_wiersz(_podmiot="Alfa Sp. z o.o.", _nazwa_obiektu="PV Wyszki")]) @@ -128,37 +128,37 @@ def _para(self, **zmiany_b): b_.update(zmiany_b) return a, pd.DataFrame([_wiersz(**b_)]) - def test_zgodne_pola_wstrzymane_daja_potwierdzenie(self): + def test_matching_held_out_fields_give_a_confirmation(self): a, b = self._para() au = linkage_audit(a, b).as_dict() assert (au["par"], au["potwierdzonych"], au["falszywych"]) == (1, 1, 0) assert au["precyzja_dolna"] == 1.0 - def test_oba_pola_tozsamosci_rozbiezne_to_falszywe_dopasowanie(self): + def test_both_identity_fields_divergent_means_a_false_linkage(self): a, b = self._para(_podmiot="Beta Sp. z o.o.", _nazwa_obiektu="PV Bulkowo") au = linkage_audit(a, b).as_dict() assert au["falszywych"] == 1 assert au["precyzja_gorna"] == 0.0 - def test_jedno_pole_rozbiezne_to_niepewne(self): + def test_one_divergent_field_means_uncertain(self): a, b = self._para(_nazwa_obiektu="PV Bulkowo") au = linkage_audit(a, b).as_dict() assert (au["niepewnych"], au["falszywych"]) == (1, 0) assert au["precyzja_dolna"] == 0.0 and au["precyzja_gorna"] == 1.0 - def test_inny_zapis_formy_prawnej_to_ten_sam_podmiot(self): - """Publikujący zmienia zapis formy prawnej miedzy edycjami.""" + def test_a_different_spelling_of_the_legal_form_is_the_same_entity(self): + """The publisher changes the spelling of the legal form between editions.""" a, b = self._para(_podmiot="Alfa sp.z o.o.") au = linkage_audit(a, b).as_dict() assert au["potwierdzonych"] == 1 - def test_nazwa_rozszerzona_nie_jest_konfliktem(self): + def test_an_extended_name_is_not_a_conflict(self): a, b = self._para(_nazwa_obiektu="PV Wyszki - zm. WP") au = linkage_audit(a, b).as_dict() assert au["potwierdzonych"] == 1 - def test_uzupelnienie_jednostronne_nie_jest_konfliktem(self): - """Puste w jednej edycji, wypelnione w drugiej, to redakcja, nie inny wniosek.""" + def test_a_one_sided_completion_is_not_a_conflict(self): + """Empty in one edition and filled in the other is an edit, not a different application.""" a = pd.DataFrame([_wiersz(_podmiot="Alfa Sp. z o.o.", data_wniosku=None)]) b = pd.DataFrame([_wiersz(_podmiot="Alfa Sp. z o.o.", data_wniosku="2026-07-31")]) wynik = linkage_audit(a, b) @@ -166,7 +166,7 @@ def test_uzupelnienie_jednostronne_nie_jest_konfliktem(self): kat = set(wynik.rozbieznosci["kategoria"]) assert kat == {"uzupelnienie_jednostronne"} - def test_granice_precyzji_sie_nie_krzyzuja(self): + def test_the_precision_bounds_do_not_cross(self): a = pd.DataFrame([_wiersz(lokalizacja_tekst=f"M{i}", _podmiot="Alfa Sp. z o.o.", _nazwa_obiektu=f"PV {i}") for i in range(4)]) b = pd.DataFrame([_wiersz(lokalizacja_tekst="M0", _podmiot="Alfa Sp. z o.o.", _nazwa_obiektu="PV 0"), @@ -179,9 +179,9 @@ def test_granice_precyzji_sie_nie_krzyzuja(self): assert au["precyzja_dolna"] <= au["precyzja_gorna"] -class TestKolizjeKlucza: - def test_kolizje_i_odrzucenia_sa_raportowane(self): - """Wiersze o powtarzajacym sie kluczu sa odrzucane, a liczba jest jawna.""" +class TestKeyCollisions: + def test_collisions_and_rejections_are_reported(self): + """Rows with a repeated key are rejected and the count is explicit.""" a = pd.DataFrame([_wiersz(), _wiersz(), _wiersz(lokalizacja_tekst="Inna")]) b = pd.DataFrame([_wiersz()]) d = compare_editions(a, b).as_dict() @@ -190,16 +190,16 @@ def test_kolizje_i_odrzucenia_sa_raportowane(self): assert d["wspolnych"] == 1 -class TestZgodnoscZWersjaPandas: - """Klucz nie moze zalezec od wersji pandas. +class TestPandasVersionCompatibility: + """The key must not depend on the pandas version. - Defekt wykryty przy uruchomieniu notatnika Colab na pandas 3: `.astype(str)` - zamienialo brak na lancuch "nan" w pandas 2, a w pandas 3 zachowuje wartosc - brakujaca, wiec zlaczenie skladowych klucza rzucalo TypeError. Klucz buduje - sie teraz jawna konwersja. + A defect found when the Colab notebook was run on pandas 3: `.astype(str)` + turned a missing value into the string "nan" in pandas 2, while in pandas 3 + it keeps the missing value, so joining the key components raised TypeError. + The key is now built with an explicit conversion. """ - def test_brak_wartosci_daje_pusty_segment_bez_wyjatku(self): + def test_a_missing_value_gives_an_empty_segment_with_no_exception(self): import numpy as np import pandas as pd @@ -211,8 +211,8 @@ def test_brak_wartosci_daje_pusty_segment_bez_wyjatku(self): assert "nan" not in k.lower(), k assert "None" not in k, k - def test_braki_dopasowuja_sie_do_brakow(self): - """Wiersz z brakiem laczy sie tylko z wierszem, w ktorym brak tez jest.""" + def test_gaps_match_gaps(self): + """A row with a gap links only to a row that has the gap as well.""" import numpy as np import pandas as pd @@ -226,9 +226,9 @@ def test_braki_dopasowuja_sie_do_brakow(self): class TestLinkageRecall: - """Czułość klucza: pary, których klucz treściowy NIE połączył.""" + """Recall of the key: the pairs the content key did NOT join.""" - def test_zmiana_mocy_rozrywa_pare_i_jest_odzyskiwana(self): + def test_a_change_of_capacity_breaks_a_pair_and_it_is_recovered(self): a = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV Wyszki", moc_wprowadzana=1000.0)]) b = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV Wyszki", @@ -239,10 +239,10 @@ def test_zmiana_mocy_rozrywa_pare_i_jest_odzyskiwana(self): r = linkage_recall(a, b) assert r.odzyskanych == 1 assert r.odzyskane.iloc[0]["pola_klucza_rozne"] == "moc_wprowadzana" - assert r.czulosc_klucza == 0.0 # zero par połączonych, jedna możliwa + assert r.czulosc_klucza == 0.0 # zero pairs joined, one possible - def test_pola_tozsamosci_musza_byc_rozlaczne_z_kluczem(self): - """Pole wspólne z kluczem nie wykryje pary rozerwanej zmianą tego pola.""" + def test_the_identity_fields_must_be_disjoint_from_the_key(self): + """A field shared with the key will not detect a pair broken by a change of that field.""" a = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV Wyszki", lokalizacja_tekst="Stacja A")]) b = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV Wyszki", @@ -251,14 +251,14 @@ def test_pola_tozsamosci_musza_byc_rozlaczne_z_kluczem(self): zepsute = linkage_recall(a, b, pola_tozsamosci=("_podmiot", "lokalizacja_tekst")) assert zepsute.odzyskanych == 0 - def test_niejednoznaczna_tozsamosc_nie_jest_odzyskiwana(self): + def test_an_ambiguous_identity_is_not_recovered(self): a = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV", moc_wprowadzana=1.0), _wiersz(_podmiot="Alfa", _nazwa_obiektu="PV", moc_wprowadzana=2.0)]) b = pd.DataFrame([_wiersz(_podmiot="Alfa", _nazwa_obiektu="PV", moc_wprowadzana=3.0)]) assert linkage_recall(a, b).odzyskanych == 0 - def test_zero_jako_brak_jest_wylaczone_domyslnie(self): - """Zero jest wartością ujawnioną; zrównanie go z brakiem to decyzja analityka.""" + def test_zero_as_a_gap_is_switched_off_by_default(self): + """Zero is a disclosed value; treating it as a gap is the analyst's decision.""" a = pd.DataFrame([_wiersz(moc_pobierana=0.0)]) b = pd.DataFrame([_wiersz(moc_pobierana=None)]) assert surrogate_key(a).iloc[0] != surrogate_key(b).iloc[0] @@ -266,11 +266,11 @@ def test_zero_jako_brak_jest_wylaczone_domyslnie(self): == surrogate_key(b, zero_jako_brak=True).iloc[0]) -class TestKluczEncjiWezel: - """Klucz musi być dobrany do encji, tak samo jak rdzeń schematu. +class TestNodeEntityKey: + """The key has to be chosen to fit the entity, just as the schema core is. - Klucz wnioskowy na wierszach węzłowych nie zgłasza błędu, po cichu - produkuje kolizje, bo pola wniosku są tam puste. + The application key on node rows reports no error; it silently produces + collisions, because the application fields are empty there. """ def _wezly(self): @@ -284,12 +284,12 @@ def _wezly(self): "klasa_zasobu": None, "moc_wprowadzana": None, "moc_pobierana": None}, ]) - def test_klucz_wezlowy_rozroznia_poziomy_napiecia_tej_samej_stacji(self): + def test_the_node_key_distinguishes_voltage_levels_of_the_same_station(self): d = self._wezly() assert surrogate_key(d, fields=NODE_KEY_FIELDS).nunique() == 2 - def test_klucz_wnioskowy_na_wezlach_daje_kolizje(self): - """Regresja: to jest tryb awarii, dla którego NODE_KEY_FIELDS istnieje.""" + def test_the_application_key_on_nodes_produces_collisions(self): + """Regression: this is the failure mode NODE_KEY_FIELDS exists for.""" d = self._wezly().assign(poziom_napiecia="66 kV") assert surrogate_key(d).nunique() == 1 assert surrogate_key(d, fields=NODE_KEY_FIELDS).nunique() == 2 diff --git a/tests/test_pse_energa.py b/tests/test_pse_energa.py index b31c49c..42ee2b7 100644 --- a/tests/test_pse_energa.py +++ b/tests/test_pse_energa.py @@ -1,8 +1,8 @@ -"""Testy adapterów PSE S.A. i ENERGA-OPERATOR S.A. +"""Tests of the PSE S.A. and ENERGA-OPERATOR S.A. adapters. -Testy regresyjne pilnują trzech defektów wykrytych POMIAREM na wzorcu odczytanym -wzrokowo -- każdy z nich przechodził niezauważony przez testy jednostkowe, bo -każdy dawał wynik pusty albo pozornie sensowny, nie wyjątek. +The regression tests guard three defects found by MEASUREMENT against a visually +read reference set; each of them passed unnoticed through the unit tests, because +each produced an empty or an apparently sensible result rather than an exception. """ from __future__ import annotations @@ -24,45 +24,45 @@ def _ma(plik: str) -> bool: return os.path.exists(os.path.join(DANE, plik)) -# --- rejestr ------------------------------------------------------------- +# --- registry ------------------------------------------------------------ -def test_adaptery_zarejestrowane(): +def test_the_adapters_are_registered(): assert "pl_pse" in REGISTRY assert "pl_energa" in REGISTRY assert get_adapter("pl_pse").publisher == "PSE S.A." assert get_adapter("pl_energa").publisher == "ENERGA-OPERATOR S.A." -# --- regresja 1: pusty identyfikator ------------------------------------ +# --- regression 1: empty identifier ------------------------------------- -def test_blank_lapie_nan(): - """``nan`` jest w Pythonie prawdziwe -- ``if v`` nie wystarcza.""" +def test_blank_catches_nan(): + """``nan`` is truthy in Python, so ``if v`` is not enough.""" assert T._blank(float("nan")) is True assert T._blank(None) is True assert T._blank(" ") is True assert T._blank("0") is False -def test_zastepnik_identyfikatora_dziala_gdy_id_puste(): +def test_the_identifier_surrogate_works_when_the_id_is_empty(): raw = pd.DataFrame({"id_obiektu": [None, "X-1", float("nan")], "lp": ["1.", "2.", None]}) out = T.to_schema(raw, publisher_key="pse", data_publikacji="2026-08-31") assert out["id_wniosku"].tolist() == ["pse:poz:1", "X-1", "pse:poz:3"] -# --- regresja 2: poziom napięcia klasowy -------------------------------- +# --- regression 2: class voltage level ----------------------------------- -def test_poziom_napiecia_klasowy_bez_jednostki(): - """"SN" to klasa napięcia, nie liczba kilowoltów -- "SN kV" nic nie znaczy.""" +def test_a_class_voltage_level_carries_no_unit(): + """"SN" is a voltage class, not a number of kilovolts, so "SN kV" means nothing.""" assert T._volt("SN") == "SN" assert T._volt("sn") == "SN" assert T._volt("110") == "110 kV" assert T._volt("110; 400") == "110; 400 kV" -# --- regresja 3: data z komórki arkusza --------------------------------- +# --- regression 3: date from a spreadsheet cell -------------------------- -def test_daty_przechodza_przez_typ_timestamp(): - """openpyxl zwraca daty jako Timestamp; ``str()`` na nich gubił wszystkie daty.""" +def test_dates_survive_the_timestamp_type(): + """openpyxl returns dates as Timestamp; ``str()`` on them lost every date.""" raw = pd.DataFrame({ "id_obiektu": ["A"], "data_zlozenia": [pd.Timestamp("2023-08-07")], @@ -72,22 +72,22 @@ def test_daty_przechodza_przez_typ_timestamp(): out = T.to_schema(raw, publisher_key="pse", data_publikacji=None) assert out["data_wniosku"].iloc[0] == "2023-08-07" assert out["data_warunkow"].iloc[0] == "2024-03-18" - # nierówność nie jest datą: pole schematu puste, treść zachowana w rozszerzeniu + # an inequality is not a date: the schema field stays empty, the content is kept in an extension assert out["data_energizacji"].iloc[0] is None assert out["_energizacja_tekst"].iloc[0] == "po 30.06.2026" -# --- regresja 4: status rozwiązanej umowy ------------------------------- +# --- regression 4: status of a terminated agreement ---------------------- -def test_umowa_rozwiazana_nie_jest_obowiazujaca(): - """Lista rozwijana wspólnego szablonu deklaruje oba statusy osobno.""" +def test_a_terminated_agreement_is_not_an_effective_one(): + """The drop-down list of the shared template declares both statuses separately.""" assert harmonize_status("UMOWA O PRZYŁĄCZENIE rozwiązana") == "UMOWA_ROZWIAZANA" assert harmonize_status("UMOWA O PRZYŁĄCZENIE obowiązująca") == "UMOWA_OBOWIAZUJACA" assert harmonize_status("UMOWA O PRZYŁĄCZENIE - obiekt przyłączony") == "PRZYLACZONY" -def test_slownik_szablonu_odwzorowany_w_calosci(): - """Każda wartość listy rozwijanej szablonu musi dać znany token, nie NIEOKRESLONY.""" +def test_the_template_vocabulary_is_mapped_in_full(): + """Every value of the template drop-down list must yield a known token, not NIEOKRESLONY.""" statusy = [ "WNIOSEK w weryfikacji", "WNIOSEK kompletny - w trakcie analizy technicznej i ekonomicznej", "WNIOSEK niekompletny", "WNIOSEK wycofany", "WARUNKI PRZYŁĄCZENIA wydane", @@ -101,14 +101,14 @@ def test_slownik_szablonu_odwzorowany_w_calosci(): "ODB", "OSD", "OSDn", "EW", "SG", "OGW", "JS", "MIX"] for r in rodzaje: assert harmonize_klasa(r) != "NIEOKRESLONA", r - # szablon deklaruje BG jako BLOK GAZOWY, nie biogaz -- wbrew intuicji nazwy + # the template declares BG as BLOK GAZOWY, a gas unit, not biogas, against the intuition of the name assert harmonize_klasa("BG") == "GAZ" -# --- testy na dokumentach źródłowych ------------------------------------ +# --- tests against the source documents ---------------------------------- -@pytest.mark.skipif(not _ma("pse_art7_8l_20260831.xlsx"), reason="brak dokumentu PSE") -def test_pse_pelny_przebieg(): +@pytest.mark.skipif(not _ma("pse_art7_8l_20260831.xlsx"), reason="PSE document not present") +def test_pse_full_run(): r = get_adapter("pl_pse").parse([ os.path.join(DANE, "pse_art7_8l_20260831.xlsx"), os.path.join(DANE, "pse_lista_rozdzielni_brak_mozliwosci_20260204.xlsx"), @@ -116,16 +116,16 @@ def test_pse_pelny_przebieg(): f = r.frame assert (f["_encja"] == "WNIOSEK").sum() == 876 assert (f["_encja"] == "WEZEL").sum() == 69 - # odnośniki przypisów odcięte od treści, nie wklejone w nią + # footnote markers cut off from the content, not pasted into it assert not f["lokalizacja_tekst"].astype(str).str.fullmatch(r"WYPM|CPKK").any() assert f["_przypisy"].notna().sum() == 69 - # PSE ujawnia pkt 2) jako LICZBĘ MIEJSC, nie moc -- pole mocy zostaje puste + # PSE discloses point 2) as a NUMBER OF SLOTS, not a capacity, so the capacity field stays empty assert f.loc[f["_encja"] == "WEZEL", "moc_dostepna"].isna().all() assert f.loc[f["_encja"] == "WEZEL", "_liczba_dostepnych_miejsc"].notna().any() -@pytest.mark.skipif(not _ma("energa_wnioski_odmowy_20260831.pdf"), reason="brak dokumentu Energi") -def test_energa_pelny_przebieg(): +@pytest.mark.skipif(not _ma("energa_wnioski_odmowy_20260831.pdf"), reason="Energa document not present") +def test_energa_full_run(): r = get_adapter("pl_energa").parse([ os.path.join(DANE, "energa_wnioski_odmowy_20260831.pdf"), os.path.join(DANE, "energa_moc_dostepna_odbiorcza_20260831.pdf"), @@ -134,14 +134,14 @@ def test_energa_pelny_przebieg(): f = r.frame wnioski = f[f["_encja"] == "WNIOSEK"] assert len(wnioski) == 5286 - # liczby porządkowe dokumentu odtworzone bez luk i bez powtórzeń + # the ordinal numbers of the document reconstructed with no gaps and no repetitions lp = pd.to_numeric(wnioski["_lp_dokumentu"].str.rstrip("."), errors="coerce") assert lp.notna().all() assert sorted(lp.astype(int)) == list(range(1, 5287)) - # Energa jest pierwszym źródłem w panelu wypełniającym moc_dostepna + # Energa is the first source in the panel that fills moc_dostepna wezly = f[f["_encja"] == "WEZEL"] assert len(wezly) == 96 assert wezly["moc_dostepna"].notna().all() assert set(wezly["_kierunek"]) == {"odbiorcza", "wytworcza"} - # data publikacji z DOKUMENTU, nie z nazwy pliku + # publication date from the DOCUMENT, not from the file name assert (wnioski["data_publikacji"] == "2026-06-30").all() diff --git a/tests/test_pt_eredes.py b/tests/test_pt_eredes.py index d491de9..e4bd3cf 100644 --- a/tests/test_pt_eredes.py +++ b/tests/test_pt_eredes.py @@ -1,9 +1,10 @@ -"""Testy adaptera portugalskiego. +"""Tests of the Portuguese adapter. -Najważniejszy z nich pilnuje rozstrzygnięcia o jednostkach: publikujący podaje -moc pozorną w MVA, schemat operuje mocą czynną w kW, więc pole mocy musi zostać -PUSTE. Wpisanie tam liczby z MVA byłoby cichym błędem jednostki, tej samej -klasy, co błędy, które projekt już raz wykrył pomiarem. +The most important of them guards the decision about units: the publisher gives +apparent power in MVA, the schema works with active power in kW, so the capacity +field has to stay EMPTY. Writing an MVA figure there would be a silent unit +error, of the same class as the errors this project has already caught once by +measurement. """ import csv @@ -59,57 +60,57 @@ def _wiersz(**zmiany): return r -class TestJednostki: - def test_moc_dostepna_zostaje_pusta_bo_zrodlo_podaje_moc_pozorna(self, tmp_path): - """Rdzeń rozstrzygnięcia: MVA to nie kW i nie wolno tego przeliczać.""" +class TestUnits: + def test_available_capacity_stays_empty_because_the_source_gives_apparent_power(self, tmp_path): + """The heart of the decision: MVA is not kW and it must not be converted.""" d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz()])).frame assert pd.isna(d.loc[0, "moc_dostepna"]) assert pd.isna(d.loc[0, "moc_zarezerwowana"]) assert d.loc[0, "_moc_dostepna_mva"] == pytest.approx(12.5) assert d.loc[0, "_jednostka_mocy_zrodlowa"] == SOURCE_POWER_UNIT - def test_przecinek_dziesietny_zrodla_jest_odczytywany(self, tmp_path): + def test_the_decimal_comma_of_the_source_is_read(self, tmp_path): d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz()])).frame assert d.loc[0, "_moc_przylaczona_mva"] == pytest.approx(11.5908) assert d.loc[0, "_moc_zakontraktowana_mva"] == pytest.approx(0.298) -class TestRdzen: - def test_rdzen_wezla_spelnia_flaga_ograniczenia_a_nie_moc(self, tmp_path): - """Alternatywa rdzenia encji WĘZEŁ działa, choć pole mocy jest puste.""" +class TestCore: + def test_the_node_core_is_satisfied_by_the_constraint_flag_not_by_capacity(self, tmp_path): + """The core alternative of the WEZEL entity works although the capacity field is empty.""" d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz()])).frame assert bool(core_complete_mask(d).iloc[0]) is True assert pd.isna(d.loc[0, "moc_dostepna"]) - def test_zerowa_zdolnosc_to_ograniczenie_a_nie_brak_danych(self, tmp_path): + def test_zero_capability_is_a_constraint_and_not_missing_data(self, tmp_path): d = get_adapter("pt_eredes").parse(_plik( tmp_path, [_wiersz(capacidade_de_recepcao_mt_at_mva_ultimo_trimestre="0")])).frame assert bool(d.loc[0, "ograniczenie_flaga"]) is True - def test_brak_wartosci_zdolnosci_nie_jest_ograniczeniem(self, tmp_path): - """Pusta komórka to nieujawnienie; oznaczenie jej jako ograniczenia byłoby zmyśleniem.""" + def test_a_missing_capability_value_is_not_a_constraint(self, tmp_path): + """An empty cell is a non-disclosure; marking it as a constraint would be an invention.""" d = get_adapter("pt_eredes").parse(_plik( tmp_path, [_wiersz(capacidade_de_recepcao_mt_at_mva_ultimo_trimestre="")])).frame assert d.loc[0, "ograniczenie_flaga"] is None -class TestOdwzorowanie: - def test_grupa_podstacji_trafia_w_pole_lokalizacji(self, tmp_path): - """To samo pole, co lista stacji w wierszu węzłowym publikującego polskiego.""" +class TestMapping: + def test_the_substation_group_goes_into_the_location_field(self, tmp_path): + """The same field as the list of stations in the node row of the Polish publisher.""" d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz()])).frame assert d.loc[0, "lokalizacja_tekst"] == "Monchique, Aljezur" assert d.loc[0, "_encja"] == "WEZEL" - def test_kwartal_zrodla_staje_sie_data_konca_kwartalu(self, tmp_path): + def test_the_quarter_of_the_source_becomes_the_end_of_quarter_date(self, tmp_path): d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz()])).frame assert d.loc[0, "data_publikacji"] == "2026-06-30" - def test_nierozpoznany_zapis_kwartalu_daje_brak_a_nie_zgadywanie(self, tmp_path): + def test_an_unrecognised_quarter_notation_gives_a_gap_and_not_a_guess(self, tmp_path): d = get_adapter("pt_eredes").parse(_plik( tmp_path, [_wiersz(data_ultimo_trimestre="wiosna")])).frame assert d.loc[0, "data_publikacji"] is None - def test_poziom_napiecia_z_niezerowych_kolumn_zdolnosci(self, tmp_path): + def test_the_voltage_level_comes_from_the_non_zero_capability_columns(self, tmp_path): d = get_adapter("pt_eredes").parse(_plik(tmp_path, [_wiersz( **{"capacidade_de_recepcao_at_mva_ultimo_trimestre": "0", "capacidade_de_recepcao_mt_15kv_mva_ultimo_trimestre": "3,2"})])).frame diff --git a/tests/test_quality.py b/tests/test_quality.py index 19ae732..c2a82ed 100644 --- a/tests/test_quality.py +++ b/tests/test_quality.py @@ -3,17 +3,17 @@ from gridqueue.quality import RULES, run_quality -def test_jest_osiem_regul_i_kazda_ma_podstawe(): +def test_there_are_eight_rules_and_each_has_a_basis(): assert len(RULES) == 8 assert {r.kod for r in RULES} == {f"R{i}" for i in range(1, 9)} for r in RULES: assert r.podstawa -def test_r1_monotonicznosc_dat(): +def test_r1_date_monotonicity(): df = pd.DataFrame({ "data_wniosku": ["2026-01-01", "2026-05-01"], - "data_warunkow": ["2026-02-01", "2026-04-01"], # drugi wiersz odwrócony + "data_warunkow": ["2026-02-01", "2026-04-01"], # second row reversed "data_umowy": ["2026-03-01", None], "data_energizacji": [None, None], }) @@ -22,10 +22,10 @@ def test_r1_monotonicznosc_dat(): assert rep["reguly"][0]["szczegoly"]["pary"]["data_wniosku>data_warunkow"] == 1 -def test_r2_dwuletnia_waznosc_warunkow(): +def test_r2_two_year_validity_of_the_conditions(): df = pd.DataFrame({ "data_warunkow": ["2022-01-01", "2024-01-01"], - "_data_utraty_waznosci": ["2025-06-01", "2026-01-01"], # pierwszy > 2 lata + "_data_utraty_waznosci": ["2025-06-01", "2026-01-01"], # the first one is more than 2 years "data_umowy": [None, None], }) rep = run_quality(df, tuple(r for r in RULES if r.kod == "R2")).as_dict() @@ -34,7 +34,7 @@ def test_r2_dwuletnia_waznosc_warunkow(): assert d["sprawdzonych_dat_utraty"] == 2 -def test_r3_status_wobec_dat(): +def test_r3_status_against_the_dates(): df = pd.DataFrame({ "status_procesu": ["ODMOWA", "ODMOWA", "PRZYLACZONY"], "data_odmowy": ["2026-01-01", None, None], @@ -45,21 +45,21 @@ def test_r3_status_wobec_dat(): assert rep["reguly"][0]["naruszenia"] == 1 -def test_r4_spojnosc_jednostek_wykrywa_mw_zamiast_kw(): +def test_r4_unit_consistency_detects_mw_instead_of_kw(): df = pd.DataFrame({"moc_pobierana": [700.0, 0.7, 0.0, None]}) rep = run_quality(df, tuple(r for r in RULES if r.kod == "R4")).as_dict() assert rep["reguly"][0]["naruszenia"] == 1 assert rep["reguly"][0]["szczegoly"]["per_pole"]["moc_pobierana"] == 1 -def test_r5_zakresy_wartosci(): +def test_r5_value_ranges(): df = pd.DataFrame({"data_wniosku": ["1900-01-01", "2026-01-01"], "moc_pobierana": [-5.0, 10.0]}) rep = run_quality(df, tuple(r for r in RULES if r.kod == "R5")).as_dict() assert rep["reguly"][0]["naruszenia"] == 1 -def test_r6_duplikaty(): +def test_r6_duplicates(): df = pd.DataFrame({"id_wniosku": ["a", "a", "a", "b"]}) rep = run_quality(df, tuple(r for r in RULES if r.kod == "R6")).as_dict() assert rep["reguly"][0]["naruszenia"] == 2 @@ -67,7 +67,7 @@ def test_r6_duplikaty(): assert rep["reguly"][0]["szczegoly"]["max_krotnosc"] == 3 -def test_r7_kompletnosc_rdzenia(): +def test_r7_core_completeness(): df = pd.DataFrame({ "id_wniosku": ["a", "b"], "lokalizacja_tekst": ["x", None], "klasa_zasobu": ["PV", "PV"], "moc_pobierana": [1.0, 2.0], @@ -77,24 +77,24 @@ def test_r7_kompletnosc_rdzenia(): assert rep["reguly"][0]["naruszenia"] == 1 -def test_r8_slownik_kontrolowany(): +def test_r8_controlled_vocabulary(): df = pd.DataFrame({"klasa_zasobu": ["PV", "PANELE"], "status_procesu": ["ODMOWA", "ODMOWA"]}) rep = run_quality(df, tuple(r for r in RULES if r.kod == "R8")).as_dict() assert rep["reguly"][0]["naruszenia"] == 1 -def test_reguly_nie_rzucaja_na_pustej_ramce(): +def test_the_rules_do_not_raise_on_an_empty_frame(): rep = run_quality(pd.DataFrame()).as_dict() assert rep["n_wierszy"] == 0 assert all(r["naruszenia"] >= 0 for r in rep["reguly"]) -def test_r7_nie_karze_wniosku_wytworczego_za_brak_mocy_pobieranej(): - """R7 mierzy braki ujawnienia, nie własność schematu. +def test_r7_does_not_penalise_a_generating_application_for_missing_import_capacity(): + """R7 measures gaps in disclosure, not a property of the schema. - Przed wersją 1.0 rdzeń wymagał `moc_pobierana` bezwarunkowo, więc każdy - wniosek czysto wytwórczy był liczony jako naruszenie. Tu pinujemy nowy - kontrakt: naruszeniem jest brak JAKIEJKOLWIEK mocy. + Before version 1.0 the core required `moc_pobierana` unconditionally, so every + purely generating application was counted as a violation. Here we pin the new + contract: the violation is the absence of ANY capacity. """ import pandas as pd @@ -106,11 +106,11 @@ def test_r7_nie_karze_wniosku_wytworczego_za_brak_mocy_pobieranej(): ]) r7 = [x for x in run_quality(df).as_dict()["reguly"] if x["kod"] == "R7"][0] assert r7["naruszenia"] == 1 - klucz = "WNIOSEK/co najmniej jedno z: moc_pobierana, moc_wprowadzana" + klucz = "WNIOSEK/at least one of: moc_pobierana, moc_wprowadzana" assert r7["szczegoly"]["per_pole"][klucz] == 1 -def test_r7_ocenia_wezel_wymaganiami_wezla(): +def test_r7_judges_a_node_by_the_node_requirements(): import pandas as pd from gridqueue.schema import ENTITY_COLUMN @@ -124,11 +124,11 @@ def test_r7_ocenia_wezel_wymaganiami_wezla(): assert r7["szczegoly"]["wierszy_encji"] == {"WEZEL": 2} -def test_as_frame_zwraca_wiersz_na_regule(): - """Dokumentacja obiecywala te metode, a pakiet jej nie mial. +def test_as_frame_returns_one_row_per_rule(): + """The documentation promised this method and the package did not have it. - Defekt wyszedl dopiero przy uruchomieniu notatnika Colab, ktory korzystal - z publicznego API tak, jak opisuje je dokumentacja. + The defect only came out when the Colab notebook was run, because the + notebook used the public API exactly as the documentation describes it. """ import pandas as pd @@ -143,14 +143,14 @@ def test_as_frame_zwraca_wiersz_na_regule(): assert ramka["udzial"].between(0, 1).all() -def test_r3_nie_wywraca_sie_na_pustym_publikujacym(): - """R3 musi dzialac, gdy kolumna publikujacego jest obecna, ale pusta. +def test_r3_does_not_fall_over_on_an_empty_publisher(): + """R3 has to work when the publisher column is present but empty. - `groupby` pomija grupe o wartosci pustej, wiec wiersz bez tej adnotacji nie - ma wlasnego wpisu w slowniku pol ujawnianych. Przed poprawka odwolanie po - kluczu rzucalo `KeyError`, regula zwracala -1, a suma naruszen calego - raportu stawala sie ujemna -- defekt niemy, wykryty dopiero uruchomieniem - pakietu na ramce zbudowanej recznie. + `groupby` skips a group whose value is empty, so a row without that + annotation has no entry of its own in the dictionary of disclosed fields. + Before the fix, the lookup by key raised `KeyError`, the rule returned -1, + and the total number of violations in the whole report became negative: a + silent defect, found only by running the package on a hand-built frame. """ import pandas as pd diff --git a/tests/test_schema.py b/tests/test_schema.py index 996480f..0b48dc4 100644 --- a/tests/test_schema.py +++ b/tests/test_schema.py @@ -10,7 +10,7 @@ ) -def test_schema_ma_21_pol_i_4_polowy_rdzen_bezwarunkowy(): +def test_schema_has_21_fields_and_a_4_field_unconditional_core(): assert len(SCHEMA) == 21 assert len(FIELDS) == len(set(FIELDS)) == 21 assert set(CORE_FIELDS) == { @@ -20,26 +20,26 @@ def test_schema_ma_21_pol_i_4_polowy_rdzen_bezwarunkowy(): assert SCHEMA_VERSION == "1.0" -def test_rdzen_mocy_jest_alternatywa_nie_konkretnym_polem(): - # Pole mocy nie może być wymagane bezwarunkowo: wniosek czysto wytwórczy - # deklaruje moc wprowadzaną, odbiorczy pobieraną. +def test_the_power_core_is_an_alternative_not_one_specific_field(): + # A power field cannot be required unconditionally: a purely generating + # application declares export capacity, a demand one import capacity. assert "moc_pobierana" not in CORE_FIELDS assert "moc_wprowadzana" not in CORE_FIELDS assert CORE_ALTERNATIVES == (("moc_pobierana", "moc_wprowadzana"),) wspolny = {"id_wniosku": "X1", "lokalizacja_tekst": "Pozna\u0144", "klasa_zasobu": "PV", "status_procesu": "WNIOSEK_ZLOZONY"} df = pd.DataFrame([ - {**wspolny, "moc_wprowadzana": 1200.0, "moc_pobierana": None}, # wytwórczy - {**wspolny, "moc_wprowadzana": None, "moc_pobierana": 90.0}, # odbiorczy - {**wspolny, "moc_wprowadzana": 500.0, "moc_pobierana": 500.0}, # dwukierunkowy - {**wspolny, "moc_wprowadzana": None, "moc_pobierana": None}, # bez mocy + {**wspolny, "moc_wprowadzana": 1200.0, "moc_pobierana": None}, # generating + {**wspolny, "moc_wprowadzana": None, "moc_pobierana": 90.0}, # demand + {**wspolny, "moc_wprowadzana": 500.0, "moc_pobierana": 500.0}, # bidirectional + {**wspolny, "moc_wprowadzana": None, "moc_pobierana": None}, # no capacity ]) assert core_complete_mask(df).tolist() == [True, True, True, False] -def test_rdzen_jest_osobny_dla_kazdej_encji_obowiazku(): - # Wiersza encji WEZEL nie wolno oceniać wymaganiami encji WNIOSEK: pkt 2 - # przepisu ma inny przedmiot niż pkt 1/3/4. +def test_the_core_is_separate_for_each_entity_of_the_duty(): + # A WEZEL entity row must not be judged by the requirements of the WNIOSEK + # entity: point 2 of the provision has a different subject than points 1/3/4. assert set(CORE_BY_ENTITY) == {"WNIOSEK", "WEZEL"} df = pd.DataFrame([ {ENTITY_COLUMN: "WEZEL", "id_wezla": "SE-1", "moc_dostepna": 0.0}, @@ -51,7 +51,7 @@ def test_rdzen_jest_osobny_dla_kazdej_encji_obowiazku(): assert core_complete_mask(df).tolist() == [True, True, False, True] -def test_brak_anotacji_encji_znaczy_wniosek(): +def test_a_missing_entity_annotation_means_an_application(): df = pd.DataFrame([{"id_wniosku": "X1", "lokalizacja_tekst": "\u0141\u00f3d\u017a", "klasa_zasobu": "ODB", "status_procesu": "PRZYLACZONY", "moc_pobierana": 40.0}]) @@ -59,14 +59,14 @@ def test_brak_anotacji_encji_znaczy_wniosek(): assert core_complete_mask(df).tolist() == [True] -def test_kazde_pole_ma_podstawe_prawna_i_grupe(): +def test_every_field_has_a_legal_basis_and_a_group(): for f in SCHEMA: assert f.podstawa, f.name assert f.group in {"tozsamosc", "moc", "proces"}, f.name assert sum(len(v) for v in GROUPS.values()) == 21 -def test_jednostka_kanoniczna_mocy_to_kw(): +def test_the_canonical_power_unit_is_kw(): for f in SCHEMA: if f.name.startswith("moc_"): assert f.unit == "kW", f.name @@ -101,21 +101,21 @@ def test_canonical_date(raw, expected): assert canonical_date(raw) == expected -def test_canonical_power_odrzuca_nieznana_jednostke(): +def test_canonical_power_rejects_an_unknown_unit(): with pytest.raises(ValueError): canonical_power_kw("1", "GW") -def test_validate_instance_wykrywa_brak_rdzenia(): +def test_validate_instance_detects_a_missing_core(): row = {"id_wniosku": "X1", "lokalizacja_tekst": "Warszawa, Grochowska"} problems = validate_instance(row) assert any("klasa_zasobu" in p for p in problems) assert any("status_procesu" in p for p in problems) - # moc nie jest polem rdzenia bezwarunkowo, więc jej brak nie jest tu zgłaszany + # capacity is not a core field unconditionally, so its absence is not reported here assert not any("moc_pobierana" in p for p in problems) -def test_validate_instance_przepuszcza_poprawny_wiersz(): +def test_validate_instance_passes_a_correct_row(): row = { "id_wniosku": "X1", "lokalizacja_tekst": "Warszawa, Grochowska", "klasa_zasobu": "ODB", "moc_pobierana": 12000.0, @@ -125,14 +125,14 @@ def test_validate_instance_przepuszcza_poprawny_wiersz(): assert validate_instance(row, strict_vocab=True) == [] -def test_validate_instance_wykrywa_pole_spoza_schematu(): +def test_validate_instance_detects_a_field_outside_the_schema(): row = {c: "x" for c in CORE_FIELDS} row["moc_pobierana"] = 1.0 row["nieistniejace_pole"] = 1 - assert any("spoza schematu" in p for p in validate_instance(row)) + assert any("fields outside the schema" in p for p in validate_instance(row)) -def test_validate_instance_wykrywa_zly_typ_i_zly_geopoint(): +def test_validate_instance_detects_a_wrong_type_and_a_wrong_geopoint(): row = {c: "x" for c in CORE_FIELDS} row["moc_pobierana"] = "dużo" row["wspolrzedne"] = (999.0, 0.0) @@ -141,7 +141,7 @@ def test_validate_instance_wykrywa_zly_typ_i_zly_geopoint(): assert any("wspolrzedne" in p for p in problems) -def test_validate_frame_liczy_wypelnienie_i_rdzen(): +def test_validate_frame_counts_fill_rate_and_core(): df = pd.DataFrame({ "id_wniosku": ["a", "b"], "lokalizacja_tekst": ["x", None], @@ -156,7 +156,7 @@ def test_validate_frame_liczy_wypelnienie_i_rdzen(): assert rep["wypelnienie"]["data_umowy"] == 0.0 -def test_empty_frame_i_schema_table(): +def test_empty_frame_and_schema_table(): ef = empty_frame() assert list(ef.columns)[:21] == list(FIELDS) st = schema_table()